diff --git a/.agents/notes/README.i18n.yaml b/.agents/notes/README.i18n.yaml
new file mode 100644
index 0000000000..fa9c0d9a21
--- /dev/null
+++ b/.agents/notes/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
+README.md: 4db9f16956b9c569cf5f9b53f04cb650f6058668
+README.zh.md: 60ec5421e7f271460daebc966aa6548f6ef8a511
diff --git a/.agents/notes/README.md b/.agents/notes/README.md
index e62dc18954..4db9f16956 100644
--- a/.agents/notes/README.md
+++ b/.agents/notes/README.md
@@ -1,5 +1,7 @@
 # Agent Notes
 
+English | [中文](README.zh.md)
+
 One kind of design doc lives here. An **Agent Note** records a decision or proposal that shapes this codebase — the *why* and *what we gave up*, the parts code and docs can't carry. This file is the front door and contract: where Agent Notes live, when to write one, and [the in-file format](#the-file-format).
 
 ## Layout and naming
diff --git a/.agents/notes/README.zh.md b/.agents/notes/README.zh.md
new file mode 100644
index 0000000000..60ec5421e7
--- /dev/null
+++ b/.agents/notes/README.zh.md
@@ -0,0 +1,117 @@
+# Agent Notes
+
+[English](README.md) | 中文
+
+这里存放一类设计文档。**Agent Note（agent 决策记录）** 记录塑造本代码库的决策或提案：代码和文档无法承载的*为什么*以及*放弃了什么*。本文件是入口和契约：Agent Note 存放在哪里、何时需要写一份，以及[文件内格式](#the-file-format)。
+
+## 布局与命名
+
+每份 Agent Note 有两个维度，都编码在其**路径**中：`{lifecycle}/{class}/yyyy-mm-dd-topic-title.md`。
+
+- **生命周期**（顶层文件夹）是 Agent Note 的状态，Agent Note 随状态变化在文件夹之间移动：
+  - **`proposed/`**：实施前评审的提案；尚未构建（或仅部分构建）。
+  - **`implemented/`**：决策已交付。文件记录做了什么决定、否决了什么，并**与实际交付的内容保持同步**：当代码后续移动文件、重命名包（package）或更改键名/默认值时，Agent Note 在同一个变更中同步更新（仅限事实——路径、名称、结构——而非决策本身）。见 [implemented/AGENTS.md](implemented/AGENTS.md)。
+  - **`rejected/`**：提案经过讨论后被否决。保留以备查阅，避免同一问题被反复争论。
+- **类别**（嵌套文件夹）是决策的*种类*——见下方[分类](#classification)。
+
+文件名中的日期是该主题**首次提出**的时间（以 git 历史为准）。Agent Note 之间的交叉引用使用相对 Markdown 链接（`[topic](../../implemented/architecture/2026-…-….md)`），从不使用纯文字或编号，这样既可机械检查，也能在文件夹间移动时保持有效。
+
+目录树就是清单：浏览其生命周期/类别文件夹，或搜索仓库即可。请勿添加集中式 `INDEX.md`；设计理由见[不设索引的 Agent Note](implemented/process/2026-07-19-remove-generated-agent-note-index.md)。
+
+<a id="classification"></a>
+
+## 分类
+
+每份 Agent Note 属于 `scripts/agent-note-tree.ts` 中封闭集合里的一个路径编码类别；分类门禁拒绝其他文件夹。新增类别需要同时更新规范集合与本节。见[分类 Agent Note](implemented/process/2026-06-20-agent-note-classification.md)。
+
+| 类别 | 覆盖范围 |
+|---|---|
+| `feature` | 面向用户或模型的新功能。 |
+| `bug-fix` | 修正缺陷或弥补事故复盘（postmortem）发现的缺口。 |
+| `simplification` | 在不增加功能的前提下移除代码、行为或对外表面积。 |
+| `architecture` | 关于**交付源码**的结构性决策：包之间的关系、运行时词汇。 |
+| `process` | 代码**周边**的工具、策略或工作流——门禁、包管理器、vendor 化——不涉及运行时行为。 |
+| `testing` | 测试基础设施与策略。 |
+
+`architecture` 与 `process` 的界线：**architecture** 关乎我们交付的源码；**process** 关乎围绕源码的工具与工作流。（`refactor` 被有意排除：它与 `simplification` 重叠，而后者的判别标准「可观察行为是否改变」已经覆盖了它。）
+
+## 何时需要写一份
+
+每个非平凡变更都必须在同一 PR（Pull Request）中新增或更新至少一份 Agent Note。如果变更修改了行为、架构、跨文件或跨包契约、流程或工具、测试策略、磁盘、协议或配置格式，或者其他维护者可能合理重新审视的决策，就属于非平凡变更。对未来重大工作的提案从 `proposed/` 开始；已经做出的决策从 `implemented/` 开始。选择与决策匹配的类别文件夹（见[分类](#classification)）。
+
+更新已经拥有该决策的 Agent Note 即可满足规则；不要创建重复记录。只有不涉及行为、契约、结构、流程或理由变化的纯机械性或局部编辑才可豁免。Agent Note 永远不会被编辑为一个*不同的决策*：用新 Agent Note 取代旧的，并互相链接。编辑 `implemented/` Agent Note 以跟踪其现有决策的所在位置是必需的，而非禁止的；见 [implemented/AGENTS.md](implemented/AGENTS.md)。
+
+<a id="the-file-format"></a>
+
+## 文件格式
+
+每份 Agent Note 遵循统一的文件内格式，由 `pnpm run verify-agent-note-format`（[scripts/verify-agent-note-format.ts](../../scripts/verify-agent-note-format.ts)，`doc-sync`（文档同步门禁）的一环）强制执行；该格式的设计动机及其否决的替代方案见[统一格式 Agent Note](implemented/process/2026-07-05-uniform-agent-note-format.md)。
+
+### 头部块
+
+每份 Agent Note 的前三行严格为：
+
+```markdown
+# Agent Note: <title>
+
+Status: <status>
+```
+
+后跟一个空行。`Status:` 的值有三种形式，且必须与文件所在的生命周期文件夹一致——门禁会交叉检查：
+
+- `Status: proposed`
+- `Status: implemented`
+- `Status: rejected — <why, in one line>`
+
+状态行不带日期、不带括号补充说明：文件名记录首次提出日期，git 记录其余一切；「以修订形式接受」之类的说明属于正文内容（在陈述决策的地方说明修订）。拒绝原因是唯一带内容的状态，因为读者查阅被否决的 Agent Note 时，结论正是他们要找的。
+
+### 正文骨架
+
+每份 Agent Note 的正文以 `## Problem` 开头：动机，写法上不依赖解决方案即可独立成文。后续内容取决于生命周期；固定章节使用以下规范名称且仅限这些名称，而真正独特的技术章节（包拓扑、协议契约、schema 等）在必需章节之间可自由组织。
+
+#### `proposed/`
+
+```markdown
+## Problem
+## Proposal
+…bespoke sections…
+## Alternatives considered
+## Acceptance criteria
+## Risks
+```
+
+`## Proposal` 描述拟议的变更，可以合理地使用将来时态——计划、迁移步骤和待解决问题在工作尚未完成时属于此处。`## Acceptance criteria` 说明什么可观察状态意味着完成。`## Risks` 涵盖可能出错的事项以及该变更有意放弃的东西。
+
+#### `implemented/`
+
+```markdown
+## Problem
+## Decision
+…bespoke sections…
+## Alternatives considered
+## Consequences
+```
+
+`## Decision` 以现在时态描述已交付的现实，整个文件按 [implemented/AGENTS.md](implemented/AGENTS.md) 的要求与之保持同步。`## Consequences` 记录权衡的代价**与**收益。提案阶段的标题在此属于规格用语，门禁会拒绝它们：`## Proposal`、`## Plan`、`## Migration plan` 和 `## Acceptance criteria` 不得出现在 implemented Agent Note 中（原因见 [slop 检查清单](../../docs/AGENTS.md)）。`## Testing`、`## Deferred` 或 `## Related` 章节在陈述现在时态的事实时是允许的。
+
+#### `rejected/`
+
+被否决的 Agent Note 是冻结的提案：保留提案时的所有章节（包括 `## Acceptance criteria` 或 `## Plan`），结论写在 `Status:` 行上。仅头部块、`## Problem` 开头、`## Proposal` 章节以及下方的「曾考虑的替代方案」强制要求适用。
+
+### 曾考虑的替代方案——必需
+
+每份 Agent Note 都必须包含 `## Alternatives considered` 章节：每个真实的替代方案及其落选原因，每个替代方案用一个加粗引导的段落，或对争议较大的替代方案用 `### Why not <X>?` 子节。记录决策时不记录它击败了什么，就是在邀请反复争论——正是这些 Agent Note 存在的意义所要防止的。
+
+替代方案是记录下来的，不是凭空编造的。日期早于 2026-07-05 且替代方案无法从记录中重建的 Agent Note，在该章节位置放置以下精确注释，门禁仅对格式规范之前的文件接受此注释：
+
+```markdown
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
+```
+
+### 在生命周期之间移动
+
+将文件在生命周期文件夹之间移动意味着在同一个变更中更新 `Status:` 行并满足目标文件夹的骨架要求——否则门禁会失败。具体而言，`proposed/` → `implemented/` 将 `## Proposal` 改写为现在时态的 `## Decision`，将 `## Acceptance criteria` 和 `## Risks` 折入 `## Consequences`（或折入一个现在时态的 `## Testing`/`## Verification` 章节，用于描述现在锁定该行为的内容），并用实际交付的内容替换计划——即 [implemented/AGENTS.md](implemented/AGENTS.md) 所要求的改写，使之机械化。`proposed/` → `rejected/` 仅在 `Status:` 行添加原因并冻结文件。
+
+### 中文对侧文件
+
+`.zh.md` 对侧文件按 [i18n 契约](../../docs/i18n/README.md)逐章节镜像其英文兄弟文件的结构；机器检查的头部标记（`# Agent Note: ` 和 `Status:` 行）保持英文原样不翻译。格式门禁跳过 `.zh.md` 文件——配对门禁负责它们的一致性。
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
new file mode 100644
index 0000000000..01823c55d0
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-content-block-vocabulary.md: 9aad01cee6083b1f380be66869af3137a07d9f1f
+2026-06-11-content-block-vocabulary.zh.md: 5720f0742a0729a3f98e4b05ab37acf97ae78db5
diff --git a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.md b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.md
index 1133b990c3..9aad01cee6 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-content-block-vocabulary.zh.md)
+
 ## Problem
 
 The harness needs one internal language for messages that the loop, session log, and all plugins speak.
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
new file mode 100644
index 0000000000..5720f0742a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md
@@ -0,0 +1,28 @@
+# Agent Note: 由 dsh-llm 拥有的提供方无关内容块词汇
+
+Status: implemented
+
+[English](2026-06-11-content-block-vocabulary.md) | 中文
+
+## 问题
+
+harness 需要一套统一的内部消息语言，供 agent loop（智能体循环）、会话日志和所有插件共同使用。
+
+## 决策
+
+自主拥有词汇：消息是类型化内容块的数组（`text`、`reasoning`、`tool-call`、`tool-result`），其联合类型派生自可合并扩展的 `ContentBlockMap`，插件通过声明合并添加新的块类型。同一可合并扩展映射模式为所有「字符串化」字段提供类型（`MessageSource`、`FinishReason`、`TurnTrigger`、`TurnEndReason`）。流式输出采用原始分片协议；`BlockAssembler` 是唯一的共享组装实现。适配器负责转换为提供方的协议格式（wire format）——映射成本留在适配器中，正是它该在的地方。
+
+会话内上下文注入（`context/message`）和轮次中途 steering（`steering/message`）最初渲染为带标签的 user-role 信封（system-reminder 模式），而非引入新角色，因此适配器无需承担额外负担。如今两者都投影为无包装的普通用户内容；见[注入内容信封 Agent Note](../simplification/2026-07-20-unwrap-injected-content-envelopes.md)。实际适配器验证已确认此渲染方式符合当前 DeepSeek 的行为；如果未来某提供方出现不兼容，应在该适配器内处理，而非引入新的规范角色。
+
+## 曾考虑的替代方案
+
+- **镜像 DeepSeek/OpenAI chat-completions 结构**：对第一个提供方零映射成本，但对富内容（推理、结构化块形式的工具结果）处理不便。
+- **原样采用 Anthropic Messages 块结构**：经过实战检验，但规范类型将镜像一个 harness 并非首要对接的第三方 API。
+
+## 后果
+
+- 推理（reasoning）在核心层有了归属，无需依赖提供方特有的结构。
+- 多模态块只有在适配器、UI 和上下文压缩（context compaction）三方协同支持后才会回归；见 [drop-image Agent Note](../simplification/2026-07-04-drop-image-content-block.md)。
+- 缓存提示与 assistant prefill 在有实际适配器能兑现之前保持缺席；见[无生产者的词汇变体](../simplification/2026-07-04-prune-producerless-vocabulary-variants.md)与[无端到端可用路径的请求旋钮](../simplification/2026-07-04-drop-inert-request-knobs.md) Agent Note。
+- 每个适配器都需承担翻译成本；首批真实适配器已验证了流式输出协议，新适配器应继续在适配器本地测试中验证其提供方特有的映射。
+- 跨包（package）边界的 ID 使用品牌类型（`CallId`、agent 与会话共享的 `SessionId`）——零运行时开销的名义类型。
diff --git a/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.i18n.yaml
new file mode 100644
index 0000000000..41265a5b0f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-custom-schema-dsl.md: 947d53555df078bfa9f3dac48eab4b8c0074007c
+2026-06-11-custom-schema-dsl.zh.md: 26ebfe2fb15a6c034e809b3f51187342fa500193
diff --git a/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.md b/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.md
index bf8c02140a..947d53555d 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.md
@@ -2,13 +2,15 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-custom-schema-dsl.zh.md)
+
 ## Problem
 
 Tool parameters must reach the model as standard JSON Schema while giving tool authors typed `execute(args)` without casts. Schemastery already serves plugin config, but the tool-author API needs per-property `required: true` booleans rather than JSON Schema's separate `required` array.
 
 ## Decision
 
-A small custom DSL in dsh-tools: `SchemaSpec` (per-property specs with `required: true` booleans), type-level `InferArgs<S>` mapping a spec to the argument type (required keys non-optional, others genuinely optional via `?`), a runtime `schemaSpecToJsonSchema()` converter, and `defineTool()` tying them together. Raw JSON-Schema `ToolDefinition`s remain accepted by `ToolRegistry.register()` — that's how MCP-sourced tools arrive.
+This decision is superseded by the [unified JSON-value schema DSL](2026-07-20-unified-json-value-schema-dsl.md), which retains the small authoring surface while making parameters and typed values share one vocabulary. `ParameterSchemaSpec` keeps per-property `required: true`; `InferArgs<S>` maps required keys to non-optional properties; `parameterSchemaSpecToJsonSchema()` compiles the implicit open object root; and `defineTool()` ties inference, compilation, and validation together. Raw JSON-Schema `ToolDefinition`s remain accepted by `ToolRegistry.register()` for MCP and other external tools.
 
 ## Alternatives considered
 
@@ -17,5 +19,5 @@ A small custom DSL in dsh-tools: `SchemaSpec` (per-property specs with `required
 ## Consequences
 
 - First-party tool authors get zero-cast typed args; the type gymnastics cost stays inside the core package (sanctioned by the AGENTS.md type-safety policy).
-- The DSL is deliberately small (string/number/boolean/object/array, enum, default, nested properties/items). Gaps vs full JSON Schema (unions, formats, constraints) are accepted until real tools demand them.
+- The owning unified note defines the current nodes, literal constraints, unions, JSON-value boundary, and object-openness rules.
 - The `InferArgs` mapping is regression-tested at the type level after an early optionality bug.
diff --git a/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.zh.md b/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.zh.md
new file mode 100644
index 0000000000..26ebfe2fb1
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.zh.md
@@ -0,0 +1,23 @@
+# Agent Note: 使用自定义类型化工具 schema DSL 替代 schemastery
+
+Status: implemented
+
+[English](2026-06-11-custom-schema-dsl.md) | 中文
+
+## 问题
+
+工具参数必须以标准 JSON Schema 形式到达模型，同时让工具作者在 `execute(args)` 中获得类型化的参数而无需类型断言。Schemastery 已用于插件配置，但工具作者 API 需要逐属性的 `required: true` 布尔值，而非 JSON Schema 的独立 `required` 数组。
+
+## 决策
+
+该决策已由[统一 JSON 值 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)取代；新设计保留小型编写接口，同时让参数与类型化值共享一套词汇。`ParameterSchemaSpec` 保留逐属性的 `required: true`；`InferArgs<S>` 将必需键映射为非可选属性；`parameterSchemaSpecToJsonSchema()` 编译隐式开放的对象根；`defineTool()` 则将类型推导、编译与校验串联起来。原始 JSON Schema 的 `ToolDefinition` 仍是 `ToolRegistry.register()` 接受的输入，供 MCP 和其他外部工具使用。
+
+## 曾考虑的替代方案
+
+**Schemastery**（已作为 vendor 引入，用于插件 Config）经评估后被否决：它面向的是基于 StandardSchema 的校验／转换，而非 JSON Schema *生成*，因此会增加间接层却无法干净地产出协议格式（wire format）。
+
+## 后果
+
+- 第一方工具作者获得零类型断言的类型化参数；类型体操的成本留在核心包内部（符合 AGENTS.md 的类型安全策略）。
+- 当前节点、字面量约束、联合类型、JSON 值边界与对象开放性规则均由上述统一说明定义。
+- `InferArgs` 映射在类型层面有回归测试，源于早期一个可选性 bug。
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
new file mode 100644
index 0000000000..c6ddb39d01
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-dev-invariants-over-deep-readonly.md: 8f0e79f15af82ce3125b1f6f767d4ea727aa6d29
+2026-06-11-dev-invariants-over-deep-readonly.zh.md: 2f787bbd55b5a9a91bc5342351756e45cb0515d3
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 fb1dc93159..8f0e79f15a 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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.
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
new file mode 100644
index 0000000000..2f787bbd55
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
@@ -0,0 +1,60 @@
+# Agent Note: 源端拥有的会话不可变性与开发模式不变式
+
+Status: implemented
+
+[English](2026-06-11-dev-invariants-over-deep-readonly.md) | 中文
+
+## 问题
+
+会话日志需要两种不同的保护：对每条已存储事实的不可变所有权，以及对跨时间和服务 seam 的事实之间关系的检查。如果将二者混为一个可选的开发插件，生产环境的历史记录将失去保护；如果试图通过 TypeScript readonly 类型同时表达两者，既无法建立运行时边界，也无法描述关系规则。
+
+会话日志是回放、请求重建、持久化与用户可见历史的持久真源。会话包（package）外部的代码必须能检视历史，但不能保留一个可在之后改写历史的引用；从调用方接受的输入也不能继续连接到调用方拥有的可变对象。
+
+单个值的不可变性只是契约的一半。一份日志可以包含完全不可变的记录，但其序列、轮次/步骤嵌套、工具调用配对、作用域分发或重建的模型请求是错误的。这些规则涉及多条记录或多个服务，无法通过冻结单个对象来建立。
+
+TypeScript readonly 类型不是充分的运行时边界。它们在程序运行时消失，类型转换可以绕过它们，而递归的 `DeepReadonly<T>` 会扩散到每个日志和消息消费方，尽管某些下游请求处理 API 有意使用可变值。
+
+## 决策
+
+职责在始终启用的存储边界与可选的开发断言之间分离。
+
+### Session 拥有不可变历史
+
+`Session` 仅在一次递归遍历完成无损 JSON 快照的物化之后才接受事件。该遍历拒绝不支持的值，并产出进入日志的确切分离记录，因此验证与存储不会从有状态的 getter 观察到不同的值，也不会保留调用方拥有的嵌套引用。
+
+被接受的事件及其所有后代在发布前被深度冻结。`append()` 返回该拥有的冻结事件，`session/event` 观察者接收同一记录，`session.events` 返回冻结的数组快照。先前返回的数组不会因后续 append 而增长。种子记录在构造成功前经过相同的验证、快照与冻结边界。
+
+此保证属于 `Session` 而非可选监听器，因为每种组合都依赖可信的历史。无论是否注册了开发支持插件，生产部署、聚焦测试或自定义嵌入都获得相同的存储语义。
+
+### 派生请求保持分离
+
+`deriveMessages()` 将已记录的表面事件投影为分离的、深度冻结的 `Message` 对象，并返回一份新的数组快照。因此请求组装可以将派生历史与其他输入组合，而不会暴露一条回到日志的路径。缓存复用安全的不可变投影，而非为每次模型调用重新克隆完整历史。
+
+### 包拥有的不变式配套插件检查关系
+
+`dsh-invariants` 注册可配置的 `ctx.invariants` 服务，本身不包含产品检查。每个包发布一个 `./invariant` 所有权配套插件；`dsh-session`、`dsh-agent`、`dsh-scope` 和 `dsh-agent-loop` 目前添加需要 trace 状态或观察另一个 seam 的规则：单调递增的序列号、轮次与步骤嵌套、工具调用/结果配对、合法的 agent（智能体）状态转换、主体正确的作用域分发，以及循环构建的请求与从其会话日志前缀重建的请求之间的等价性。全局启用和包名 regex 过滤器归该服务所有（见[包拥有的不变式服务](2026-07-19-package-owned-invariant-service.md)）。
+
+当会话配套插件附加到已有或已播种的会话时，它回放不可变日志以重建跟踪状态。服务为每项贡献提供一个可 dispose（资源释放）的子 fiber，因此轮次中途热重载是安全的，同时不赋予诊断逻辑对会话存储的所有权。
+
+## 曾考虑的替代方案
+
+### 全面的 deep-readonly 类型
+
+[被否决的不可变公共表面提案](../../rejected/architecture/2026-06-11-immutable-public-surfaces.md)会在公共日志和消息表面上应用递归 readonly 类型。这能提供编辑器反馈，但无法提供运行时保证：TypeScript 类型在运行时被擦除，插件代码可以通过类型转换绕过。它还会将 readonly 类型推入有意进行修改的消费方。在 `Session` 边界处的运行时所有权保护所有调用方，无需这种类型传播。
+
+### 仅在开发模式冻结
+
+仅当不变式插件安装时才冻结历史，会使核心保证依赖于组合方式。代码可能通过开发测试，却在生产环境或省略了该插件的聚焦组合中破坏历史。因此存储不可变性始终启用，而开销更大的关系检查则保持为可选的开发支持。
+
+### 仅在派生消息时克隆
+
+分离 `deriveMessages()` 能保护最常见的请求路径，但 `session.events` 的其他读取者、append 返回值和会话事件观察者仍能修改持久历史。日志必须保护自身的边界；派生投影是额外的隔离边界，而非替代品。
+
+## 后果
+
+- 每个被接受的实时或种子会话事件在任何观察者接收之前，都已从调用方拥有的输入中分离并深度不可变。
+- `session.events` 暴露稳定的不可变快照，而非私有的增长数组。
+- 请求侧的修改无法通过派生消息触及已存储的历史。
+- 开发构建可以启用关系断言而不改变存储行为；dispose 或过滤一个配套插件不会削弱日志不可变性。
+- `dsh-invariants` 配置全局启用状态以及包允许/阻止 regex 列表；每项检查仍由其产品包拥有并测试。
+- 运行时边界对每个被接受的事件产生一次递归快照与冻结的开销；后续读取者和缓存投影复用已拥有的不可变记录。
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
new file mode 100644
index 0000000000..6ea6fce11e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-event-sourced-sessions.md: 15ba7b23d5eae48e7dee2328b5924493d54aeeb0
+2026-06-11-event-sourced-sessions.zh.md: da3be5965a6900076f253cad065b847c6f5ce17e
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 bab36ee783..15ba7b23d5 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-event-sourced-sessions.zh.md)
+
 ## Problem
 
 The MVP requires strict event-based tracing with fully replayable sessions (严格的基于事件的trace、logging系统，session完全可回放).
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
new file mode 100644
index 0000000000..da3be5965a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
@@ -0,0 +1,28 @@
+# Agent Note: 事件溯源的会话与派生消息历史
+
+Status: implemented
+
+[English](2026-06-11-event-sourced-sessions.md) | 中文
+
+## 问题
+
+MVP 要求严格的基于事件的追踪，以及完全可回放的会话（严格的基于事件的 trace、logging 系统，会话完全可回放）。
+
+## 决策
+
+`Session` 是一份仅追加的、类型化的 `SessionEvent` 日志，是唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`）；原始流分片被记录以保证 token 级别的回放保真度，而组装后的 `assistant/message` 事件才是派生的权威依据。回放/fork = 用已有日志初始化一个新会话。
+
+追加操作是同步的（热路径从不阻塞于 I/O）；`session/event` 是同步通知；持久化插件在后台缓冲写入，并在每个轮次结束时触发的 `session/flush` 检查点处等待排空。
+
+顺序契约：agent loop（智能体循环）*先*追加到会话，再发出对应的 Cordis 事件；`agent/step-result` waterfall（瀑布式事件）在 `assistant/message` 追加之前运行，因此日志记录的是工具调度实际使用的消息。回归测试固定了这一顺序。
+
+## 曾考虑的替代方案
+
+**可变消息数组 + 事件仅作通知发出**：更简单，但状态与日志可能分歧；采用事件溯源后，日志本身即是状态，分歧在结构上不可能发生。
+
+## 后果
+
+- 回放、追踪与遥测在结构上得到保证，而非事后附加。
+- 持久化仍是插件关注点；内存存储随 dsh-session 一起提供。
+- 事件词汇可通过合并扩展（插件可添加如压缩（compaction）事件）；[会话持久化](2026-06-14-session-persistence.md)在日志变为持久后冻结了其形状。
+- 派生成本随日志长度增长，压缩（未来插件）是预期的缓解手段，而非日志变更。
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
new file mode 100644
index 0000000000..a15ebcfddf
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-microkernel-event-taxonomy.md: 8bf05b7deba5f054d4ec8ecf104c3b8798e42d4e
+2026-06-11-microkernel-event-taxonomy.zh.md: 4ff2ab632ca02e98137a15f19a7996a740a519b0
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 abdadb447b..8bf05b7deb 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-microkernel-event-taxonomy.zh.md)
+
 ## Problem
 
 The product principle is "everything is a plugin": hooks, /goal, /loop, dynamic workflows, compaction, sandboxing, permissions, UI, persistence, MCP, skills must all be writable as plugins without modifying the core.
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
new file mode 100644
index 0000000000..4ff2ab632c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 微内核——通过 Cordis 事件分类体系实现扩展，唯一具体循环
+
+Status: implemented
+
+[English](2026-06-11-microkernel-event-taxonomy.md) | 中文
+
+## 问题
+
+产品原则是「一切皆插件」：钩子、/goal、/loop、动态工作流、上下文压缩（context compaction）、沙箱、权限、UI、持久化、MCP、skill（技能）都必须能以插件形式编写，无需修改核心。
+
+## 决策
+
+纯 Cordis 事件分类体系。agent loop（智能体循环）的扩展 seam 是带类型的事件，具有明确的分发模式：
+
+- **waterfall（瀑布式事件）**（around-middleware）：插件可变换、否决、恢复或包装：`agent/prompt-submit`、`agent/request`、`agent/request-error`、`agent/step-result`、`agent/turn-continuation`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
+- **serial**（按监听器顺序依次 await；bail 值会阻止后续监听器执行）：用于有序检查点。所有 `agent/pre-step` 和 `agent/post-step` 监听器在全部弃权时才继续运行，而 `agent/turn-stop` 返回的第一个 stop 值即为最终的终止决策。
+- **parallel**（await 扇出）：每个监听器都必须获得独立执行的机会：`session/flush` 持久性检查点。
+- **emit**（同步 fire-and-forget）：用于通知：轮次/步骤边界、流分片、生命周期、错误，以及包含不可变 `tools/result` 观测的事件。
+
+事件词汇定义在接口包中（dsh-agent 声明 agent/* 事件）；`@deepseek-ai/dsh-agent-loop` 是唯一的具体循环插件，且自身可替换——外部不得依赖它。
+
+## 曾考虑的替代方案
+
+**专用中间件栈（koa-compose 风格）** 与**显式阶段状态机（插件向其中插入阶段）**：两者都需要重新实现 Cordis 原生事件系统已提供的分发、dispose（资源释放）与重载语义；作为 Cordis effect，监听器天然获得 HMR（热模块替换）与 dispose 能力。
+
+## 后果
+
+- 每个 MVP 功能都映射到一个监听器（[功能→机制映射](../../../../docs/cookbook/extension-cookbook.md#the-feature--mechanism-map)是证明义务，保持更新）。
+- HMR 与 dispose 无需额外工作：监听器和注册均为 Cordis effect。
+- waterfall 语义（调用 `next()` 或短路）不直观，需要教学——在 AGENTS.md 中记录，并由组合测试覆盖。
+- 循环必须具备防御性：插件异常在轮次级别被隔离，任何 seam 发出的 steering（中途引导）永远不会被搁置（有回归测试保障）。
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
new file mode 100644
index 0000000000..0697332171
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-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
+2026-06-11-runtime-arg-validation.md: e0bca0ff24c5adc7ca58007932dff6580694b01d
+2026-06-11-runtime-arg-validation.zh.md: 09958147766b4015d6bebf786c4947b9d2941f74
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 454f12d0af..e0bca0ff24 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
@@ -2,15 +2,17 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-runtime-arg-validation.zh.md)
+
 ## Problem
 
-`defineTool` ([the custom schema DSL](2026-06-11-custom-schema-dsl.md)) gives tool authors a typed `execute(args)` via the `InferArgs<S>` mapping. But that type is a compile-time claim about a value that arrives at runtime as model-generated JSON: nothing forced the model to honor the schema, so a malformed call — missing a required key, a string where a number was declared, an enum value outside the set — reached `execute` typed-in-name-only. The tool body then either crashed on the bad shape (a generic stack trace the model can't act on) or, worse, silently misbehaved. Meanwhile the converter already encodes the exact structure a validator would need to walk.
+`defineTool` ([the unified schema DSL](2026-07-20-unified-json-value-schema-dsl.md)) gives tool authors a typed `execute(args)` via the `InferArgs<S>` mapping. But that type is a compile-time claim about a value that arrives at runtime as model-generated JSON: nothing forced the model to honor the schema, so a malformed call — missing a required key, a string where a number was declared, or a literal outside the declared set — reached `execute` typed-in-name-only. The tool body then either crashed on the bad shape or silently misbehaved.
 
 ## Decision
 
-`validateArgs(spec, args): string[]` interprets a `SchemaSpec` over a runtime value, returning human-readable violations (empty = valid), and is total (never throws). `defineTool` runs it before the typed body; on violations it throws `ToolArgsError` (`code: 'INVALID_ARGS'`, message listing the violations), which the registry's existing execute-waterfall catch turns into an `isError` result the model reads and self-corrects from.
+`validateArgs(spec, args): string[]` compiles a `ParameterSchemaSpec` and delegates to the shared `validateJsonSchemaValue()` walker, returning human-readable violations for a well-formed declaration. `defineTool` snapshots the compiled parameter schema at definition time and runs that validation before the typed body; violations throw `ToolArgsError` (`INVALID_ARGS`), which the registry returns as an error result the model can correct.
 
-The validator mirrors `schemaSpecToJsonSchema` semantics exactly — same structure walked, same rules: top level must be a non-array object; required keys come only from `required: true`; extra keys are allowed (no `additionalProperties: false`); `default` is not applied; an `object`/`array` prop without `properties`/`items` only type-checks; `enum` is membership. Raw-registered (MCP) tools are not touched — they validate their own input.
+The validator and compiler therefore share exact semantics: the implicit parameter root is an open object; required keys come only from `required: true`; defaults remain annotations; explicit nested objects honor their declared openness; arrays recurse through `items`; scalar literal constraints are type-correct; and `oneOf` accepts exactly one matching branch. Raw-registered tools own their input validation.
 
 ## Consequences
 
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
new file mode 100644
index 0000000000..0995814776
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
@@ -0,0 +1,24 @@
+# Agent Note: 模型边界处的运行时参数校验
+
+Status: implemented
+
+[English](2026-06-11-runtime-arg-validation.md) | 中文
+
+## 问题
+
+`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` 仅在恰好一个分支匹配时才接受。原始注册的工具自行负责输入校验。
+
+## 后果
+
+- 模型在自身畸形调用上获得可操作的反馈，而非不透明的崩溃，弥合了 `InferArgs` 的承诺与运行时现实之间的鸿沟。
+- 校验器与 `InferArgs` 必须保持一致；一项[属性测试](../testing/2026-06-11-property-based-testing.md)生成满足 spec 的参数并断言它们通过 `validateArgs`（同时断言定向破坏的参数被拒绝），以机械方式封堵漂移风险。
+- `ToolArgsError` 目前是带 `code` 字段的普通 `Error`；如果日后引入 harness 级别的错误分类体系，它将变为子类，但不影响读取 `.message` 的调用方。
+- 校验开销相对于一次模型调用可忽略不计。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.i18n.yaml
new file mode 100644
index 0000000000..ca9d2117ec
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-structured-error-taxonomy.md: 9122193b3d01cf5a4c315e6f7a7218153fd4a60a
+2026-06-11-structured-error-taxonomy.zh.md: 56a196ccd10a81b51953887f18e522412cd9463b
diff --git a/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md b/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md
index b2f4ea66b4..9122193b3d 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-structured-error-taxonomy.zh.md)
+
 ## Problem
 
 Failures crossed seams as bare strings. A tool error flattened to a text block — name, code, and stack lost — so a future sandbox/retry plugin couldn't tell ENOENT from EACCES, and the model got less actionable feedback than it could. A non-Error throw degraded further: the loop wrapped it in `new Error(String(x))`, dropping any code. And `LlmError` was the only typed error in the system, with no shared base, so there was nothing for a consumer to `instanceof` against generically.
diff --git a/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.zh.md b/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.zh.md
new file mode 100644
index 0000000000..56a196ccd1
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.zh.md
@@ -0,0 +1,26 @@
+# Agent Note: 结构化错误分类体系
+
+Status: implemented
+
+[English](2026-06-11-structured-error-taxonomy.md) | 中文
+
+## 问题
+
+故障跨越 seam 时只是裸字符串。工具错误被扁平化为一个文本块（name、code 和 stack 全部丢失），导致未来的沙箱/重试插件无法区分 ENOENT 和 EACCES，模型得到的反馈也不如本可以那样具有可操作性。非 Error 的 throw 退化更严重：agent loop（智能体循环）将其包装为 `new Error(String(x))`，丢弃了所有 code。而 `LlmError` 是系统中唯一的类型化错误，没有共享基类，消费方无法对其进行通用的 `instanceof` 判断。
+
+## 决策
+
+在 `dsh-llm`（叶子包，所有其他包都已依赖它，不引入新的依赖边）中引入一个 `HarnessError extends Error` 基类：稳定的 `code`（与 `message` 分离）、通过 `ErrorOptions` 进行 `cause` 链接、`name` 默认为子类名。`isHarnessError` 在 seam 处做类型收窄。
+
+- `LlmError` 和 `ToolArgsError`（dsh-tools）继承该基类，保留各自既有的 code。
+- `ToolExecutionResult` 新增可选字段 `error: { name, code }`，在注册表的 catch 中当抛出值为 `HarnessError` 时填充。agent loop 将其转发到 `tool/result` 会话事件（该事件也新增了同一可选字段），使结构化的失败信息存活到日志中，供重试/沙箱插件和回放使用。面向模型的文本块保持不变。
+- agent loop 的 `toError` 将非 Error 的 throw 包装为 `HarnessError`（`code: 'UNKNOWN'`，原始值作为 `cause` 链接），而非裸 `Error`；这样即使是不规范的 throw 也能携带可路由的 code 进入会话的 `error` 事件（该事件此前已暴露 `code`）。
+
+## 后果
+
+- 错误端到端可机器路由：插件可以基于 `error.code` 分支，而无需对消息做子串匹配。
+- 一个基类被广泛导入，但它位于所有包已经依赖的包中，代价仅是一条 import 语句，而非新的依赖边。
+- `deriveMessages` 不会将 `error` 暴露到模型历史中——模型仍然看到文本块；结构化字段服务于代码和回放。
+- 参数校验保留其既有的 code 和行为；包自有的诊断不变式独立携带稳定 code，使不变式注册表无需导入产品包。共享基类增加了跨 seam 的路由元数据，不改变面向模型的文本。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.i18n.yaml
new file mode 100644
index 0000000000..61ecb29ca3
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-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
+2026-06-11-tool-schemas-in-prompt-assembly.md: 3643ac3d61be08f629ef0cd0424fef5cb9696c3a
+2026-06-11-tool-schemas-in-prompt-assembly.zh.md: 10389fd7c63755e5b00b3c508fd303a541287f2c
diff --git a/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.md b/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.md
index 59ea9117dc..3643ac3d61 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-tool-schemas-in-prompt-assembly.zh.md)
+
 ## Problem
 
 On the wire, tool schemas travel in a dedicated `tools` field of the model request, not in prompt text. Architecturally, though, "what the model is told it can do" is one coherent concern: prompt sections and the tool list are assembled from the same plugin contributions and consumed at the same moment.
diff --git a/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.zh.md b/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.zh.md
new file mode 100644
index 0000000000..10389fd7c6
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.zh.md
@@ -0,0 +1,23 @@
+# Agent Note: 工具 schema 是系统提示词组装的一部分
+
+Status: implemented
+
+[English](2026-06-11-tool-schemas-in-prompt-assembly.md) | 中文
+
+## 问题
+
+在协议格式（wire format）层面，工具 schema 通过模型请求中专用的 `tools` 字段传输，而非嵌入提示词文本。然而从架构角度看，「模型被告知它能做什么」是一个统一的关注点：提示词段落与工具列表由相同的插件贡献组装，并在同一时刻被消费。
+
+## 决策
+
+`PromptAssembly { sections, tools }`：系统提示词服务同时收集有序的文本段落和工具 schema（工具注册表自动贡献一个提供方）。agent loop（智能体循环）每个步骤消费一份 assembly；适配器将 `sections` 映射到提供方的 system 槽位，将 `tools` 映射到协议格式的 `tools` 字段。因此 `system-prompt/assemble` waterfall（瀑布式事件）是模型预先获知的所有信息的唯一拦截点：工具过滤（ToolSearch / 渐进式披露）是一次 assembly 重写，与提示词编辑无异。
+
+## 曾考虑的替代方案
+
+**循环从工具注册表和提示词服务分别查询**：将一个统一的关注点拆到两个 seam 上；任何想影响「模型被告知什么」的拦截（工具过滤、plan 模式）都需要在两个接口上各挂一个监听器，而非一次 assembly 重写即可完成。
+
+## 后果
+
+- 一条 waterfall 统管模型的常驻上下文；plan 模式等插件可以在一个监听器中同时替换提示词文本和可见工具。
+- assembly 接口通过声明合并实现可扩展（没有无类型的 `extras` 包——扩展即声明合并），为未来的槽位预留空间。
+- 将 schema 放在「提示词」服务中略有概念上的意外感，已在本文及包 README 中加以说明。
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
new file mode 100644
index 0000000000..63063f8d5f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-13-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
+2026-06-13-capability-seams.md: 7c755dced7825d2831acc0901f6412b8e5afe95a
+2026-06-13-capability-seams.zh.md: 4148c79cb5e1930dca77eaf3afd2024f508275b5
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 5ca299abc0..7c755dced7 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-13-capability-seams.zh.md)
+
 ## Problem
 
 The harness has swappable capabilities — bash execution today, sandboxed/remote executors and alternative model providers tomorrow. A capability has three concerns that change at different rates and for different reasons: the *contract* (what the capability is), the *implementation* (how it runs), and the *consumer surface* (what the model and other plugins program against). Bundling them in one package couples those rates of change — swapping a local executor for a sandboxed one would churn the tool schemas the model sees, even though the model-facing contract never changed.
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
new file mode 100644
index 0000000000..4148c79cb5
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: 能力 seam——接口／实现／消费方三分
+
+Status: implemented
+
+[English](2026-06-13-capability-seams.md) | 中文
+
+## 问题
+
+harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化／远程执行器和替代模型提供方。一项能力涉及三个关注点，它们以不同速率、因不同原因变化：*契约*（这项能力是什么）、*实现*（它如何运行）、*消费方接口*（模型和其他插件面向什么编程）。将三者捆绑在一个包（package）中会耦合这些变化速率——把本地执行器换成沙箱化执行器时，模型看到的工具 schema 也会被搅动，尽管面向模型的契约从未改变。
+
+这与「谁在运行时提供、谁需要一项能力」是不同的问题，后者 Cordis 已通过服务 + `inject` 解决（提供方注册 `ctx.bash`；消费方声明 `inject: ['bash']`，其 fiber 挂起直到服务存在）。该机制是必要的，但不决定包的边界；本 Agent Note 决定的是包的边界。
+
+## 决策
+
+一项可替换的能力由**三个包**构成：
+
+1. **接口**——一个抽象服务加词汇类型，拥有 `ctx.<key>`，仅依赖其词汇依赖（例如 `dsh-bash`：`BashExecutor`、`BashRunResult`、`BashProcess`）。
+2. **实现**——一个具体子类，以插件形式加载（例如 `dsh-bash-local`：子进程、进程组 kill、溢出文件截断）。沙箱化／远程后端是实现同一接口的兄弟包。
+3. **消费方**——模型和插件看到的内容（例如 `dsh-tool-bash`：`bash` schema，后台句柄注册到通用任务运行时）。消费方 `inject` 接口键，从不导入实现类型。
+
+实现与消费方由此独立演进：沙箱化执行器替换 `dsh-bash-local` 时无需触碰任何工具 schema。
+
+当各部分确实属于同一个关注点时，三分并非强制：LLM（大语言模型） seam 将接口 + 消费方合并为 `dsh-llm`（消费方是 agent loop（智能体循环）本身，而非可替换的 schema 表面），适配器作为实现包。不要预防性地拆分——如果一项能力只有一种可设想的实现和一个消费方，就保持为一个包，直到第二种出现。
+
+## 曾考虑的替代方案
+
+- **单一合并包**：否决。因为它重新耦合了三分设计本要分离的三种变化速率（这正是拆分的意义所在）。
+- **`@cordisjs/plugin-capability`**：这是完全不同的维度。它是一个权限／能力*安全*服务（具名权限加继承，通过 `ctx.capability.test` 对会话进行检测），是延后的权限/沙箱工作（`tools/pre-execute` deny/ask seam）的候选方案，不是替换实现的机制。混淆这两个「能力」概念正是本 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
new file mode 100644
index 0000000000..f1d2fe1a90
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-13-twin-llm-adapters.md: 5c3308b281ce71407002e95dd6e794da2a421fa8
+2026-06-13-twin-llm-adapters.zh.md: 93b084973bccaeb802508e4e939a259c281f2608
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 7f2f5933ad..5c3308b281 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-13-twin-llm-adapters.zh.md)
+
 ## Problem
 
 `dsh-llm` owns a provider-neutral streaming vocabulary — the `StreamChunk` protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`) and the content-block types ([the content-block vocabulary](2026-06-11-content-block-vocabulary.md)). A vocabulary defined against a single adapter risks baking that adapter's quirks into the "neutral" contract: anything the one implementation happens to do becomes the de-facto spec, and the abstraction is unverified until a second provider arrives — by which point the leak is expensive to fix.
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
new file mode 100644
index 0000000000..93b084973b
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
@@ -0,0 +1,27 @@
+# Agent Note: 以两个 LLM 适配器作为设计验证孪生体
+
+Status: implemented
+
+[English](2026-06-13-twin-llm-adapters.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` + SSE（Server-Sent Events）解析，直接对接 DeepSeek API。
+- `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'}` 结束）。后一项分歧正是由基于库的适配器暴露出来的，单一手写适配器会将其隐藏。
+
+## 曾考虑的替代方案
+
+- **单一适配器**：代码更少、e2e 成本减半，但「提供方无关」的声明无从验证；词汇会默默编码 DeepSeek-via-fetch 的假设。
+- **mock 第二适配器**：更便宜，但不会触及真实提供方的协议格式（wire format）怪癖，因此证明力有限。孪生体是真实对真实的验证。
+
+## 后果
+
+孪生体使适配器和需要密钥的 e2e 维护量翻倍——两者都覆盖 V4 Flash 和 Pro 在各代表性推理（reasoning）模式下的行为——换来的是持续的 seam 中立性验证和第二份实现示例。两个适配器均使用 `apiKey`、`baseURL` 和 `models`；手写适配器暴露 `thinking`/`reasoningEffort`，pi-ai 适配器暴露一个 `reasoning` 级别。未来如果有一致性测试套件，可以通过后续 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
new file mode 100644
index 0000000000..8b9aaea118
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-14-session-persistence.md: 2683bcd68e1f52fbd2bc78660fbe17e556a9a60d
+2026-06-14-session-persistence.zh.md: 28e32925a5866fe520c0d9c3eb7b0647845d36f5
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 4e105ef598..2683bcd68e 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-14-session-persistence.zh.md)
+
 ## Problem
 
 Sessions lived only in memory. The example `session-jsonl.ts` plugin (duplicated byte-for-byte in both examples) was write-only telemetry: it buffered `session/event` and appended JSON lines, with no read/replay path, no crash-safety (no fsync, no atomic write, a fire-and-forget dispose drain), no listing, and no format versioning. Nothing could rehydrate a past session from disk into a live agent, so durable resume ("continue yesterday's task"), durable forking, and the ACP `session/load` method ([ACP support](../feature/2026-06-14-acp-agent-client-protocol.md)) were all impossible.
@@ -19,16 +21,16 @@ Key choices recorded here because they are durable, contested, and surprising:
 
 - **The canonical durable log persists every `SessionEvent` verbatim, including `assistant/chunk`.** `deriveMessages()` skips chunks, and a chunk-filtered rollout (Codex's `policy.rs`) is tempting — but `seq = log.length` and the load-validation `events[i].seq === i` require a *contiguous* 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, `load` preserves its contiguous, parseable events and appends risk-classified error results for unanswered assistant calls, a missing `step/end`, and `turn/end` with `{ kind: 'interrupted' }`. The synthetic results keep resumed provider transcripts valid. Only an incomplete final record is discarded; 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), `load` is 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, interrupted-turn close on load, contiguous-seq), expressed once over file bytes and once over rows.
-- **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()`. 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).)
+- **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), `load` is 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, interrupted-turn close on load, 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).)
 - **`ctx.agents.create()` and `ctx.agents.resume()` are async factories; resume additionally crosses the persistence boundary.** `ctx.agents.resume({ resumeSessionId })` awaits `ctx.sessionPersistence.load`, recreates the live session with the loaded events (so `lastTurnNumber`/`deriveMessages` continue), and registers the fresh agent under the exact resumed id. 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
 
-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; **hard-injecting `sessionPersistence` into the loop** — would pend non-persistent demos forever.
+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`; `load` rejects any non-current version (no migration — the pre-release session format is pinned at `SESSION_FORMAT_VERSION = 0` and absorbs shape churn, per the AGENTS.md pre-release stance). Stated honestly: append-only + flush is robust to partial trailing writes (tolerated on load) but not to fsync-less power loss mid-line; a DB/WAL backend is the stronger option later.
 
 ## 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 the foundation the ACP `session/load` ([ACP support](../feature/2026-06-14-acp-agent-client-protocol.md)) needs — all 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, and serializability semantics. Persisting the full log also settles event fidelity: `assistant/chunk` remains verbatim.
+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 the foundation the ACP `session/load` ([ACP support](../feature/2026-06-14-acp-agent-client-protocol.md)) needs — all 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, integer-metadata, and serializability semantics. Persisting the full log also settles event fidelity: `assistant/chunk` remains verbatim. 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
new file mode 100644
index 0000000000..28e32925a5
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 会话持久化作为基于现有 `SessionEvent` 的抽象服务
+
+Status: implemented
+
+[English](2026-06-14-session-persistence.md) | 中文
+
+## 问题
+
+会话此前仅存在于内存中。示例插件 `session-jsonl.ts`（在两个示例中逐字节重复）是只写的遥测：它缓冲 `session/event` 并追加 JSON 行，没有读取/回放路径，没有崩溃安全性（无 fsync、无原子写入、fire-and-forget 的 dispose 排空），没有列表功能，也没有格式版本控制。没有任何机制能将磁盘上的历史会话重新注入到活跃的 agent（智能体）中，因此持久恢复（「继续昨天的任务」）、持久 fork 以及 ACP（Agent Client Protocol）的 `session/load` 方法（[ACP 支持](../feature/2026-06-14-acp-agent-client-protocol.md)）都无法实现。
+
+[事件溯源模型](2026-06-11-event-sourced-sessions.md)将仅追加日志作为唯一真源，并从中派生 LLM（大语言模型）历史。持久化必须忠实于这一设计：直接持久化现有的 `SessionEvent`，不引入需要来回转换的并行「持久化消息」类型。后端也必须可替换——当前用文件存储，以后用数据库存储——统一在一个接口之后。
+
+## 决策
+
+持久化是一个抽象的**能力 seam**（[能力 seam](2026-06-13-capability-seams.md)，`dsh-bash` 模板），而非循环或核心逻辑：
+
+1. **接口**（`dsh-session-persistence`，`ctx.sessionPersistence`）：一个抽象的 `SessionPersistence` 服务，提供 `create`/`append`/`load`/`list`。其持久化单元就是现有的 `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`。** `deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及加载验证 `events[i].seq === i` 要求日志是*连续*的；过滤掉分片会留下空洞，同时破坏契约和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
+- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，`load` 保留其连续、可解析的事件，并为未应答的 assistant 调用追加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。合成的结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
+- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 契约的事务中），`load` 是 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.load`，用加载的事件重建活跃会话（使 `lastTurnNumber`/`deriveMessages` 得以延续），并以原样恢复的 id 注册新 agent。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
+
+## 曾考虑的替代方案
+
+上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 契约；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储及查询列不一致；**接受非全新的未版本化 SQLite 文件**可能覆盖无关对象或应用标识；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
+
+格式版本控制：header 携带一个 `version`；`load` 拒绝任何非当前版本（不做迁移——预发布阶段的会话格式固定为 `SESSION_FORMAT_VERSION = 0` 并吸收形状变动，遵循 AGENTS.md 的预发布立场）。坦率地说：仅追加 + 刷写对部分尾部写入是健壮的（加载时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是后续更强的选项。
+
+## 后果
+
+新增两个包（package），以及 `dsh-session` 中的元数据 seam（`session.header`，`create(id?, options?)` 签名）。收益：持久恢复/fork、读取/回放路径、崩溃容忍，以及 ACP `session/load`（[ACP 支持](../feature/2026-06-14-acp-agent-client-protocol.md)）所需的基础——全部基于现有的事件溯源日志，后端在一个接口之后可替换。可复用的 `runPersistenceContract` 测试套件以相同的仅追加、连续 seq、惰性物化、整数元数据与可序列化语义约束每个后端。持久化完整日志还确定了事件保真度：`assistant/chunk` 保持逐字节不变。SQLite 初始化要么提交完整的自有 schema 与 header 标识，要么不留下任何会使下次打开受阻的部分 schema。
diff --git a/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.i18n.yaml
new file mode 100644
index 0000000000..46cb7aaa20
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-15-turn-enclosure-invariant.md: 6e2abd1716f8efc08c06d5ff8faec38282f2a17f
+2026-06-15-turn-enclosure-invariant.zh.md: 0921c2574dc171e887664d8a2ea840a4e81f1531
diff --git a/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md b/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md
index 00352b01c4..6e2abd1716 100644
--- a/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md
+++ b/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-15-turn-enclosure-invariant.zh.md)
+
 ## Problem
 
 A durable session-persistence backend (added in a companion change) uses the **turn** as its crash-recovery boundary: a crash can leave an unclosed final turn, which `load` closes with a synthetic `turn/end {kind:'interrupted'}` while preserving the turn's real events (see [session persistence](2026-06-14-session-persistence.md)). This recovery is only well-defined if nothing *legitimately* durable sits OUTSIDE a turn — between the last `turn/end` and the next `turn/start` — since such an event would be swept into the next turn's interrupted close.
diff --git a/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.zh.md b/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.zh.md
new file mode 100644
index 0000000000..0921c2574d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: 每个会话事件都封闭在一个轮次内
+
+Status: implemented
+
+[English](2026-06-15-turn-enclosure-invariant.md) | 中文
+
+## 问题
+
+持久化的会话持久化后端（在配套变更中引入）以**轮次**作为崩溃恢复边界：崩溃可能留下一个未关闭的最终轮次，`load` 会用一个合成的 `turn/end {kind:'interrupted'}` 将其关闭，同时保留该轮次的真实事件（见[会话持久化](2026-06-14-session-persistence.md)）。这种恢复只有在没有任何*合法的*持久事件位于轮次之外（即上一个 `turn/end` 与下一个 `turn/start` 之间的间隙）时才是良定义的，否则这类事件会被卷入下一个轮次的中断关闭中。
+
+这一假设并不成立。有两条路径在任何轮次之外记录了事件：
+
+1. **排队的用户消息。** agent loop（智能体循环）排空排队消息并在 `turn/start` *之前*追加 `user/message`——于是一个轮次自身的提示词落在了前一个 `turn/end` 与下一个 `turn/start` 之间的间隙中。
+2. **空闲时的上下文注入。** `agent.inject()` 直接追加一条 `context/message`。它在生产环境中的真实调用方是 `dsh-tool-bash`，后者从 `ctx.bash.onTaskDone` 注入后台任务完成通知——该回调在后台 bash 任务完成时触发，而这经常发生在 agent **空闲**（轮次之间）时。
+
+在情况 2 中，如果注入的 `context/message` 是 flush/dispose 之前的最后一个事件（之后没有轮次追加 `turn/end`），`scanLog` 会将其视为崩溃残留并在**恢复时丢弃**——注入的上下文已持久写入磁盘，但重新加载后被静默丢失。情况 1 本身无害（`user/message` 之后总会跟着它触发的轮次），但使「什么可以出现在轮次之外」这条规则变得模糊。
+
+## 决策
+
+**每个会话事件都位于一个轮次内部**：在 `turn/start` 与其匹配的 `turn/end` 之间。具体而言：
+
+- agent loop 在 `turn/start` **之后**（轮次内部）追加排队的 `user/message` 事件，而非之前。因此，一旦这些消息被记录，就欠下一个 `turn/end`，既有的 finalizer 保证它被写入。
+- agent **运行中**调用 `agent.inject()` 时，它会加入已打开的轮次。当前步骤执行 assistant 工具调用期间，已接受的上下文按到达顺序等待该批次结算，随后在每个已记录结果之后追加；即使执行中断，也会在轮次关闭前写入。
+- agent **空闲时**调用 `agent.inject()`，则将 `context/message` 包裹在一个一次性轮次中：`turn/start{trigger:{kind:'injection'}}` → `context/message` → `turn/end{completed}`。一个新的 `injection` 变体加入可合并扩展的 `TurnTriggerMap`。
+- agent loop 每次迭代从日志推导下一个轮次编号（`lastTurnNumber(session) + 1`），而不是维护一个私有计数器，这样空闲注入的一次性轮次不会与下一个真实轮次的编号冲突。
+- `dsh-session/invariant` companion 将该检查注册到 `ctx.invariants`：选中后，在没有打开轮次的情况下追加 `user/message` / `context/message` / `steering/message` 会抛出归因于 `@deepseek-ai/dsh-session` 的 `InvariantError`。
+
+可序列化性不变式在同一源码边界处强制执行（`Session.append` 对不可 JSON 序列化的数据抛出异常），因此「什么可以进入日志」现在由一个位置统一管控，而非由下游碰巧在监听的某个后端各自发现。
+
+## 曾考虑的替代方案
+
+**放宽读取端而非约束生产端**——让 `scanLog` 提交位于已打开轮次之外的事件。否决：一条单一、可检查的生产端规则优于一个更宽松的边界扫描（后者需要同时推理部分轮次*和*轮次间的散落事件）。
+
+## 后果
+
+轮次现在是*唯一的*持久性/回放边界，因此[会话持久化](2026-06-14-session-persistence.md)的崩溃恢复规则是完备的，而不仅仅是充分的：被中断的最终轮次被关闭（用合成的 `turn/end {interrupted}`），其真实事件得以保留，且零风险将轮次间上下文混入其中，因为不存在轮次间上下文。`scanLog` 保持简洁（最多一个可能未关闭的最终轮次，绝无散落的轮次间事件），空闲时的后台任务通知在持久化 + 恢复后依然存活。
+
+代价：空闲时调用 `agent.inject()` 现在写入三行日志而非一行；派生的历史中多出一个仅包含注入上下文（无 assistant 输出）的轮次——`deriveMessages()` 已经纯粹按事件类型派生，因此渲染结果完全相同。`injection` 触发器是一个新的磁盘词汇值；与每次 `SessionEventMap`/`TurnTriggerMap` 的新增一样，它属于冻结格式的一部分。轮次内的事件顺序发生了变化（`turn/start` 现在先于 `user/message`），这对任何断言旧顺序的代码可观测——agent loop 自身的测试是唯一的此类消费方。
+
+该规则有意采用生产端强制、开发环境检查的方式，而非读取端容忍的方式：未来的后端（SQLite/WAL）无需额外工作即可继承同样干净的边界，而在轮次外记录事件的插件会在开发环境中大声失败，而非在下次重新加载时静默丢失数据。
+
+轮次内检测到的失败在 `turn/end` 之前记录。后续的 flush 失败没有有效的轮次内位置，因此通过 `agent/error` 和日志报告，而非作为会话事件追加。这保持了回放日志的平衡；持久化的运维诊断需要一个独立的遥测通道。
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
new file mode 100644
index 0000000000..6f85d08fe8
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-17-filesystem-capability-seam.md: 08e8d52b314eb10e2c7ec444dd61a96d8621e032
+2026-06-17-filesystem-capability-seam.zh.md: 6f4889234516ee134c9873781a874b5f1a3644ac
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 e76ca22e2d..08e8d52b31 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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.
@@ -122,7 +124,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 the returned `ContentBlock[]`. 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 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.
 
 The defensive-pattern classes this repo has been bitten by are pinned directly:
 
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
new file mode 100644
index 0000000000..6f48892345
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -0,0 +1,160 @@
+# Agent Note: 文件系统能力 seam——ctx.fs、本地后端与面向模型的文件系统工具
+
+Status: implemented
+
+[English](2026-06-17-filesystem-capability-seam.md) | 中文
+
+## 问题
+
+harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`），但文件系统操作即将作为面向模型的工具加入，却没有等价的 seam。如果 `read`、`write` 和 `edit` 直接使用 `node:fs`，面向模型的工具包将同时承担文件系统执行策略、本地路径解析、原子写入行为、文本解码、符号链接行为和编辑语义。
+
+这把三个独立变化的关注点耦合在了一起：
+
+1. 文件系统契约：插件可以请求哪些操作。
+2. 后端：当前是本地磁盘，未来可能是沙箱/远程/项目作用域的文件系统。
+3. 消费方接口：面向模型的 `read` / `write` / `edit` schema 与结果格式化。
+
+如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的契约应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
+
+我们需要文件系统工具在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
+
+## 决策
+
+文件系统访问是一个一等的能力 seam，遵循[能力 seam Agent Note](2026-06-13-capability-seams.md)：
+
+1. `@deepseek-ai/dsh-fs`（`packages/fs/fs`）拥有抽象的 `ctx.fs` 服务、文件系统词汇类型，以及 `fs/*` 策略事件词汇。
+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 或面向模型的提示词引导。
+
+读后写/编辑与观测状态策略是第四个包 `@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) 做出。本文已更新为描述最终落地的四包形态。
+
+第一个后端有意仅限本地：`dsh-fs-local` 基于宿主文件系统实现 `ctx.fs`。未来的兄弟后端可在同一接口之后提供沙箱、远程、虚拟或项目作用域的文件系统。
+
+第一个消费方有意仅限文本文件：`dsh-tool-fs` 暴露面向模型的 `read`、`write` 和 `edit` 工具，处理 UTF-8 文本文件。未来的消费方可以添加目录列表、搜索/glob、二进制安全操作、文件监视或更高层的项目操作，只要 `ctx.fs` 上存在所需能力，就无需改动本地后端包。直接目录列表后来由[为文件系统 seam 添加直接目录列举能力](2026-07-03-filesystem-directory-listing-seam.md)添加。
+
+文件系统权限和沙箱并非此拆分所隐含。本地后端从其配置的基目录解析相对路径，但隔离策略是独立的决策：要么由更严格的 `ctx.fs` 实现强制执行，要么由权限/沙箱插件包装 `tools/execute` 并在调用到达消费方之前否决。
+
+读后写/编辑与观测状态属于 `dsh-fs-policy`，而非 `ctx.fs`。通过 `fs/*` 事件门控，策略按不透明 actor 记录版本，并提供可选的变更期望；提供方原子性地强制新鲜度。`dsh-tool-fs` 发出事件但不依赖策略。见[拆分文件系统 seam](../simplification/2026-06-26-fsspec-style-fs-seam.md)和[事件门控插件](2026-06-26-file-context-as-event-gate.md) Agent Note。
+
+## 包拓扑
+
+文件系统 seam 使用与 bash 三件套相同的依赖方向：
+
+```text
+@deepseek-ai/dsh-tool-fs  --depends on-->  @deepseek-ai/dsh-fs  <--depends on--  @deepseek-ai/dsh-fs-local
+        consumer                                interface                         implementation
+```
+
+`@deepseek-ai/dsh-fs` 仅依赖 `cordis` 加上来自 `@deepseek-ai/dsh-llm` 的仓库级 `HarnessError` 基类。它声明 `ctx.fs` 键、抽象 `FileSystem` 服务、后端和消费方共享的词汇类型、文件系统错误词汇，以及 `fs/*` 策略事件词汇。它不持有观测状态存储，也不持有 owner 推导形态；事件传递一个不透明的 `object` actor，提供方从不读取它，`dsh-fs-policy` 插件在这些事件之上拥有 owner 推导形态和观测状态存储。
+
+`@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` 中。
+
+根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入实现包。
+
+## `ctx.fs` 契约
+
+`@deepseek-ai/dsh-fs` 拥有一个语义文件系统服务。它比 `readFile` / `writeFile` 更高层，这样 `tool-fs` 就不必重新实现路径解析、版本管理、文本解码、二进制拒绝、分页、原子替换、符号链接行为或字面编辑语义。
+
+该接口涵盖以下语义操作：
+
+- 将模型/插件提供的路径解析为后端定义的目标。
+- 获取目标元数据而不读取文件内容。
+- 从目标读取有界的 UTF-8 文本页。
+- 创建或替换一个 UTF-8 文本文件。
+- 通过字面替换编辑一个已有的 UTF-8 文本文件。
+
+提供方 seam 还携带策略所依赖的新鲜度钩子——但观测状态存储和 owner 推导位于 `dsh-fs-policy` 插件中，而非 `ctx.fs` 上：
+
+- 后端为每个目标铸造一个不透明的 `version` 令牌（在 `stat` 以及每次读取/变更结果中）。
+- `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 将其替换为此处描述的基于新鲜度的策略插件。）
+
+路径解析是显式的，允许异步。本地解析可能只做路径规范化，但沙箱/远程/项目作用域的后端可能需要 I/O 才能将用户提供的路径解析为稳定的目标标识。
+
+解析后的目标必须至少暴露三个概念：
+
+- 原始输入路径，用于诊断。
+- 不透明的 `targetKey`，用于陈旧守护和文件状态查找。本地后端可能使用类似 realpath 的键；远程后端可能使用工作区 URI 或文件 id。消费方禁止解析或假设它是本地绝对路径。
+- `displayPath`，用于面向模型/UI 的输出。根据后端不同，它可能是本地绝对路径、工作区相对路径或远程 URI。
+
+读取和变更结果必须包含不透明的文件 `version`。本地后端从 bigint stat 元数据（`dev`、`ino`、`size`、`mtimeNs` 和 `ctimeNs`）派生令牌，因此同大小重写和 inode 替换都会可靠地使消费方失效；远程后端可以使用 revision id 或类似 hash 的令牌。`dsh-fs-policy` 插件记录版本用于陈旧检查；消费方可以展示相关元数据但禁止解释版本令牌。
+
+提供方返回已解码的文本：`readText` 返回整个常规文本文件，`streamText` 为大文件流式传输相同的文本语义。两者负责常规文件检查；有界的行/输出处理不是它们的职责——行窗口化、带行号渲染和总行数统计位于执行器（`dsh-tool-fs`）中，执行器通过 `ctx.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 的观测状态选择提供哪个期望。
+
+字面编辑是提供方原语（`editText`），而非在 `tool-fs` 中由读取加写入组合而成。字面匹配、重复匹配拒绝、CRLF 保留、二进制拒绝、可选的陈旧版本检查和原子读-改-写必须一起留在后端的变更临界区内。`editText` 接受相同的可选版本期望；陈旧检查在字面匹配之前运行，因此基于旧读取的编辑会报 `FS_STALE_VERSION`。远程后端可以将编辑实现为原生的 compare-and-edit 操作；消费方不强制本地风格的组合。
+
+策略插件（而非 `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 添加直接目录列举能力](2026-07-03-filesystem-directory-listing-seam.md)添加。）
+
+## 工具消费方行为
+
+`@deepseek-ai/dsh-tool-fs` 是面向模型的消费方。它拥有工具名称、JSON Schema、模型边界的参数校验、提示词段落和结果格式化。它不拥有文件系统执行。
+
+第一个工具套件包含：
+
+- `read`：检查一个 UTF-8 文本文件并返回带行号的内容与分页引导。
+- `write`：创建或完全替换一个 UTF-8 文本文件。
+- `edit`：通过替换字面文本更新一个已有的 UTF-8 文本文件，默认要求唯一匹配，并允许显式的全部替换模式。
+
+每个工具遵循相同的执行形态：
+
+1. 校验并规范化模型参数。
+2. 调用相应的 `ctx.fs` 操作。
+3. 将结果格式化为面向模型的 `ContentBlock[]`。
+4. 让抛出的后端/工具错误流经 `ToolRegistry.execute()`，由其转换为 `isError` 工具结果。
+
+该包通过 `ctx.systemPrompt.section(...)` 注册提示词引导，通过 `ctx.tools.register(...)` 注册 schema。工具 schema 仍通过 `SystemPrompt.assemble()` 和 `ToolRegistry.schemas()` 流入正常的提示词组装路径；无需改动 agent loop（智能体循环）。
+
+工具包在后端变化时保持面向模型的契约稳定：本地后端和远程后端内部可能以不同方式解析路径，但 `read` / `write` / `edit` schema 不会仅因后端变化而改变。
+
+默认部署要求在用 `write` 或 `edit` 更新已有文件之前先 `read`。`tool-fs` 不通过检查是否运行过名为 `read` 的工具来实现这一点：它分发 `fs/write-intent`/`fs/edit-intent` 事件（将执行上下文作为不透明 actor 传递），`dsh-fs-policy` 插件推导 owner、对先前观测进行门控并提供版本期望。任何窗口化读取都能授权后续的写入/编辑，只要文件未变。用 `write` 创建新文件不要求先前观测。
+
+根插件通过组合各工具的注册辅助函数来注册完整套件。它注入 `fs`、`tools` 和 `systemPrompt`。
+
+## 测试
+
+测试遵循包边界，而不仅是用户可见的工具：`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` 目录中的独占 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` 提供方；后续的提供方以无继承状态启动。
+
+## 曾考虑的替代方案
+
+- **面向模型的工具直接基于 `node:fs`**：工具包将同时承担执行策略、路径解析、原子写入、文本解码和编辑语义，耦合问题部分所列的三个独立变化的关注点，且任何后端替换都会搅动 schema。
+- **单一合并包 `dsh-fs-tools`**：seam 之前的形态；以与 bash 相同的接口/实现/消费方拆分理由否决，且合并名称从未成为公开接口。
+- **观测状态放在 `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) 取代：沙箱/远程后端不应继承面向模型的观测策略，因此提供方只保留版本令牌和可选的版本守护变更。
+
+## 后果
+
+**`cwd` 可能被误认为沙箱。** 本地后端的基目录是解析默认值，而非自动的隔离边界。如果需要隔离，必须由后端契约或 `tools/execute` 上的权限/沙箱插件强制执行。
+
+**接口可能变得过于本地化。** 如果 `ctx.fs` 返回 `absolutePath` 之类的字段，远程、沙箱或虚拟后端会变得尴尬。契约应暴露显示元数据，而不要求消费方理解宿主路径。
+
+**接口可能变得过于薄。** 如果 `ctx.fs` 只镜像 `node:fs` 原语，`tool-fs` 将重新实现二进制检测、分页、原子写入和编辑语义，重新制造本 Agent Note 试图避免的耦合。
+
+**编辑语义天然易受竞争影响。** 字面编辑是读-改-写操作；守护手段是后端的原子变更临界区加上可选的版本期望，因此并发编辑确定性地收敛——一个赢，另一个得到 `FS_STALE_VERSION`。
+
+**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方 seam 只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
+
+**`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测契约不变。
+
+**观测状态持久化被推迟。** 观测状态存在于内存中（`dsh-fs-policy` 内部的 `WeakMap`），因此恢复的会话保守地要求文件在写入/编辑前重新读取，直到未来的会话事件或持久化机制使观测可回放。
+
+**错误码成为 seam 的一部分。** `FsError` 错误码使陈旧版本和观测失败可通过既有的结构化错误分类体系进行机器路由。代价是 `dsh-fs` 从 `dsh-llm` 导入共享的 `HarnessError` 基类；该依赖是有意为之且限于错误词汇。
+
+**包拆分的成本前置。** 三包拆分在只有一个后端时就增加了样板代码。这是有意为之：文件系统访问是可能的沙箱/远程边界，在面向模型的工具发布后再改包接口代价更高。
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
new file mode 100644
index 0000000000..8c6edb72a9
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-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
+2026-06-18-agent-lifecycle-and-ownership-seams.md: 70ebf1c6de97cb14e27377ec1f9bac18fc0766a6
+2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: 54d174aa325384f7c7492f072f10954f0b1d08c9
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-seams.md
index 3d84c8074b..70ebf1c6de 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-seams.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-18-agent-lifecycle-and-ownership-seams.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.
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
new file mode 100644
index 0000000000..54d174aa32
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
@@ -0,0 +1,50 @@
+# Agent Note: Agent 生命周期与所有权 seam
+
+Status: implemented
+
+[English](2026-06-18-agent-lifecycle-and-ownership-seams.md) | 中文
+
+## 问题
+
+ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 seam 的症状：插件可以通过 `ctx.agents` 创建或恢复 agent（智能体），但无法独立拥有和 dispose（资源释放）单个 agent，而长时间运行的 bash 任务在执行器中也没有稳定的所有者。ACP 在断连时中止并等待 agent，却无法仅注销该会话的 agent；`session/cancel` 无法取消已入队但尚未开始的工作；`tool-bash` 将任务所有权保存在插件本地的 `Map` 中，因此一次 HMR（热模块替换）重载就可能让旧任务看起来无主。
+
+## 决策
+
+三个 seam：队列感知的取消、`AgentHandle` 释放器，以及 bash 所有者令牌。
+
+### 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 生命周期与协作式结算契约。
+
+### 2. `AgentHandle` 异步释放器
+
+`ctx.agents.create`/`resume`（以及 `AgentFactory` 接口）返回 `AgentHandle = { agent: Agent; dispose(): Promise<void> }`。释放器是一种**消费方能力**——仅持有裸 `Agent` 的注册表观察者无法将其拆除。调用方 fiber 和已注册的 factory 提供方是结构上的共同所有者：调用方卸载强制结构化所有权，而提供方卸载必须停止旧实例，因为其实例作用域的依赖 surface 通过该提供方解析。三条路径都会进入同一个 memoize 的拆除过程：停止循环、等待其退出与空闲刷写完成（完全停稳，而非仅把状态翻转为 `disposed`）、分离 agent、分离其会话，然后解除其 scope。每个公开 ID 在其精确注册表条目分离时变得可复用；不存在独立的保留释放阶段。由配置创建的 agent 已归 `AgentLoop` fiber 所有（handle 被丢弃）。ACP 在其 `SessionRecord` 中保存每个会话的释放器，并在断连/拆除时运行它，因此单纯的客户端断连不会留下已注册 agent 或会话存储条目——即使 `session/load` 与拆除竞争（刚恢复的 handle 会在 closed-guard 抛出前释放）。
+
+**拆除顺序对持久性至关重要**，实现将会话生命周期折叠进 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 中的所有者令牌
+
+后台任务所有权从 `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 影响。）
+
+## 验证
+
+以下不变式已经成立，并由测试固定：
+
+- ACP 断连/会话关闭后，不留下该会话的任何已注册 agent 或会话存储条目，即使 `session/load` 与拆除竞争。
+- 已入队的提示词启动前执行 `session/cancel`，能阻止该提示词运行；后来接受的提示词仍是独立的已入队轮次。
+- `tool-bash` HMR 重载不会使另一个会话能够读取或终止已有的后台任务（所有权保留在执行器上）。
+- 既有的非 ACP 演示无需显式管理 handle 仍能工作；由配置创建的 agent 仍归 `AgentLoop` 插件 fiber 所有。
+
+## 会话所有者令牌在存活 agent 中唯一
+
+bash 所有者 token 比较依赖共享的 `Agent.id`/`SessionId` 在存活 agent 中唯一。并发的同 ID 操作可以都私下准备，但发布会依次进入会话和 agent；`SessionStore.enter()` 拒绝重复的存活会话 id，每个失败事务都回滚自己的私有状态。因此程序化调用方无法发布两个共享同一会话 token 的存活 agent。访问*策略*（token 比较）留在消费方 `tool-bash`；bash seam 只存储不透明的 `owner` 字符串且从不解释它——这是正确的接口/实现/消费方拆分。
+
+## 曾考虑的替代方案
+
+- **公开的 `BashTask.owner` 字段**而非 `BashExecutor.ownerOf(id)` seam：否决。一条读取路径即可，无需冗余 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)）。
+
+## 后果
+
+本变更有意触及公开接口（`Agent`、`AgentFactory`、bash seam），而非作为 ACP 的局部补丁。同步 `Agent.send()` 的简洁易用性得以保留；异步生命周期路径是增量添加的，供需要它的所有者使用。
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
new file mode 100644
index 0000000000..4946fc219a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-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
+2026-06-18-session-surface.md: 80034881d0112076759a68737b5931c8ff659d15
+2026-06-18-session-surface.zh.md: 26a3119faf0b6988049a7599ea9551a8ae65d63d
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 f1297b1f05..80034881d0 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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()`.
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
new file mode 100644
index 0000000000..26a3119faf
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -0,0 +1,73 @@
+# Agent Note: 会话 surface：事件日志上的有序投影
+
+Status: implemented
+
+[English](2026-06-18-session-surface.md) | 中文
+
+## 问题
+
+事件日志是权威数据源，但历史操纵此前没有持久化的共享机制。如果没有这样的机制，上下文压缩（context compaction）等插件只能通过顺序敏感的监听器改写派生请求，不留溯源信息，且每次新增操纵都要反复修改 `deriveMessages()`。
+
+## 决策
+
+新增一个 **surface**：事件 seq 的派生、缓存有序投影（即产出 LLM（大语言模型）消息的事件子集），通过事件日志中的 `surfaceOp` 标记维护。
+
+### `SessionEvent` 新增两个顶层字段
+
+每个 `SessionEvent` 获得两个可选字段（结构性元数据，与 `seq`/`time` 同级）：
+
+- **`sourceEventSeqs?: number[]`**：作为溯源来源的事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；在该事件上省略字段表示旧数据或未记录的溯源。其他 surface 事件一旦出现此字段，就必须是非空列表。溯源是核心设计原则；没有它，replace-range 操作在回放时无法被验证。
+- **`surfaceOp?: SurfaceOp`**：该事件如何进入 surface。非 surface 事件不携带此字段。
+
+### SurfaceOp：两种操作
+
+```ts
+export type SurfaceOp =
+  | 'append'                                    // normal tail append
+  | { op: 'replace'; start: number; end: number }  // shadow [start, end] inclusive
+```
+
+1. **Append**：在尾部追加新事件的 seq。`user/message`、`assistant/message`、`tool/result`、`context/message`、`steering/message` 使用此操作。agent loop（智能体循环）在所有此类追加上传入 `surfaceOp: 'append'`，并在适用时记录 `sourceEventSeqs`：每个成功的 `assistant/message` 都记录完整的 `assistant/chunk` 来源集合（包括 `[]`），而 `tool/result` 记录其 `tool/call` 来源。
+
+2. **Replace**：移除从 `start` 到 `end`（两端包含）的条目，并在其位置插入新事件的 seq。`start` 和 `end` 都必须存在于当前 surface；`start === end` 表示替换单个条目。该事件的 `sourceEventSeqs` 必须包含所有被遮蔽的 surface seq。被遮蔽的事件仍留在日志中，但不再出现在 surface 上。
+
+### SurfaceManager：基于增量，而非全量重建
+
+一个 `Session` 拥有一个 `SurfaceManager`，后者维护事件 seq 的有序 `number[]`。管理器会在提交前校验每个种子或追加候选项而不应用它，然后只处理上次同步之后已经提交的事件，而不重新扫描整个日志。`Session.surface` 通过只读的 `SessionSurface` 契约暴露同一个管理器，因此接纳、派生历史、压缩与工作区上下文共享同一份增量状态。Replace 按数组位置找到两端都包含的端点，并把替换 seq splice 到该范围；不会用第二个管理器、链接对象或 seq 到节点的 map 来重复表达顺序。
+
+无新事件时增量处理为 O(1)，有新事件到达时为 O(新事件数)。
+
+`deriveMessages()` 在存在 surface 标记时使用 surface，对没有标记的会话回退到既有的线性扫描（向后兼容）。
+
+### 持久化
+
+新字段作为顶层 JSON 属性序列化。JSONL 后端无需任何改动：`JSON.stringify`/`JSON.parse` 透明地保留一切。SQLite 后端的 `events` 表新增两个可空 TEXT 列（`source_event_seqs`、`surface_op`）。磁盘上的 `SCHEMA_VERSION` 递增以反映列集变化，并且按照预发布的 bump-and-reject 策略，由其他构建写入的数据库在打开时被拒绝而非迁移（没有需要升级的持久化用户数据）。会话格式 `version` 固定为 `SESSION_FORMAT_VERSION = 0`（「不稳定/预发布」立场）：可选的 surface 字段被吸收而不递增版本号。
+
+### 崩溃恢复
+
+`repair.ts` 模块在崩溃后为孤立的工具调用合成 `tool/result` 闭合事件。这些闭合事件携带 `surfaceOp: 'append'` 和指向孤立 `tool/call` 事件的 `sourceEventSeqs`，确保重建的 surface 有效。
+
+### 不变式
+
+`Session` 在始终启用的 seed/append 边界校验 `sourceEventSeqs` 与 `surfaceOp`：只有 `assistant/message` 可以使用空的溯源列表；引用必须唯一、更早且已知；替换端点必须存在于 surface 顺序中；溯源必须覆盖每个被遮蔽的节点。这些是单记录接纳与存储投影规则，不是可选的不变式服务贡献。
+
+每个 surface 可达事件都必须携带 `surfaceOp`，否则它将从派生历史中消失。类型化的 `append` 重载对字面事件类型强制执行此规则；`append` 和种子构造函数中的运行时检查覆盖宽化联合类型和加载的日志。按照预发布格式策略，无效的种子被拒绝而非升级。
+
+## 曾考虑的替代方案
+
+- **逐插件的 `agent/request` 包装**（surface 之前的历史操纵模式）：监听器排序脆弱、无法持久记录改动内容，且每种新操纵都迫使核心 `deriveMessages()` 再次修改。
+- **半开区间 `[start, endExclusive)` 的 replace 范围**：否决。端点由 surface 事件 seq 命名，单条目替换（`start === end`）在闭区间语义下读起来更自然。
+- **链接节点对象加 seq map**：否决。生产代码不读取前驱链接，唯一的后继用途就是数组中的下一个位置，而替换本来就需要线性 `indexOf` 查找。单个 seq 数组在保留相同渐进复杂度的同时，只留下一个需要校验的表示。
+- **脏标记后全量重建**替代增量处理：在会话生命周期内为 O(N²)，每次单事件追加都要重新扫描所有先前事件。
+
+## 后果
+
+- **`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`**：抽象接口不变。
+
+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 接纳会与位置范围和溯源校验一起强制这条规则，不依赖可选的诊断插件。
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
new file mode 100644
index 0000000000..b289d47edd
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-18-shared-persistence-write-coordinator.md: ea9c4fb74f7c1bd68fb62efedd3e1657da96ea65
+2026-06-18-shared-persistence-write-coordinator.zh.md: 3b4dd7b762c2f39a908eabe23e5d734981b5767b
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 27360087a2..ea9c4fb74f 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
@@ -2,25 +2,28 @@
 
 Status: implemented
 
+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 buffers, serialized flush chains, 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. A code-level diff showed the two backends were byte-identical — or same-algorithm — for ALL of it: the four maps (`states`/`buffers`/`chains`/`inits`), `installWritePath`, `initFor`, `onCreated`'s four cases, `flush`, `drain`, `serialize`, `adopt`, `adoptLivePrefix`, `assertVersion`, and the `create`/`append`/`load` skeletons. 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 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.
 
 ## Decision
 
-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 four public service methods (`create`/`append`/`load`/`list`) to it.
+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`/`load`/`inspect`) 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; it cannot reach the coordinator's private orchestration state, and the public `SessionPersistence` service shape is unchanged, so a third-party backend MAY still implement the abstract service directly without the coordinator at all.
+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 the non-mutating `inspect` contract used by read models.
 
-The coordinator retires each live session from its `session/disposed` notification: it waits for that exact Session object's initialization, serializes a final drain, and then removes the owned state, buffer, and init entries. Failed drains retain their buffers for backend teardown to retry. Settled per-id chain tails remove themselves only when they are still the current tail, so a completion cannot erase a newer operation for the same id. Backend teardown unregisters the write-path listeners before awaiting all admitted retirements, remaining buffers, and chains, then closes the backend.
+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 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.
 
 ### The hook interface (`PersistenceBackend<TornMarker>`)
 
-Six methods (five required + an optional lifecycle hook) — the only seam between the coordinator and storage:
+Five required members plus an optional lifecycle hook form the only boundary between the coordinator and storage:
 
 - `name` — backend label for the dispose-failure `AggregateError`.
-- `loadStored(id)` — read a stored prefix by id, scanning ANY storage scope (every JSONL cwd bucket; SQLite's id is globally unique). Used by resume/load and, via `!== undefined`, the create-collision probe.
-- `loadLive(id, cwd)` — read a stored prefix SCOPED to `cwd`. **Deliberately distinct from `loadStored`**: HMR live-adoption must only adopt a persisted log at the SAME cwd as the live session; a same-id log at a different cwd is a collision, not a resume. Collapsing the two reintroduces a cross-cwd adoption bug. SQLite ignores `cwd`.
+- `loadStored(id)` — read one stored prefix by id across every storage scope (every JSONL cwd bucket; SQLite's id is globally unique). Resume/load, non-mutating inspection, live adoption, and the create-collision probe share this lookup. The coordinator asserts the returned id and rejects a stored/live cwd mismatch before repair or state publication.
 - `appendBatch(meta, events, isMaterialized)` — durably append a contiguous batch, lazily materializing the session ATOMICALLY when not yet materialized (the materialize-write and the first event batch must commit together — a crash between them must not leave a materialized-but-empty session; this is why there is no separate `materialize` hook).
 - `commitRepair(meta, tornMarker, closers)` — make a crash repair durable: truncate the torn tail (iff `tornMarker !== undefined`) and append `closers`. **NOT required to be atomic** — JSONL legitimately truncates-then-appends in two fsync'd steps, SQLite does DELETE+INSERT in one transaction. Used by `load` (truncate + synthetic closers) and live-adoption (truncate only, `closers = []`).
 - `list()` — list all stored metadata.
@@ -32,13 +35,13 @@ The single design choice that keeps the seam clean: the crash-repair "where is t
 
 ## Testing
 
-The shared `runPersistenceContract` (public-API contract) keeps running for every backend. `runCoordinatorContract` (`tests/coordinator-contract.ts`) holds the write-path orchestration — adoption, HMR, collision, session and backend disposal drains, and crash-tail repair — and runs once per backend through a `CoordinatorFixture` (an in-memory reference + jsonl + sqlite). Coordinator-specific tests pin retirement map cleanup, same-id chain-tail races, failed-drain retry, and close ordering. The per-backend specs retain storage mechanics only (JSONL: path safety, fsync rollback, bucket listing; SQLite: schema version, `scanRows`, transaction rollback). A through-coordinator torn-tail→load→`commitRepair` test per real backend (via a `corruptTail` fixture hook) keeps the coordinator's torn-marker repair branch covered under the 100% per-file gate — the contract crash test only produces synthetic closers, never a torn marker, so it could not reach that branch.
+The shared `runPersistenceContract` (public-API contract) runs for every backend and proves that `inspect` leaves interrupted logs and revisions unchanged before `load` performs 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. Coordinator-specific tests cover 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.
 
 ## Alternatives considered
 
 - **A base class the backends extend** — rejected for composition: a backend exposes only the hooks, cannot reach the coordinator's private orchestration state, and a third-party backend may still implement the abstract service directly without the coordinator at all.
-- **A wider hook surface** — each candidate hook folded away: there is no separate `materialize` hook (the materialize-write must commit atomically with the first event batch inside `appendBatch`), no separate create-collision probe (it is `loadStored(id) !== undefined`), and no coordinator pass-through for `list()` (listing needs none of the orchestration).
+- **A wider hook surface** — each candidate hook folds away: there is no scope-specific live lookup because `loadStored` plus the coordinator's cwd check preserves the collision boundary, no storage-locator generic because validated JSONL metadata reproduces its path while SQLite is already id-bound, no separate `materialize` hook because the first batch must commit atomically with materialization, no separate create-collision probe because it is `loadStored(id) !== undefined`, and no coordinator pass-through for `list()` because listing needs none of the orchestration.
 
 ## Consequences
 
-The coordinator adds one indirection, an opaque torn marker, and detached session-retirement tasks, 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 uncommitted buffers, and makes backend teardown the quiescence boundary. Its hook surface stays narrow: collision checks reuse `loadStored`, materialization stays atomic inside `appendBatch`, and listing bypasses the coordinator. New backends implement storage primitives rather than copy the event-buffer-flush lifecycle.
+The coordinator adds one indirection, an opaque torn marker, and detached session-retirement tasks, 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, and non-mutating 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 cannot race a new live owner by committing interruption closers. New backends implement storage primitives rather than copy the eager 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
new file mode 100644
index 0000000000..3b4dd7b762
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -0,0 +1,47 @@
+# Agent Note: 共享持久化写入协调器
+
+Status: implemented
+
+[English](2026-06-18-shared-persistence-write-coordinator.md) | 中文
+
+## 问题
+
+`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 契约，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 seam 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
+
+## 决策
+
+将一个后端无关的 `PersistenceCoordinator` 提取到 `dsh-session-persistence` 中。协调器统一拥有编排逻辑；每个第一方后端组合一个协调器实例（`new PersistenceCoordinator(ctx, this)`），实现一个小型 `PersistenceBackend` 钩子接口，并将其有状态的公开方法（`create`/`append`/`load`/`inspect`）委托给协调器。由后端拥有的元数据与修订版本列举会绕过协调器。
+
+组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括供读模型使用、不修改状态的 `inspect` 契约。
+
+协调器为每个确切的存活 `Session` 持有一个控制器；该控制器统合初始化、待处理事件与共享 flush promise。每个 `session/event` 都会立即启动排空，而 `session/flush` 只观察完全停稳，不会发起常规写入路径。[flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义该生命周期。
+
+协调器通过 `session/disposed` 退役会话：它等待控制器完成初始化和当前 flush，串行执行最后一次排空，且仅在成功后才移除控制器与其拥有的每 id 状态。失败时保持控制器可被找到，以供后端 teardown（拆除）重试。每个 id 的已结算链尾仅在其仍是当前链尾时才移除自身，因此旧操作完成后不会抹除同一 id 的新操作。后端 teardown 会注销写入路径监听器、flush 每个剩余的控制器、等待所有按 id 串行化的操作，最后关闭后端。
+
+### 钩子接口（`PersistenceBackend<TornMarker>`）
+
+五个必需成员加一个可选的生命周期钩子，构成协调器与存储之间唯一的边界：
+
+- `name`——后端标签，用于 dispose 失败时的 `AggregateError`。
+- `loadStored(id)`——按 id 跨所有存储范围读取一个已存储前缀（JSONL 的所有 cwd bucket；SQLite 的 id 全局唯一）。恢复/加载、不修改状态的检查、存活会话接管与创建碰撞探测共用此查找。协调器会断言返回的 id，并在修复或发布状态之前拒绝已存储记录与存活会话的 cwd 不匹配。
+- `appendBatch(meta, events, isMaterialized)`——持久追加一个连续批次，在尚未物化时原子地惰性物化会话（物化写入与首批事件必须一起提交——崩溃不得留下一个已物化但为空的会话；这就是为什么没有单独的 `materialize` 钩子）。
+- `commitRepair(meta, tornMarker, closers)`——使崩溃修复持久化：截断损坏的尾部（当且仅当 `tornMarker !== undefined`）并追加 `closers`。**不要求原子性**——JSONL 合理地分两步 fsync（先截断再追加），SQLite 在一个事务中完成 DELETE+INSERT。用于 `load`（截断 + 合成 closers）和 live-adoption（仅截断，`closers = []`）。
+- `list()`——列出所有已存储的元数据。
+- `close?()`——可选的生命周期清理（SQLite 关闭 db 句柄；JSONL 省略），在 dispose effect 中于排空至完全停稳之后被 await，因此 close 失败不会掩盖排空错误。
+
+### 不透明的 torn marker
+
+保持 seam 整洁的唯一设计选择：崩溃修复中「损坏尾部在哪里」的 token 对协调器是不透明的。协调器计算合成 closers（它拥有来自 `dsh-session` 的 `interruptedTurnClosers`），但它只测试 `tornMarker !== undefined` 并将值原样传回 `commitRepair`——从不检视其内容。每个后端选择自己的 marker 类型：JSONL 携带要截断到的字节偏移，以及从不完整最终帧中解码出的任何完整事件；SQLite 则携带要从其开始删除的 seq。协调器因此既不了解字节长度，也不了解帧恢复状态。
+
+## 测试
+
+共享的 `runPersistenceContract`（公开 API 契约）为每个后端运行，并证明在 `load` 执行恢复之前，`inspect` 会保持被中断的日志与修订版本不变。`runCoordinatorContract`（`tests/coordinator-contract.ts`）通过内存参考实现、JSONL 与 SQLite 覆盖接管、HMR、碰撞、会话与后端 dispose 排空，以及崩溃尾部修复。协调器专属测试覆盖立即执行的后续批次、存活控制器清理、同 id 链尾竞态、排空失败重试与关闭顺序。各后端自身的测试规格只保留存储机制。每个真实后端都有一个经由协调器的崩溃尾部修复测试，以覆盖不透明 marker 分支，因为契约中的崩溃用例会产生合成 closers，却不会产生 torn marker。
+
+## 曾考虑的替代方案
+
+- **后端继承的基类**——否决，改用组合：后端只暴露钩子，无法触及协调器的私有编排状态，且第三方后端仍可完全不使用协调器、直接实现抽象服务。
+- **更宽的钩子面**——每个候选钩子都被折叠掉：没有限定存储范围的实时查找，因为 `loadStored` 加上协调器的 cwd 检查即可维持碰撞边界；没有存储定位器泛型，因为经验证的 JSONL 元数据可还原其路径，而 SQLite 已按 id 绑定；没有单独的 `materialize` 钩子，因为首批事件必须与物化原子提交；没有单独的创建碰撞探测，因为它就是 `loadStored(id) !== undefined`；`list()` 也不经由协调器透传，因为列举不需要任何编排。
+
+## 后果
+
+协调器增加了一层间接、一个不透明的 torn marker 和脱离会话生命周期的退役任务，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查与不修改状态的检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时，不会因提交中断 closers 而与新的存活所有者产生竞态。新后端只需实现存储原语，而无需复制立即写入生命周期。
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
new file mode 100644
index 0000000000..35c9875149
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-branded-ids.md: 93bab1d47c793cc4dd1f1d19fa3af22d1721be29
+2026-06-20-branded-ids.zh.md: 6cc8a45717b547614a873d3f13c54c3950484a22
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 e7a3110fce..93bab1d47c 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-branded-ids.zh.md)
+
 ## Problem
 
 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.
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
new file mode 100644
index 0000000000..6cc8a45717
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
@@ -0,0 +1,69 @@
+# Agent Note: 在所有应有之处使用 branded ID
+
+Status: implemented
+
+[English](2026-06-20-branded-ids.md) | 中文
+
+## 问题
+
+harness 使用 `Branded<B> = string & { readonly [BRAND]: B }` 机制，为 `CallId`（`packages/llm/llm/src/brand.ts`）和 agent/会话共享的 `SessionId`（`packages/core/session/src/types.ts`）做 brand 处理；该机制由纯类型包（package） `@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`），所以该混淆可由不受信任的输入触达。
+
+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` 为键）、`ToolPresenter` 的 call-id map、ACP 的会话 id 记录和 loading set，以及持久化协调器。在集合键处丢弃 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）。
+
+- **铸造独立的 `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`。（理由见下一节。）
+
+- **阻止 brand 侵蚀。** 将既有 brand 传播到缺口 2 列出的 `Map` 键类型和公开方法参数中：`Map<SessionId, Session>`、`Map<SessionId, Agent>`、`get(id: SessionId)`、`Map<CallId, …>`、ACP 的 `SessionId` surface、协调器的 `Map<SessionId, …>`。这是 diff 中机械量最大的部分，也是让*既有* brand 在查找处真正发挥作用（而不仅仅标注在结构体字段上）的关键。
+
+示意形状（工厂模式与已有的三个 brand 完全一致）：
+
+```ts ignore-check
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** A background bash task handle (generated `bash-N` by the local executor). */
+export type BashTaskId = Branded<'BashTaskId'>
+export function BashTaskId(id: string): BashTaskId {
+  return id as BashTaskId
+}
+
+/** A bash task's opaque isolation key — the consumer's owner identity, NOT the bash seam's. */
+export type OwnerToken = Branded<'OwnerToken'>
+export function OwnerToken(id: string): OwnerToken {
+  return id as 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 位置），且不引入耦合。
+
+## 不在范围内 / 可能的扩展
+
+遵循「不是每个 string 都需要 brand」的策略，刻意保持窄范围。以下每项都是合理的未来 brand 候选，附带推迟理由而非承诺：
+
+- **`ModelId`**（`GenerateOptions.model`，`LlmService` 适配器注册表的键）：一个真正的跨包查找键（config → agent → llm → 适配器）；合理的下一个 brand，仅为控制本 Agent Note 的影响范围而暂不纳入。
+- **`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 中处理，不应捆绑进这次纯类型变更。
+
+## 验证
+
+已落地的不变式：`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。
+
+## 后果
+
+- **两个接口面的机械性改动。** 传播 brand 涉及 bash seam（接口 + 实现 + 消费方）以及 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-extract-example-app-packages.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.i18n.yaml
new file mode 100644
index 0000000000..35bc3836ff
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-extract-example-app-packages.md: 8e87a7164d9cc4789705b3d8fe83dc4978b4def0
+2026-06-20-extract-example-app-packages.zh.md: bb5bf6a78d749bf2fc0637a48bff4496399a787d
diff --git a/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md b/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md
index 05d72e4e49..8e87a7164d 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-extract-example-app-packages.zh.md)
+
 ## Problem
 
 An example folder is supposed to be *thin* — the variable wiring of a demo, not the demo's machinery. Before this change it was thick. Each example carried a hand-rolled `start.ts` boot bootstrap, an infra preamble (`timer`, and — for the stdio demos — `logger` + `hmr`), nested includes of three shared YAML fragments (`base.yml` / `base-core.yml` / `acp-agent/acp-tail.yml`), and per-example `agent-loop`/persistence/system-prompt config. The actual app — the spine of services every agent needs — was spread across the leaf and those includes.
@@ -24,7 +26,7 @@ Each example is now **mostly an invocation of an app package**, splitting the wi
 
 The proposal listed `hmr` among the interactive app's baked-in front-door cluster. Validating against the code, baking `hmr` into the app package fights Cordis in two ways, so it ships as a **leaf `cordis.yml` entry** instead:
 
-1. `@cordisjs/plugin-hmr` is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader` service, so it can only run in the real `demo:*`/bin subprocess, never in the in-process unit/coverage tier.
+1. `@cordisjs/plugin-hmr` is a Loader-only, subprocess-only dev plugin — it requires the live `loader` service and its internal module access, so it can only run in the real `demo:*`/bin subprocess, never in the in-process unit/coverage tier.
 2. The in-process test tier (vitest) cannot even *import* the vendored `hmr` module (its class-decorator `@Inject` form fails under Vite's transform), so a package whose `apply` statically imported it could never satisfy the per-file 100% coverage gate on its headline function.
 
 Crucially, `hmr` is not a stdout-purity footgun: a stray entry in the ACP config does not corrupt JSON-RPC frames. Every shipped app omits a stdout console logger; the app or protocol driver alone owns stdout.
diff --git a/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.zh.md b/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.zh.md
new file mode 100644
index 0000000000..bb5bf6a78d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.zh.md
@@ -0,0 +1,57 @@
+# Agent Note: 将示例应用提取为独立包
+
+Status: implemented
+
+[English](2026-06-20-extract-example-app-packages.md) | 中文
+
+## 问题
+
+示例目录本应是*精简的*——只包含演示的可变接线，而非演示的基础设施。在此次变更之前，它是臃肿的。每个示例都携带一份手写的 `start.ts` 启动引导、一段基础设施前导（`timer`，以及 stdio 演示所需的 `logger` + `hmr`（热模块替换））、三个共享 YAML 片段的嵌套引用（`base.yml` / `base-core.yml` / `acp-agent/acp-tail.yml`），还有各示例自身的 `agent-loop`/持久化/系统提示词配置。真正的应用——每个 agent（智能体）都需要的服务主干——散落在叶子配置和那些 include 中。
+
+叶子配置还拥有耦合的前门。ACP（Agent Client Protocol）要求 stdout 纯净，并通过 `session/new` 创建 agent；终端应用和 Headless 应用则预创建 `main`，但进程 I/O 契约不同。防止错误组合的唯一屏障是文档中的文字警告，而三个 `start.ts` 文件重复着 Loader 引导和生命周期代码。
+
+## 决策
+
+每个示例现在**主要是对一个应用包（package）的调用**，沿着既有的[接口 / 实现 / 消费方 seam](2026-06-13-capability-seams.md) 拆分接线：**应用包拥有组合**，叶子 `cordis.yml` 只拥有**可替换的选择**（哪个 LLM（大语言模型）适配器、哪个 bash 执行器、模型、提示词、持久化根目录）。
+
+- **`@deepseek-ai/dsh-agent-spine-demo`**（[packages/examples/agent-spine-demo](../../../../packages/examples/agent-spine-demo)）组合了不含提供方、不含执行器、不含 UI 的主干，并转发 agent loop（智能体循环）的 agent 列表配置。它对具体 loop 的依赖是有意为之，因为该包组合的是主干而非扩展主干；替换 loop 意味着提供另一个 bundle。
+- **`@deepseek-ai/dsh-tui-demo`**、**`@deepseek-ai/dsh-cli-demo`** 和 **`@deepseek-ai/dsh-acp-demo`** 各自内置其进程角色。TUI 包含全屏 UI 和预创建的 `main`；Headless 包含 one-shot driver 和预创建的 `main`；ACP 包含 bridge 且不预创建 agent。三者都包含 JSONL 持久化，并省略 stdout logger。
+- **`start.ts` 已移除。** 每个应用包都暴露一个 bin；`demo:*` 脚本调用它。Loader 引导、`.env` 加载和快速失败守卫位于共享的 [`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot) 包（在逐文件覆盖率门禁下有单元测试——见[共享应用 bin 的启动胶水](../simplification/2026-07-04-share-app-bin-boot-glue.md)）；精简的自执行入口由 keyless 的 Loader 路径测试驱动。
+- **每个叶子 `cordis.yml` 精简为**后端、可选产品工具，以及一个承载应用配置的 app 条目。TUI 和 Headless 把模型/会话选择路由到预创建的 agent；ACP 把初始提供方/模型路由到 bridge。
+- **`base.yml`、`base-core.yml` 和 `acp-agent/acp-tail.yml` 已退役**——它们共享的主干现在位于 `dsh-agent-spine-demo` 中。
+
+`bash-local` 和 LLM 适配器仍然是**叶子选择**：bundle 提供 `tool-bash`（消费方 schema），叶子选择执行器实现，因此沙箱执行器或回放适配器无需触碰应用即可替换。
+
+### 实现修正：`hmr` 保留为叶子条目
+
+提案最初将 `hmr` 列入交互式应用内置的前门集群。对照代码验证后发现，将 `hmr` 内置到应用包中会在两个方面与 Cordis 冲突，因此改为作为**叶子 `cordis.yml` 条目**交付：
+
+1. `@cordisjs/plugin-hmr` 是一个仅限 Loader、仅限子进程的开发插件——它需要活跃的 `loader` 服务及其内部模块访问权限，因此只能在真实的 `demo:*`/bin 子进程中运行，不能在进程内的单元/覆盖率测试层运行。
+2. 进程内测试层（vitest）甚至无法*导入* vendor 的 `hmr` 模块（其 class-decorator `@Inject` 形式在 Vite 的 transform 下会失败），因此一个 `apply` 静态导入了它的包永远无法满足其主函数的逐文件 100% 覆盖率门禁。
+
+关键在于，`hmr` 不是 stdout 纯净隐患：ACP 配置中误加该条目不会破坏 JSON-RPC 帧。所有已交付应用都省略 stdout 控制台 logger；stdout 只归应用或协议 driver 所有。
+
+## 曾考虑的替代方案
+
+### 为什么不继续用共享 YAML include 来管理接线？
+
+旧的 `base*.yml`/`acp-tail.yml` include 已经去重了*配置*，但 YAML include 无法**封装**前门耦合——它只能在注释中描述，并信任每个叶子遵守。它也无法拥有 `bin`，因此启动胶水一直在三个 `start.ts` 文件中重复。包将「ACP 应用绝不向 stdout 输出日志」从文字警告变成了产物的属性：叶子中不存在可以写错的 logger 条目。
+
+## 验证
+
+- 示例目录只包含配置、README 和测试：`start.ts`、基础设施前导和共享 YAML include 已移除。
+- `demo:tui`、`demo:headless` 和 `demo:acp` 调用应用包的 bin。
+- 每个新包都有 README 和逐文件 100% 覆盖率；每个应用包还有一个 keyless 的真实 Loader 路径 bin 冒烟测试，用于捕获[事后分析 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) 中描述的导出形状故障。
+- ACP 回放 transcript（文本记录）保持不变，因为插件集合和加载顺序未改变。
+
+## 后果
+
+- **裸插件树的教学性。** 主干现在隐藏在 bundle 之后，查看完整树意味着打开 `dsh-agent-spine-demo`。应用包的 README 承担了这份教学职责。
+- **多了一层间接。**「这个演示加载了什么？」从扫描单个 YAML 变成了阅读一个包。
+
+## 相关
+
+- 取代[使共享示例基础配置与提供方无关](../../rejected/architecture/2026-06-20-providerless-example-base.md)：一旦主干移入 `dsh-agent-spine-demo` 且 `base*.yml` 文件被删除，将 `base.yml` 重命名为无提供方核心便不再有意义。
+- 基于[能力 seam](2026-06-13-capability-seams.md)的接口/实现/消费方拆分——后端和展示层保持为叶子选择；主干是共享 bundle。
+- 与[将包重组为模块化层级结构](2026-06-20-package-hierarchy.md)互补：新的 app/core 包按该层级结构归入既有分组（`core` 放可复用的主干 bundle，`ui` 放应用特有的前门）。
+- 后续的[冗余 agent 移除](../simplification/2026-07-20-remove-stdio-and-echo-agents.md)拥有最终的 TUI/Headless 拆分，并移除行式与仅 mock 的叶子。
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
new file mode 100644
index 0000000000..ec8a2059a2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-generic-long-running-tool-runtime.md: 25668a6a699576e435670b9580385073f2f036fe
+2026-06-20-generic-long-running-tool-runtime.zh.md: 3c214bb4309ea331ae2d4ba73c01df1ded8f40ef
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 4db0d78910..25668a6a69 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-generic-long-running-tool-runtime.zh.md)
+
 ## Problem
 
 Background bash originally combined two responsibilities: the bash executor ran processes and also managed task ids, ownership, incremental reads, cancellation, completion listeners, and model-facing control tools. Adding background subagents required the same lifecycle and interaction contract. Implementing that contract independently for every long-running capability would duplicate isolation, cleanup, notification, and prompt behavior while teaching the model a different collect-and-stop protocol for each producer.
@@ -21,7 +23,11 @@ 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`, 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/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.
+
+`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.
+
+A model-facing producer exposes that committed id in its canonical success value, normally `{ kind: 'background', taskId }`; Native rendering may keep human-readable prose. A pre-aborted background call fails rather than returning a no-op because no task exists to satisfy the promised handle. Once registration publishes the id, cancellation belongs to the task's own controller and the task runtime: later cancellation of the producing tool call must not kill the published task. `task_kill`, owner disposal, and service teardown request cancellation; foreground execution remains coupled to the call's `exec.signal`.
 
 The producer hooks define three responsibilities:
 
@@ -73,11 +79,11 @@ Stream reads share one task-scoped consuming cursor because the owning model is
 
 The system prompt tells the model to retain task ids, continue independent work instead of busy-polling or duplicating a running task, collect relevant tasks before its final answer, and kill work that no longer matters. Completion injects a logged `context/message` into the exact owner's session; it becomes durable context for the next request but does not wake an idle agent.
 
-The runtime marks a terminal task `reported` when a read or wait delivers it, when a live waiter has claimed delivery at settlement, or when the model explicitly kills it. Reported tasks do not inject redundant completion notices. Listener failures are logged independently, do not stop later listeners, and are not awaited by waiters or teardown.
+The runtime marks a terminal task `reported` when a read or wait delivers it, when a live waiter has claimed delivery at settlement, or when the model explicitly kills it. Reported tasks do not inject redundant completion notices. Listener failures are logged independently, do not stop later listeners, and are not awaited by waiters or teardown. When a snapshot carries `outputLimitBytes`, `dsh-tool-tasks` preserves UTF-8 boundaries and reuses an existing producer truncation marker rather than duplicating it. Reads reserve status suffixes and retain the output tail; completion notices reserve the stable `background task <id>` prefix and `task_output` instruction before truncating variable kind, label, status, detail, or the truncation marker itself, so the minimum PTY cap still identifies the task to collect. The task surface resolves the caller-visible producer cap in a prepended pre-execute listener before policy can deny or short-circuit dispatch, then applies it through the task definitions' last-mile `finalizeContent` callback so normalized tool errors, outer pipeline failures, and single-text policy results cannot escape the bound; deliberately structured multi-block policy results retain policy ownership of their shape and size.
 
 ## Producer opt-in
 
-Each producer owns whether its schema exposes `run_in_background` through defaulted config. `dsh-tool-bash` and each `dsh-tool-subagent` instance use `enableRunInBackground`, defaulting to true. A disabled instance omits the parameter and also rejects a forced background argument at execution because the generic argument validator permits undeclared keys. Schema omission advertises the capability; the execution check enforces it.
+Each producer owns whether its schema exposes `run_in_background` through defaulted config. `dsh-tool-bash`, `dsh-tool-pty`, and each `dsh-tool-subagent` instance use `enableRunInBackground`, defaulting to true. A disabled instance omits the parameter and also rejects a forced background argument at execution because the generic argument validator permits undeclared keys. Schema omission advertises the capability; the execution check enforces it.
 
 `ctx.tasks` does not rewrite producer schemas. A bundle forwards configuration only for producers it owns. If a background call reaches `start()` without an attached surface, the runtime fence fails before execution.
 
@@ -119,7 +125,7 @@ Authorization, not unguessability, is the access boundary, and ids do not derive
 
 ## Testing
 
-Unit coverage pins preflight atomicity, per-kind ids, stream and final reads, wait timeout and abort races, cancellation, first-wins settlement, listener containment, notice suppression, owner isolation, stale owner instances, owner cleanup, service teardown, and the no-surface fence. Producer tests cover bash process mapping, subagent startup cancellation, terminal mapping, and disposal. Snapshot coverage pins the control-tool schemas and prompt guidance.
+Unit coverage pins preflight atomicity, per-kind ids, output-limit validation and projection, complete UTF-8 result bounds, stream and final reads, wait timeout and abort races, cancellation, first-wins settlement, listener containment, notice suppression, owner isolation, stale owner instances, owner cleanup, service teardown, and the no-surface fence. Producer tests cover bash process mapping, subagent startup cancellation, terminal mapping, and disposal. Snapshot coverage pins the control-tool schemas and prompt guidance.
 
 ## Consequences
 
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
new file mode 100644
index 0000000000..3c214bb430
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -0,0 +1,134 @@
+# Agent Note: 后台任务运行时（`ctx.tasks`）与通用任务控制工具
+
+Status: implemented
+
+[English](2026-06-20-generic-long-running-tool-runtime.md) | 中文
+
+## 问题
+
+后台 bash 原本兼有两项职责：bash 执行器既运行进程，又管理 task id、所有权、增量读取、取消、完成监听器和面向模型的控制工具。新增后台 subagent 需要相同的生命周期与交互契约。如果每种长时间运行能力都独立实现该契约，就会重复隔离、清理、通知和提示词行为，还会让模型为每种生产方学习不同的收集与停止协议。
+
+任务注册表、控制工具与完成通知共同构成一项 harness 功能。bash 和 subagent 只提供执行专属的钩子，不拥有通用任务行为。
+
+## 决策
+
+`tasks/` 包组拥有后台任务语义：
+
+- `@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 保持独立，不依赖会话或任务注册表。
+
+`TaskService` 是一个具体的进程内服务。TODO(task-service-backend)：当第二个后端明确所需生命周期后，将其公共契约与实现分离；systemd 驱动的运行时是一种可能方案，但本 PR（Pull Request）不臆测其持久性、重连、所有权或观察语义。
+
+## 运行时契约
+
+字面类型见[任务数据结构目录](../../../../docs/core-data-structures/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
+
+`outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `TaskSnapshot`；通用控制接口添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有接口行为，因此运行时不会向无关的生产方类别施加隐式默认值。
+
+面向模型的生产方会在规范成功值中暴露已提交的 id，通常为 `{ kind: 'background', taskId }`；Native 渲染仍可保留便于人类阅读的行文。预先被中止的后台调用会失败，而不是返回空操作，因为不存在可履行所承诺句柄的任务。一旦注册过程发布 id，取消就归任务自身的控制器与任务运行时所有：随后取消生产工具调用不得终止已发布的任务。`task_kill`、所有者资源释放和服务拆除会请求取消；前台执行仍与调用的 `exec.signal` 耦合。
+
+生产方钩子定义三项职责：
+
+- `cancel(reason?)` 同步请求终止，具备幂等性，并且必须使 `done` 完成。
+- `done` 从不拒绝，并且仅在生产方释放任务资源后完成。
+- 可选的 `readOutput()` 返回下一个消费式输出增量。省略该钩子即声明这是最终输出任务，其终止结果来自 `TaskOutcome.output`。
+
+状态包括 `running`、`stopping`、`completed`、`killed` 和 `failed`。退出码或停止原因等生产方专属信息放在 `detail` 中，注册表不解释这些信息。任务 kind 构成可合并扩展的字符串联合；task id 带品牌，并按 `<kind>-N` 生成，每个 kind 各有一个计数器。
+
+运行时为 `done` 附加一个 continuation，记录第一个终止结果、解决等待方，并逐个调用完成监听器，同时隔离每个监听器的错误。首次结果优先的结算在资源销毁期间至关重要：如果 `cancel` 抛出，运行时会强制将记录标为失败，并警告工作可能遗留，而不是永远等待一个可能永不完成的 promise。后续生产方结果不能覆盖该诊断，也不能重复通知。`cancel` 返回后如果最终未使 `done` 完成，仍会阻塞资源销毁，因为运行时无法区分这种情况与缓慢但有效的停止。
+
+任务注册不是生产方工具 fiber 的 effect。因此，重新加载工具或控制接口插件不会终止由 agent（智能体）和后端拥有的工作。任务服务自身释放时会取消所有实时任务，并等待遵守契约的生产方。
+
+## 授权与所有者生命周期
+
+task id 在运行时全局可见且可预测，因此注册表会授权每次访问。`get`、`read`、`wait` 和 `kill` 接受调用方 `Agent`；`list` 仅返回该调用方可见的任务。有所有者的任务仅允许对应的确切会话访问。无所有者任务向非 agent 调用方开放，并随任务服务一起终止。
+
+快照存储所有者的品牌化 `SessionId` 以供授权，生命周期操作则保留确切的实时 `Agent` 实例。这两种身份用途不同：会话相等性授予访问权，精确对象身份决定清理和完成通知的接收方。复用 agent 或会话 id，不能将旧作用域的清理或通知重定向到替代实例。
+
+某个所有者的第一个任务会向 `owner.ctx` 附加一个异步 effect。agent 作用域释放时会取消该所有者的实时任务、等待其终止记录，并移除其快照。该 effect 可跨生产方重载存续，并加入 agent 现有的完全停稳边界。任务服务保留 effect disposer，使服务重载可以在全局资源销毁后，从仍然存活的 agent 作用域中分离回调。
+
+对于遵守契约的生产方，`AgentHandle.dispose()` 只在所属后台工作停止后解决。需要比 agent 存活更久的工作必须以无所有者方式启动；要跨运行时重启存续，则需另行设计持久任务。
+
+## 服务接口
+
+`TaskService` 提供：
+
+- `start(spec)`：经过预检的原子注册。
+- `get(id, caller?)` 和 `list(caller?)`：非消费式快照。
+- `read(id, caller?)`：消费式流增量或幂等的最终结果。
+- `kill(id, caller?, reason?)`：取消。
+- `wait(id, timeoutMs, caller?, signal?)`：有界的终止等待。
+- `onTaskDone(listener)`：effect 作用域内的观察，具有精确所有者投递和监听器隔离。
+- `attachSurface(name)`：控制接口可用性防线。
+
+`wait` 在任务完成时返回终止快照，在等待超时时返回实时快照。中止一次等待只取消该次等待。如果结算已经将终止投递分配给该等待方，终止快照仍然优先。等待方在中止时同步注销，因此同一 tick 内的结算无法代表一个什么也未收到的读取方压制完成通知。
+
+如果生产方加载时没有任何控制接口，调用方就能启动无法收集或停止的工作。因此，`dsh-tool-tasks` 在其整个生命周期内调用 `attachSurface()`；没有附加接口时，`start()` 会在生产方开始执行前失败。该检查发生在启动时而非插件加载时，因为兄弟插件可能并发激活。自定义的非模型接口可以自行附加，无需让注册表了解工具名称。
+
+## 面向模型的控制接口
+
+`dsh-tool-tasks` 注册三个与 kind 无关的工具，并使用通用 ACP（Agent Client Protocol）卡片：
+
+- `task_output(task_id, wait?, timeout_ms?)` 读取输出，并始终追加 `[status: ...]`。流式任务只返回上次读取以来的输出；最终输出任务在结算后返回结果。除非指定 `wait: true`，否则读取不会阻塞；等待超时由插件配置提供默认值并限定上限。等待超时会报告仍在运行的状态，不会停止任务。
+- `task_list()` 将调用方可见的任务返回为 `<id> [<kind>] <status> — <label>`，没有任务时返回 `(no background tasks)`。
+- `task_kill(task_id, reason?)` 立即请求取消。可选的已记录原因会转发给生产方。终止任务报告现有状态；生产方的取消操作若抛出，调用便会失败，任务保持运行。
+
+流式读取共享一个任务作用域内的消费游标，因为所属模型是预期读取方。UI 或多个独立读取方需要单独的非消费式观察 API；共享该游标会让读取方彼此消费对方的输出。
+
+系统提示词要求模型保留 task id、在后台工作运行时继续处理独立工作而非忙轮询或重复启动同一任务、在给出最终答案前收集相关任务，并终止不再重要的工作。完成时，系统会向确切所有者的会话注入一条已记录的 `context/message`；它会成为下一个请求的持久上下文，但不会唤醒空闲的 agent。
+
+当读取或等待交付终止任务、实时等待方在结算时认领了投递，或模型显式终止任务时，运行时将终止任务标为 `reported`。已报告的任务不会注入冗余的完成通知。监听器失败会独立记录，不会阻止后续监听器，也不会被等待方或资源销毁过程等待。当快照携带 `outputLimitBytes` 时，`dsh-tool-tasks` 会保持 UTF-8 边界，并复用生产方已有的截断标记，而不会重复添加。读取会为状态后缀预留空间并保留输出尾部；完成通知会先为稳定的 `background task <id>` 前缀与 `task_output` 指令预留空间，再截断可变的 kind、label、status、detail，乃至截断标记本身，因此 PTY 的最小上限仍能标识需要收集的任务。任务接口在策略有机会拒绝或短路分发之前，于最先执行的 pre-execute 监听器中解析调用方可见的生产方上限；随后通过任务定义最后一道的 `finalizeContent` 回调应用该上限，使规范化的工具错误、外层流水线失败与单文本策略结果都无法绕过该边界；经特意结构化的多块策略结果仍由策略拥有其形状与大小。
+
+## 生产方显式启用
+
+每个生产方通过带默认值的配置，自行决定其 schema 是否暴露 `run_in_background`。`dsh-tool-bash`、`dsh-tool-pty` 和每个 `dsh-tool-subagent` 实例都使用 `enableRunInBackground`，默认值为 true。禁用的实例会省略该参数；由于通用参数校验器允许未声明的键，它还会在执行时拒绝强制传入的后台参数。省略 schema 用于声明能力不可用；执行检查负责强制该约束。
+
+`ctx.tasks` 不改写生产方 schema。bundle 只转发其所拥有生产方的配置。如果后台调用在没有附加接口的情况下到达 `start()`，运行时防线会在执行前使其失败。
+
+## 生产方集成
+
+bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `BashProcess`，提供增量读取、取消、退出事实以及不拒绝的完全停稳 promise。本地执行器只为自身释放时能终止并等待进程而保留实时句柄。前台调用方继续直接使用 `resolve` 和 `run`。
+
+对于后台 bash，`dsh-tool-bash` 将调用方 agent 注册为所有者。其钩子将 `kill()` 映射为取消，将 `done` 映射为 completed 或 killed 的 `TaskOutcome`，并将 `readOutput()` 映射为进程的有界增量输出，以及溢出文件与沙箱通知。通用任务工具拥有 id、状态行、列表、等待和完成通知。
+
+对于后台 subagent，`dsh-tool-subagent` 创建由任务拥有的 `AbortController`，并在任务 starter 内启动提供方。无论提供方就绪前后，取消都会中止同一个 signal。`done` 同时等待子运行结果和子运行释放，将已完成输出映射为最终结果，将中止映射为 `killed`，并将其他停止原因或基础设施失败映射为 `failed`。中间子历史保留在子会话中，不通过 `readOutput()` 暴露。
+
+## 备选方案
+
+### 按功能划分控制工具
+
+为 bash 与 subagent 分别提供输出/停止工具，会重复 id、隔离、清理、通知和指导，并增加模型的 schema 与协议负担。统一运行时将执行专属行为保留在生产方中，而无需复制任务生命周期。
+
+### 立即抽象任务运行时后端
+
+当前 `TaskStart.run()` 契约传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在第二种实现出现前抽取接口，会固化错误的边界。
+
+### 由消费方负责授权或清理事件
+
+由消费方负责检查，会使每个新接口的隔离实现不一致或遗漏。广播清理事件会迫使每个监听器过滤所有 agent，且不提供注册 disposer。集中授权加一个所有者作用域内的 effect，为每个消费方提供相同防线，以及可等待、可移除的生命周期钩子。
+
+### 阻塞输出或单独的等待工具
+
+默认阻塞会在后台工作运行时串行化父任务。只等待而不读取会增加一次不返回有用信息的模型调用和 schema。`task_output(wait: true)` 显式表达阻塞，并将其与结果交付合并。
+
+等待使用共享的 deadline 原语，而不使用通用工具超时策略。等待超时是一次成功的观察，会返回 `[status: running]`；通用策略会将它替换为超时错误。任务返回 task id 后，没有任何工具调用超时会控制任务生命周期。
+
+### 由运行时拥有输出接收端
+
+推送式接收端可以集中缓冲，但 bash 已经在执行器 seam 后拥有有界缓冲、截断与溢出文件。拉取格式化增量能够保留这一所有权。拥有存储的持久化后端可能足以支持重新审视生产方接口。
+
+### 随机 id、提升或生命周期会话事件
+
+授权而非不可猜测性才是访问边界，并且 id 不用于派生文件系统路径；顺序生成的品牌化 id 可保持 transcript（文本记录）易读。将前台任务提升为后台任务需要 SDK 并未规定的用户交互契约。启动、读取和通知已作为工具与上下文事件记录，因此专用任务会话事件会重复面向模型的事实。
+
+## 测试
+
+单元覆盖固定预检原子性、按 kind 分配的 id、输出上限的校验与投影、完整结果的 UTF-8 字节上限、流式与最终读取、等待超时与中止竞态、取消、首次结果优先的结算、监听器隔离、通知压制、所有者隔离、陈旧的所有者实例、所有者清理、服务资源销毁和无接口防线。生产方测试覆盖 bash 进程映射、subagent 启动取消、终止映射与释放。快照覆盖固定控制工具 schema 与提示词指导。
+
+## 后果
+
+bash 命令与 subagent 共享一套 id 词汇、列表、通知格式、提示词习惯和控制工具。新的长时间运行生产方只需实现执行钩子，而不必再实现一套注册表与工具族。[工具实操手册](../../../../docs/cookbook/adding-a-tool.md)将生产方指向本契约。
+
+有所属后台 bash 会随其 agent 一起停止，不再比 agent 存活更久。后台进程没有执行器超时；调用方必须终止无关工作，或依赖所有者/服务释放。流式读取只支持一个消费方，完成通知不会唤醒空闲 agent；生产方的 `cancel` 返回后如果未使 `done` 完成，仍可能阻塞资源销毁。持久任务、独立观察游标和前台提升仍属于单独设计。
diff --git a/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.i18n.yaml
new file mode 100644
index 0000000000..63ef106781
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-package-hierarchy.md: ab0732172934414f2361b9e4976b54e5daee298c
+2026-06-20-package-hierarchy.zh.md: 57058860de5b4cba3e8a45ecad9d611d068fb82c
diff --git a/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md b/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md
index 1ba3b94e8b..ab07321729 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-package-hierarchy.zh.md)
+
 The later [fold-stdio-helper](../simplification/2026-07-04-fold-stdio-ui-helper.md) decision superseded the original `support/ui-stdio` placement, and the [redundant-agent removal](../simplification/2026-07-20-remove-stdio-and-echo-agents.md) subsequently removed that surface entirely. The uniform depth-two hierarchy remains the decision owned here.
 
 ## Problem
diff --git a/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.zh.md b/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.zh.md
new file mode 100644
index 0000000000..57058860de
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.zh.md
@@ -0,0 +1,77 @@
+# Agent Note: 将包重组为模块化层级结构
+
+Status: implemented
+
+[English](2026-06-20-package-hierarchy.md) | 中文
+
+后续的[折叠 stdio helper](../simplification/2026-07-04-fold-stdio-ui-helper.md)决策取代了最初的 `support/ui-stdio` 放置方式，[冗余 agent 移除](../simplification/2026-07-20-remove-stdio-and-echo-agents.md)随后又彻底移除了该接口。这里拥有的决策仍是统一的二层目录深度。
+
+## 问题
+
+`packages/` 原先是扁平的：18 个包（package）全部位于 `packages/<name>/`，从路径上完全看不出一个包属于核心产品 API、可替换的能力 seam、提供方适配器、产品集成，还是示例/测试支撑。包的 README 带着 `FIXME(package-hierarchy)`，`scripts/publint-all.ts` 带着 `TODO(package-inventory)`，标记的正是这个问题。核心包、提供方集成、能力 seam、示例 UI 支撑和仅用于快照的回放支撑看起来同样基础。
+
+这不仅仅是外观问题。由于每个顶层包看起来都属于同一个公开接口，未来移除更加困难，而 publish/lint/doc 脚本不得不通过注释或手工维护的静态列表来编码意图，而不是从布局中直接读取。
+
+## 决策
+
+按模块角色将包分组，统一放在 `packages/<group>/<pkg>/` 深度。分组目录是纯容器（没有 `package.json`）；每个包保留其 `@deepseek-ai/dsh-<pkg>` 名称——这是仓库结构与维护策略的调整，不是包的重命名。
+
+```text
+packages/
+  core/                  (product API spine)
+    session/
+    system-prompt/
+    tools/
+    agent/
+    agent-loop/
+  llm/                   (product — capability family)
+    llm/
+    llm-deepseek/
+    llm-pi-ai/
+  bash/                  (product — capability family)
+    bash/
+    bash-local/
+    tool-bash/
+  session-persistence/   (product — capability family)
+    session-persistence/
+    session-persistence-jsonl/
+    session-persistence-sqlite/
+  ui/                    (product integration)
+    acp/
+  support/               (dev/test/example infrastructure)
+    invariants/
+    ui-stdio/
+    llm-replay/
+```
+
+### 放置决策
+
+- **能力族使用同名嵌套。** 一个族的接口包位于 `packages/<group>/<group>/`（`llm/llm`、`bash/bash`、`session-persistence/session-persistence`），实现和消费方作为扁平兄弟并列。不设额外的 `adapters/`/`impls/` 子层——每个包恰好在深度 2，这使 workspace glob 保持简洁的 `packages/*/*`，并让一条 `@deepseek-ai/dsh-*` tsconfig 通配符即可解析所有包（唯一的目录名使 first-on-disk-wins 无歧义）。
+- **`session` 留在 `core/`；持久化独立成族。** 会话日志是核心产品 API。其存储后端构成一个平行的能力族（`session-persistence/`），与 `llm/` 和 `bash/` 对称，而非嵌套在 `core/session/` 下。
+- **`agent-loop` 在 `core/` 中。** 它是 `agent` seam 唯一的具体实现，但作为 harness 的默认产品循环交付，因此与核心主干同处。插件仍然依赖 `agent` 的词汇，从不依赖 `agent-loop`，所以循环仍可替换。
+- **`invariants` 和 `ui-stdio` 属于 `support/`，不是产品。** `invariants` 是开发模式的契约检查。`ui-stdio` 从示例中提取出来以便复用和满足覆盖率门禁——它与示例耦合，因此与 `llm-replay`（快照测试的回放适配器）一起放在 `support/` 中。`acp` 是 `ui/` 的唯一成员，因为它是真正的产品接口（编辑器驱动的 ACP 桥接），与 readline 演示辅助工具在结构上截然不同。
+
+### 去重包列表
+
+包列表此前在五个地方重复枚举。统一的深度 2 布局使大部分可以被推导：
+
+- `tsconfig.base.json` 通过一条 `@deepseek-ai/dsh-*` `paths` 通配符（每个分组列一个候选）映射所有包，取代了逐包条目。聚合配置（`tsconfig.host.json`、`tsconfig.client.json`）复用该源映射，并携带显式 project references 以保持包/vendor 类型检查边界完整。（这里引入了一个细节：路径候选中包含 `/*/`，朴素的正则注释剥离器会将其误认为块注释——`scripts/doc-typecheck.ts` 正是因此通过 TypeScript 解析器读取 JSONC 配置，而非手动剥离注释。）
+- `scripts/publint-all.ts` 通过读取层级结构（`packages/<group>/<pkg>`）推导列表，解决了 `TODO(package-inventory)`。
+- 聚合配置的 project `references` 仍为显式列表——TypeScript project references 没有通配符形式。从 manifest（元数据清单）生成这些引用留作后续工作（见[通过发现机制获取包清单](../../proposed/process/2026-06-20-discover-package-inventory.md)）。
+
+### 新增的护栏
+
+两道 doc-sync/hygiene 门禁确保结构及其引用保持正确，使本次重组所需的手动检查无需日后重复：
+
+- `scripts/verify-package-paths.ts` 标记 Markdown 或 `.ts` 注释/字符串中的 `packages/<path>` 引用，如果该引用无法解析**且**某个路径段命名了一个真实存在的包，即指向已移动包的陈旧路径。如果路径命名的包在任何地方都不存在（前瞻性提案），则不予标记，因此该门禁在 proposed/implemented/rejected 中统一适用。
+- `scripts/check-workspace-constraints.ts` 断言 `packages/<group>/<pkg>` 形状：分组目录不带 `package.json`，且没有包扁平地位于根层或嵌套更深。分组名称保持开放——添加新分组无需修改门禁；只有深度 2 的形状是固定的。
+
+## 曾考虑的替代方案
+
+- **第三层（每个族下设 `adapters/`/`impls/`）**：否决。统一深度 2 使 workspace glob 保持简洁的 `packages/*/*`，并让一条 `@deepseek-ai/dsh-*` tsconfig 通配符即可解析所有包。
+- **将持久化嵌套在 `core/session/` 下**：否决。存储后端构成一个平行的能力族，与 `llm/` 和 `bash/` 对称，而会话日志本身属于核心产品 API。
+- **`ui-stdio` 放在 `ui/` 下**：否决。它是与示例耦合的开发支撑，不是产品接口；`acp` 是 `ui/` 的唯一成员，因为编辑器实际驱动它。
+
+## 后果
+
+本次重组在一次协调的变更中搅动了 import、workspace glob、文档链接、构建引用和包路径。这种变动在发布前是可接受的（依据 AGENTS.md 中「基础优先于爆炸半径」的立场），因为它阻止了扁平布局将支撑包固化为产品契约，且这是一次性成本：通配符 `paths`、glob 推导的 publint 列表和形状门禁意味着新增一个包无需额外的结构性编辑。
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
new file mode 100644
index 0000000000..e72b100327
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-21-mandatory-app-attribution-headers.md: a8ffe91c431cdc7907626bbc3eaf8096035777de
+2026-06-21-mandatory-app-attribution-headers.zh.md: 5529a42dddf4615ee1054b4d1dee36b077800d7d
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 fdd98b89cb..a8ffe91c43 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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.
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
new file mode 100644
index 0000000000..5529a42ddd
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -0,0 +1,84 @@
+# Agent Note: 对提供方请求强制携带 `User-Agent` 归属标识
+
+Status: implemented
+
+[English](2026-06-21-mandatory-app-attribution-headers.md) | 中文
+
+## 问题
+
+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 上保持诚实。
+
+直接触发因素来自 OpenRouter 的[应用归属](https://openrouter.ai/docs/app-attribution)文档。OpenRouter 根据 `HTTP-Referer` 加上 display/category 头部来创建应用页面和排名。这有价值，但它不是 HTTP 标准中的应用身份机制。风险在于：把 OpenRouter 的精确头部集当作通用标准来采纳，然后将提供方特有的头部泄漏到直连 DeepSeek 的请求、未来的 OpenAI/Anthropic/Vertex 适配器、测试服务器或无限期记录未知字段的代理中。
+
+## 调研
+
+- **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 可以后续支持运营者联系方式，但不得凭空捏造或全局强制要求。
+- **请求体中的 `user` 或 `metadata` 字段不是应用归属。** 部分模型 API 暴露稳定的终端用户标识符、请求元数据、标签或项目/账户头部。这些对滥用监控、内部计费、仪表盘或链路追踪有用，但它们要么标识的是终端用户而非产品，要么是提供方特有的 body schema，要么不保证能通过 OpenAI 兼容网关透传。它们不能替代静态的应用身份头部。
+- **SDK 遥测头部标识的是 SDK，而非应用。** 官方和第三方 SDK 常发送库/版本头部。这些帮助 SDK 维护者调试其客户端，但除非应用显式提供产品归属层，否则它们不能标识 harness 作为应用。
+- **pi-ai 有一流的头部钩子。** `@earendil-works/pi-ai` 的 `StreamOptions.headers` 将调用方头部最后合并（覆盖提供方默认值），因此基于库的适配器无需包装或上游改动即可满足与手写适配器相同的协议格式契约。mock 服务器测试套件对两个适配器都断言头部到达了线路。
+
+## 决策
+
+在 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` 归属。
+
+提供方无关的身份由 `dsh-llm`（`packages/llm/llm/src/attribution.ts`）拥有，而非各适配器。`AppIdentity` 仅包含构建 `User-Agent` 所需的公开产品事实，默认的 `APP_IDENTITY` 确定了提案中留待决定的值：
+
+- `User-Agent` 的产品 token：`deepseek-harness`（与 Agent Note 之前的线路值及仓库/组织身份保持连续性）
+- 版本：通过 `createRequire` 从所属包的 manifest 读取，绝不手动复制常量
+- 应用 URL：`https://github.com/deepseek-ai/deepseek-harness-sdk`——计划中的公开主页；`attribution.ts` 中的 `FIXME` 标记在该仓库实际存在之前阻塞发布
+
+默认值是强制的且非空。白标部署通过向 `attributionHeaders(identity)` 传入自己的 `AppIdentity` 来覆盖——覆盖 seam 就是函数参数，在有消费方需要之前不做部署配置管道——省略时回退到 harness 默认值而非抑制归属。没有逐请求 API 允许模型、用户提示词、会话 id、cwd、用户邮箱、API key 所有者或本地机器身份影响这些字段。
+
+线路映射（`attributionHeaders`；代码中头部名称小写——HTTP 字段名在线路上不区分大小写）：
+
+| 目标 | 映射 |
+|---|---|
+| 所有基于 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`。 |
+| 未来提供方 | 仅 `User-Agent`，除非后续提供方特有的 Agent Note 接受额外头部。不要类比复用 `HTTP-Referer`。 |
+
+端点检测不在本 Agent Note 范围内，因为此处不接受任何端点特有的映射。如果后续支持 OpenRouter，检测必须是显式的：要么是专门的 OpenRouter 提供方包，要么是显式的 `provider: 'openrouter'` / `attributionTarget: 'openrouter'` 配置，而非任意路径片段或模型名称。
+
+## 验证
+
+已落地的契约：
+
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/core-data-structures/llm-streaming.md` 的适配器契约章节）。
+- 共享辅助函数（`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`）。
+- 没有应用归属字段携带机密、本地路径、会话 id、提示词文本、模型输出、用户邮箱或逐用户的稳定标识符。
+- 适配器 README 声明了 `User-Agent` 归属策略，并明确避免将 OpenRouter 应用归属记录为已实现的行为。
+
+## 曾考虑的替代方案
+
+**现在就实现 OpenRouter 应用归属。** 本 Agent Note 否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本 Agent Note 试图标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
+
+**向所有提供方发送 OpenRouter 头部。** 否决。这会把一份自定义的 OpenRouter 契约当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
+
+**仅使用提供方账户/项目身份。** 否决。组织/项目头部、API key、云账户和计费项目标识的是谁付费或谁拥有请求，而非哪个应用在发送流量。它们也不暴露公开的应用标题/类别，无法帮助 OpenRouter 等网关构建应用排名。
+
+**终端用户 `user`/`metadata` 字段。** 本 Agent Note 否决。这些对滥用监控和客户支持有价值，但描述的是请求背后的人或租户。应用归属必须是静态的产品身份，且可安全地在每个请求上发送。
+
+**仅配置启用的归属。** 否决。默认关闭的设置正是适配器不断漂移的原因。策略是强制默认归属加可覆盖的公开值，而非可选归属。
+
+**以产品命名的 token（`deepseek-harness-sdk`）。** 曾考虑用于 `User-Agent` token，因为产品名是 DeepSeek Harness SDK。`deepseek-harness` 因连续性胜出：它是提供方从本代码库已经看到的身份，与组织/仓库身份和包 scope 一致，且在展示文案承载产品名的同时保持线路归属稳定。
+
+## 后果
+
+**提供方看到流量来自 harness。** 这正是目的，但意味着此前混在通用 SDK 流量中的部署变得可识别。缓解措施：仅发送静态公开产品数据，并允许 fork/白标部署传入自己的 `AppIdentity`。
+
+**应用 URL 指向一个尚不存在的仓库。** `deepseek-ai/deepseek-harness-sdk` 是计划中的公开主页；在它创建之前，该 URL 是一个悬空承诺。常量上的 `FIXME` 标记阻塞发布，不允许带着未解决的问题出门（见 `docs/development.md` 标记语义）。
+
+**不同客户端库的头部支持有差异。** 手写适配器直接设置头部；基于 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
new file mode 100644
index 0000000000..70ec051143
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-24-web-capability-seam.md: 4f4e821fec9494fe9ea96894267707d9dd202e4d
+2026-06-24-web-capability-seam.zh.md: d7c07a8ae0365c321120102a0af401d85d7e2eae
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 b3dad98f18..4f4e821fec 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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.
@@ -75,6 +77,8 @@ Provider packages depend only on `dsh-web` and Cordis. They own credentials, end
 `ctx.web` is a provider registry plus a provider-selecting execution surface. The registry half stays close to `LlmService`: a `Map<id, provider>` per capability kind, `registerSearchProvider` / `registerFetchProvider` methods that return disposers, duplicate ids that throw `WebError`, and execution-time resolution that throws when the selected provider is absent or unusable. The authoritative signatures live in `packages/web/web/src/types.ts`; the seam's shape:
 
 ```ts
+import type { WebFetchRequest, WebFetchResult, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web'
+
 interface WebSearchProvider {
   readonly id: string
   available(): boolean
@@ -206,18 +210,18 @@ The seam request deliberately does not include a per-call timeout, `format`, `pr
 HTTP status is part of the fetched resource state, not automatically a tool failure. A successful network fetch of a `404` or `500` response returns `WebFetchResult` with the status code and a bounded decoded body when the content type is supported. `WebError` is for failures to safely retrieve or represent the resource: invalid or blocked URL, redirect policy violation, timeout, abort, response too large, unsupported content type, provider failure, or network failure.
 
 ```ts
-interface WebFetchRequest {
+export interface WebFetchRequest {
   readonly url: string
 }
 
-interface WebFetchResult {
+export interface WebFetchResult {
   readonly url: string
   readonly statusCode: number
   readonly body: WebFetchBody
   readonly truncated: boolean
 }
 
-type WebFetchBody =
+export type WebFetchBody =
   | { readonly kind: 'html'; readonly content: string }
   | { readonly kind: 'text'; readonly content: string }
 ```
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
new file mode 100644
index 0000000000..d7c07a8ae0
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -0,0 +1,336 @@
+# Agent Note: Web 能力 seam——稳定的工具覆盖多个提供方
+
+Status: implemented
+
+[English](2026-06-24-web-capability-seam.md) | 中文
+
+## 问题
+
+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 注册。让每个提供方注册自己的工具则有相反的问题：工具的可用性、名称、描述和参数将取决于恰好加载了哪些提供方包，提供方特有字段会泄漏到模型契约中。
+
+还有一个提供方选择的问题。现有的 `tool-bash` 和 `tool-fs` 可以依赖 Cordis 的 `inject`，因为只有一个后端服务键。Web 有两项独立能力（`search` 和 `fetch`），每项能力可能有多个提供方。`inject: ['web']` 能证明 seam 存在，但不能证明存在可用的搜索或 fetch 提供方，也无法定义多个提供方注册时谁胜出。
+
+## 决策
+
+Web 访问是一个一等能力 seam，遵循[能力 seam Agent Note](2026-06-13-capability-seams.md)：
+
+1. `@deepseek-ai/dsh-web`（`packages/web/web`）拥有 `ctx.web`、提供方注册、提供方选择、共享的请求/结果词汇，以及 web 特有的错误。
+2. 提供方包实现具体后端并向 `ctx.web` 注册能力，例如 `@deepseek-ai/dsh-web-search-exa`、`@deepseek-ai/dsh-web-search-perplexity`、`@deepseek-ai/dsh-web-search-deepseek` 和 `@deepseek-ai/dsh-web-fetch-local`。
+3. `@deepseek-ai/dsh-tool-web`（`packages/web/tool-web`）拥有面向模型的 `web_search` 和 `web_fetch` 工具 schema、提示词段落、参数校验、结果格式化，以及通过 `ctx.web` 实现的工具展示。
+
+提供方不注册工具。提供方注册能力。`dsh-tool-web` 是面向模型的名称、描述、提示词引导、JSON Schema、展示的唯一所有者。
+
+搜索和 fetch 是两个独立工具，但属于同一个 web 访问 seam。`ctx.web` 为两个并行注册表统一拥有提供方选择、abort/错误词汇和部署配置。它们的请求 schema 和提供方逻辑保持独立；共享的服务是触达 web 的产品边界。
+
+`dsh-tool-web` 在产品启用了相应工具且 `ctx.web` seam 存在时注册面向模型的 web 工具。后端可用性是执行时关注点，而非 schema 注册时关注点：
+
+- `web_search` 在产品/应用启用了 web 搜索时注册，`web_fetch` 在启用了 web fetch 时注册。
+- 工具绝不会仅仅因为其选定的提供方缺失、配置错误、缺少凭证、存在歧义或暂时不可用就被注销。
+- 提供方在执行时解析，当选定的能力无法运行时返回结构化的 `WebError`。
+
+这使模型 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](../simplification/2026-07-04-drop-unconsumed-web-observation-surface.md) 记录了这一判断：基于调用的派生选择与基于启用的注册使得没有消费方需要变更信号或独立于执行和错误路由的可用性探测；未来的提供方状态面板会重新引入它实际消费的最小信号或查询。
+
+## 包拓扑
+
+由三个包构成的接口/实现/消费方拆分沿用 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 一致：
+
+```text
+@deepseek-ai/dsh-tool-web  --depends on-->  @deepseek-ai/dsh-web  <--depends on--  @deepseek-ai/dsh-web-search-exa
+        consumer                                 interface                       implementation
+                                                                 <--depends on--  @deepseek-ai/dsh-web-search-perplexity
+                                                                                  implementation
+                                                                 <--depends on--  @deepseek-ai/dsh-web-search-deepseek
+                                                                                  implementation
+                                                                 <--depends on--  @deepseek-ai/dsh-web-fetch-local
+                                                                                  implementation
+```
+
+运行时，提供方包向 `ctx.web` 注册能力；`tool-web` 向 `ctx.tools` 注册稳定的工具并通过 seam 执行：
+
+```mermaid
+flowchart LR
+  exa["@deepseek-ai/dsh-web-search-exa"] -->|registerSearchProvider| web["@deepseek-ai/dsh-web / ctx.web"]
+  perplexity["@deepseek-ai/dsh-web-search-perplexity"] -->|registerSearchProvider| web
+  deepseek["@deepseek-ai/dsh-web-search-deepseek"] -->|registerSearchProvider| web
+  fetchLocal["@deepseek-ai/dsh-web-fetch-local"] -->|registerFetchProvider| web
+  toolWeb["@deepseek-ai/dsh-tool-web"] -->|search/fetch| web
+  toolWeb -->|ctx.tools.register| webSearch["tool: web_search"]
+  toolWeb -->|ctx.tools.register| webFetch["tool: web_fetch"]
+```
+
+`@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` 是一个提供方注册表加上一个带提供方选择的执行面。注册表部分与 `LlmService` 保持接近：每种能力类别一个 `Map<id, provider>`，`registerSearchProvider`/`registerFetchProvider` 方法返回 disposer，重复 id 抛出 `WebError`，执行时解析在选定提供方缺失或不可用时抛出异常。权威签名见 `packages/web/web/src/types.ts`；seam 的形状：
+
+```ts
+import type { WebFetchRequest, WebFetchResult, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web'
+
+interface WebSearchProvider {
+  readonly id: string
+  available(): boolean
+  search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
+}
+
+interface WebFetchProvider {
+  readonly id: string
+  available(): boolean
+  fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
+}
+
+interface WebService {
+  registerSearchProvider(provider: WebSearchProvider): () => void
+  registerFetchProvider(provider: WebFetchProvider): () => void
+
+  search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
+  fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
+}
+```
+
+可选的 signal 是执行控制，而非业务输入：`tool-web` 直接传递 `exec.signal`，使轮次取消、工具超时和 agent dispose（资源释放）能到达提供方的网络请求、流读取器和高开销解码。seam 不传递 `ToolExecution`——否则 `dsh-web` 就要依赖 `dsh-tools`。
+
+提供方 id 是稳定字符串，在各自的能力类别内唯一。注册重复的搜索提供方 id 或重复的 fetch 提供方 id 会失败，而非静默替换旧提供方。提供方注册返回 disposer，沿用现有的 `ctx.tools.register()`/`ctx.systemPrompt.section()` 模式：变更包裹在 `ctx.effect()` 中，注册随贡献它的 fiber 一起拆除。
+
+## 提供方可用性与选择
+
+提供方可用性与能力选择是两个独立概念，但都保持最小化。提供方仅报告该具体实现是否可用，通过廉价的本地检查（如凭证是否存在、端点配置是否可解析）。提供方的 `available()` 禁止发起网络调用。
+
+`LlmService` 完全没有状态类型：可用性通过注册表成员资格加解析时抛出来表达。`ctx.web` 遵循同样的纪律。seam 不暴露聚合的能力状态查询——`search()`/`fetch()` 在每次调用时根据配置的提供方 id、已注册的提供方和每个提供方廉价的本地 `available()` 布尔值派生选择结果，选择失败就是执行时抛出的结构化 `WebError`。需要知道某项能力能否运行的调用方通过执行并路由该错误来获知；没有任何东西作为可变服务状态存储。
+
+该布尔值是选择的输入，而非健康系统。`tool-web` 从不直接调用提供方的 `available()`——它进入 seam 的唯一路径是 `search()`/`fetch()`——因此选择策略只有一个所有者。
+
+选择不得依赖注册顺序。Cordis 加载顺序、配置排列和 HMR 时序不是产品语义。
+
+| 情况 | 执行行为 |
+|---|---|
+| 配置的提供方 id 已注册且 `available() === true` | 运行该提供方 |
+| 配置的提供方 id 未注册 | 以 `WEB_PROVIDER_CONFIGURED_MISSING` 失败 |
+| 配置的提供方 id 已注册但不可用 | 以 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE` 失败 |
+| 未配置提供方 id，且该类别恰好有一个已注册且可用的提供方 | 运行该唯一提供方 |
+| 未配置提供方 id，且该类别无已注册提供方 | 以 `WEB_PROVIDER_UNAVAILABLE` 失败 |
+| 未配置提供方 id，且该类别有多个可用提供方已注册 | 以 `WEB_PROVIDER_AMBIGUOUS` 失败，而非按注册顺序选择 |
+| 未配置提供方 id，且有提供方存在但均不可用 | 以 `WEB_PROVIDER_UNAVAILABLE` 失败 |
+
+「唯一提供方自动选择」规则面向测试、演示和简单部署。产品配置设置显式提供方 id：
+
+```yaml
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: exa
+    fetchProvider: local-http
+
+- id: web-search-exa
+  name: '@deepseek-ai/dsh-web-search-exa'
+
+- id: web-search-perplexity
+  name: '@deepseek-ai/dsh-web-search-perplexity'
+
+- id: web-search-deepseek
+  name: '@deepseek-ai/dsh-web-search-deepseek'
+
+- id: web-fetch-local
+  name: '@deepseek-ai/dsh-web-fetch-local'
+
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+```
+
+运维覆盖走同一条显式选择路径：`DSH_WEB_SEARCH_PROVIDER=perplexity` 等同于配置 `searchProvider: perplexity`，而非 `dsh-tool-web` 内部的隐式优先级链。
+
+`ctx.web.search()` 和 `ctx.web.fetch()` 在执行时按上述选择规则解析提供方。如果选定的能力不可用，它们抛出带有结构化代码的 `WebError`，如 `WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE` 或 `WEB_PROVIDER_AMBIGUOUS`。如果未显式配置提供方且不存在可用提供方，执行错误是通用的 `WEB_PROVIDER_UNAVAILABLE` 情况；刻意不提供对每个不可用提供方的诊断汇总。
+
+## 搜索请求与结果 schema
+
+面向模型的 `web_search` 工具很小。唯一的面向模型参数是：
+
+- `query`：必填字符串。
+
+`max_results` 不暴露给模型。它是 `dsh-tool-web` 层的决策：工具设定结果上限——`searchMaxResults` 插件配置，默认 `8`（与 OpenCode 的 Exa 默认值对齐），类似 `dsh-tool-fs` 的 `readLimit`——并作为 `WebSearchRequest` 上的 `maxResults` 传给 seam。将其排除在模型 schema 之外意味着模型只需提问，产品控制返回多少上下文；该字段日后可以提升为面向模型的参数而不破坏 seam。
+
+`maxResults` 沿工具 → seam → 提供方流动，上限在返回路径上强制执行：
+
+- `dsh-tool-web` 拥有该值并将其放在 `WebSearchRequest.maxResults` 上。
+- `ctx.web` 将请求原样传递给选定的提供方。
+- 当提供方的 API 支持结果数量控制时（Exa 的 `numResults`），提供方在请求层应用 `maxResults`，作为成本/延迟优化。
+- `ctx.web` 在结果上强制执行上限：如果提供方返回的 source 数量超过 `maxResults`——因为其 API 没有结果数量控制（Perplexity）或忽略了提示——seam 将 `sources[]` 截断到 `maxResults` 并在返回前将 `WebSearchResult.truncated` 设为 `true`。这使上限成为面向模型层可以依赖的单一跨提供方保证，而非每个提供方都必须记得遵守的东西。
+
+seam 请求不携带提供方特有的控制——没有 Perplexity 模型选择、搜索时效性、域名过滤器、Exa `livecrawl`、Exa `type`、区域提示、生成式回答预算或搜索深度。只有当某个字段具有提供方无关的语义，且工具 schema 和选定的提供方都能诚实地遵守时，才会添加。
+
+```ts
+interface WebSearchRequest {
+  readonly query: string
+  /** Upper bound on returned sources; the seam truncates to it. Omitted = no bound. `dsh-tool-web` always sets it. */
+  readonly maxResults?: number
+}
+
+interface WebSearchResult {
+  readonly content?: string
+  readonly sources: readonly WebSearchSource[]
+  readonly truncated: boolean
+}
+
+interface WebSearchSource {
+  readonly url: string
+  readonly title?: string
+  readonly snippet?: string
+  readonly publishedAt?: string
+}
+```
+
+`content` 是可选的提供方生成的回答文本、搜索上下文或摘要。`sources[]` 是可移植的引用面。source 必有 URL；title、snippet 和 `publishedAt` 可选，因为并非每个提供方都返回它们。`title` 不是必填：Perplexity 风格的引用可能只提供 URL，强制适配器编造标题会让 seam 说谎。`dsh-tool-web` 渲染 `title ?? hostname(url)` 风格的回退标签用于展示。`publishedAt` 是可选的发布/抓取时间戳，为 ISO-8601 字符串——Exa 在每条结果上以 `publishedDate` 返回它，Perplexity 在搜索结果上返回 `date`，因此它是真实的提供方数据而非派生值；seam 以字符串形式传递，日期解析留给消费方。
+
+Exa 搜索将提供方扁平 `results[]` 的每一项映射为 `WebSearchSource`：`url` ← `url`、`title` ← `title`、`snippet` ← 第一个 `highlights[]` 条目（没有 highlight 的条目没有可移植的 snippet，被丢弃）、`publishedAt` ← `publishedDate`。Exa 不返回提供方生成的回答，因此 `content` 省略。Perplexity 搜索将 `choices[0].message.content` 映射为 `content`，并优先使用结构化的顶层 `search_results[]` 作为 `sources[]`——`url` ← `url`、`title` ← `title`、`snippet` ← `snippet`（常为空）、`publishedAt` ← `date`——仅在 `search_results` 缺失时回退到纯 URL 的 `citations[]` 数组（这些 source 只有 `url`）。如果提供方返回的结构化字段少于 seam 支持的，适配器省略那些可选字段。
+
+完整页面获取仍是 `web_fetch(url)` 的职责。搜索 snippet 是发现上下文，不是获取到的页面正文。
+
+## Fetch 请求与结果 schema
+
+`web_fetch` 的实现是一个匿名公开 HTTP(S) fetch 提供方 `local-http`。它从具体 URL 获取字节，应用下述基本传输卫生措施（仅 http/https、拒绝 URL 中的凭证、字节/时间上限、跨源重定向阻断），解码文本内容，并仅返回最小的模型可用结果：最终 URL、状态码、正文和截断标志。它不携带浏览器 cookie、编辑器凭证、git 凭证、内部认证令牌，也不隐式访问私有服务。（完整的 SSRF/私有网络阻断推迟——见[推迟工作](#deferred-work)。）
+
+seam 请求比 OpenCode 的面向模型工具更小：
+
+- `url`：必填 HTTP(S) URL。
+
+seam 请求刻意不包含逐调用超时、`format`、`prompt` 或提供方特有的提取控制。取消通过直接的可选执行信号实现，fetch 提供方拥有一个部署配置的超时兜底。`format` 是对已获取资源的展示决策；`prompt` 是更高层的 LLM 摘要指令；Firecrawl、Exa、Tavily 或 Parallel 等提取 API 可能不暴露具体的 HTTP 响应。如果产品日后需要提供方支撑的页面提取，那是一个独立的 `web_extract` 能力或对本 seam 的刻意扩展——提取语义绝不通过将每个 HTTP 字段设为可选来偷渡进 `web_fetch`。
+
+HTTP 状态码是已获取资源状态的一部分，不自动构成工具失败。成功的网络获取一个 `404` 或 `500` 响应会返回带有状态码和有界解码正文（当内容类型受支持时）的 `WebFetchResult`。`WebError` 用于无法安全获取或表示资源的失败：无效或被阻断的 URL、重定向策略违规、超时、abort、响应过大、不支持的内容类型、提供方失败或网络失败。
+
+```ts
+export interface WebFetchRequest {
+  readonly url: string
+}
+
+export interface WebFetchResult {
+  readonly url: string
+  readonly statusCode: number
+  readonly body: WebFetchBody
+  readonly truncated: boolean
+}
+
+export type WebFetchBody =
+  | { readonly kind: 'html'; readonly content: string }
+  | { readonly kind: 'text'; readonly content: string }
+```
+
+`WebFetchResult.url` 是允许的重定向之后的最终 URL。请求 URL 已在 `WebFetchRequest` 中，因此没有单独的 `requestedUrl`/`finalUrl` 对。
+
+`WebFetchBody` 是封闭的可辨识联合类型，因为正文类别需要 seam、提供方和工具三方协调变更，而非独立的插件扩展。穷举 switch 使新类别在每个渲染器处编译失败，直到被处理。独立的对象分支为类别特有字段留出空间。
+
+提供方负责安全的资源获取：URL 校验、HTTP 传输、重定向策略、超时、abort 传播、字节上限、字符集解码、内容类型分类和二进制拒绝。`dsh-tool-web` 负责展示：HTML 转 Markdown、HTML 转纯文本、面向模型的截断格式化，以及未来的摘要。
+
+fetch 提供方的资源控制：
+
+- 仅接受 `http:` 和 `https:` URL；拒绝 URL 中的凭证。
+- 强制执行最大 URL 长度、响应字节上限、解码正文字符上限、超时和重定向跳数上限。
+- Abort 信号传播到网络获取和高开销解码。
+- 仅自动跟随同源重定向；跨源重定向以 `WEB_REDIRECT_BLOCKED` 失败，要求一次新的工具调用，从而触发新的提供方/权限决策。（Claude Code 的 WebFetch 使用同样的模型——它不自动跟随跨主机重定向，而是将重定向目标返回给模型以发起新调用。）
+- 请求携带显式的产品 User-Agent，而非静默伪装浏览器。
+
+SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他非公开目的地，通过先 DNS 解析再验证 IP 来防御 rebinding，并在重定向的每一跳重新验证）**推迟**——见[推迟工作](#deferred-work)。在其落地之前，`web_fetch` 是一个 SSRF 原语，不得在能触达敏感内部网络目标的部署中启用。
+
+## 工具消费方行为
+
+`dsh-tool-web` 拥有两个 `ToolDefinition`：`web_search` 和 `web_fetch`。它拥有面向模型的 JSON Schema、snake_case 参数名、提示词段落、结果渲染为 `ContentBlock[]`、`presentCall` 和 `presentResult`。
+
+`dsh-tool-web` 禁止枚举提供方或直接调用提供方的 `available()`。它进入 seam 的唯一路径是 `ctx.web.search()`/`ctx.web.fetch()`。这将提供方选择保持在单一层；否则工具包可能判定某个提供方可用，而执行时解析出不同的状态。
+
+工具注册是最小化的稳定同步：插件启动时，`dsh-tool-web` 的 `Config`（`search?: boolean`、`fetch?: boolean`，均默认 `true`）启用或禁用每个 web 工具；已启用的工具通过基于 effect 的注册表以 fiber 作用域的 disposer 注册；任何工具都不会仅因其选定的提供方缺失、不可用或存在歧义而被 dispose；dispose `tool-web` fiber 时自动拆除其注册。
+
+提供方可用性变化影响执行结果和诊断信息，而非面向模型的 schema 是否存在。如果产品完全不需要 web 工具，在配置中禁用 `dsh-tool-web` 或单个 web 工具即可；如果需要 web 工具但后端配置有误，模型在执行时看到结构化的工具错误。
+
+提示词引导解释了语义分工——`web_search` 用于发现和获取当前信息，`web_fetch` 用于模型需要特定 URL 内容的场景——提示词和工具结果告诉模型用 Markdown 链接引用相关 URL。
+
+面向模型的输出以文本为先，因为工具结果是 `ContentBlock[]`，但 seam 的产出保持结构化，以便 UI 展示和未来的适配器无需解析渲染后的文本。
+
+## 错误
+
+`dsh-web` 定义 `WebError extends HarnessError`，带有稳定的错误码，仅覆盖调用方可能合理分支的状态：
+
+- `WEB_PROVIDER_UNAVAILABLE`
+- `WEB_PROVIDER_CONFIGURED_MISSING`
+- `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`
+- `WEB_PROVIDER_AMBIGUOUS`
+- `WEB_DUPLICATE_PROVIDER`
+- `WEB_INVALID_URL`
+- `WEB_BLOCKED_URL`
+- `WEB_REDIRECT_BLOCKED`
+- `WEB_FETCH_TOO_LARGE`
+- `WEB_FETCH_TIMEOUT`
+- `WEB_ABORTED`
+- `WEB_UNSUPPORTED_CONTENT_TYPE`
+- `WEB_PROVIDER_ERROR`
+
+`WEB_DUPLICATE_PROVIDER` 在 `registerSearchProvider`/`registerFetchProvider` 发现该能力类别中已有相同 id 时同步抛出（类似 `LlmService` 的 `DUPLICATE_ADAPTER`）；它是注册时的编程错误而非执行结果，但共享 `WebError` 码空间，使调用方看到统一的分类体系。`WEB_PROVIDER_ERROR` 是提供方自身失败通过 seam 浮出的兜底码，包括 `web-fetch-local` 中的网络/传输失败（DNS、连接拒绝、TLS）；刻意不设单独的 `WEB_NETWORK` 码——提供方设置描述性消息，使模型和日志能区分网络失败与提供方 API 失败。
+
+工具执行让这些错误流经 `ToolRegistry.execute()`，后者已将 `HarnessError` 转换为带结构化元数据的错误工具结果。模型得到可读的错误消息；钩子、测试和 UI 代码可以根据稳定的错误码路由。
+
+## 测试
+
+每一层在自己的 seam 处固定：`dsh-web` 中的注册/选择/截断/abort 契约与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事后分析 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
+
+## 曾考虑的替代方案
+
+### 让每个提供方注册自己的面向模型工具
+
+这与最灵活的提供方插件系统一致：每个提供方可以暴露其完整的原生 schema。在 harness 中被否决，因为它将面向模型的名称、描述、提示词引导和结果格式化的所有权交给了提供方包。多个搜索提供方会产生重复的工具名或提供方特有的工具名，模型将学到后端细节而非稳定的产品能力。
+
+### 将提供方调度直接放在 `dsh-tool-web` 中
+
+这类似 OpenCode 的本地 web 搜索：一个稳定的 `websearch` 工具在内部调度到 Exa 或 Parallel。对于小型产品路径可以接受，但作为 harness 基础是错误的。工具包将拥有提供方选择、凭证、请求映射、传输、响应解析和展示，使得在不将 Exa 和 Perplexity 的差异烘焙进工具 schema 的情况下难以添加它们。
+
+### 将搜索和 fetch 拆为两个 seam（`dsh-search`、`dsh-fetch`）
+
+很有吸引力，因为两半不共享请求 schema 和业务逻辑，各自能干净地映射到 bash/fs 的三包模板上，且 `WebService` 上的 `Search`/`Fetch` 方法对重复也会消失。否决，因为共享的机制——提供方 id 注册表、不依赖注册顺序的选择策略、abort 传播、`WebError` 分类体系，以及面向产品的「这个 harness 如何触达 web」配置面——是真实存在的，否则会在两个几乎相同的 seam 之间重复。一个 `ctx.web` 中间层给产品一个统一的注入和配置对象，给提供方选择一个唯一的所有者。代价是并行的 `searchX`/`fetchX` 方法对，这是有意接受的。
+
+### 选择第一个注册的提供方
+
+否决。注册顺序不是产品策略。它可能随配置顺序、插件加载、HMR 或重构而变化。提供方选择必须是显式的，或仅在恰好只有一个可用提供方时自动选择。
+
+### 将 Firecrawl/Exa/Tavily/Parallel 提取视为 fetch
+
+在第一版中否决。这些提供方通常返回提取或摘要后的内容，而非具体的 HTTP 响应。如果产品需要提取，日后设计 `web_extract` 或刻意扩展 fetch seam。
+
+### 镜像 Claude Code 的 `url + prompt` WebFetch 形状
+
+在 seam 层面否决。`prompt` 将 fetch 变成 LLM 摘要，并将公开 web 获取耦合到模型提供方。harness seam 应当确定性地获取和解码；`dsh-tool-web` 日后可以将摘要作为展示模式提供，而无需让 `ctx.web` 依赖 `ctx.llm`。
+
+## 后果
+
+**搜索 schema 刻意精简。** Exa 和 Perplexity 都暴露了有用的提供方特有控制；只有当某个控制能以提供方无关的方式定义、且工具注册和提供方执行都能诚实遵守时，才会添加。
+
+**Perplexity 引用可能稀疏。** 一条引用可能只有 URL。将 `title` 和 `snippet` 设为可选使 seam 保持诚实，但意味着 `tool-web` 需要渲染回退标签。
+
+**稳定的工具注册将配置错误推迟到执行时。** 当产品启用了 web 访问时，保持工具可见是正确的；但期望 web 搜索可用的产品应用应当醒目地浮出结构化的 `WEB_PROVIDER_CONFIGURED_MISSING`/`WEB_PROVIDER_CONFIGURED_UNAVAILABLE`/`WEB_PROVIDER_AMBIGUOUS` 失败，使用户不会在模型调用工具后才发现配置问题。
+
+**提供方状态可能在启动后变化。** 一个工具可能在步骤开始时组装的请求中可见，但在执行前失去其提供方。执行路径重新解析并以结构化错误失败。
+
+**Fetch 是网络边界，不仅仅是只读工具。** `web_fetch` 能触达敏感网络目标或通过 URL 外泄数据。仅交付基本传输卫生措施（仅 http/https、拒绝凭证、字节/时间上限、跨源重定向阻断）；SSRF/私有网络阻断推迟（见[推迟工作](#deferred-work)），因此在其落地之前，`web_fetch` 不得在能触达内部目标的环境中启用。
+
+**大量 web 内容可能损害上下文质量。** 提供方强制执行字节/字符上限并报告 `truncated`；`tool-web` 格式化有界的模型输出，附带清晰的继续或后续引导。
+
+## 推迟工作
+
+- `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`。
+- 推迟的权限系统落地后的权限策略集成。
+- `query` 和 `maxResults` 之外的提供方无关搜索控制，待 Exa 和 Perplexity 都能诚实遵守时再添加。
+
+## 开放问题
+
+- 产品应用包是否应在启动时探测 web 配置（当 web 被显式配置时将 `WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE` 和 `WEB_PROVIDER_AMBIGUOUS` 视为致命错误），还是将配置错误留到首次执行时浮出？
+- 推迟的权限系统落地后，公开 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
new file mode 100644
index 0000000000..614868ada0
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-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
+2026-06-26-file-context-as-event-gate.md: 4700222aa2e0f91d9f355495c228e2eb92825f55
+2026-06-26-file-context-as-event-gate.zh.md: 21c8706bcc14790a5092fa59e03bce329049760a
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 3f34cf3559..4700222aa2 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-26-file-context-as-event-gate.zh.md)
+
 ## Problem
 
 [The split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) put `ctx.fileContext` between the model-facing tools and the `ctx.fs` provider: `dsh-tool-fs` injects `fileContext` and routes every `read`/`write`/`edit` through its methods. That makes `fileContext` **in-path and mandatory**. The tool cannot reach `ctx.fs` without it, the policy layer owns the fs I/O and the read windowing, and a deployment that does not want observed-state policy cannot simply drop the package — `dsh-tool-fs` would fail to resolve `ctx.fileContext`.
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
new file mode 100644
index 0000000000..21c8706bcc
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -0,0 +1,171 @@
+# Agent Note: 将 `dsh-fs-policy` 改为事件门控插件，而非方法接口
+
+Status: implemented
+
+[English](2026-06-26-file-context-as-event-gate.md) | 中文
+
+## 问题
+
+[拆分文件系统 seam Agent Note（agent 决策记录）](../simplification/2026-06-26-fsspec-style-fs-seam.md) 在面向模型的工具与 `ctx.fs` 提供方之间放置了 `ctx.fileContext`：`dsh-tool-fs` 注入 `fileContext`，并将每次 `read`/`write`/`edit` 路由到它的方法。这使得 `fileContext` **位于关键路径上且不可省略**。工具不经过它就无法访问 `ctx.fs`，策略层掌控着 fs I/O 和读取窗口，而一个不需要观测状态策略的部署也无法简单地移除该包——`dsh-tool-fs` 会因无法解析 `ctx.fileContext` 而失败。
+
+这把三件本应可分离的事情耦合在了一起：
+
+1. **工具做什么**——解析路径、读取窗口、写入/编辑文件。这是工具的职责，只需要 `ctx.fs`。
+2. **新鲜度/观测策略**——「编辑前必须先读」、「写入/编辑必须基于你读到的版本」。这是 `dsh-fs-policy` 插件的职责。
+3. **观测状态的记录**——一个副作用，永远不应阻止工具正常运行。
+
+由于工具调用的是 `fileContext` 方法，移除策略层就是一个破坏性变更，而非优雅地失去一个*附加*能力。策略层对工具的运行是承重性的，而非可选的收紧。
+
+## 决策
+
+反转控制流。**`dsh-tool-fs` 成为执行器，直接调用 `ctx.fs`**；**`dsh-fs-policy` 成为门控 + 记录插件**，通过事件参与，从不通过工具调用的方法，也不注册 `ctx.fileContext` 服务。
+
+```text
+tool          dsh-tool-fs       executor: resolves, reads windows, writes/edits via ctx.fs;
+                                emits fs policy events; renders results
+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
+                                guard is OPTIONAL; owns the fs policy event vocabulary
+provider      dsh-fs-local      local implementation of ctx.fs
+```
+
+该模型是叠加式的：裸 `ctx.fs` 执行原子化、无约束的文本 I/O，而 `dsh-fs-policy` 叠加观测状态、先读后编辑和版本守卫。因此移除策略层后工具仍可用，只是不受约束。正式发布的 agent 配置会加载策略；裸模式的存在是为了让策略在服务边界保持可选，而非作为正常部署姿态。
+
+`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` 在其 waterfall（瀑布式事件）处理器中 stat 并比较版本，该检查与工具实际写入之间会存在 TOCTOU 间隙——文件可能在此期间变化，因此该检查只是一个虚假保证，提供方的锁无论如何都要兜底。将版本检查放在提供方的临界区中既无竞态又无额外 `stat`。所以 `dsh-fs-policy` **不做**任何文件系统 I/O；「必须基于最近一次读取」的保证由 CAS *实现*，`dsh-fs-policy` 只负责选择基准（`vObserved`）并对先前观测进行门控。
+
+## 提供方契约变更：版本守卫变为可选
+
+为使裸提供方不受约束，其两个 mutation 上的版本守卫变为**可选**——传入则守卫，省略则无条件执行：
+
+```ts ignore-check
+// writeText: expected is now optional. The FsWriteIntent union is UNCHANGED.
+writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
+//   undefined          → unconditionally create-or-overwrite (bare default)
+//   createIfAbsent     → create only, reject an existing file (dsh-fs-policy, unobserved)   [unchanged]
+//   replaceIfVersion   → overwrite only at the observed version, else FS_STALE_VERSION    [unchanged]
+
+// editText: expected becomes optional (was the required { version: FsVersion }).
+editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
+//   undefined    → unconditionally replace literal text in the current content (bare default);
+//                  a missing target still reports FS_STALE_VERSION
+//   { version }  → edit only at that version, else FS_STALE_VERSION (the current behavior)
+```
+
+`FsWriteIntent` 联合类型本身不变——第三种「无条件」状态通过*省略* `expected` 来表达，因此两个 mutation 共享同一种对称形状（`expected?`：省略 = 无守卫，传入 = 有守卫）。这对 `dsh-fs-policy` 使用的有守卫路径保持完全向后兼容；只有之前不可能出现的「无守卫」情况是新增的，且它是裸提供方的默认行为。无论哪种情况，mutation 仍在后端的 per-target 锁内运行，因此无条件写入/编辑仍是原子的（不会产生撕裂文件）；「无条件」去掉的是*版本*前置条件，而非原子性。`editText` 在有守卫和无守卫路径上都将缺失目标报告为 `FS_STALE_VERSION`，保持一个统一的编辑失败码表示「此刻无法编辑该目标」。
+
+## 事件词汇（由 `dsh-fs` 拥有）
+
+事件定义在 `@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——不携带面向模型的概念（行窗口、行号或渲染后的页脚不会泄漏到此层）。
+
+**两个 `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 结构。
+
+```ts
+import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+
+interface Events {
+  /**
+   * Single-slot decision: produce the write expectation for the next
+   * ctx.fs.writeText. The default returns undefined (unconditional create-or-
+   * overwrite — the bare provider). The policy listener returns createIfAbsent
+   * (unobserved) or { kind: 'replaceIfVersion', version: vObserved } (observed).
+   * The listener does NOT call next(): one decision, not a composable chain. @mode waterfall
+   */
+  'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
+  /**
+   * Single-slot decision: produce the optional version guard for the next
+   * ctx.fs.editText. The default returns undefined (unconditional edit of the
+   * current content — the bare provider; no stat). The policy listener returns
+   * { version: vObserved }, or throws FS_NOT_OBSERVED if the actor is unset or
+   * has not observed the target. Does NOT call next(): one decision. @mode waterfall
+   */
+  '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
+   * 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/*` 决策事件是**由工具分发的无绑定 waterfall**（类似 `agent/request`，由循环分发且无 `this`），而非服务绑定的 waterfall（如 `llm/stream`）。分发者是 `dsh-tool-fs` 插件，它不是一个服务。
+
+## 工具契约（`dsh-tool-fs`）
+
+工具保留其面向模型的 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`；策略插件不得继续作为工具的类型依赖。
+
+`dsh-tool-fs` 是一个注册全部三个工具（`read`/`write`/`edit`）的单一根插件，与 `dsh-tool-bash` 相同。它注入 `fs`（加 `tools`/`systemPrompt`），从不注入 `fileContext`。（最初的提案还将每个工具作为 `/read`/`/write`/`/edit` 子路径插件暴露，供聚焦部署使用；实现时被放弃——没有消费方需要单工具部署，且子路径发布迫使引入兄弟工具包都不需要的定制 `tsdown`/`tsconfig`/`files`/workspace-constraint 处理。每工具的注册辅助函数（`applyReadTool`/`applyWriteTool`/`applyEditTool`）仍作为根插件组合的内部模块保留。）
+
+通过让 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`。
+
+工具在每次分发时将 `exec`（工具执行上下文）作为 `actor` 参数传入，以便 `dsh-fs-policy` 推导其观测状态的 owner。工具不知道策略插件是否存在：它始终在 `next` thunk 中提供裸默认行为，而 `dsh-fs-policy` 在默认部署中会在 thunk 运行前短路它。
+
+**`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`。
+
+- `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)`。
+
+一条观测状态条目是**先前观测记录**：成功的 `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`）
+
+这不是预期的部署姿态——加载 fs 工具的配置预期也会加载 `dsh-fs-policy`。它是工具不再耦合于策略方法服务后所存在的无约束提供方下限。当 `dsh-fs-policy` 不存在时，每个 `fs/*` waterfall 落入其 `undefined` 默认值，`fs/observed` 无监听器：
+
+- **read** 行为不变（它从不需要策略；只是 emit 了一个现在无人监听的 `fs/observed`）。
+- **write** 无条件 create-or-overwrite：`expected` 为 `undefined`，因此 `writeText` 无论文件是否存在、无论当前版本如何都直接写入。无先读要求，无版本检查。
+- **edit** 无条件替换文件当前内容中的字面文本：`expected` 为 `undefined`，因此 `editText` 无版本守卫、无先读要求地匹配并重写（`FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` 仍适用——它们关乎字面匹配，而非新鲜度）。缺失目标仍报告 `FS_STALE_VERSION`，与有守卫编辑路径的「此刻无法编辑该目标」错误码一致。
+
+两个 mutation 仍是原子的（后端的 per-target 锁是无条件的）。仅仅是*不存在*（而非丢失）的是 `dsh-fs-policy` 本会叠加的策略：观测状态、先读后编辑和版本守卫的写入/编辑。加载 `dsh-fs-policy` 后，其监听器返回有守卫的 `expected` 值而非 `undefined`，从而叠加这些约束；裸提供方本身无需任何变更。
+
+## 取代关系
+
+本 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` 的描述已在同一变更中更新。
+
+## 验证
+
+测试固定了两条路径：无 `dsh-fs-policy` 时，根工具插件对 `dsh-fs-local` 启动，read、create、overwrite 和未读 edit 均成功；有策略时，未读 edit 返回 `FS_NOT_OBSERVED`，未读 overwrite 被 `createIfAbsent` 门控。策略决定后，后注册的 intent 监听器不会被触达。陈旧编辑通过提供方 CAS 失败，而策略不执行 `stat`；工具预算在两条路径上保持 read 一次 `stat`，write 或 edit 均为零次。面向模型的 schema 逐字节不变，因此快照不变。
+
+## 曾考虑的替代方案
+
+- **保留 `ctx.fileContext` 作为关键路径上的方法服务**——[拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 最初落地的形态；否决，因为工具无法在没有策略层的情况下运行，使策略对基本操作是承重性的，而非可选的收紧。
+- **策略侧版本检查**（`dsh-fs-policy` 在其 waterfall 处理器中 stat 并比较版本）——否决，因为该检查与工具实际写入之间存在 TOCTOU 间隙；提供方的 mutation 临界区是唯一无竞态的位置，因此策略只选择 CAS 基准并对先前观测进行门控。
+- **每工具 `/read`/`/write`/`/edit` 子路径插件**——实现时放弃：没有消费方需要单工具部署，且子路径发布迫使引入兄弟工具包都不需要的定制 `tsdown`/`tsconfig`/`files`/workspace-constraint 处理；每工具的注册辅助函数仍作为根插件组合的内部模块保留。
+
+## 后果
+
+- **事件间接层取代方法调用。** 一次 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`。
+- **移除读后确认 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
new file mode 100644
index 0000000000..51d0eb9a78
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-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
+2026-06-30-bash-stdin-env-trusted-plugin-surface.md: 284cd45a66294dbc9e8207a1e00e9642d32d4e58
+2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 9486f8c35c5060150b072fb673acca5d4167ec1a
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 cc1de3c53e..284cd45a66 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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.
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
new file mode 100644
index 0000000000..9486f8c35c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 在 bash seam 上支持 stdin 与额外 env
+
+Status: implemented
+
+[English](2026-06-30-bash-stdin-env-trusted-plugin-surface.md) | 中文
+
+## 问题
+
+钩子子系统以 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)。
+
+## 决策
+
+在 `BashExecRequest`（模型/插件侧请求）和 `BashExecSpec`（`run`/`start` 所作用的已解析 spec）上**同时**添加 `stdin?: string` 与 `env?: Record<string, string>`，并在 `dsh-bash-local` 中贯穿它们：`resolve()` 原样传递，`run()`/`start()` 将其传给 `runBash`，后者把字节写入子进程的 stdin 并合并额外 env。
+
+三个有意为之的选择：
+
+1. **模型侧工具不暴露 `stdin` 和 `env`。** Shell 语法已覆盖这些需求，重复参数只会增加接口面而不带来权限隔离。工具仅从声明的模型参数、signal 和 owner 构建请求；受信的进程内调用方可以直接设置 seam 字段。harness 自有变量使用[托管环境决策](../feature/2026-07-10-agent-session-identity-and-log-location.md)规定的独立 `dshEnv` 通道，因此普通 `env` 无法替换它们。
+
+2. **`env` 在凭证擦除之后合并，因此调用方显式设置的条目即使具有凭证形态的名称也会胜出。** 后续的托管命名空间决策保留 `DSH_*`：环境条目会被移除，普通 `env` 无法设置它们，受信的 `dshEnv` 最后合并。完整顺序为 `scrub(process.env, including DSH_*)` → `ENV_OVERRIDES` → 普通 `env` → `dshEnv`。
+
+3. **`stdin`/`env` 在已解析 spec 上是 required-absent-OK（普通 optional），而非像 `owner` 那样 required-but-nullable。** `owner` 之所以是 required-but-nullable，是因为*静默*缺失的 owner 会产生一个无主、跨会话可读的任务——一个安全隐患，显式的 `undefined` 可以防范。`stdin`/`env` 没有这种风险：缺失意味着「无 stdin / 无额外 env」，这是安全的常规情况（所有模型驱动的调用都如此）。因此它们保持普通 optional，与 `signal` 一致。
+
+`dsh-bash-local` 仅在有字节需要写入时才创建 stdin 管道；否则 fd 0 仍为 `/dev/null`，保持先前行为。它写入字节后关闭管道。子进程未读取即退出时产生的 `EPIPE` 被忽略，因为命令退出码和输出决定结果。
+
+## 曾考虑的替代方案
+
+**可配置的环境秘密擦除。** 否决，属于推测性需求。受信调用方可以在擦除之后显式提供所需值，无需削弱默认的环境保护。
+
+## 后果
+
+钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量，保留其进程组终止、截断和溢出行为。模型接口面不变，bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/core-data-structures/bash.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
new file mode 100644
index 0000000000..2da1519019
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-30-event-domain-semantics.md: 7310840088d4ff77ddf83c5c16753b4d46256692
+2026-06-30-event-domain-semantics.zh.md: 61d99878ab5e04b74d55d02789c434e0919bd785
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 56c3fdf231..7310840088 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-30-event-domain-semantics.zh.md)
+
 ## Problem
 
 The harness extends the agent loop through a Cordis event taxonomy (see [the microkernel event-taxonomy Agent Note](2026-06-11-microkernel-event-taxonomy.md)). As that taxonomy grew, the line between the three event domains blurred:
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
new file mode 100644
index 0000000000..61d99878ab
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 事件域语义——会话是事实日志，agent 是运行时表面
+
+Status: implemented
+
+[English](2026-06-30-event-domain-semantics.md) | 中文
+
+## 问题
+
+harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）（见[微内核事件分类体系 Agent Note](2026-06-11-microkernel-event-taxonomy.md)）。随着该分类体系的增长，三个事件域之间的界限变得模糊：
+
+- `session/*` 承载持久的、事件溯源的日志（`SessionEventMap`）。
+- `agent/*` 承载运行时实时信号，向插件传递 `Agent` 句柄。
+- `tools/*` 承载工具注册表与执行 seam。
+
+两个问题促使我们固定语义。第一，若干轮次/步骤边界同时作为持久的 `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 桥接的基础。
+
+## 决策
+
+**三个域，各司其职，以一条边界规则统一。**
+
+- **`session/*`——持久的、可回放的事实日志。** 拥有 `SessionEventMap`；每条记录仅含 JSON（无活对象）。每次追加触发一次 `session/event` emit，加上 `session/flush` 并行持久性检查点。它同时也是实时 transcript（文本记录）源：想渲染或响应已发生事件的消费方在此订阅，因此实时渲染与 `session/load` 回放共享同一路径。
+- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。两种形态：拦截 waterfall（瀑布式事件）（`agent/request`、`agent/step-result`、`agent/turn-continuation`）可变更或否决；瞬态 emit（`agent/status`、`agent/error`、`agent/created`/`agent/disposed`、`agent/queued`）在持有 `Agent` 的情况下通知。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和中途 steering（中途引导）（`steering/message`）同理。
+- **`tools/*`——工具注册表与执行 seam。**
+
+**边界规则：** 持久的、可回放的事实是 `SessionEvent`；实时拦截或瞬态/活对象信号是 `agent`/`tools` Cordis 事件。轮次或步骤边界是持久事实，因此存在于会话日志中并从 `session/event` 源读取——不会被镜像为 `agent/*` emit。
+
+**将规则应用于边界镜像：** 全部四个边界镜像——`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`——被**移除**。没有生产消费方需要在边界处获取活的 `Agent`：ACP 桥接从 `session/event` 的 `turn/end` 加 `agent/status` 结算；唯一的轮次镜像消费方（`dsh-ui-stdio`，一个一次性测试 REPL）从 `session/event` 渲染边界，同时保留其实时目标对象用于固定的 `main` 标签。步骤镜像先被移除（它们完全没有消费方）；轮次镜像在 ui-stdio 迁移后随之移除，见[移除边界镜像事件 Agent Note](../simplification/2026-06-20-remove-agent-boundary-mirror-events.md)，该决策由它负责。移除 emit 也简化了循环的 `closeStep`/`closeTurn`（各只需一次 append，无需配对 emit）。
+
+## 后果
+
+- 循环不再 emit 任何边界镜像；`closeStep` 仅追加 `step/end`，`closeTurn` 仅追加 `turn/end`。`Session.append` 负责 post-commit observer 隔离，因此抛出异常的边界 observer 无法改变轮次结果或饿死后续消费方；接受或内部校验失败仍会在边界进入日志之前逃逸。
+- 之前通过已移除 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](../simplification/2026-07-04-remove-agent-steering-mirror.md) 单独移除——它镜像的是持久的 `steering/message`。
+- Cordis 事件目录（`docs/cordis-catalog/events.md`）重新生成以移除镜像事件。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..74c94e5b4f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-02-fs-per-session-cwd.md: aeb17e0a235720bee277f6533468dbdb6cae82dc
+2026-07-02-fs-per-session-cwd.zh.md: b9ad4b868c472c8feb9e6f65e42b1658ffdcd2e0
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 0a6d9b85b1..aeb17e0a23 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-02-fs-per-session-cwd.zh.md)
+
 ## Problem
 
 The ACP bridge gives every session its own workspace: `session/new` records the editor's project directory as `SessionHeader.cwd`, and `dsh-tool-bash` defaults each bash call's `workdir` to the calling agent's `session.header.cwd` (see [the per-session cwd Agent Note work in `packages/ui/acp`](../../../../packages/ui/acp) and `resolveWorkdir` in `dsh-tool-bash`). So a bash command in session A runs in A's project, and in session B runs in B's — one server process, N workspaces.
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
new file mode 100644
index 0000000000..b9ad4b868c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 相对文件系统路径按调用方的会话 cwd 解析
+
+Status: implemented
+
+[English](2026-07-02-fs-per-session-cwd.md) | 中文
+
+## 问题
+
+ACP（Agent Client Protocol）桥接层为每个会话提供独立的工作区：`session/new` 将编辑器的项目目录记录为 `SessionHeader.cwd`，`dsh-tool-bash` 将每次 bash 调用的 `workdir` 默认设为调用方 agent（智能体）的 `session.header.cwd`（见 [`packages/ui/acp`](../../../../packages/ui/acp) 中的每会话 cwd Agent Note 工作与 `dsh-tool-bash` 中的 `resolveWorkdir`）。因此会话 A 中的 bash 命令在 A 的项目目录执行，会话 B 中的在 B 的项目目录执行——一个服务器进程，N 个工作区。
+
+文件系统解析使用的是插件加载时的 cwd，而 bash 使用的是会话的项目目录。因此，当编辑器项目目录与服务器启动目录不同时，相对路径的解析结果就会不一致；快照测试因为让这两个路径相同而掩盖了这个 bug。
+
+一个有效的绝对 cwd 本身可能看起来有两个父目录：当它包含 `symlink/..` 时，文件系统查找会先跟随符号链接再应用 `..`，而 `path.resolve()` 会从词法上抹掉这两个组件。如果用词法解析沙箱策略却从原始 cwd 启动 bash，就会把权限授予无关的词法父目录、拒绝真实工作区内的写入，并让文件系统工具把相对路径解析进错误目录。
+
+普通的符号链接 cwd 在请求的相对路径包含 `..` 时也暴露同一区别：进程从符号链接的物理目标开始遍历，`path.resolve(cwd, path)` 却从其词法拼写开始遍历。因此，对于同一个模型提供的路径，read 会选择与 bash 或沙箱化 mutation 不同的文件。
+
+## 决策
+
+将调用方的会话 cwd 传入路径解析，与 `dsh-tool-bash` 对 `workdir` 的处理方式完全一致。当 cwd 或请求路径任一包含父目录段时，在任何词法 join 之前把 cwd 解析为原生文件系统标识；没有遍历会使标识可观察时，则保留普通 cwd 拼写以供展示。mutation 和沙箱化 bash 调用复用解析后的沙箱策略根目录，使一次调用只有一个工作区标识。**调用方**（即工具）提供 cwd；提供方不读取会话或 agent。
+
+- `FileSystem.resolve` 接受 `resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>`。`opts.cwd` 是相对 `path` 解析时的基准目录；绝对 `path` 忽略它；省略 `opts.cwd` 则使用后端自身的默认值。后端执行 I/O 时，`opts.signal` 可以取消解析。options 对象把调用方拥有的两个解析控制项放在一起，避免位置参数继续增长。
+- `dsh-fs-local.resolve` 使用 `resolveLocalTarget(opts?.cwd ?? this.config.cwd, path)`。`config.cwd` 仍作为调用方未提供 cwd 时的默认值（非 ACP／无会话场景，以及 `process.cwd()` 本身就是工作区的单会话 stdio 演示）。
+- `dsh-tool-fs` 的 `read`/`write`/`edit` 通过共享的 `sessionCwd(exec, requestedPath)` 辅助函数（`exec.agent?.session.header.cwd`，与 bash 的 `resolveWorkdir` 对应）获取会话 cwd，并传给 `resolve`。只要任一值中的父目录段可能跨越符号链接，该辅助函数就使用原生 realpath 语义，否则保留普通拼写；沙箱化 mutation 复用完整策略的 `workspaceRoot`；非 agent／无 header 的调用方得到 `undefined`，后端因此应用其默认值。
+
+## 曾考虑的替代方案
+
+### 为何由调用方（而非提供方）提供 cwd
+
+提供方 seam 不得依赖 `dsh-agent`／`dsh-session`——它是一个文本存储后端，沙箱或远程实现同样满足该接口，而这些实现没有「agent 会话」的概念。工具已经接收了 `ToolExecution`（`exec`），其中携带 agent，因此工具是将 `exec → cwd` 投影并向提供方传递一个纯字符串的正确位置。这遵循「包（package）边界处显式优于隐式」的约定：基准目录作为显式参数传入，提供方据此行动，而非让提供方越界去读取它不应知晓的会话。这也与 `dsh-tool-bash` 一一对应，使两个面向模型的文件操作接口以相同方式解析路径。
+
+默认值只存在于一个地方——提供方的 `config.cwd`。`sessionCwd` 在没有会话时返回 `undefined` 而非 `process.cwd()`，因此工具永远不会自行制造一个提供方本应自行选择的基准目录。
+
+## 后果
+
+- 在 ACP 演示中，fs 工具与 bash 现在对每个会话的工作区达成一致；编辑器可以打开任意项目目录，两类工具都在该目录下操作。
+- 对于包含 `symlink/..` 的会话 cwd，或普通符号链接 cwd 搭配含父目录遍历的相对路径，bash、文件系统工具和沙箱授权都会从同一个物理工作区解析；词法父目录不会获得授权。
+- `FsTarget` 的标识不变：`targetKey` 仍为解析后绝对路径的 realpath，因此 observed-state 键控与符号链接标识不受影响——正确的每会话 cwd 产生与 bash 目标相同的 key。
+- 向后兼容：所有现有的 `resolve(path)` 调用（均在测试中）继续正常工作；新参数是可选的。
+- 单会话 stdio 演示不受影响：它不提供会话 cwd（其 agent 的会话没有 `cwd`），因此解析回退到 `config.cwd = process.cwd()`，即工作区本身。
diff --git a/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.i18n.yaml
new file mode 100644
index 0000000000..632ba388a2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-02-result-time-applied-hunk-diffs.md: fe163484ad56858fabd55dacace1d56814bd93e4
+2026-07-02-result-time-applied-hunk-diffs.zh.md: e8283a40d96c031a84e2627117801b3043eb8904
diff --git a/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md b/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md
index 8ddd1e8941..fe163484ad 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-02-result-time-applied-hunk-diffs.zh.md)
+
 ## Problem
 
 The [tagged render-intent union](2026-07-02-tool-render-intent-union.md) gave `dsh-tool-fs` write/edit a `card:'diff'` at CALL time, derived purely from the tool's args: write ⇒ `{oldText:null, newText:content}` (the whole new file), edit ⇒ `{oldText:old_string, newText:new_string}` (the bare replaced snippet). An editor renders that as an inline diff, but it is a **context-free** diff — the bare `old_string`→`new_string` with no surrounding lines, and a `replace_all` that touched five scattered sites still renders as one snippet pair.
@@ -14,24 +16,20 @@ The obstacle is a seam boundary: `presentResult(args, result)` is a **pure funct
 
 Add a **persisted, tool-private presentation channel** so a tool's `execute` can attach a result-time render payload that survives replay, and use it to carry the applied-hunk diff.
 
-### 1. A `meta` channel on the tool result (core)
+### 1. A replayable presentation projection on canonical tool output (core)
 
-`ToolDefinition.execute` may now return either its model-facing `ContentBlock[]` (unchanged, the common case) OR `{ content: ContentBlock[]; meta?: unknown }`:
+The original implementation let `execute` return `{ content, meta }`. The [canonical tool-output contract](2026-07-20-canonical-tool-output-contract.md) supersedes that authoring shape: every tool now returns one schema-declared JSON value, `output.render(args, value)` derives model-facing blocks, and optional `output.presentationMeta(args, value)` derives replayable UI data.
 
-```ts ignore-check
-type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown }
-```
+`presentationMeta` is tool-owned `JsonValue` that the core persists without interpreting its fields. `Session.append` validates it with the rest of the event, and replay passes the stored payload back to `presentResult`; presentations therefore reproduce without I/O or recomputation. The canonical value itself remains execution-local and is not added to the session format.
 
-`meta` is tool-owned `unknown` that the core persists without interpretation. `Session.append` rejects non-JSON values, and replay passes the stored payload back to `presentResult`; presentations therefore reproduce without I/O or recomputation. Runtime validation avoids adding a shared serializable-value dependency to the tools core.
-
-This is the general shape ("a tool attaches durable result presentation"), not an fs-specific one — any tool can use it.
+This remains the general shape ("a tool projects durable result presentation"), not an fs-specific one—any tool can use it.
 
 ### 2. The tool computes the hunk; the backend returns before/after (fs)
 
 Per the [capability-seam split](2026-06-13-capability-seams.md), the storage backend returns only **storage facts** and the model-facing tool owns **presentation**:
 
 - `dsh-fs` widens `FsEditOutcome` with `{ before: string; after: string }` and `FsWriteOutcome` with `{ before: string | null; after: string }` (`before: null` ⇒ a create, or an existing-but-undiffable binary/non-UTF-8 file). The local backend already holds both texts at write time; it returns them as raw LF-normalized text, with **no diff/UI concept** entering the seam.
-- `dsh-tool-fs` stores contextual hunks in `meta: { diffs: FileDiff[] }`. Successful mutations always complete with a diff card because ACP result content replaces the pending card: creates or unchanged overwrites fall back to an args-derived whole-file diff, while edits use applied hunks. Failed mutations carry no diff metadata and render their error normally.
+- `dsh-tool-fs` returns canonical before/after mutation facts and projects contextual hunks as `meta: { diffs: FileDiff[] }`. Successful mutations always complete with a diff card because ACP result content replaces the pending card: creates or unchanged overwrites fall back to an args-derived whole-file diff, while edits use applied hunks. Failed mutations carry no diff metadata and render their error normally.
 
 ### 3. The bridge renders a `diff` result card
 
@@ -43,7 +41,7 @@ Per the [capability-seam split](2026-06-13-capability-seams.md), the storage bac
 
 ## Consequences
 
-`tool/result` events may now carry a tool-private `meta` payload — part of the on-disk vocabulary, runtime-gated to JSON by `Session.append` — and any tool can attach durable result presentation without another core change. The diff card reproduces on session reload and snapshot replay for free: it is read back from the log, never recomputed. The costs: an overwrite holds both the prior and new text in memory to compute a UI-only hunk (`TODO(overwrite-diff-bound)`), and `dsh-tool-fs` carries a small, well-known runtime dependency.
+`tool/result` events carry a tool-private `meta` payload—part of the on-disk vocabulary, runtime-gated to JSON by `Session.append`—and any tool can project durable result presentation without another core change. The diff card reproduces on session reload and snapshot replay for free: it is read back from the log, never recomputed. The costs: an overwrite holds both the prior and new text in memory to compute a UI-only hunk (`TODO(overwrite-diff-bound)`), and `dsh-tool-fs` carries a small, well-known runtime dependency.
 
 ## Non-goals
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.zh.md b/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.zh.md
new file mode 100644
index 0000000000..e8283a40d9
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.zh.md
@@ -0,0 +1,57 @@
+# Agent Note: 结果时刻的 applied-hunk diff 用于文件变更
+
+Status: implemented
+
+[English](2026-07-02-result-time-applied-hunk-diffs.md) | 中文
+
+## 问题
+
+[带标签的 render-intent 联合类型](2026-07-02-tool-render-intent-union.md)为 `dsh-tool-fs` 的 write/edit 在调用时刻提供了 `card:'diff'`，纯粹从工具参数推导：write ⇒ `{oldText:null, newText:content}`（整个新文件），edit ⇒ `{oldText:old_string, newText:new_string}`（裸替换片段）。编辑器将其渲染为行内 diff，但这是一个**无上下文**的 diff：裸的 `old_string`→`new_string` 没有周围行，而一次触及五个分散位置的 `replace_all` 仍然渲染为一对片段。
+
+在对接 `claude-agent-acp` 自身的 ACP（Agent Client Protocol） bridge 时可以看到完整编辑器 diff 的样子：变更应用后，它发出第二个 `tool_call_update`，其 diff 是**带 ±3 行上下文的 applied hunk**（`replace_all` 的每个变更位置各一个 hunk），由工具的 `structuredPatch` 重建。这个结果时刻的 hunk 正是让 Zed 在文件中*原位*显示变更（而非浮动片段）的关键。我们的工具止步于调用时刻的片段；完成后的结果只携带纯文本「updated successfully」，没有 diff。
+
+障碍在于一个 seam 边界：`presentResult(args, result)` 是 **`args` + 面向模型的 `result`（`{content, isError}`）的纯函数**——它在实时流式输出和会话日志回放中都会运行，因此必须具备回放确定性且不能做 I/O。它看不到文件的前后内容，而 `FsEditOutcome`/`FsWriteOutcome` 只携带替换计数和版本号，没有文本。因此无法计算——甚至无法携带——applied hunk 给 presenter。
+
+## 决策
+
+添加一个**持久化的、工具私有的展示通道**，使工具的 `execute` 能附加一个结果时刻的渲染载荷并在回放中存活，并用它来携带 applied-hunk diff。
+
+### 1. 规范工具输出上的可回放展示投影（core）
+
+原始实现允许 `execute` 返回 `{ content, meta }`。[规范工具输出契约](2026-07-20-canonical-tool-output-contract.md)取代了这种编写形态：每个工具如今返回一个由 schema 声明的 JSON 值，`output.render(args, value)` 从中派生面向模型的内容块，可选的 `output.presentationMeta(args, value)` 则派生可回放的 UI 数据。
+
+`presentationMeta` 是工具自有的 `JsonValue`，core 会持久化它，但不解释其中的字段。`Session.append` 将它与事件的其余部分一并校验，回放再把存储的载荷传回 `presentResult`；因此展示无需 I/O 或重新计算即可复现。规范值本身只存在于执行期间，不会加入会话格式。
+
+这仍是通用形态（「工具投影持久化的结果展示」），而非 fs 特有；任何工具都可以使用。
+
+### 2. 工具计算 hunk；后端返回 before/after（fs）
+
+按照 [capability-seam 拆分](2026-06-13-capability-seams.md)，存储后端只返回**存储事实**，面向模型的工具拥有**展示**：
+
+- `dsh-fs` 将 `FsEditOutcome` 扩展为包含 `{ before: string; after: string }`，将 `FsWriteOutcome` 扩展为包含 `{ before: string | null; after: string }`（`before: null` 表示创建，或已存在但不可 diff 的二进制/非 UTF-8 文件）。本地后端在写入时已持有两份文本；它以原始 LF 规范化文本返回，**不让任何 diff/UI 概念进入 seam**。
+- `dsh-tool-fs` 返回规范的变更前／后事实，并将上下文 hunk 投影为 `meta: { diffs: FileDiff[] }`。成功的变更始终以 diff 卡片完成，因为 ACP 结果内容会替换待定卡片：创建或无变化的覆写回退到由参数推导的整文件 diff，而编辑使用 applied hunk。失败的变更不携带 diff 元数据，正常渲染其错误信息。
+
+### 3. Bridge 渲染 `diff` 结果卡片
+
+`ToolResultView` 新增 `DiffResultView { card:'diff'; title?; diffs: FileDiff[] }`；bridge 结果侧的 `switch (view.card)` 增加 `diff` 分支，发出 `{type:'diff'}` 的 `ToolCallContent` 块（与调用侧分支对称）。ACP 的 `tool_call_update.content` 在编辑器中替换调用时的内容，因此结果 diff **取代**调用时刻的片段（并防止面向模型的结果文本覆盖它）——两次更新序列（先调用片段，再结果 diff）与 `claude-agent-acp` 完全一致。
+
+## 曾考虑的替代方案
+
+**手写或 vendor diff 算法。** 上下文 hunk 有已知的边界情况，因此 `dsh-tool-fs` 使用带类型的 [`diff`](https://www.npmjs.com/package/diff) 包，并在一个模块中规范化 `structuredPatch` 输出。仓库的 vendor 策略适用于框架源码，而非每个叶子工具库。
+
+## 后果
+
+`tool/result` 事件携带工具私有的 `meta` 载荷；它属于磁盘格式词汇的一部分，由 `Session.append` 在运行时限制为 JSON。任何工具都可以投影持久化的结果展示，无需再改 core。diff 卡片在会话重载和快照回放时免费复现：它从日志中读回，从不重新计算。代价：覆写操作在内存中同时持有旧文本和新文本以计算仅用于 UI 的 hunk（`TODO(overwrite-diff-bound)`），且 `dsh-tool-fs` 引入了一个小型、知名的运行时依赖。
+
+## 非目标
+
+- **实时增量 diff 流式输出。** hunk 在变更完成后一次性计算；没有逐键 diff。
+- **对二进制/非 UTF-8 覆写做 diff。** 此类文件的 `before` 为 `null`（没有文本 diff 基础）；写入仍然成功，结果渲染整文件 diff（`oldText: null`）而非上下文 hunk。
+- **重命名/移动 diff。** 仅限单个已解析路径的内容 diff。
+- **限制覆写 diff 基础的大小。** 覆写操作将整个旧文件读入内存以计算上下文 hunk（加上已持有的新内容），因此非常大的文本覆写会为仅 UI 用途的 diff 分配两份文本。未来的改进可以设定预读上限，超过阈值时回退到整文件/无上下文 diff；在读取位置以 `TODO(overwrite-diff-bound)` 跟踪。
+
+## 相关
+
+- 补全了[带标签的 render-intent 联合类型](2026-07-02-tool-render-intent-union.md)中作为非目标列出的最后一项表示差异——该 Agent Note 的「非目标」一节已更新，记录 applied-hunk diff 在此处交付。
+- 基于[文件系统 capability seam](2026-06-17-filesystem-capability-seam.md)（before/after 是后端返回的存储事实）和[事件溯源会话](2026-06-11-event-sourced-sessions.md)（`meta` 载荷持久化在 `tool/result` 事件上，因此回放可复现卡片）。
+- `meta` 通道有意设计为通用的：未来的工具（结构化搜索、数据表结果）可以附加自己的持久化结果展示而无需再改 core。
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
new file mode 100644
index 0000000000..c4e769f684
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-02-tool-render-intent-union.md: c7adf8f405000ec7940f82e1e1e2406d86253461
+2026-07-02-tool-render-intent-union.zh.md: 01dff0daaacc45f5c85eb2c4380dc78800ce9a81
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 9d7fac0471..c7adf8f405 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-02-tool-render-intent-union.zh.md)
+
 ## Problem
 
 A tool declares how its calls render in a UI (an editor's tool-call card) through two callbacks, `presentCall`/`presentResult` on `ToolDefinition`, returning `ToolCallPresentation` / `ToolResultPresentation` with an optional `ToolTerminal` sub-shape. These grew incrementally into a **bag of optional fields**: `title`, `kind`, `rawInput`, `content`, `locations`, `terminal` on the call; `title`, `content`, `terminal` on the result; `cwd`/`output`/`exitCode`/`signal` on `ToolTerminal`. The split of responsibility is muddy:
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
new file mode 100644
index 0000000000..01dff0daaa
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
@@ -0,0 +1,82 @@
+# Agent Note: 用于工具调用展示的带标签 render-intent 联合类型
+
+Status: implemented
+
+[English](2026-07-02-tool-render-intent-union.md) | 中文
+
+## 问题
+
+工具通过 `ToolDefinition` 上的两个回调 `presentCall`/`presentResult` 声明其调用在 UI（编辑器的工具调用卡片）中如何渲染，返回 `ToolCallPresentation` / `ToolResultPresentation`，并带有一个可选的 `ToolTerminal` 子结构。这些类型在增量演进中变成了一个**可选字段的集合**：调用侧有 `title`、`kind`、`rawInput`、`content`、`locations`、`terminal`；结果侧有 `title`、`content`、`terminal`；`ToolTerminal` 上有 `cwd`/`output`/`exitCode`/`signal`。职责划分模糊不清：
+
+- 调用侧和结果侧的 `terminal` 字段重叠，bridge 需要将每次调用的 `content` 块、`terminal` 块和 `rawInput` 用临时条件逻辑拼接在一起。
+- 哪些组合是*合法的*没有文档说明：一个设置了 `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 拼接的可选字段。」被否决的 Agent Note [折叠工具拥有的 UI 呈现](../../rejected/simplification/2026-06-20-generic-tool-rendering.md)明确推迟了此事：富渲染「应当在至少有两个真实工具和两个真实消费方验证词汇之后，以带标签 render-intent 联合类型的形式回归。」该条件现已满足：两个生产者族（`dsh-tool-bash`、`dsh-tool-fs`）和两个消费方（ACP bridge 实时路径 + 快照回放路径）。
+
+## 决策
+
+用一个**以 `card` 为标签的可辨识联合类型**替代可选字段集合。工具为每次调用/结果声明一个渲染意图；bridge 根据标签分发。
+
+```ts ignore-check
+type FileLocation = { path: string; line?: number }
+type FileDiff = { path: string; oldText: string | null; newText: string } // oldText null ⇒ new file
+
+// presentCall → ToolCallView
+type ToolCallView = GenericCallView | TerminalCallView | DiffCallView
+interface GenericCallView { card: 'generic'; title: string; kind?: ToolCallKind; rawInput?: unknown; content?: ContentBlock[]; locations?: FileLocation[] }
+interface TerminalCallView { card: 'terminal'; title: string; description?: string; cwd?: string }
+interface DiffCallView { card: 'diff'; title: string; diffs: FileDiff[]; locations?: FileLocation[] }
+
+// presentResult → ToolResultView
+type ToolResultView = GenericResultView | TerminalResultView
+interface GenericResultView { card: 'generic'; title?: string; content?: ContentBlock[] }
+interface TerminalResultView { card: 'terminal'; title?: string; output?: string; exitCode?: number; signal?: string }
+```
+
+`card` 在每个变体上都是**必填**的——真正的判别式，而非可选默认值。bridge 执行 `switch (view.card) { case 'generic': … case 'terminal': … case 'diff': … default: assertNever(view) }`。该联合类型是**封闭的**（遵循 [switch 穷举约定](../../../../AGENTS.md)）：第四种渲染意图（表格、图表）无论如何需要新的 bridge 代码来渲染，因此一个由插件添加但被 bridge 静默丢弃的变体，比编译错误更糟糕。新增变体会在 bridge 的 switch 处中断编译——这正是我们想要的信号。
+
+### 为什么带标签联合类型优于字段集合
+
+- **无效状态变得不可表达。** generic 卡片不能携带终端输出；terminal 卡片不能携带 diff。旧的字段集合允许所有这些组合。
+- **bridge 分发而非拼接。** 每种卡片一个分支，各自精确产出该卡片所需的协议格式（wire format），而非调和五个交互关系未文档化的可选字段。
+- **`diff` 成为一等意图。** `dsh-tool-fs` 的 write/edit 声明 `card:'diff'`；bridge 输出 ACP `{type:'diff', path, oldText, newText}` 的 `ToolCallContent`（已存在于 SDK 的 `ToolCallContent` 联合类型中，此前 bridge 未使用）。这正是本次重设计解锁的能力。
+
+### 生产者映射
+
+- `dsh-tool-fs` read → `generic`（`kind:'read'`，附带一个 follow-along `location`）；write → `diff`（`oldText:null`）；edit → `diff`（`oldText:old_string || null`，`newText:new_string ?? ''`）。这与 `claude-agent-acp` 的 `toolInfoFromToolUse` 中 Read/Write/Edit 各分支逐字段对应。
+- `dsh-tool-bash` foreground → `terminal` 调用 + `terminal` 结果；`run_in_background` → `generic`。通用 `task_*` 控制工具拥有各自的 generic 卡片。
+- `dsh-tool-todo` → `generic`。
+
+### 终端回退的归属
+
+`TerminalResultView` 只携带 `output`/`exitCode`/`signal`。不具备终端能力的 UI 需要一个围栏 ` ```console ` 文本回退；该推导移至 **bridge**（在无能力路径上将 `output` 包裹在围栏代码块中），而非由工具双重编码。这使 bash 工具的结果保持单一结构化形状，并逐字节保留既有的能力门控行为。
+
+### 纯函数性保持不变
+
+`presentCall`/`presentResult` 仍然是 `args`（`presentResult` 还有 result）的纯函数——它们在实时流式输出和会话日志回放中都会运行，因此必须具备回放确定性。每个 view 仅从 args 推导：write 的 diff 是新文件风格（`oldText:null`），因为工具在调用时没有旧内容；edit 的 diff 是 `old_string`→`new_string`。
+
+## 相对路径显示标题
+
+`claude-agent-acp` 将文件卡片标题中的路径相对于会话 cwd 做缩短处理（`toDisplayPath`）——显示 `Read src/foo.ts` 而非 `/abs/proj/src/foo.ts`——同时保持 `locations[]`/`diff.path` 为**原始路径**（编辑器打开真实路径）。我们的 `presentCall` 是纯函数/仅依赖 args，无法访问会话 cwd，因此这一相对化处理发生在 **bridge**，bridge 已经将会话 cwd 传入工具调用渲染逻辑（与它用于解析 terminal 卡片标题的 cwd 相同）。bridge 仅对标题做相对化，方式是对已知的 `locations[0].path`/`diffs[0].path` 子串做精确的结构化替换——对所有文件卡片类型通用，从不针对工具名做特殊处理。
+
+## 曾考虑的替代方案
+
+- **完全删除工具自有的展示**：即[被否决的 collapse 提案](../../rejected/simplification/2026-06-20-generic-tool-rendering.md)；其自身的结论正是推迟到两个真实工具和两个真实消费方存在后再做此联合类型，该条件现已满足。
+- **可合并扩展的联合类型**（`ContentBlockMap` 模式）：否决。新的渲染意图无论如何需要新的 bridge 代码来渲染，因此一个被 bridge 静默丢弃的插件添加变体，比封闭联合类型在 bridge 的 `assertNever` switch 处引发的编译错误更糟糕。
+- **保留可选字段集合**：即「问题」一节所剖析的现状：无效状态可表达、字段交互无文档、且完全无法请求 diff 卡片。
+
+## 后果
+
+新的渲染意图会在 bridge 的 switch 处引发编译中断——这是有意为之：渲染代码必须先于卡片种类存在。无效的卡片/字段组合现已不可表达，bash 回退推导归 bridge 所有，工具只返回一个结构化形状。第四种卡片（表格、图表）的门槛是在同一个变更中编写其 bridge 分支。
+
+## 非目标
+
+- **实时增量 `terminal_output_delta` 流式输出**与**命令分类**：终端渲染 Agent Note 自身推迟的后续工作，本 Agent Note 不涉及。
+
+## 相关
+
+- 取代[折叠工具拥有的 UI 呈现](../../rejected/simplification/2026-06-20-generic-tool-rendering.md)（已否决——「等两个真实工具和两个真实消费方，然后做带标签 render-intent 联合类型」）中的推迟决定。该条件现已满足；本 Agent Note 即为那个联合类型。
+- 被[结果时已应用 hunk 差异](2026-07-02-result-time-applied-hunk-diffs.md)扩展：后者添加了一个持久化的 `meta` 通道，使 write/edit 在结果时输出 `DiffResultView`（应用后的变更：带上下文行的 contextual hunk / 每个 `replace_all` 位点一个，或创建时的整文件 diff），叠加在本联合类型的调用时 diff 卡片之上。
+- 将 `ToolTerminal` 折入 [ACP terminal 与工具调用渲染](../feature/2026-06-18-acp-terminal-and-tool-rendering.md)所描述的 `terminal` view（`_meta` terminal 卡片约定和能力门控不变；仅 harness 侧的展示类型改变）。
+- ACP SDK 的 `Diff` / `ToolCallContent` 类型支撑新的 `diff` 卡片。
diff --git a/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.i18n.yaml
new file mode 100644
index 0000000000..0a8c0d62fa
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-03-filesystem-directory-listing-seam.md: c7db576ff3c7a56622f90a4400bd9297c9591bef
+2026-07-03-filesystem-directory-listing-seam.zh.md: 75ee6851127ca6d8c3fc60a66115d521d4627cdc
diff --git a/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md b/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md
index d40c50695d..c7db576ff3 100644
--- a/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-03-filesystem-directory-listing-seam.zh.md)
+
 ## Problem
 
 `@deepseek-ai/dsh-fs` is the provider seam for filesystem access, with local and future non-local backends behind the same `ctx.fs` contract. Before this change it could resolve paths, stat targets, read text, stream text, write text, and edit text. That was enough for model-facing file tools, but not for non-model-facing consumers that need to enumerate directories without importing `node:fs`.
diff --git a/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.zh.md
new file mode 100644
index 0000000000..75ee685112
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.zh.md
@@ -0,0 +1,53 @@
+# Agent Note: 为文件系统 seam 添加直接目录列举能力
+
+Status: implemented
+
+[English](2026-07-03-filesystem-directory-listing-seam.md) | 中文
+
+## 问题
+
+`@deepseek-ai/dsh-fs` 是文件系统访问的提供方 seam，本地后端与未来的非本地后端共享同一个 `ctx.fs` 契约。在本次变更之前，它能解析路径、stat 目标、读取文本、流式读取文本、写入文本和编辑文本。这对面向模型的文件工具已经足够，但对于需要枚举目录而又不想直接导入 `node:fs` 的非模型侧消费方来说还不够。
+
+直接的压力来自 skill（技能）加载：读取单个 `SKILL.md` 已经可以走 `ctx.get('fs')`，但发现哪些 skill 根目录包含 `<name>/SKILL.md` 或 `<name>.md` 仍需要目录枚举。如果仅在 `dsh-skill` 中添加目录列举，要么保留对 Node 的直接依赖，要么在文件系统提供方栈之外发明一个一次性的本地辅助函数。
+
+本决策只添加提供方能力，不涉及面向模型的 `ls`/`list` 工具或 skill 发现机制的变更。那些消费方需要独立的 UX、提示词与策略决策。
+
+## 决策
+
+在 `@deepseek-ai/dsh-fs` 中添加 `FileSystem.listDir(target, signal?)`。
+
+`listDir` 仅列举一层目录。它以稳定的名称顺序返回直接子项，包含以下字段：
+
+- `name`：子项的 basename；
+- `type`：`file`、`directory` 或 `other`；
+- `target`：已解析的子项 `FsTarget`；
+- `version`：可用时返回的轻量元数据；
+- `size`：可用时返回的常规文件大小。
+
+它从不读取文件内容。递归遍历、glob 匹配、分页、搜索、文件监听和面向模型的渲染均有意不在范围内。
+
+本地后端通过 `readdir({ withFileTypes: true })`、`resolveLocalTarget` 以及元数据 `stat`/`realpath` 探测来实现。结果顺序是确定性的（`name.localeCompare`），以保持未来消费方的提示词/列表输出稳定，并提高前缀缓存复用率。
+
+损坏或已消失的子项可以表示为 `type: 'other'`（不带 `version`/`size`）；它们不会中止整个列举。在列举目录或解析/探测子项元数据时遇到权限或后端 I/O 故障，则以结构化的 `FsError` 错误码使整个列举失败：
+
+- `FS_NOT_FOUND`：目标不存在；
+- `FS_NOT_DIRECTORY`：目标存在但不是目录；
+- `FS_PERMISSION_DENIED`：权限不足；
+- `FS_IO_ERROR`：其他后端 I/O 故障；
+- `FS_ABORTED`：调用被中止。
+
+## 曾考虑的替代方案
+
+**在添加 seam 的同时添加面向模型的 list 工具。** 否决。其提示词、schema 和渲染契约与提供方原语相互独立。
+
+**让每个消费方自行枚举目录。** 否决。这会将 `dsh-skill` 等产品包绑定到 Node/本地文件系统行为上，绕过策略/远程/沙箱后端。
+
+**让 `listDir` 支持递归或 glob 形式。** 暂时否决。skill 根发现只需要直接子项，而简单的单层列举是未来消费方可以安全组合的最小后端契约。
+
+**跳过元数据解析失败的子项。** 否决。API 承诺返回已解析的子项 target，因此解析子项时的权限/IO 故障属于契约失败。损坏或已消失的子项是例外，因为它们仍可在不声称拥有一个活跃已解析文件的前提下被表示。
+
+## 后果
+
+每个文件系统后端现在必须多实现一个提供方原语。这是 harness 尚未发布时有意为之的基础工作，但也意味着未来的沙箱/远程后端需要定义等价的直接子项列举行为。
+
+该能力仍停留在提供方层面。在消费方落地之前，ACP（Agent Client Protocol）/模型会话仍需使用 `bash` 等既有工具来列举目录。缺少面向模型的 `listdir` 工具是预期行为，而非接线错误。
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
new file mode 100644
index 0000000000..1f232965a5
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-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
+2026-07-05-prompt-variables-and-tool-guidance-ownership.md: 94f5fa409e7b539b48750d12576c7a342a30c9ba
+2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: f1379e143a94a3ae3a07b3120c6f0b9fc8561fe9
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 cdd37091a2..94f5fa409e 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md)
+
 ## Problem
 
 The assembled system prompt had four defects, all of one family: facts the harness already knows were restated by hand somewhere else, and drifted.
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
new file mode 100644
index 0000000000..f1379e143a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
@@ -0,0 +1,72 @@
+# Agent Note: 提示词变量与工具指导归属
+
+Status: implemented
+
+[English](2026-07-05-prompt-variables-and-tool-guidance-ownership.md) | 中文
+
+## 问题
+
+组装后的系统提示词存在四个缺陷，同属一类：harness 已知的事实在别处被手工重述，然后漂移。
+
+**模型无法知道自己的名字。** `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)` 为这种分裂的症状道歉，旧终端欢迎横幅也手动枚举了工具集。
+
+**Persona 渲染在工具指导之后。** agent loop（智能体循环）将 `agent.options.systemPrompt` 字符串拼接在已组装的 section 之后，于是模型先读到「Use the read tool…」再读到「You are a coding agent」——与 identity-first 约定（Claude Code、Codex）相反，且是 section 流水线之外的第二条组合路径。
+
+**Fork 工具的描述是假的。** `dsh-tool-subagent` 硬编码了一段为 spawn 语义编写的描述——「a separate agent that works in its own context … it does not see this conversation」——而 `subagent_fork` 实例（其子 agent 继承父级已完成的轮次）拿到了同样的措辞；YAML 行文在带外纠正了这个谎言。小问题：`PromptSection.name` 文档标注为「(diagnostics / dedup)」，但重复项被静默接受。
+
+## 决策
+
+**一条原则：提示词中的每个事实恰好有一个归属方。** 模型名称和工作区是配置/会话事实 → harness 将它们暴露为变量，persona 引用它们。每个工具的语义和何时使用 → 工具的 `description`。description 无法承载的跨调用习惯 → 工具包（package）的提示词 section。harness 来源标识 → 静态的 `harness:identity` section。部署角色与行为 → 部署的 persona。
+
+### 组装上下文
+
+`SystemPrompt.assemble(context)` 接受一个可合并扩展的 `AssembleContext`。`dsh-system-prompt` 声明可选的 `scope` 选择器用于 scoped 路由，而 `dsh-agent` 通过声明合并将可选的类型化 `agent` 字段附加到其上（类型层面的 `agent → system-prompt` 边，无运行时依赖循环）。循环在每个步骤调用 `assembleContextFor(agent)`，使两个字段标识同一个 agent；section 文本提供方可以读取该上下文，`system-prompt/assemble` waterfall（瀑布式事件）也接收它，监听器可据此按 agent 过滤或扩展。
+
+### 提示词变量
+
+插件通过 `ctx.systemPrompt.variable(name, provider)` 注册 `{{name}}` 值。组装过程将它们解析到 waterfall 可见的变量映射中。渲染阶段拒绝以下情况：引用了未知的 own-property、已注册的提供方返回 `undefined`、格式错误的完整引用、以及仍包含闭合 `}}` 的不平衡引用；孤立的未匹配 `{{` 保留为行文，替换后的值不会被重新扫描。注册阶段拒绝无效或重复的变量名，section 名称也必须唯一。
+
+`dsh-agent-loop` 注册两个内置变量，均为上下文 agent 的纯投影：`model`（= `options.model`）和 `cwd`（= `session.header.cwd`）。示例 persona 写 `powered by the {{model}} model`——模型名称只在 `model:` 配置键中声明一次。`{{cwd}}` 仅在 ACP 示例中演示：每个 ACP 会话携带客户端的 cwd，而配置预创建的 stdio agent 没有 cwd（在那里声称 `{{cwd}}` 的 persona 会导致该轮次失败——这是有意为之）。变量留在 loop 插件上（不同于下面的 section）：它们是本循环驱动的 agent 的运行时事实，替换循环自行提供自己的变量。
+
+### Persona 作为 order-0 section
+
+`dsh-system-prompt` 拥有 order 为 `-100` 的 `harness:identity` 和 order 为 0 的配置 `deployment:persona`，因此两者在循环被替换时仍然存活。提示词渲染只有一条路径 `renderPrompt(assembly)`，已路由请求 header 因此会记录准确的提示词，稍后由 `ctx.tokenMeter` 为压缩压力回放。agent 作用域的 `deployment:persona` 遮蔽全局默认值，允许 subagent 提供方在发布前安装 persona。约定的 order 区间为：identity `-100`、persona `0`、工具指导 `100–199`。
+
+### 工具指导归属
+
+每个工具的语义和选择指导放在工具 description 中。提示词 section 只承载跨调用习惯，例如检查 bash 退出标记或优先使用文件系统工具而非 shell 命令。`todo_write` 和 subagent 工具不需要 section，因为它们的 description 包含完整契约。部署 persona 只包含角色和行为。
+
+### Subagent 对话历史描述符
+
+`SubagentProvider.inheritsParentContext` 描述的是对话种子，而非作用域、服务、工具或权限。spawn 和 ACP 将其设为 `false`；fork 设为 `true`。`dsh-tool-subagent` 根据该标志派生工具和提示词参数的描述，包括 fork 继承已完成轮次但不继承进行中轮次这一点。提供方生命周期事件使该措辞与响应式提供方注册保持同步；其设计动机见[提供方生命周期事件 Agent Note](2026-07-05-subagent-provider-lifecycle-events.md)。
+
+## 曾考虑的替代方案
+
+- **循环自行组合一行 identity 文本**：在必须保持精简的那个包（「用插件，不改循环」）中硬编码面向模型的行文，且在 section 流水线之外构成第二条组合路径。（identity 确实以代码字面量交付——但作为 `dsh-system-prompt` 注册的普通 section，其 `system-prompt/assemble` waterfall 仍是部署需要移除它时的逃生阀。）
+- **通过 `agent/request` waterfall 注入模型名称**：提示词文本会在两处组合，更早渲染的 persona 也可能与最终已路由 header 不一致。拥有延迟路由的请求插件还必须拥有该模型在提示词中更早出现的声明。
+- **在每个 persona 中手写模型名称**：与上方一行的 `model:` 键重复，配置修改后静默失实；正是本 Agent Note 要治愈的病症。
+- **宽松插值（未知引用保留原样或替换为空）**：一个拼写错误 `{{modle}}`（或一个空洞）会被发送给模型，直到 transcript（文本记录）审查时才会被发现。
+- **在配置中为每个 subagent 实例编写措辞**：面向模型的行文回到每个部署 × 实例中，重蹈 P2 病症。**根据提供方名称选择措辞**：`providerName` 本身是配置，重命名提供方后会静默获得错误的措辞。
+- **在 `apply` 时解析提供方（加载顺序要求）** 与 **仅用 section 承载 subagent 措辞（在 assemble 时惰性解析）**：提供方生命周期事件的替代方案；两者均在[提供方生命周期事件 Agent Note](2026-07-05-subagent-provider-lifecycle-events.md)中被否决。
+
+## 不在范围内
+
+- 更多变量（`date`、platform、git 状态）：注册表使每个变量成为拥有该事实的插件的一行贡献；本 Agent Note 不认领任何一个。
+- 为预创建的 stdio agent 提供配置 `cwd`（可让 stdio persona 使用 `{{cwd}}` 并按真实路径分区持久化）：推迟到会话 cwd 方案重新讨论时。
+
+## 交付的不变式
+
+- tui-agent 的提示词通过一条组装路径依次渲染 identity、带插值模型名的 persona，然后是 fs/bash/web 指导。
+- fork 和 fresh subagent 的描述反映提供方是否继承已完成的对话轮次；工具随提供方生命周期变化而出现、消失和重新措辞。
+- 未知、无值、格式错误或不平衡的变量引用会指明 section 名称并抛出异常；重复的 section、变量和工具注册同样抛出异常。
+- 快照回放与提示词无关：它按轮次和步骤索引已记录的分片流，不比较发出的请求。
+
+## 后果
+
+- 组装后的提示词中每个事实现在恰好有一个归属方，leaf YAML 中手工维护的工具行文已消除：加载或卸载一个工具插件不再需要编辑任何部署的 persona。
+- `{{model}}` 在组装时反映 `AgentOptions.model`。如果一个插件在 `agent/request` waterfall 中切换模型，提示词对该步骤的声明就会过时；如果一个插件在那里提供模型（options.model 未设置——循环文档中记载的回退路径），变量在渲染时无值，包含 `{{model}}` 的 persona 会在 waterfall 运行前失败。两者的补救方式相同，就是归属规则本身：拥有延迟绑定模型事实的插件在 `system-prompt/assemble` waterfall 上提前声明它（`assembly.variables['model'] = …`）——一个归属方，两处声明；一个循环测试端到端固定了 supply 路径。已接受。
+- 当一个已绑定的提供方不存在时（尚未激活、已卸载、HMR（热模块替换）重载中），subagent 工具不存在，该窗口内的模型请求中不会包含它。这是诚实的状态——替代方案是注册一个 description 或执行都不可信的工具。
+- 严格性意味着 persona 可能在渲染时导致轮次失败（例如在无 cwd 的会话上使用 `{{cwd}}`）。失败是受控的——该轮次以 `error` 结束，循环存活——且这是一个我们希望大声暴露的撰写错误。
+- 目前没有在提示词行文中转义字面 `{{name}}` 的语法；如果真实提示词确实需要，再行添加。
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
new file mode 100644
index 0000000000..f9c309c39f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-05-reconstructable-requests.md: 153d37a2faf2265134d5ff9e88f0bbfa275328e0
+2026-07-05-reconstructable-requests.zh.md: caf51c3065e416fd11aebc1c1d4dc2ee248e2e5c
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 99a7633c5b..153d37a2fa 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-05-reconstructable-requests.zh.md)
+
 ## Problem
 
 The request pipeline did not guarantee prefix stability for provider caching, and the session log could not reconstruct what the model saw. It omitted model, system prompt, and tool schemas while allowing per-call request rewrites. Cache behavior and replay equivalence therefore depended on whichever plugins happened to be loaded.
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
new file mode 100644
index 0000000000..caf51c3065
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -0,0 +1,56 @@
+# Agent Note: 每个 LLM（大语言模型）请求都可从会话日志重建
+
+Status: implemented
+
+[English](2026-07-05-reconstructable-requests.md) | 中文
+
+## 问题
+
+请求流水线未能保证前缀稳定性以利用提供方缓存，会话日志也无法重建模型实际看到的内容。日志遗漏了 model、系统提示词和工具 schema，同时允许逐次调用的请求改写。因此缓存行为和回放等价性取决于碰巧加载了哪些插件。
+
+快乐路径的参考形态是 MiniCode 的 `LLMClient`：一个有状态的对话客户端，随对话推进只做追加而不重建，仅在系统提示词、工具集或压缩（compaction）真正改变了模型需要看到的内容时才重置。本 Agent Note 回答的设计问题是：如何在不放弃事件溯源的前提下获得这种纪律。
+
+## 决策
+
+### 原则
+
+**模型可见 ⟺ 已记录。** 凡到达模型请求的内容都必须记录在会话日志中。可检查的推论：**循环发出的每个对话请求都是会话日志的纯函数**——任何人持有日志即可逐字节重建请求。精确的范围声明：该保证覆盖循环构建的 `GenerateOptions`；提供方协议格式（wire format）字节由此推导而来，因为两个适配器的序列化在固定代码版本下都是逐消息的纯函数；直接的一次性调用（压缩的 summarize 调用）记录其信封标量（`compact/summary.{provider, model, maxTokens}`），其输入是对日志区域的确定性代码运算——可从日志加代码重建，因为只有循环会标记请求归属，所以它们不在不变式内。
+
+前缀缓存稳定性是推论 #1，而非标题：一个仅追加的日志经逐节点纯函数投影，在 header 不变时自然产出前一请求的追加扩展——稳定性是涌现的，不是管理出来的。字节精确的审计/回放是推论 #2；带*可归因*漂移的恢复与 fork 是推论 #3。
+
+### 机制
+
+**消息。** `Session.deriveMessages()` 带缓存：每个 surface 条目在首次出现时通过公开的逐事件函数 `deriveEventMessage(event)` 精确投影一次；surface 重写（压缩的 `replace`，即 `SurfaceManager.replaceGeneration`）触发重建。调用方每次获得一个新数组，底层是共享的深度冻结消息：通过投影变异已记录的历史是不可表达的（会抛异常），取代了旧的逐次调用克隆隔离。外部重建器对日志前缀折叠同一个公开函数，因此不可能有两条路径产生分歧。
+
+`EpochHeader` 记录请求的非历史状态：调用配置、渲染后的系统提示词、工具 schema 和会话前缀，空值规范化为缺失。`request/header` 始终写入完整快照：首个循环实例使用 reason `initial`，后续实例使用 `resume`，实例内变更使用 `change`。`foldRequestHeader` 选择最新快照。旧的 `request/header-delta` 事件和已移除的 `fallback` reason 在追加或加载时都会被拒绝。
+
+每个步骤重建提示词组装。在实例的首个步骤中，`agent/session-prefix` 以一个冻结的空种子为基础，用仅限请求的开场消息进行扩展；结果在通用 `agent/pre-step` 检查点与边界快照之前被冻结并缓存于该循环实例。首次调用配置从显式的 `AgentOptions` 出发，保留 fork 覆盖和恢复重配置；后续调用从折叠后的 header 出发。`agent/request` 只能替换那个冻结的配置种子，模型可见内容通过已记录的通道进入。循环记录欠下的 header 事件（前缀唯一的持久归宿），从前缀、快照和 header 构建 `GenerateOptions`，对其深度冻结但保持 `AbortSignal` 活跃。每实例状态仅有缓存的前缀和锚定快照是否已写入。
+
+**`step/start` 是重建边界。** 一个步骤从该序列之前的事件推导消息。快照之后的注入加入下一次请求，事件发布期间的重入追加被拒绝。`agent/pre-step(agent, turn, step, signal)` 仍是当前请求所需内容的通用 seam。header 重建选择该步骤的 `request/header`，或在无新 header 写入时沿用前一个快照。
+
+**强制执行。** `dsh-agent-loop/invariant` 配套插件向 `ctx.invariants` 注册，并在被选用时通过一个全新的 `Session` 独立重建每个循环请求，使活跃缓存无法为自身背书，然后在 `llm/stream` 处比较消息和折叠后的 header 字段。循环通过 `dsh-llm` 的 `markAgentLoopRequest()` 记录精确的冻结请求；这一进程内标识让配套插件和其他请求观察者识别对话工作，而直接的一次性调用无论其冻结形状或会话 id 如何都保持排除。正确性依赖于序列有界的重建，而非监听器顺序。带密钥的 e2e 要求首次请求之后有正值的 cache-read token；逐步骤用量是生产信号，header 变更或压缩表现为下一步骤的 cache-read 下降。
+
+### MiniCode 形态：采纳，但溯源箭头反转
+
+与 MiniCode 相同，对话仅追加推进，仅在模型可见状态变更时重置。与 MiniCode 不同，事件日志仍是真源，因为它同时拥有持久化、恢复、边界、工具配对和溯源。`Session` 缓存从日志推导的消息和 header 折叠结果，使每个请求都可独立检查。
+
+## 曾考虑的替代方案
+
+- **客户端作为真源**（照搬 MiniCode）：在日志之外多出一个运行时真相——两者漂移而无人察觉；见上节。
+- **镜像日志的有状态传输客户端**：重复对话状态，需要围绕监听器做回滚，留下未记录的编辑面，且仍无法重建请求 header。Session 拥有的缓存加已记录的 header 避免了这些分裂的真相。
+- **逐次调用的请求标量**（一个可自由变异的配置传给每次 `agent/request` 分发）：监听器可以零记账地逐次切换 model，悄然放弃本设计旨在保护的提供方缓存。配置是逐对话的已记录状态；waterfall（瀑布式事件）提议，日志记录。
+- **检测并报告**（比较连续请求，发散时告警）：事后捕获违规；违规请求仍可构造并发出。因接口层面的不可表达性而否决。
+- **事件驱动组装**（仅在变更信号时重新渲染）：存在漏信号的 bug 类别——会话中途注册的工具发出 `tools/change` 而非 `system-prompt/change`，第三方提供方可能什么都不发。逐步骤渲染加值比较在零信号纪律下即可稳健工作。
+- **自定义 header-delta 编解码器**（系统行编辑、按名称键控的工具编辑、完整配置/前缀替换）：减少了重复字节，却复制了表示及其 diff/apply/fallback 机制。完整快照只保留一种回放表示。
+- **Header 快照上的叙事性变更字段列表**：可以通过比较连续快照推导。`reason` 仍保留，因为实例边界无法从快照值推导。
+
+## 后果
+
+- 一个日志无法解释的请求不可能被意外构造——无论是循环还是监听器；变异已构建的请求会抛异常；每个 header 变更都是持久的、可 diff 的日志事件。
+- 在建议性通道之间做选择是变更频率的决策，而本设计使稳定的那个在结构上成为默认：`agent/session-prefix` 的贡献在每个循环实例中只组合一次并逐字复用，因此以零边际成本扩展可缓存前缀，且不可能在会话中途击穿提供方缓存；会话中途变化的内容通过仅追加的历史通道流入——`agent.inject()` 以及工具/prompt-submit 的 `additionalContexts`——每条都是持久的 `context/message`，付出一次代价后即被前缀缓存，代价是在历史和日志中累积。将会话冻结的开场内容路由到前缀，将变更通知路由到历史通道；逐步骤的仅限请求尾部槽位被有意放弃（无消费方，且持久追加覆盖了当前所有更新模式）。
+- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身的 reasoning-content 排除由服务端管理。
+- `step/start` 监听器行为变更（见上文）是对插件唯一可观察的语义变更；`agent/pre-step` 是当前请求的 seam。
+- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 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/architecture/2026-07-05-subagent-provider-lifecycle-events.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.i18n.yaml
new file mode 100644
index 0000000000..516dd4edcb
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-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
+2026-07-05-subagent-provider-lifecycle-events.md: afd45027e8b56cbf1d17e6dec749d8602c81124d
+2026-07-05-subagent-provider-lifecycle-events.zh.md: 58d439936a3f2cc51d8190cbebe8e68cdb14c855
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 44733bb8c9..afd45027e8 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-05-subagent-provider-lifecycle-events.zh.md)
+
 ## Problem
 
 [The prompt-variables Agent Note](2026-07-05-prompt-variables-and-tool-guidance-ownership.md) makes `dsh-tool-subagent` DERIVE its model-facing wording from its provider: `SubagentProvider.inheritsParentContext` (spawn/ACP `false`, fork `true`) drives both the tool description and the `prompt` parameter description, so the fork tool stops lying about context inheritance. That fix created a cross-fiber data dependency: a tool's description is fixed at TOOL REGISTRATION (deliberately — the description is where tool-choice guidance lives), but the provider arrives on its own plugin fiber, on no particular schedule.
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
new file mode 100644
index 0000000000..58d439936a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: Subagent 提供方生命周期事件——`subagent/provider-added` / `subagent/provider-removed`
+
+Status: implemented
+
+[English](2026-07-05-subagent-provider-lifecycle-events.md) | 中文
+
+## 问题
+
+[提示词变量 Agent Note](2026-07-05-prompt-variables-and-tool-guidance-ownership.md) 让 `dsh-tool-subagent` 从其提供方派生面向模型的措辞：`SubagentProvider.inheritsParentContext`（spawn/ACP 为 `false`，fork 为 `true`）同时驱动工具描述和 `prompt` 参数描述，使 fork 工具不再在上下文继承问题上对模型撒谎。这一修复引入了跨 fiber 的数据依赖：工具描述在工具注册时固定（这是有意为之——描述是 tool-choice 引导所在之处），但提供方在自己的插件 fiber 上到达，时机不确定。
+
+如果在工具插件的 `apply` 时刻解析提供方，就会产生一个隐式的加载顺序要求（「在 cordis.yml 中把后端列在工具前面」）。这个要求不成立，因为 Cordis Loader 并发启动同级条目，且 `Entry.init()` 不会等待激活完成：延迟到达的后端即使列在前面，也可能让工具 fiber 失败。Loader 不提供同级顺序保证——「异步状态不是同步状态」（见[防御性模式](../../../../docs/defensive-patterns.md)）。
+
+## 决策
+
+注册表将提供方的成员变化作为类型化事件广播，消费方镜像这些事件而非假设顺序：
+
+- **`subagent/provider-added(provider)`**：一个提供方在 `ctx.subagents` 注册表中变为可解析。在注册时发出。
+- **`subagent/provider-removed(name)`**：一个提供方离开注册表（其插件 fiber 被 dispose（资源释放）——卸载或 HMR（热模块替换）重载）。从注册的 disposer 中发出。
+
+`dsh-tool-subagent` 镜像其命名提供方的生命周期：当提供方可用（或变为可用）时注册工具——在那一刻从该提供方派生措辞——当提供方离开时注销工具，并在重新注册时（HMR 重载）重新派生。提供方不在时工具不存在，因此不会对模型撒谎。这里有意不留下任何需要文档化的加载顺序要求：事件让顺序问题消失，而非将其钉死。
+
+这些事件还完善了 seam 的词汇：`ctx.subagents` 是一个命名注册表，多个委派后端（`spawn`、`fork`、`acp`）在其上共存；一个其他插件从中派生状态的注册表，应当以类型化事件广播成员变化，而非要求轮询或依赖加载顺序。
+
+## 曾考虑的替代方案
+
+- **在 `apply` 时解析提供方，不存在则抛异常**：否决。「先列后端」这一要求声称了 Loader 并不存在的顺序保证。
+- **重试查找（轮询直到提供方出现）**：最终能收敛，但在框架已有的机制（effect 注册 + disposal）之外发明了一套私有就绪协议；它也无法感知提供方离开，因此 HMR 会遗留一个措辞描述已 dispose 后端的工具。
+- **仅在 section 中放置 subagent 措辞，在组装时惰性解析**：同样能容忍任意加载顺序，但将 tool-choice 引导移出了描述，与提示词变量 Agent Note 建立的所有权规则相矛盾（每个工具的语义和何时使用属于描述）。响应式注册既保持描述的权威性，又不依赖顺序。
+- **根据提供方名称而非提供方对象确定措辞**：`providerName` 本身是配置，重命名后的提供方会静默获得错误的措辞；从已解析提供方自身的 `inheritsParentContext` 派生则不会漂移。
+
+## 后果
+
+- 从命名提供方派生状态的消费方响应 `subagent/provider-added`/`-removed` 事件，而非在 `apply` 时读取注册表；`dsh-tool-subagent` 是参考实现。
+- **添加时大声失败；移除时按监听器隔离。** 添加监听器可以回滚注册。移除在 disposal 期间运行，因此单个监听器抛异常只会被记录日志，不会饿死后续镜像或干扰拆解流程。`start()` 仍在每次运行时按名称解析提供方，防止陈旧工具调用已移除的后端。见[事件目录](../../../../docs/cordis-catalog/events.md)与[生产者/消费方映射](../../../../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-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
new file mode 100644
index 0000000000..6d14977e92
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-06-timeout-deadline-library.md: 11d4b8cd48dd345d2324b63e01bd726f12d846b4
+2026-07-06-timeout-deadline-library.zh.md: 334914c689adf54a654c5907395c29ceeeb50891
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 1c407d777d..11d4b8cd48 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-timeout-deadline-library.zh.md)
+
 ## Problem
 
 Timeout handling was drifting apart across the tool-bearing capabilities, and the divergence was not superficial — it was the same logic re-implemented three ways, each with its own subtle correctness burden.
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
new file mode 100644
index 0000000000..334914c689
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -0,0 +1,115 @@
+# Agent Note: 共享的超时/截止时间原语，硬终止留给各能力自行实现
+
+Status: implemented
+
+[English](2026-07-06-timeout-deadline-library.md) | 中文
+
+## 问题
+
+超时处理在各个承载工具的能力之间逐渐分化，而且这种分化并非表面的：同一套逻辑被以三种方式重新实现，各自带有微妙的正确性负担。
+
+- **bash**（[packages/bash/bash-local/src/run.ts](../../../../packages/bash/bash-local/src/run.ts)）在进程管道内部有一套完整、正确的超时实现：一个经配置钳位的 `timeoutMs`，两个独立触发器（用于超时的 `killTimer` 和用于上游取消的 `onAbort` 监听器），各自调用同一个 `kill()` 闭包对进程组执行 SIGTERM→宽限期→SIGKILL 升级，以及两个正交的结果布尔值（`timedOut`、`aborted`）独立锁存。
+- **web_fetch**（[packages/web/web-fetch-local/src/provider.ts](../../../../packages/web/web-fetch-local/src/provider.ts)）有一套正确但*手写*的超时：构造一个 `AbortController`，连接 `setTimeout(() => controller.abort(new WebError(…, 'WEB_FETCH_TIMEOUT')))`，手动添加和移除上游信号监听器，在 `finally` 中清除定时器，并在 `translateAbortOrNetwork` 辅助函数中从 `signal.reason` 恢复超时原因（因为 reader 只抛出裸 `AbortError`）。
+- **web_search**（[packages/web/tool-web/src/search.ts](../../../../packages/web/tool-web/src/search.ts)）**完全没有超时**：`WebSearchRequest`（[packages/web/web/src/types.ts](../../../../packages/web/web/src/types.ts)）不携带 `timeoutMs` 字段，各提供方的 `search()` 只转发 `exec.signal`。（web_search 在本次设计中保持无超时——见「后果」。）
+
+每个新的外部进程或网络工具都要重新推导同样四件事：钳位请求值、启动定时器、将超时与上游取消融合、在出口处区分「超时」与「已取消」。而融合与原因恢复恰恰是最容易出微妙错误的部分（web_fetch 的 `signal.reason` 处理就是证据）。与此同时，各能力执行的*终止*操作不可归约地不同：bash 杀死一个 OS 进程组（工作运行在子进程中，在本运行时之外，只能通过信号触达），而 web 中止一个进程内的 `fetch`（undici 拆除 socket）。不存在一个能停止所有能力工作的单一机制。
+
+## 决策
+
+`@deepseek-ai/dsh-timeout` 位于 `packages/util/`（与 `dsh-brand` 同级），负责超时的*计时与分类*这一半；*终止*那一半——硬终止——留在各能力的实现中。它是一个纯函数库，**不是** Cordis 服务或插件：不接收 `ctx`、不注册任何东西、不持有跨调用状态、不发射事件。这里刻意不设中央「超时服务」，因为那样的服务必须知道如何停止每个能力的工作——而这正是微内核要排除在共享层之外的知识，也是 Codex 将 `ExecExpiration` 限定于 exec 族所示范的原则。
+
+### 库的对外接口
+
+四个函数、一个 watchdog 接口加一个 reason 类型：
+
+```ts ignore-check
+/** The internal reason attached to a timeout abort, so consumers can classify it after the fact. */
+export class TimeoutReason extends Error {
+  override name = 'TimeoutReason'
+
+  constructor(readonly code: string, readonly timeoutMs: number) {
+    super(`${code} after ${timeoutMs}ms`)
+  }
+}
+
+/** Validate/fill a caller's optional positive hint from the backend's default, then cap at its max. */
+export function clampTimeout(
+  requested: number | undefined,
+  def: number,
+  max: number,
+  name = 'timeoutMs',
+): number
+
+/**
+ * Build a deadline signal that aborts on upstream cancellation OR on timeout,
+ * with the timeout carrying a `TimeoutReason`. `timeoutMs <= 0` means "no
+ * timeout" (background tasks): forward only the upstream signal, arm no timer.
+ * The returned object's `[Symbol.dispose]` clears the timer — `using` for a
+ * scope-lifetime consumer, a manual call for an event-lifetime one.
+ */
+export function deadline(
+  upstream: AbortSignal | undefined,
+  timeoutMs: number,
+  code: string,
+): { signal: AbortSignal; [Symbol.dispose](): void }
+
+/** A stable signal plus one-at-a-time, timer-guarded async-iterator demand. */
+export interface IdleWatchdog {
+  readonly signal: AbortSignal
+  next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>
+  [Symbol.dispose](): void
+}
+
+/** Arm only while one iterator `next()` is outstanding, then rearm on later demand. */
+export function idleWatchdog(
+  upstream: AbortSignal | undefined,
+  timeoutMs: number,
+  code: string,
+): IdleWatchdog
+
+/** Recover the TimeoutReason from an aborted signal (or error); `code` scopes the match to this deadline's timer. */
+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 被视为上游取消而非内层能力自身的超时。
+
+### 职责划分
+
+| 关注点 | 负责方 |
+|---|---|
+| 校验请求提示并钳位默认值/最大值 | `dsh-timeout`（`clampTimeout`）：纯算术加共享的正有限请求契约 |
+| 启动一次性定时器、到期中止、携带 reason、与上游取消融合 | `dsh-timeout`（`deadline`） |
+| 仅围绕未结算的迭代器 demand 启动和重启 | `dsh-timeout`（`idleWatchdog`） |
+| 清除定时器 | `dsh-timeout`（任一原语的 `[Symbol.dispose]`） |
+| 中止后对首个 abort reason 进行分类 | `dsh-timeout`（`timeoutOf`） |
+| **实际终止工作** | 各能力的实现 |
+| 默认值/最大值*数值* | 各能力的配置 |
+| 超时 `code` 字符串 | 各能力（`WEB_FETCH_TIMEOUT` ≠ `BASH_TIMEOUT`） |
+
+信号只*通知*；终止始终是监听方的职责，而监听方因能力而异。bash 自行编写 `addEventListener('abort', kill)`，因为 OS 进程存在于本运行时之外，没有别的东西会杀死它；web 将 `d.signal` 交给 `fetch`，由 undici 拆除 socket。这也是文件读/写/编辑**不接受** `timeoutMs` 的原因：本地系统调用最多只能尽力中止，超时无法强制 `fsync`/`rename` 停止，添加超时将是一个违反「显式优于隐式」的隐式默认值。两个参考 agent 出于同样的原因对文件 I/O 不设超时。
+
+### 各能力如何消费该库
+
+- **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`。
+
+## 后果
+
+- `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。统一的 SIGTERM→宽限期→SIGKILL 终止路径不变，seam 类型 `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 基线，已满足）。
+- 模型流现在共享一个可重启的定时器契约，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
+
+以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema/快照覆盖率规划就绪后获得可选的面向模型的 `timeout_ms`；未来基于 ripgrep 的文件系统发现工具可以在存在后消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
+
+## 曾考虑的替代方案
+
+**统一的超时*插件* / `ctx.timeout` 服务。** 基于微内核原则否决。一个能停止任何工具工作的服务必须理解每个能力的终止机制（进程组 SIGKILL、socket 拆除、系统调用边界检查），这正是架构所禁止的「内核知道太多」。Codex 的 `ExecExpiration` 被限定于 exec 族，正是因为它驱动的 kill（`killpg`）是进程族特有的；MCP 和模型流各自保有自己的。不存在一个连贯的中间层能为所有东西拥有终止权，因此共享部分只能是纯计时/分类那一半——一个库，而非服务。
+
+**每个工具各自实现超时，不共享代码（先前的现状，也是 Claude Code 的选择）。** 否决，因为它已经在产生分化和重复的正确性负担：web_fetch 手写了与未来网络/进程类工具各自需要重新推导的完全相同的 controller/reason 逻辑，而融合 + `signal.reason` 恢复正是容易出错的部分。Claude Code 容忍完全重复；本仓库有一个统一的共享 abort 通道（每次 `execute` 上的 `exec.signal`），使得一个小型共享原语严格更优，因此成本/收益不同。
+
+**用 `withTimeout(promise, ms)` 包装器代替信号工厂。** 否决，因为让 promise 与定时器竞争只是在截止时间到达时 resolve *工具调用*的 promise，而不会停止底层工作——子进程或 fetch socket 会泄漏。分发信号并要求能力监听，才能强制一条真实的终止路径存在。这与「dispose 必须达到完全停稳，而非仅仅请求它」的防御性规则一致。
+
+**保留 bash 独立的超时和取消触发器。** 否决，因为一个 deadline 信号移除了定制定时器并标准化了分类。竞争的原因报告先到达的那个 abort，而既有的 SIGTERM→SIGKILL 终止路径保持不变。
diff --git a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.md b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.md
index f90e653a7c..2962f1006e 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.md
@@ -150,6 +150,6 @@ The formatter hook is deliberately small: a tool turns a `RetentionNotice` into
 
 **Put `read` windowing behind `ItemRetainer`.** Rejected for v1: `read` is the only current window consumer, and its semantics are file pagination rather than generic retention. A single `Omitted` count cannot represent both sides of a line window, and `read` also carries `totalLines`, offset-range errors, per-line preview truncation, and a byte cap over selected output. Keeping `read-render` tool-owned avoids growing the shared library around one special case.
 
-**Make truncation part of `ToolExecutionResult`.** Rejected: the tool registry would have to understand tool-specific recovery guidance, grouping, line numbering, exit status, and provider semantics. Retention is a library used before a tool returns `ContentBlock[]`; the model-facing result remains tool-owned.
+**Make truncation part of `ToolExecutionResult`.** Rejected: the tool registry would have to understand tool-specific recovery guidance, grouping, line numbering, exit status, and provider semantics. Retention is a library used by a tool's Native renderer; the model-facing projection remains tool-owned while the [canonical value](2026-07-20-canonical-tool-output-contract.md) may retain the complete acquired result.
 
 **Expose limits in every model-facing tool schema.** Rejected as the default: Claude Code's grep exposes `head_limit` / `offset`, but this harness keeps routine budgets as deployment config unless the model genuinely needs pagination control. A future read-like continuation field can be added per tool; it does not belong in the shared retention primitive.
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
new file mode 100644
index 0000000000..bd2426f377
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-07-tool-call-timeout-policy.md: 69fd1ee721de69621d3b57c10d960da0651b94dd
+2026-07-07-tool-call-timeout-policy.zh.md: c0dc56127cb983bd515db424d0ca37da9d0e978a
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 82da8347a6..69fd1ee721 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-07-tool-call-timeout-policy.zh.md)
+
 ## Problem
 
 The [timeout/deadline Agent Note](2026-07-06-timeout-deadline-library.md) extracted the timing-and-classification primitive into `@deepseek-ai/dsh-timeout`, but timeout policy was still attached to individual capabilities and model-facing schemas. `bash` exposed `timeoutMs`; `web_fetch` exposed `timeout_ms`; `web_search` had no model-facing timeout even though providers already honor `exec.signal`; a future grep/glob tool would either import the timeout library directly or invent its own timeout policy. That is the wrong authoring shape for a plugin SDK: a tool author should normally forward `exec.signal` to the implementation it calls, and deployment policy should decide the budget.
@@ -61,7 +63,10 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
   return {
     content: [{ type: 'text', text: `Error: tool call timed out after ${timeoutMs}ms` }],
     isError: true,
-    error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+    error: {
+      message: `tool call timed out after ${timeoutMs}ms`,
+      info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+    },
   }
 }
 ```
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
new file mode 100644
index 0000000000..c0dc56127c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -0,0 +1,114 @@
+# Agent Note: 工具调用超时策略作为插件
+
+Status: implemented
+
+[English](2026-07-07-tool-call-timeout-policy.md) | 中文
+
+## 问题
+
+[超时/截止时间 Agent Note](2026-07-06-timeout-deadline-library.md) 将计时与分类原语提取到了 `@deepseek-ai/dsh-timeout`，但超时策略仍然附着在各个能力和面向模型的 schema 上。`bash` 暴露了 `timeoutMs`；`web_fetch` 暴露了 `timeout_ms`；`web_search` 没有面向模型的超时参数，尽管提供方已经遵循 `exec.signal`；未来的 grep/glob 工具要么直接导入超时库，要么自行发明超时策略。对于一个插件 SDK 来说，这是错误的编写范式：工具作者通常只需将 `exec.signal` 转发给其调用的实现，而部署策略来决定预算。
+
+与此同时，仓库中并非所有超时都是面向模型的工具调用预算。钩子通过直接调用 `ctx.bash` 执行命令钩子，而非通过 `ctx.tools.execute()`；`bash` 模型工具通过同一个后端复用前台执行、后台启动、后台轮询和钩子调用。一步到位地将所有超时移入工具插件会混淆这些路径，并有破坏钩子超时语义的风险。
+
+## 决策
+
+工具调用超时是仅适用于面向模型的工具执行的策略，由三部分组成：
+
+- `@deepseek-ai/dsh-timeout` 仍是拥有 `deadline()` 和 `timeoutOf()` 的共享库。
+- `@deepseek-ai/dsh-tools` 在 `tools/pre-execute` 和 `tools/post-execute` 之间有一个环绕分发的 waterfall（瀑布式事件）`tools/execute`。
+- `@deepseek-ai/dsh-timeout-policy` 从注册表读取每个工具声明的 `timeoutMs`，并通过派生新的 `exec.signal` 来包装有此声明的调用。
+
+执行流水线如下：
+
+```text
+ctx.tools.execute(exec)
+  -> tools/pre-execute
+  -> tools/execute
+       -> registry dispatch (the base next())
+            -> tool.execute(args, exec)
+            -> thrown tool errors normalize to ToolExecutionResult
+  -> tools/post-execute
+```
+
+默认行为是保守的：未声明 `timeoutMs` 的工具不会从该插件收到 `TOOL_TIMEOUT` 截止信号。
+
+### `tools/execute` 环绕 seam
+
+`@deepseek-ai/dsh-tools` 声明了一个 `tools/execute` waterfall，其基础 `next()` 是带规范化的分发 thunk——即同一个内部 `try`/`catch`，将抛出的工具错误（或未知工具错误）转换为 `isError` 的 `ToolExecutionResult`。监听器接收 `(exec, next)`：调用 `next()` 委托给分发（返回其结果，可选地包装），或返回替代结果以短路分发。整个流水线仍位于 `execute` 的外层 try/catch 内，因此抛出异常的监听器会变成 `isError` 结果，而非轮次失败。
+
+catch 是基础 `next`（而非 waterfall 之外的东西）这一点至关重要：当提供方看到超时信号并抛出自己的上游中止错误时，注册表分发首先将其转换为普通错误结果，然后 `timeout-policy` 才能将最终结果替换为 `TOOL_TIMEOUT`。
+
+### `timeout-policy` 插件
+
+该插件是 `@deepseek-ai/dsh-timeout-policy`，一个零配置的函数/命名空间插件（`name` / `inject` / `apply`），位于 `packages/timeout/` 组。每个工具的预算声明在工具自身，而非本插件：`ToolDefinition` 携带一个可选的 `timeoutMs`，由拥有该工具的插件从自身配置中设置。例如 `dsh-tool-web` 将 `fetchTimeoutMs` / `searchTimeoutMs`（默认 30000）解析到 `web_fetch` / `web_search` 的定义上：
+
+```yaml
+- id: timeout-policy
+  name: '@deepseek-ai/dsh-timeout-policy'
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+  config:
+    fetchTimeoutMs: 30000
+    searchTimeoutMs: 30000
+```
+
+超时放在工具定义上而非自由文本名称映射中，消除了拼错名称导致策略不生效的问题。`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` 永远不会看到本插件的截止信号。
+
+`timeout-policy` 拥有 `TOOL_TIMEOUT` 代码的两种用途：传递给 `deadline()`/`timeoutOf()` 的内部截止代码（有作用域，使嵌套的外层截止读为普通取消）和结构化工具结果错误代码。其替换结果为：
+
+```ts ignore-check
+function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
+  return {
+    content: [{ type: 'text', text: `Error: tool call timed out after ${timeoutMs}ms` }],
+    isError: true,
+    error: {
+      message: `tool call timed out after ${timeoutMs}ms`,
+      info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+    },
+  }
+}
+```
+
+这是一个协作式截止。它不会通过竞争工具 promise 来杀死任意工作；工具或其调用的能力必须遵循 `exec.signal` 并达到完全停稳。因此声明 `timeoutMs` 意味着「此工具与 `exec.signal` 协作」，插件 README 将此作为其契约。
+
+无需新的会话事件来保证可重建性：`TOOL_TIMEOUT` 是该调用的最终面向模型的 `tool/result`，因此现有会话日志已经记录了下一次模型请求所见的内容和结构化 `{ name, code }` 错误。
+
+### 现有工具适配
+
+`web_fetch` 和 `web_search` 已迁移。`dsh-tool-web` 保留对其面向模型 schema 的所有权，这些 schema 不暴露超时旋钮：`web_fetch` 移除了 `timeout_ms` 参数以匹配参考 agent 的形状，`web_search` 保持仅查询。工具体不导入 `@deepseek-ai/dsh-timeout`；它们将 `exec.signal` 转发给 `ctx.web`。
+
+`dsh-web-fetch-local` 保留一个配置级别的 `timeoutMs` 作为大型资源兜底，服务于直接调用 `ctx.web.fetch()` 的调用方和配置错误的部署；它不拥有面向模型的超时。当 `TOOL_TIMEOUT` 信号先到达 fetch 提供方时，提供方作用域的分类将其视为上游 `WEB_ABORTED`，而外层 `tools/execute` 包装器将最终工具结果替换为 `TOOL_TIMEOUT`。一个已发布的 web 工具部署将提供方兜底配置为高于 `timeout-policy` 预算，使工具调用策略在模型调用中通常胜出。
+
+`bash` 保持当前的后端超时路径。`dsh-tool-bash` 继续暴露 `timeoutMs` 和 `run_in_background`；`dsh-bash-local` 继续使用 `@deepseek-ai/dsh-timeout` 处理 `BASH_TIMEOUT`；钩子桥接继续调用 `runHook()` 并通过 `ctx.bash` 传递 `timeoutMs`。这保持了前台/后台/钩子行为的稳定。
+
+`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 可以后续添加调用方自有截止模式；这不在本次范围内。
+
+## 曾考虑的替代方案
+
+**将插件命名为 `tool-timeout`。** 字面的 Agent Note 名称匹配了 `gen-tool-catalog` 完整性守卫的 `packages/*/tool-*` glob，该 glob 要求每个匹配项注册一个面向模型的工具。本插件不注册任何工具——它是一个 `tools/execute` 包装器——因此 `tool-*` 名称要么导致 `verify-tool-catalog` 失败，要么强制产生一个误导性的启动条目。包（package）为 `@deepseek-ai/dsh-timeout-policy`，位于新的 `packages/timeout/` 组；cordis.yml 的 `id` 仍可为 `timeout-policy`。
+
+**仅保留逐工具的超时处理。** 这是 `bash` 和 `web_fetch` 的既有形态，也与 Claude Code 和 Codex 对 shell 命令的做法一致。它对 web 类工具不利，因为每个新的支持超时的工具都必须自行选择校验方式、上限语义、文档、快照和分类。插件集中了策略和分类，让每个工具的 schema 专注于业务输入。
+
+**立即将所有超时策略移出 bash-local。** 长期来看更干净——bash-local 将成为纯子进程执行器，所有调用方自行管理截止时间。但作为第一步不合适，因为钩子直接调用 `ctx.bash`，且 bash 模型工具的前台/后台语义与工具调用生命周期不同。保留 `BASH_TIMEOUT` 维持了这些路径的稳定，同时让工具调用超时在更简单的工具上先行验证。
+
+**为所有工具使用全局默认预算。** 方便，但会让工具作者意外：任何偶然运行超过全局预算的工具在插件加载后就会开始失败。逐工具声明预算使采纳成为有意的行为。
+
+**暴露面向模型的 `timeout_ms` 覆盖参数。** Claude Code 的 `WebFetch`/`WebSearch` 和 Codex 的 web 工具将超时排除在模型调用形状之外。模型覆盖会使超时成为提示词语义的一部分，并迫使 `timeout-policy` 引入 schema/参数剥离规则。Web 超时仅作为部署策略。
+
+**让 `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` 给超时一个词法作用域：启动、委托、分类、释放。
+
+**使用 `Promise.race` 对非协作工具强制超时。** 与超时库 Agent Note 相同的理由否决：它在底层进程、fetch 或提供方操作可能仍在运行时就将控制权返回给调用方。插件只发送信号；终止仍是实现方的责任。
+
+## 后果
+
+- `@deepseek-ai/dsh-tools` 在有意拆分 pre/post 工具钩子的拦截 seam 之后，获得了一个环绕分发的表面。其契约是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到原始的工具抛出。
+- 多个 `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-08-agent-scope-contexts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
new file mode 100644
index 0000000000..67955d377d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-08-agent-scope-contexts.md: e4c076189a8e8a438b561232d3779ad1f6ab0d08
+2026-07-08-agent-scope-contexts.zh.md: 35e725e43d402b048daf12c3b4be384b3fd2d2ce
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 68c9bd3b3e..e4c076189a 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-08-agent-scope-contexts.zh.md)
+
 ## Problem
 
 One application needs to share infrastructure across many agents while letting each agent have its own tools, prompt contributions, policies, and listeners. Shared adapters, persistence, and user interfaces belong to the deployment; a persona, tool variant, or listener often belongs to one agent.
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
new file mode 100644
index 0000000000..35e725e43d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
@@ -0,0 +1,171 @@
+# Agent Note: agent 即注册作用域
+
+Status: implemented
+
+[English](2026-07-08-agent-scope-contexts.md) | 中文
+
+## 问题
+
+一个应用需要在多个 agent（智能体）之间共享基础设施，同时让每个 agent 拥有自己的工具、提示词贡献、策略和监听器。共享的适配器、持久化和用户界面属于部署层面；而 persona、工具变体或监听器往往只属于某一个 agent。
+
+为每个 agent 建立独立的服务图会重复共享基础设施。使用一个全局注册图则有相反的问题：某个 agent 特有的贡献可能泄漏到无关的 agent 中。贡献者需要一种普通的注册机制，既能决定谁可以看到某项贡献，又能决定何时清理它。
+
+该机制还需要一个发布边界。agent 在其本地世界构建完成之前不得变为可见，拆除时也必须保留该本地世界直到最终工作停止。
+
+## 决策
+
+每个存活的 agent 拥有一个扁平的注册层，通过 `agent.ctx` 暴露。代码通过拥有某项贡献的上下文进行注册；具备作用域感知的服务将部署全局注册与恰好一个匹配的 agent 层合并；操作从其真实 agent 选择该层；该层在 agent 的完整发布生命周期内存在。
+
+Cordis 是 SDK 底层的插件框架。Cordis **上下文**是插件用来访问服务和注册效果的对象，效果的清理跟随该上下文。[Cordis 入门](../../../../docs/cordis-primer.md)对该框架有更详细的说明。
+
+对大多数贡献者而言，完整契约是四条规则：
+
+| 问题 | 规则 |
+|---|---|
+| 在哪里为某个 agent 注册行为？ | 通过 `agent.ctx` 调用普通注册 API |
+| 某个 agent 的操作能看到什么？ | 部署全局加上该 agent 的层，按所属服务的合并规则 |
+| 哪些作用域监听器会运行？ | 无作用域监听器加上为该操作所属 agent 注册的监听器 |
+| 该层存在多久？ | setup 在发布前完成；dispose 保留该层直到工作完全停稳 |
+
+作用域是扁平的。解析永远不会遍历父级或兄弟作用域，生命周期所有权也不意味着注册继承。
+
+```mermaid
+flowchart LR
+  plain["Plain plugin context<br/>cleanup follows the plugin"] -->|"registers into"| globalLayer["Deployment-global layer"]
+  agentAContext["agentA.ctx<br/>cleanup follows Agent A"] -->|"registers into"| agentALayer["Agent A layer"]
+  agentBContext["agentB.ctx<br/>cleanup follows Agent B"] -->|"registers into"| agentBLayer["Agent B layer"]
+
+  operationA["Operation for Agent A"] -->|"selects"| agentAView["Agent A view<br/>globals plus A local"]
+  globalLayer --> agentAView
+  agentALayer --> agentAView
+  operationB["Operation for Agent B"] -->|"selects"| agentBView["Agent B view<br/>globals plus B local"]
+  globalLayer --> agentBView
+  agentBLayer --> agentBView
+```
+
+缺失的交叉边即隔离规则：Agent A 的本地注册不会进入 Agent B 的视图，父级的注册也不会仅因父级拥有子级的生命周期就进入子级。
+
+配套的[运行时设计 Agent Note](2026-07-12-agent-scope-runtime-design.md) 阐述了实现与正确性推理。[subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md) 负责独立的 `persona`、`toolFilter` 和 `maxDepth` 功能。
+
+### 注册来源决定可见性与清理
+
+通过普通插件上下文进行的注册是部署全局的，随该插件一起 dispose（资源释放）。同一方法通过 `agent.ctx` 调用则贡献给一个 agent，随该 agent 的作用域一起 dispose。
+
+| 注册来源 | 默认可见性 | 随谁 dispose |
+|---|---|---|
+| 普通插件上下文 | 每个符合条件的 agent 视图 | 注册插件 |
+| `agent.ctx` | 仅该 agent 的视图 | agent 作用域 |
+
+工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此契约。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
+
+普通贡献者的模式是在 agent setup 期间注册完整的本地世界：
+
+```js
+const handle = await ctx.agents.create({
+  sessionId: SessionId('reviewer'),
+  agentOptions: { model: 'model-name' },
+  setup(agentCtx) {
+    agentCtx.systemPrompt.section({
+      name: 'deployment:persona',
+      order: 0,
+      text: 'Review code, but do not modify files.',
+    })
+    agentCtx.tools.register({
+      name: 'review_summary',
+      description: 'Return the review summary.',
+      parameters: { type: 'object', properties: {} },
+      async execute() {
+        return [{ type: 'text', text: 'review complete' }]
+      },
+    })
+  },
+})
+
+ctx.tools.get('review_summary')                // undefined: not global
+ctx.tools.get('review_summary', handle.agent)  // the reviewer-local tool
+
+await handle.dispose()
+ctx.tools.get('review_summary', handle.agent)  // undefined: scope is gone
+```
+
+setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其契约仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
+
+### 操作选择视图
+
+注册来源与操作主体是两个独立的事实。通过 `agent.ctx` 调用服务决定的是新注册归属何处，并不将后续读取绑定到该 agent。
+
+工具查找与执行接收其所服务的 agent。提示词组装接收正在构建请求的 agent 的组装上下文。事件分发接收其领域主体。这使共享服务实例可在多个 agent 间复用，同时让每个操作的视图保持显式。
+
+只有采纳了作用域契约的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
+
+### 作用域事件将路由与事件数据分离
+
+关于 Agent A 的事件通常到达无作用域监听器和 A 作用域监听器，而不到达 B 作用域监听器。没有 agent 主体的事件仅到达无作用域监听器。
+
+在 Cordis 层面，`Scoped<T>` 是一个不透明的路由接收器。它携带用于选择监听器的过滤器，但本身不是领域对象。因此事件签名将真实的 `Agent`、工具执行、审批请求或其他主体作为显式参数保留，供监听器检查。
+
+以 `{ global: true }` 注册的监听器有意绕过上下文受众过滤，但其清理仍跟随注册上下文。注册表成员变更通知保持不过滤，因为它们描述的是共享注册表状态而非某个 agent 的操作。生成的[事件目录](../../../../docs/cordis-catalog/events.md)是详尽的事件参考。
+
+### 创建最后发布，dispose 最后撤销
+
+`ctx.agents.create()` 和 `resume()` 构建未发布的会话、作用域、agent 和驱动器。它们等待 `setup`，准入最终的会话和 agent 条目，按序公告，启动循环，然后才返回 handle。
+
+可选的创建信号仅在创建或恢复挂起期间取消工作。promise resolve 后，返回的 `AgentHandle` 拥有显式 dispose 权。
+
+如果加载、setup、准入或发布失败，私有事务回滚其准备的一切。使用同一个调用方提供的存活 ID 的并发操作可能都到达 setup，但最终注册表条目只准入一个；每个失败者拒绝并清理其私有资源。在等待 dispose 完成后的顺序复用仍然有效。
+
+`AgentHandle.dispose()` 反转边界。它停用创建或驱动，等待同步发布解除，停止并排空驱动器和最终会话刷写，分离 agent 和会话，最后 dispose 作用域。重复或竞争的 dispose 请求合并为一个完成 promise。
+
+调用方的 Cordis 上下文和具体的 AgentLoop 工厂是结构性共同所有者。卸载任一方都会 dispose 事务或存活 agent。
+
+```mermaid
+flowchart TB
+  request["Create or resume"] --> privateWorld["Build private session, scope, agent, and driver"]
+  privateWorld --> setup["Await composition through agent.ctx"]
+  setup --> admission["Admit final session and agent entries"]
+  admission --> publish["Announce lifecycle and start the driver"]
+  publish --> live["Return AgentHandle"]
+
+  privateWorld -->|"failure, cancellation, or owner loss"| rollback["Rollback private work"]
+  setup -->|"failure, cancellation, or owner loss"| rollback
+  admission -->|"duplicate or owner loss"| rollback
+  publish -->|"listener failure or owner loss"| rollback
+  live -->|"handle or owner disposal"| quiesce["Stop and drain work"]
+  rollback --> quiesce
+  quiesce --> detach["Detach agent, then session"]
+  detach --> revoke["Dispose the agent scope"]
+```
+
+## 安全与权限是非目标
+
+agent 作用域组合的是受信的同进程注册。它不沙箱化插件、不定义父到子的权限格、不在创建时冻结授权、也不保证子级不能做超出父级的事。
+
+父级可以拥有一个可见工具比自身更广的子级，因为生命周期所有权不赠予也不限制注册。持有 Cordis 上下文的插件同样运行在同一进程中，可以直接调用可用服务。
+
+需要非升权保证的部署需要独立的权限表示、传播规则和执行检查。父级子集授权、创建时授权快照、显式未来授权 API，以及通用的能力/输出/终止标签均不在本决策范围内。
+
+## 曾考虑的替代方案
+
+被否决的设计要么将可见性与清理分离，要么只覆盖一类注册，要么重复共享基础设施，要么将生命周期所有权与继承混为一谈。
+
+### 向每个注册传递 agent 选项
+
+类似 `tools.register(definition, { agent })` 的 API 在每个注册表中重复作用域管道，且允许可见性所有权与清理所有权漂移。通过 `agent.ctx` 注册使两个事实跟随同一个 Cordis effect owner。
+
+### 过滤事件但保持注册表全局
+
+监听器过滤可以阻止错误的钩子运行，但无法限定工具 schema、可执行查找、提示词段落、变量或其他已注册数据的作用域。agent 本地组合仍需临时的全局变更。
+
+### 为每个 agent 创建独立的服务图
+
+所需的视图是共享部署服务加上一个本地注册层。每 agent 一个图会重复适配器，并使共享持久化、提供方注册表和应用启动复杂化。
+
+### 继承父级注册作用域
+
+父子关系描述的是生命周期和对话谱系，而非通用合并策略。层级查找会让无关服务意外继承，且在没有独立权限模型的情况下无法定义安全性。
+
+## 后果
+
+贡献者使用一种熟悉的模式：通过插件上下文注册共享行为，通过 `agent.ctx` 注册本地行为，在操作中选择真实 agent，dispose 返回的 handle。从观察者角度看 setup 是原子的，拆除则保留本地行为直到工作停止。
+
+代价是显式的主体选择、异步的编程式创建，以及服务需要逐个采纳作用域。扁平注册作用域有意不等同于权限，subagent 组合控制作为独立功能存在，而非隐藏的作用域语义。
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 a9197de179..e2df9a902b 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
@@ -8,7 +8,7 @@ Tool outputs need bounded model-facing previews, but some oversized results are
 
 Before this change the behavior was uneven. `dsh-bash-local` already writes complete stdout/stderr streams to private temp spill files when its in-memory tail overflows, but ordinary text tool results were returned inline unless the tool hand-rolled its own cap. The [tool result retention library](2026-07-06-tool-result-retention-library.md) owns preview mechanics, but it does not own storage or an execution-pipeline policy that applies those mechanics to final tool results.
 
-The shape matches the timeout policy design: a tool author normally returns the text result, and a policy plugin enforces the deployment's default context budget. Tool-specific early spill remains possible later for outputs that do not survive to the final `ToolExecutionResult`; the first cut proves the default final-result path.
+The shape matches the timeout policy design: a tool author declares a canonical value plus Native renderer, and a policy plugin enforces the deployment's default context budget on rendered content. Tool-specific early spill remains possible for provider acquisition bounds; tool-owned surface spill may retain a complete acquired canonical value while replacing only presentation. The [canonical tool-output contract](2026-07-20-canonical-tool-output-contract.md) owns that split.
 
 ## Decision
 
@@ -97,9 +97,13 @@ The policy skips `read` to avoid a circular `read -> spill file -> read again` l
 ```ts ignore-check
 ctx.tools.register(defineTool({
   name: 'web_fetch',
+  output: {
+    schema: WEB_FETCH_RESULT_SCHEMA,
+    render: (_args, value) => [{ type: 'text', text: formatFetchOutput(value) }],
+  },
   async execute(args, exec) {
     const result = await ctx.web.fetch({ url: args.url }, exec.signal ? { signal: exec.signal } : undefined)
-    return [{ type: 'text', text: formatFetchOutput(result) }]
+    return 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
new file mode 100644
index 0000000000..b003d4de31
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-12-agent-scope-runtime-design.md: cf42bbacbfb9d2fcbd72aafba5ea02ddf83e1ce5
+2026-07-12-agent-scope-runtime-design.zh.md: d0d599664290dc7dc4debe1ccf8f419a40912ba1
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 e0de18e90a..cf42bbacbf 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-12-agent-scope-runtime-design.zh.md)
+
 ## Problem
 
 The [agent-scope contract](2026-07-08-agent-scope-contexts.md) is simple for contributors: register through `agent.ctx`, resolve one global-plus-agent view, publish only after setup, and retain the scope until work stops. The runtime must preserve that contract across a cooperative plugin framework, asynchronous creation, reentrant listeners, durable session commits, and worker or process failure.
@@ -218,7 +220,7 @@ A fresh registry-assigned Symbol provides collision-free execution identity with
 
 Arguments are materialized once where model/tool JSON enters the pipeline. Pre-, around-, and post-execute listeners operate on the typed execution and decisions. Call ID correlation, approval, monotonic guards, and Code Mode nesting remain explicit relational checks.
 
-After the last post-execute listener, the registry materializes and freezes the accepted final result once. Every synchronous `tools/result` observer receives that exact committed object, and observer failures are contained individually. An outer pipeline failure is normalized into a committed error result, so observers can discard staged work against the same authoritative boundary.
+After post-execute or outer pipeline normalization, the registry losslessly snapshots the candidate result, converting a snapshot failure into an ordinary error, invokes the call's snapshotted optional `ToolDefinition.finalizeContent` callback, then materializes and freezes the accepted final result once. The callback may replace only content, so structured error identity, contexts, and metadata remain registry-owned even when a tool enforces a last-mile result bound. Every synchronous `tools/result` observer receives that exact committed object, and observer failures are contained individually. An outer pipeline or candidate-snapshot failure is normalized before final content, so observers can discard staged work against the same authoritative boundary.
 
 ### The assembly waterfall owns the final model-visible composition
 
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
new file mode 100644
index 0000000000..d0d5996642
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -0,0 +1,392 @@
+# Agent Note: Agent 作用域运行时设计与正确性
+
+Status: implemented
+
+[English](2026-07-12-agent-scope-runtime-design.md) | 中文
+
+## 问题
+
+[agent 作用域契约](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份契约。
+
+主要的设计风险是为每个竞态条件引入第二套机制。独立的预留、就绪哨兵、取消中继、快照层和保护注册表可能镜像同一个事实，直到没有读者能分辨哪个才是权威的。这些机制还会诱使运行时把可信的类型化调用当作敌对的序列化边界来处理。
+
+实现需要足够的状态来维护真实的所有权和结算边界，但不能更多。正确性审查者必须能够从接受、发布到拆除，沿着一条事实链跟踪下去，而无需在并行的表示之间做调和。
+
+## 决策
+
+运行时对每个独立事实使用一种机制。作用域路由有一个不透明载体与共享 layer store；每个活跃的注册表对象有一条注册表条目；每个创建或恢复操作有一个事务；类型化的同进程调用借用 readonly 值；真实数据边界只物化一次；协作式提示词组装的结果即为权威；worker/进程代码仅在不同所有者确实可能竞争时才保留独立的终止态和完全停稳态。
+
+该设计可概括为七项选择：
+
+| 问题 | 权威机制 |
+|---|---|
+| 选择全局加某个 agent 的注册 | 不透明作用域键、路由载体与共享 layer store |
+| 拥有一个活跃的 agent 或会话 | 由其 disposer 捕获的单条注册表条目 |
+| 协调创建/恢复 | 单个 `AgentCreationTransaction` |
+| 保护持久化、队列、模型或协议格式数据 | 在该边界处一次性物化 |
+| 在同一进程内传递类型化值 | 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 如何融入生命周期。
+
+## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
+
+理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall（瀑布式事件）让监听器按顺序变换或否决一个操作。
+
+### 上下文是贯穿单个服务图的所有权路径
+
+所有 agent 共享一个 Cordis 服务图。派生的上下文不会克隆 `ToolRegistry`、`SystemPrompt`、持久化或模型适配器；它改变的是：通过该上下文进行的注册如何被标记，以及哪些 effect 拥有其清理逻辑。
+
+`agent.ctx` 就是这样一个派生上下文。服务调用仍然到达共享实例，而注册操作可以检查其调用上下文并将贡献存储在最近的作用域键下。普通的插件上下文不携带作用域键，因此注册到全局。
+
+### Fiber 与 effect 使清理成为结构性的
+
+Cordis fiber 是插件或子上下文被激活时创建的活跃实例。其状态记录该生命周期是 active、unloading、failed 还是 disposed。`ctx.effect()` 和 `ctx.on()` 返回 disposer，同时将这些 disposer 附加到注册所在的 fiber，因此卸载一个插件或 agent 作用域会移除通过该上下文注册的一切，无需单独的清单。
+
+vendor 中的 Cordis fiber 实现在任意 setup 或 `internal/plugin` 观察者运行之前就建立了所有权。可重入的卸载可以看到已启动的子 fiber 或 effect，拒绝卸载开始后添加的 effect，并通过一个公开的一次性 disposer 加入已启动的清理。拆除观察者被逐个隔离，因此一个回调无法阻止结构性清理。
+
+这些是框架生命周期保证，而非 agent 特有的策略。Agent 创建依赖它们，因为 setup 可以激活任意插件并同步重入所有者的 dispose。
+
+### Receiver 路由监听器；waterfall 组合决策
+
+Cordis 使用 dispatch receiver（`this`）过滤监听器，而 harness 的监听器需要一个显式的 agent、execution、request 或其他主体。`Scoped<T>` 标记作用域事件声明所期望的 receiver，但运行时载体刻意不暴露主体 API。
+
+因此，产品辅助函数构造载体并单独传递领域主体。这防止监听器路由变成另一套对象模型，并使事件签名在不了解载体内部的情况下也可理解。
+
+Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则否决或替换下游结果。Waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
+
+## 作用域路由：一个不透明键选择一层
+
+scope 包实现了 Cordis 路由所需的最小对象。其载体仅持有一个组合的服务过滤器和作用域谓词，而包私有地记录不透明键，并单独暴露会等待作用域 fiber 完全停稳的 disposer。
+
+### 作用域标识使用对象标识
+
+`ScopeKey` 是一个按标识比较的不透明对象。Harness 使用活跃的 `Agent` 作为自身的键，但该原语与领域无关，支持其他作用域所有者。
+
+`createScope(parent, key)` 返回一个作用域，其 `ctx` 共享父级的服务，其 effect 被标记为该键。`scopeOf(ctx)` 读取最近的注册键。`scopeTarget(base, key)` 创建事件接收器，其过滤器保留 base receiver 的 Cordis 服务过滤器，然后接纳无作用域的监听器和具有该确切键的监听器。
+
+Receiver 是一个小型载体而非领域对象的透明代理。需要 agent 的代码接收显式的事件参数；需要注册所有权的代码接收 `agent.ctx`。
+
+### 注册表读取叠加一个精确 layer
+
+作用域感知的注册表使用 `ScopedLayers`，拥有一个即时创建的全局 aggregate 和按标识键惰性创建的 aggregate。读取解析全局 layer 和至多一个精确局部 layer；它不创建状态，也从不遍历父级链。注册可见性与 Cordis effect 所有权都从同一个上下文派生，而回收会等待具体 layer 的完整 aggregate 变空（见[决策](2026-07-12-scoped-layers-store.md)）。
+
+每个服务保留其领域规则。命名 command 和提示词视图使用共享的、保持插入顺序的 shadow 合并；工具保留更丰富的 resolver，因为限制会在加入局部工具前过滤全局工具，保留的 Code Mode transport 则单独插入。提示词变量和工具 guard 保持实时迭代，而工具提供方成员关系按每次 assembly 物化。Scope 提供存储生命周期和命名遮蔽，而非通用的注册表视图。
+
+### 融合 dispatch 辅助函数防止主体漂移
+
+`agentEvents(context, agent)` 构造 agent 的载体并注入同一个 agent 作为事件主体。会话、工具、approval、提示词和 subagent 服务同样从它们已拥有的对象派生路由，而非接受一个无关的键。
+
+类型标记拒绝普通的裸 receiver 误用，开发环境不变式覆盖直接 JavaScript 或强制转换的 dispatch。主体保持显式，因为路由正确性和有用的事件数据是不同的关注点。
+
+## Agent 创建：一个事务拥有完整操作
+
+创建和恢复是一个具有多个阶段的异步生命周期，而非多个生命周期。`AgentCreationTransaction` 拥有调用方和工厂的活跃性、可选取消、私有资源、发布、回滚，以及每个所有者观察到的记忆化拆除。
+
+### 注册表条目是唯一的活跃标识记录
+
+AgentRegistry 和 SessionStore 各为每个活跃对象保留一条注册表条目。注册表条目持有稳定 ID、对象、作用域载体，以及属于该对象的少量发布或追加状态。
+
+detach 闭包捕获其确切注册表条目。它仅在映射仍指向该注册表条目时才删除，因此旧的 disposer 无法删除一个复用相同 ID 的后续对象。注册表不会重读可变的调用方对象来决定标识。
+
+没有预留 API。调用方提供的 ID 在最终写入注册表时被接纳。并发的同 ID 操作可能都完成私有 setup；恰好一个最终 `enter()` 成功，每个失败者回滚其私有资源。前一个 disposer 达到完全停稳态后，顺序复用即为有效。
+
+### 事务在等待之前就拥有准备工作
+
+事务在持久化加载或 setup 可能挂起之前，就被安装到调用方的 Cordis 上下文和具体的 AgentLoop 工厂下。它还在公开操作结算之前观察可选的创建/恢复信号。
+
+创建准备一个新 Session。恢复加载并验证持久化的 Session，然后准备相同的活跃会话标识。两条路径随后构建作用域、agent 和 driver，并调用相同的 setup/发布算法。
+
+工厂存储具体的 trace 目标，但通过调用方绑定的 Cordis trace 调用它们。这保留了依赖来源和调用方所有权，而不堆叠 trace 代理。
+
+### Setup 是私有世界内的可信组合
+
+Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开契约不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
+
+事务将异步加载和 setup 与停用进行竞争，而非无限等待外部代码拥有的 promise。如果取消或所有者卸载获胜，即使外部 promise 永不结算，公开创建也会在事务拥有的清理之后拒绝。
+
+### 发布有一条有序的提交路径
+
+发布按观察者所需的顺序接纳和宣告资源：
+
+1. 将会话写入注册表。
+2. 将 agent 写入注册表。
+3. 宣告 `session/created`。
+4. 宣告 `agent/created`。
+5. 启用公开驱动。
+6. 发射 `agent/session-start`。
+7. 启动 driver。
+
+Agent 在两个注册表和创建通知都达成一致之前绝不驱动。同步监听器可以否决或 dispose 一个所有者；事务记录发布进行中，并等待该回调栈展开后再继续拆除。每个已开始的创建宣告在回滚期间都有匹配的销毁宣告。
+
+以下序列图隔离了非显而易见的竞态：同步创建监听器可以在发布调用栈仍拥有两个注册表条目时请求 dispose。拆除必须立即停用，但要等待该栈展开后才停止和分离任何东西。
+
+```mermaid
+sequenceDiagram
+  participant Tx as AgentCreationTransaction
+  participant Registries
+  participant Listener as Synchronous listener
+  participant Driver
+
+  Tx->>Tx: mark publication in progress
+  Tx->>Registries: announce agent/created
+  Registries->>Listener: invoke inside the same call stack
+  Listener->>Tx: dispose reentrantly
+  Tx->>Tx: deactivate, teardown waits for publication
+  Tx-->>Listener: disposal request accepted
+  Listener-->>Registries: return
+  Registries-->>Tx: announcement unwound
+  Tx->>Tx: resolve publication settlement
+  Tx->>Driver: stop and drain
+  Tx->>Registries: detach agent, then session
+  Tx->>Tx: dispose scope and resolve teardown
+```
+
+### 拆除在撤销注册之前保留工作
+
+每个拆除请求加入一条记忆化路径。顺序为：
+
+1. 停用创建或驱动，让同步发布完成。
+2. 停止并排空 driver，包括空闲注入刷新。
+3. 分离 agent。
+4. 分离会话。
+5. Dispose agent 作用域。
+6. 退役事务所有权追踪。
+
+此顺序让最终的 agent 和会话事件能使用匹配的作用域监听器，并使持久化观察者在最终刷新完成前保持附加。作用域 dispose 放在最后，因为注册撤销是外部可见的生命期边界。
+
+## 会话追加：物化、验证、提交、通知
+
+会话事件跨越持久化边界，因此追加操作拥有其数据。算法的其余部分使用一条已附加的注册表条目和一个提交点。
+
+### 持久化数据一次性物化
+
+Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造函数或追加路径在存储前物化并验证它们，并暴露冻结的快照，因此后续调用方的修改无法改变持久化、回放或模型重建。
+
+这是一个真实的所有权边界：值离开调用方，可能被持久化，且必须在之后重建相同的请求。这比类型化的同进程回调或注册表定义有意更严格。
+
+### 提交前监听器可以否决；提交后观察者不能
+
+追加遵循一个序列：
+
+1. 物化持久化事件和表面意图。
+2. 取得 SessionEntry 的独占所有权，并拒绝该注册表条目上的重入追加。
+3. 解析作用域回调并运行内部不变式验证。
+4. 恰好推送一次；这是提交点。
+5. 逐个通知每个观察者，隔离同步和异步失败。
+6. 释放追加状态并兑现发布期间请求的 detach。
+
+没有观察者错误能让已提交的事件看起来未提交，一个坏的监听器也无法饿死后续监听器。Session 不变式在提交前暂存其转换，仅当同一事件到达被隔离的提交后观察者时才应用。
+
+`flush()` 启动每个持久化监听器并等待所有结果后再报告失败。这种有意的 all-settled 行为防止同步失败饿死另一个后端或最终刷新。
+
+## 信任边界：仅在所有权真正变更时复制
+
+运行时区分类型化的进程内契约与序列化及持久化边界。这是值和回调的主要简化规则。
+
+| 边界 | 所有权规则 |
+|---|---|
+| 同进程内的类型化服务/插件调用 | 借用 readonly 值和回调 |
+| 解析的插件配置或外部文件 | 验证语义和结构输入 |
+| 队列中的收件箱消息 | 在异步消费前物化 |
+| 模型/工具 JSON 输入或输出 | 在模型/工具边界处物化 |
+| 持久化会话或持久化数据 | 在提交前物化并验证 |
+| Worker、进程或协议格式消息 | 序列化、验证并拥有解码后的值 |
+
+测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产契约。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式（wire format）边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
+
+回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件契约隔离失败。
+
+## 工具与提示词：单一视图、权威组装、已提交的结果
+
+工具展示和执行共享一个私有解析器。提示词组装仍然是可信的协作式组合：注册表提供有序输入，assembly waterfall 的返回值就是 agent loop（智能体循环）记录和发送的内容。执行仅在策略或结果结算必须单调时才使用独立的单向边界。
+
+### 一个解析器定义工具视图
+
+私有解析器应用当前展示模式、活跃的全局限制、精确的局部叠加和局部遮蔽。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 语义。实现要求是一致性：被过滤掉的全局工具不能通过另一条查找路径仍可执行，局部遮蔽的定义就是被展示和执行的同一个定义。
+
+`ToolRestriction` 接受 readonly 的 allow/deny 名称并将其编译为内部集合。多个限制取交集。公开的 `visible()` 和 `knownNames()` 方法是不必要的，因为只有注册表需要中间视图。
+
+### 工具执行拥有标识和边界物化
+
+注册表为每次执行分配一个新的带品牌的 `Symbol` token。嵌套的 Code Mode 调用将外层 token 作为 `parent` 携带，因此结构化输出可以通过标识将内层捕获与其外层 `run_code` 结果关联。
+
+注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化契约，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
+
+参数在模型/工具 JSON 进入流水线时一次性物化。Pre-、around- 和 post-execute 监听器操作类型化的 execution 和决策。Call ID 关联、审批、单调守卫和 Code Mode 嵌套仍然是显式的关系检查。
+
+在 post-execute 或外层流水线完成规范化后，注册表先为候选结果创建无损快照，并将快照失败转为普通错误；随后调用在本次调用创建时已快照的可选 `ToolDefinition.finalizeContent` 回调，最后一次性物化并冻结被接受的最终结果。该回调只能替换内容，因此即使工具强制最后一道结果上限，结构化错误标识、上下文与元数据仍由注册表拥有。每个同步的 `tools/result` 观察者接收该确切的已提交对象，观察者失败被逐个隔离。外层流水线失败或候选快照失败会在最终内容处理之前被规范化，因此观察者可以丢弃针对同一权威边界的暂存工作。
+
+### Assembly waterfall 拥有最终的模型可见组合
+
+SystemPrompt 首先将全局加 agent 的段、变量和工具提供方解析为确定性的注册表贡献。作用域过滤的 `system-prompt/assemble` waterfall 随后可以重排、替换、添加或移除任何段、变量或 schema。其返回的组装结果即为权威；没有后续的恢复步骤，普通提示词段、工具定义或提供方结果上也没有终态元数据。
+
+这是一个可信的同进程扩展 seam，而非权限边界。修改 Code Mode 的 `run_code` schema 或 `tools:sdk` 指令，或结构化子级的捕获 schema 或指令的监听器，有责任在其返回的组装中保持协议的一致性。ToolRegistry 仍然保留 `run_code` 不受普通工具注册和限制影响，因为那些是注册表不变式，但 assembly 中间件仍然可以自由变换最终的模型可见表面。
+
+Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子级的精确作用域中，而 Code Mode 从同一个已解析的工具视图派生其传输和 SDK。第二套命名保护系统需要另一套所有权和碰撞规则来覆盖任意 schema 提供方（包括有意贡献重复名称的提供方），却不创建新的信任边界。
+
+### 结构化输出仅提交权威结果
+
+结构化输出将子作用域组合与两阶段执行提交相结合。子级在发布前注册其 `structured_output` 工具和指令；可信的 assembly 监听器可以变换这些普通贡献，并有责任在期望子级完成时保持协议。工具体验证候选值并按当前 `ToolExecution` 暂存，但成功捕获仅由不可变的 `tools/result` 观察决定。
+
+对于原生调用，观察者仅在该确切执行的最终结果成功时才删除暂存并提交其值。因此 post-execute 阻止或外层流水线失败不会留下已捕获的值。
+
+对于 Code Mode SDK 调用，内层成功结果记录 `{ parentToken, value }` 而非提交。观察者等待 token 匹配 `parentToken` 的 `run_code` 执行，仅在该外层最终结果也成功时才提交。程序失败、运行时中止或外层 post-policy 拒绝会丢弃待定值。
+
+一旦值处于待定或已提交状态，作用域单调守卫拒绝后续工具调用。提交后，普通串行的 `agent/turn-stop` 监听器在 continuation 和 steering（中途引导）已折叠之后返回停止决策。Schema 验证失败仍然是普通的 `INVALID_ARGS` 工具错误，子级可以在同一轮次内重试。
+
+纯 Code Mode 的注册表贡献从原生 wire schema 中省略 `structured_output`，并通过生成的 SDK 暴露它。Assembly waterfall 可以有意改变该展示；执行仍然针对子作用域定义进行验证，监听器拥有其创建的任何替代模型可见路由的一致性。
+
+### 三个执行边界有意设为单向
+
+提示词组装有意是协作式的，但三个执行事实在其可扩展阶段之后需要单向结算：
+
+| 边界 | 最终权力 | 为何普通监听器顺序不够 |
+|---|---|---|
+| 工具 pre-policy | 单调拒绝 | 后续监听器不得重新允许已被拒绝的调用 |
+| 工具结果 | 观察不可变的已提交结果 | 结构化输出必须仅提交实际逃出流水线的结果 |
+| 轮次 continuation | 在普通 continuation 折叠之后停止 | 已提交的终端输出必须结束轮次 |
+
+`ToolGuard` 是单调策略注册表。已提交的工具观察是上述被隔离的 `tools/result` 点。终端结构化输出监听普通串行的 `agent/turn-stop` 折叠，在正常 continuation 和 steering 决策之后；类型化的监听器契约不需要公开的 `strictSerial()` dispatcher。
+
+### Skill 和 approval 服务信任类型化调用方
+
+Skill 注册表定义和 approval 策略是 readonly 的同进程契约。它们的服务不克隆回调对象，也不防御交接后的回调替换。
+
+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。
+
+`SubagentStartRequest.signal` 是必需的。中止它会在启动期间和就绪之后请求取消。`SubagentRun.dispose()` 也请求取消并等待完全停稳。没有单独的公开 `run.cancel()` 通道。
+
+可选的 `sendMessage()` 支持能接受 steering 的活跃后端。可选的 `resume()` 返回 `Promise<SubagentRun>`，因为恢复的子级有相同的异步就绪边界。
+
+服务在调用提供方之前验证提供方能力和请求语义。提供方拒绝在拒绝逃出之前清理所有部分资源，且不发射 `subagent/start`/`subagent/end` 对。兑现之后，服务附加结果观察、发射作用域 start 并返回 run。提供方移除阻止后续 start，但不撤销提供方已接受的 run。
+
+### 进程内提供方复用核心事务
+
+Spawn 和 fork 共享一个进程内 driver。它通过 `parent.ctx` 创建子级，将必需的 signal 传入核心创建事务，并在未发布的 setup 期间安装 persona、工具限制和结构化输出贡献。
+
+提供方等待创建并仅返回已发布的 run。在交接时，核心创建分离其仅用于创建的 abort 监听器；提供方在安装活跃 run 监听器之前立即重新检查 signal，因此在那个窄窗口中的 abort 会 dispose 新句柄而非逃脱取消。父级拆除跟随子级，因为操作属于 `parent.ctx`；提供方卸载阻止新 start 但不成为已接受 run 的第二个撤销所有者。Run disposer 取消子级并等待 AgentHandle 的有序拆除。
+
+Spawn 使用空会话种子。Fork 使用经验证的已完成轮次前缀。对话种子仅改变历史，不导入作用域、工具、服务或权限。
+
+### ACP 提供方拥有进程直到就绪或清理
+
+ACP 提供方跨越真实的进程和协议格式边界，因此它保留验证、环境清洗、消息序列化、abort/进程竞争，以及从 kill 到进程退出并完全停稳的过程。
+
+Start 仅在 `initialize` 和 `newSession` 成功后才 resolve。Abort、spawn 失败、RPC 失败或无效启动响应在拒绝前回收进程。就绪后，result 映射 ACP 提示词结果和流式输出；dispose 请求取消、关闭连接并通过一条记忆化路径等待进程退出。
+
+## 工作流与 ACP UI：仅保留独立的异步事实
+
+Worker 和编辑器桥接比同进程注册表需要更多状态，因为消息、进程死亡和渲染可以独立结算。它们的状态围绕这些真实事实组织，而非重复的取消协议。
+
+### 工作流子级是待定 start 或已发布记录
+
+工作流宿主保持待定的提供方 start promise 和已发布的子级记录。子级仅在异步 `SubagentService.start()` 兑现时才从待定变为已发布；被拒绝的 start 清理其部分提供方工作且不产生子级生命周期对。
+
+一个宿主拥有的 AbortController 向待定和活跃子级提供必需的 signal。关闭工作流准入中止该 signal，因此没有重复的 `ChildCancel` worker RPC 或显式的宿主侧 `run.cancel()` 扇出。完全停稳需要等待待定 start 和已发布子级 dispose 两者。
+
+Worker 边界仍然序列化请求和结果。宿主保留首个终端结果仲裁、精确的子级计数、worker 死亡处理、优雅终止、迟到/重复消息拒绝和有界清理，因为结果接收、worker 退出和子级完全停稳是真正独立的事实。
+
+### 终端结果与物理清理保持分离
+
+工作流结果按公开优先级规则记录首个被接受的终端结果。该结果选定后清理可以继续：活跃子级仍需 dispose，worker 仍需终止，慢速外部后端可能超出配置的优雅期限。
+
+公开 dispose 在调用回调之前取得其记忆化 promise 的所有权。Worker 死亡在处理任何排队的迟到子级请求之前关闭准入，合成缺失的生命周期结束，并启动子级/进程清理而不重写已声明的结果。
+
+### ACP 提示词结算不依赖渲染成功
+
+ACP UI 直接将提示词与其观察到的轮次关联。它不从 `logWatermark` 扫描，也不使用会话状态作为第二个调和预言机。
+
+提示词处理在 transcript（文本记录）渲染的 `finally` 中结算关联。渲染失败可以导致展示失败，但不能跳过提示词结算或让会话永久处于进行中状态。对同一持久化的调用方提供的会话 ID 的并发加载仍被排除，因为那是真实的持久化标识竞争，而非 UUID 碰撞问题。
+
+## 正确性强制
+
+该设计通过类型、运行时逃逸点、生成的契约和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
+
+### 类型使常规路径难以误用
+
+Readonly 契约描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露就绪性。
+
+TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进程消息或持久化文件，因此运行时强制保留在这些逃逸点。
+
+### 运行时不变式覆盖跨服务事实
+
+`dsh-scope/invariant` 配套插件在被选用时验证每个声明的作用域事件使用带标记的载体，以及暴露主体的事件族使用匹配的键。独立的 `dsh-session/invariant` 贡献在追加提交前暂存 trace 验证，并在同一事件提交后推进；二者都通过 `ctx.invariants` 注册。
+
+该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合契约变成推测性的运行时机制，却不保护真实的外部边界。
+
+### 生成的产物使公开契约保持对齐
+
+事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、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)拥有公开扁平作用域契约的替代方案。此处的替代方案关注实现形态。
+
+### 使用透明代理作为作用域载体
+
+模拟主体的代理必须保持属性、可调用、可构造、私有字段、描述符和代理不变式行为，而监听器路由从不需要这些。一个小型不透明载体保持过滤器和键，而显式事件参数携带主体。
+
+### 在 setup 前预留 agent 和会话 ID
+
+预留防止重复的私有 setup 工作，但需要跨服务能力、释放排序、废弃预留清理和已准备对象绑定。ID 由调用方提供，并发复用是调用方错误；最终写入注册表时可以选择赢家，而失败的事务干净地回滚。
+
+### 对每个类型化的同进程参数做快照
+
+通用复制防御有状态 getter 和违反 readonly 契约的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
+
+### 为就绪、取消和 dispose 提供独立控制器
+
+并行哨兵可能都镜像一个操作是否活跃。一个事务或 start promise 拥有操作；独立 promise 仅在发布展开、外部工作、终端结果和物理层面的完全停稳可以独立结算时才保留。
+
+### 保留同步 subagent start 加 `run.started`
+
+这将提供方接受与就绪分离，迫使每个消费方注册部分 run、附加结果观察、等待就绪并清理就绪失败。异步 start promise 使提供方到调用方的所有权转移本身成为就绪边界。
+
+### 在 assembly 之后恢复选定的提示词或工具贡献
+
+Waterfall 之后的恢复步骤会在文档化的协作式 seam 之后创建第二套组合规则。正确分配规范的存在或缺失还需要为任意工具 schema 提供方制定所有权和碰撞规则，而这些提供方的普通输出可能包含重复名称。作用域注册已经提供了所需的按 agent 隔离，可信的 assembly 监听器拥有其返回内容的协议一致性，因此命名恢复增加了机制却不建立独立边界。
+
+### 用同进程加固替代 worker/进程生命周期守卫
+
+Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化边界。首个结果仲裁、验证、环境清洗和使进程完全停稳的清理即使在敌对的同进程回调机制不存在时仍然必要。
+
+## 后果
+
+实现更小，其证明与所有权图具有相同的形状。一个键选择一层，一条注册表条目拥有一个活跃注册表对象，一个事务拥有创建，一个解析器拥有工具视图，一个异步 promise 转移 subagent 所有权。
+
+### 设计保证的内容
+
+- 作用域贡献仅在其精确的 agent 视图中可见，并随该作用域一起 dispose。
+- 创建和恢复不暴露部分配置的句柄；最终写入注册表时的失败者和发布失败清理每个已准备的资源。
+- Dispose 在 driver 排空和最终会话工作期间保留作用域监听器和持久化，然后撤销作用域。
+- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 契约。
+- ToolRegistry 的展示、查找和执行在专家 assembly 变换之前解析相同的活跃视图，已提交的结果有一个不可变的观察点。
+- 注册表贡献是确定性输入，而可信的 assembly waterfall 拥有最终的模型可见组合。
+- Subagent start 仅返回就绪的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳契约。
+- Worker/进程结果优先级和清理在死亡、迟到消息和有界拆除下保持正确。
+
+### 代价与局限
+
+作用域感知服务仍然维护全局和按标识键索引的映射，操作必须显式携带其真实 agent。异步创建/恢复和 subagent start 要求调用方等待所有权转移并 dispose 返回的句柄。
+
+可信的 `system-prompt/assemble` 监听器可以移除或替换 Code Mode 和结构化输出协议片段。这是有意为之：监听器拥有最终组合，必须保持部署期望仍可用的任何协议。
+
+该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 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-cooperative-tool-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
index b27a40cc7f..77e3b8c14a 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
-2026-07-19-cooperative-tool-cancellation.md: 559012f10d41963698cc932727125de1b9ccfef7
-2026-07-19-cooperative-tool-cancellation.zh.md: 6af8e57349bba026ab22f257014c084c5c3c3f54
+2026-07-19-cooperative-tool-cancellation.md: be237f6ca9475699bb4af76896772a1a7409033d
+2026-07-19-cooperative-tool-cancellation.zh.md: 9ad212c2073063ccb0c838c08ab8f89c9285b26b
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 559012f10d..be237f6ca9 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
@@ -36,7 +36,7 @@ An around-dispatch wrapper may replace `exec.signal` for its delegated lifetime
 
 ### Pre-aborted entry short-circuits after materialization
 
-The registry first creates the call token and losslessly snapshots and freezes the arguments. A materialization failure wins even when the caller signal is already aborted. After successful materialization, a pre-aborted signal skips `tools/pre-execute`, approval, `tools/execute`, `tools/post-execute`, and the tool body, then publishes exactly one frozen authoritative `tools/result` with `ABORTED_BEFORE_DISPATCH`.
+The registry first creates the call token, snapshots the visible definition's optional final-content callback, and losslessly snapshots and freezes the arguments. An argument-materialization failure wins even when the caller signal is already aborted. Before final content, the registry also losslessly snapshots the candidate result and converts a result-snapshot failure into an ordinary error, so the callback can still enforce its content invariant. After successful argument materialization, a pre-aborted signal skips `tools/pre-execute`, approval, `tools/execute`, `tools/post-execute`, and the tool body, then passes `ABORTED_BEFORE_DISPATCH` through that content-only callback before publishing exactly one frozen authoritative `tools/result`.
 
 ### Started work still reaches quiescence
 
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 6af8e57349..9ad212c207 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
@@ -36,7 +36,7 @@ Status: implemented
 
 ### 进入时已中止会在物化后短路
 
-注册表先创建调用 token，并对参数进行无损快照和冻结。即使调用方信号已经中止，参数物化失败仍优先返回。物化成功后，进入时已中止的信号会跳过 `tools/pre-execute`、审批、`tools/execute`、`tools/post-execute` 和工具主体，然后发布且只发布一次冻结的权威 `tools/result`，其代码为 `ABORTED_BEFORE_DISPATCH`。
+注册表先创建调用 token，对可见工具定义的可选 `finalizeContent` callback 做快照，并对参数进行无损快照和冻结。即使调用方信号已经中止，参数物化失败仍优先返回。在最终内容处理之前，注册表还会对候选结果进行无损快照，并把结果快照失败转换为普通错误，从而使该 callback 仍能保证其内容不变量成立。参数物化成功后，进入时已中止的信号会跳过 `tools/pre-execute`、审批、`tools/execute`、`tools/post-execute` 和工具主体，然后先由该仅处理内容的 callback 处理 `ABORTED_BEFORE_DISPATCH`，再发布且只发布一次冻结的权威 `tools/result`。
 
 ### 已启动工作仍必须完全停稳
 
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 c2f039b148..055804b569 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
-2026-07-19-gui-layering-and-rpc-protocol.md: 65fb01f44698c61e6bf6958e332e1854fbb77fa9
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: e8b15789846ea124fb6a90f2afef437184d4348a
+2026-07-19-gui-layering-and-rpc-protocol.md: 63db4786adcc007d09b7a58824a59f4d1e1e8be1
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: b3037ceb8c172925581d2862ea675e53a7f8c54e
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 65fb01f446..63db4786ad 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
@@ -25,9 +25,10 @@ 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. Two kinds live here:
-    - **Pure libraries** (`ui-slots`, `web-react`, `ui-primitives`): ordinary root-index packages, statically bundled into the shell and seeded into the browser plugin loader's module table.
-    - **dshClient plugin packages** (`connection`, `runtime`, `ui-theme`, `i18n`, `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 entire implementation and its types live under `src/client/`, shipped as the `./client` subpath (a tsdown closure-factory bundle), and cross-package consumption imports the `/client` form. `runtime` additionally exports `./loader` (the shell-held browser bundle loader — a loader cannot load itself).
+- `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)):
+    - **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.
 - `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.
@@ -51,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 (a bare package name would inline a second runtime instance into a browser bundle; the tsdown purity gate rewrites or rejects it).
+- 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).
 
 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)).
 
@@ -70,7 +71,7 @@ On the protocol side: TS interfaces (`packages/host/apiproxy/src/api/`, zero Nod
 
 #### Naming rule
 
-Packages under `packages/host/*` and `packages/client/*` **must carry the directory-group prefix in the package name**: host/runtime → `dsh-host-runtime`, client/runtime → `dsh-client-runtime`. The directory name does not repeat the group prefix (host/ already expresses it). The package-name tail therefore ≠ the directory name, so the `dsh-*` wildcard in tsconfig.base.json (which resolves by directory name) misses them — **each package in these two groups needs an explicit paths entry**, including separate entries for the plugin packages' `/client` (and runtime's `/loader`) subpaths so source-level resolution matches the exports map.
+Packages under `packages/host/*` and `packages/client/*` **must carry the directory-group prefix in the package name**: host/runtime → `dsh-host-runtime`, client/runtime → `dsh-client-runtime`. The directory name does not repeat the group prefix (host/ already expresses it). The package-name tail therefore ≠ the directory name, so the `dsh-*` wildcard in tsconfig.base.json (which resolves by directory name) misses them — **each package in these two groups needs an explicit paths entry**, including separate entries for the client packages' `/client` subpaths so source-level resolution matches the exports map.
 
 #### How to integrate a new shape (operational checklist)
 
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 e8b1578984..b3037ceb8c 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
@@ -23,9 +23,10 @@ Status: implemented
 目录按照如下分层:
 - `packages/host/*`: 包只提供 Host 侧能力（代表了以现在 Harness 实体插件系统为主体的 Node.js 代码核心工程），除此之外，还包含
     - 统一后端协议（fetch、HTTP、流式接口等）定义和支持，见本篇「消息协议」起各节
-- `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住两类包：
-    - **纯库**（`ui-slots`、`web-react`、`ui-primitives`）：普通根入口包，静态打包进壳，并播种进浏览器插件 loader 的模块表。
-    - **dshClient 插件包**（`connection`、`runtime`、`ui-theme`、`i18n`、`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dshClient` 声明）；实现与类型全部住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle），跨包消费一律 import `/client` 形式。`runtime` 额外导出 `./loader`（壳持有的浏览器 bundle loader——loader 加载不了自己）。
+- `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载 RFC](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 服务。
 - `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。
@@ -49,7 +50,7 @@ harness core packages ──────────────────┘
 - `runtime → apiproxy` 单向；apiproxy 仅依赖类型定义。
 - client 侧包**永不 import** host 侧包的运行时（只吃 `/api`、`/client` 两个浏览器安全子路径）。
 - `webserver` 不依赖 `runtime`：它提供 `{ fetch }` 特定实现 ——「webserver ← runtime」只是运行时注入关系，不是包依赖。
-- client 侧跨包 import 插件包一律走 `/client` 子路径（裸包名会把第二份运行时实例内联进浏览器 bundle；tsdown 纯度门禁会改写或拒收）。
+- 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)）。
 
@@ -68,7 +69,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 
 #### 命名规则
 
-`packages/host/*` 与 `packages/client/*` 下的包名**必须含目录组前缀**：host/runtime → `dsh-host-runtime`、client/runtime → `dsh-client-runtime`。目录名不重复组前缀（host/ 已表达）。因此包名尾段 ≠ 目录名，tsconfig.base.json 的 `dsh-*` 通配（按目录名解析）命不中——**这两组的每包需显式 paths 条目**，且插件包的 `/client`（以及 runtime 的 `/loader`）子路径要单列条目，使源码级解析与 exports map 一致。
+`packages/host/*` 与 `packages/client/*` 下的包名**必须含目录组前缀**：host/runtime → `dsh-host-runtime`、client/runtime → `dsh-client-runtime`。目录名不重复组前缀（host/ 已表达）。因此包名尾段 ≠ 目录名，tsconfig.base.json 的 `dsh-*` 通配（按目录名解析）命不中——**这两组的每包需显式 paths 条目**，且 client 各包的 `/client` 子路径要单列条目，使源码级解析与 exports map 一致。
 
 #### 怎么接入一个新形态（操作清单）
 
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 1868da83b3..b49e3dcf54 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
-2026-07-19-gui-web-client-architecture.md: f21b840493b83c02d7abc3ba1c1bf90635166ec1
-2026-07-19-gui-web-client-architecture.zh.md: a50dc556cfc96b6d35feea6ef2b1aadae9f31c44
+2026-07-19-gui-web-client-architecture.md: eeae5fb3ad8eb3e9842b497ee51258375760bc93
+2026-07-19-gui-web-client-architecture.zh.md: c6f4b10c2a4c2d210c6bd7a7fa1ac470cab7c0a7
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 f21b840493..eeae5fb3ad 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
@@ -17,29 +17,22 @@ Both ends run cordis. The host is a cordis plugin tree; the browser runs a secon
 ```
 ┌─ Host ─────────────────────────┐   ┌─ Browser ─────────────────────────────────────────┐
 │ sessions/agents/SessionLog     │   │ client cordis root ctx                             │
-│ apiproxy: RPC + mux/host 双流  │◀─▶│  ├ loader（壳静态持有，不能经自己装载）             │
-│ webserver:                     │   │  ├ immediately 先行组: connection/runtime/         │
-│  ├ GET /plugins/<id>/client.js │   │  │   ui-theme/i18n（动态 bundle，并行先装）        │
-│  └ GET / 注入 __DSH_BOOT__     │   │  ├ 后续组: layout/sidebar/conversation/trajectory  │
-└────────────────────────────────┘   │  └ session scope ×N（观看驱动，惰性建）            │
+│ apiproxy: RPC + mux/host 双流  │◀─▶│  ├ vendored Loader + ctx.modules（内核，壳静态持有）│
+│ webserver:                     │   │  ├ immediately entries: connection/runtime/        │
+│  ├ GET /plugins/<id>/client.js │   │  │   ui-theme/i18n（fetch bundle，boot 预拉）       │
+│  └ GET / 注入 __DSH_BOOT__ 图  │   │  ├ lazy entries: layout/sidebar/                   │
+│                                │   │  │   conversation/trajectory（fetch bundle，按需） │
+└────────────────────────────────┘   │  ├ app-shell 伪行（壳内静态注册，同一治理）        │
+                                     │  └ session scope ×N（观看驱动，惰性建）            │
                                      │ React: loading 页 → settled → 整 UI 一次成型       │
                                      └────────────────────────────────────────────────────┘
 ```
 
 ## The client cordis tree and the loading chain
 
-Every UI plugin is simultaneously a host plugin (dual-entry package): the node half sits in the host's plugin tree so the host Loader governs its lifecycle, and the browser half is a tsdown closure bundle under the package's `exports["./client"]`. The host webserver derives the boot manifest from loaded plugins carrying a `dshClient` manifest field and injects it into the page as `window.__DSH_BOOT__` — the HTML alone tells the browser everything to fetch, zero extra round trips.
+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 — all nine plugin packages (infrastructure included) carry the `dshClient` declaration and arrive as fetched `./client` tsdown closure bundles, `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, end to end:
-
-1. `GET /` → the shell boots, mounts `ctx.loader` (the loader mechanism is held statically by the shell — a loader cannot load itself; its code home is `packages/client/runtime/src/client/loader/`, imported through the `./loader` subpath so the shell bundle does not swallow the rest of the runtime package), seeds the require module table with the pure-library instances (react, react-dom, cordis, ui-slots, web-react, ui-primitives), and renders a plugin-independent loading page.
-2. `loader.start()` reads `__DSH_BOOT__`. Entries flagged `immediately` form the early-load group (connection, runtime, ui-theme, i18n): fetched in parallel, applied in intra-group `inject` topological order, and **the whole group must land before anything else loads**. Remaining plugins then load in inject order.
-3. Each bundle executes `window.DSHClientProxy.loadPlugin({ id, factory })`. The loader calls `factory(require)` — bundles are closure factories whose external dependencies arrive through the injected `require`, resolved against the module table (no globals, no import maps; an unresolvable specifier fails loud). The factory returns its module export surface (including the cordis `apply`); the loader runs `ctx.plugin(apply)`, then **registers that export surface into the module table under the package name**, so inject topology guarantees later plugins can `require` earlier ones. Plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` (CSS Modules hashing + ownership tag = isolation).
-4. `await loader.settled()` → the shell flips from the loading page to the real UI in one pass. A single failed plugin fails loud on the loading page; there is no partial-availability mode (progressive rendering is deferred work).
-
-**The dual-instance ban**: a module-table package inlined into a plugin bundle would duplicate runtime identity (two React copies, two store registries — the root cause of an actual white-screen P0). The tsdown client preset enforces purity at build time: a bare-name import of a module-table package must resolve external (rewritten to its `/client` form where applicable), and any other workspace leak that is not an inline-safe wire/type layer fails the build (`packages/client/tsdown.client.ts`, pinned by `scripts/client-bundle-purity.spec.ts`).
-
-Dev equals prod: plugins rebuild under `tsdown --watch`, refresh reloads the same chain; vite serves only the shell (`apps/web`). 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.
+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
 
@@ -49,9 +42,9 @@ 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-map merges). 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/views/startSession), `ctx.toolviews` (named per-tool render registry with per-session scope filters). 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 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).
 
-Beyond SlotMap, two more typed registration rings follow the same declare-merge idiom: the **view ring** (`ConversationViewMap` — an entry may declare `chromeProps`/`extraProps` extension shapes; `ConvViewPropsOf<Id>`/`ChromePropsOf<Id>` compose base + extension, so a view with no declaration gets the base for free while ui-trajectory's entries carry real per-view props) and the **tool ring** (tool names stay an open set — no global key table; typing hardens inside the entry: `ToolViewProps.block` is the real `ToolCallBlock` union defined in runtime, and register infers the registrant's injected share like slots do).
+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.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)`, with `inject: ['slots', 'conversation']` as the load-order seam (the conversation service being present guarantees the slot is declared). Session-dimension differentiation happens inside the component — `useSessions` reading `parentId` — not in registry predicates; 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.
 
 **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).
 
@@ -103,16 +96,16 @@ src/client/
   service.ts   cross-domain orchestration (imports contract only)
   skeleton/    domain: shell components (ConversationRoot/InputBar/EmptyState/DetailsPanel)
   chat/        domain: the chat view
-  toolviews/   domain: the tool-row registry and samples
+  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)
 ```
 
-Domain implementation files never import a sibling domain — shared surfaces route through `contract/` (e.g. chat consumes the tool registry through a `ToolViewResolver` read-face interface, not the registry class). `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/` (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.
 
 ## 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, registers slots and toolviews), 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 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.
 - **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)).
@@ -129,5 +122,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 | Tool views are consumed by multiple views and need per-session differentiation — a named service (`ctx.toolviews`) with scope filters is the honest shape |
+| 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)) |
 | 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 a50dc556cf..c6f4b10c2a 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
@@ -17,29 +17,22 @@ Status: implemented
 ```
 ┌─ Host ─────────────────────────┐   ┌─ Browser ─────────────────────────────────────────┐
 │ sessions/agents/SessionLog     │   │ client cordis root ctx                             │
-│ apiproxy: RPC + mux/host 双流  │◀─▶│  ├ loader（壳静态持有，不能经自己装载）             │
-│ webserver:                     │   │  ├ immediately 先行组: connection/runtime/         │
-│  ├ GET /plugins/<id>/client.js │   │  │   ui-theme/i18n（动态 bundle，并行先装）        │
-│  └ GET / 注入 __DSH_BOOT__     │   │  ├ 后续组: layout/sidebar/conversation/trajectory  │
-└────────────────────────────────┘   │  └ session scope ×N（观看驱动，惰性建）            │
+│ apiproxy: RPC + mux/host 双流  │◀─▶│  ├ vendored Loader + ctx.modules（内核，壳静态持有）│
+│ webserver:                     │   │  ├ immediately entries: connection/runtime/        │
+│  ├ GET /plugins/<id>/client.js │   │  │   ui-theme/i18n（fetch bundle，boot 预拉）       │
+│  └ GET / 注入 __DSH_BOOT__ 图  │   │  ├ lazy entries: layout/sidebar/                   │
+│                                │   │  │   conversation/trajectory（fetch bundle，按需） │
+└────────────────────────────────┘   │  ├ app-shell 伪行（壳内静态注册，同一治理）        │
+                                     │  └ session scope ×N（观看驱动，惰性建）            │
                                      │ React: loading 页 → settled → 整 UI 一次成型       │
                                      └────────────────────────────────────────────────────┘
 ```
 
 ## client cordis 树与装载链
 
-每个 UI 插件同时是一个 host 插件（双入口包）：node 半边住在 host 的插件树里，由 host Loader 管辖其生命周期；浏览器半边是 tsdown 闭包 bundle，挂在包的 `exports["./client"]` 下。host webserver 从带 `dshClient` manifest 字段的已加载插件推导启动清单，注入页面为 `window.__DSH_BOOT__`——HTML 到手即知要拉什么，零额外往返。
+装载链——两类包（普通包 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 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
 
-装载链全程：
-
-1. `GET /` → 壳启动，挂 `ctx.loader`（loader 机件由壳静态持有——装载器不能经自己装载；其代码家在 `packages/client/runtime/src/client/loader/`，壳经 `./loader` 子路径 import，避免壳 bundle 吞掉 runtime 包其余部分），把纯库实体（react、react-dom、cordis、ui-slots、web-react、ui-primitives）播种进 require 模块表，渲染一张不依赖任何插件的 loading 页。
-2. `loader.start()` 读取 `__DSH_BOOT__`。带 `immediately` 标记的条目构成先行装载组（connection、runtime、ui-theme、i18n）：并行拉取、按组内 `inject` 拓扑序 apply，**全组就位后才开始装载其余插件**。其余插件随后按 inject 序装载。
-3. 每个 bundle 执行 `window.DSHClientProxy.loadPlugin({ id, factory })`。loader 调 `factory(require)`——bundle 是闭包工厂，external 依赖经注入的 `require` 到达，从模块表解析（无全局变量、无 import map；解析不到的标识符即刻大声失败）。factory 返回其模块导出面（含 cordis `apply`）；loader 执行 `ctx.plugin(apply)`，随后**以包名把该导出面登记进模块表**——inject 拓扑保证后装插件可 `require` 先装插件。插件 CSS 内联在 bundle 里，注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离）。
-4. `await loader.settled()` → 壳从 loading 页一次切换到真 UI。单插件装载失败在 loading 页大声报错；不存在部分可用模式（渐进渲染为后置工作）。
-
-**双实例禁令**：模块表包若被内联进插件 bundle，会复制运行时身份（两份 React、两套 store 注册表——一次真实白屏 P0 的根因）。tsdown client 预设在构建期把守纯度：模块表包的裸名 import 必须解析为 external（适用时改写为其 `/client` 形态），其余任何非 inline 安全 wire/类型层的 workspace 泄漏都令构建大声失败（`packages/client/tsdown.client.ts`，由 `scripts/client-bundle-purity.spec.ts` 钉住）。
-
-dev 与 prod 同链：插件在 `tsdown --watch` 下重编译，刷新即重走同一条链；vite 只管壳（`apps/web`）。类型宇宙在聚合层拆分——`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。
+类型宇宙在聚合层拆分——`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 体系：页面怎么拼
 
@@ -49,9 +42,9 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 ## 服务与 scope 寻址
 
-服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只 merge 视图表）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/views/startSession）、`ctx.toolviews`（具名按工具渲染注册表，带按会话 scope 过滤）。过去住在服务 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。
 
-SlotMap 之外还有两条同 declare-merge 惯例的类型化注册环：**视图环**（`ConversationViewMap`——entry 可声明 `chromeProps`/`extraProps` 扩展形状；`ConvViewPropsOf<Id>`/`ChromePropsOf<Id>` 组合基座+扩展，无声明的视图免费得基座，ui-trajectory 的两个 entry 带真 per-view props）与**工具环**（tool 名保持开放集——无全局键表；类型强化在 entry 内部：`ToolViewProps.block` 是 runtime 定义的真 `ToolCallBlock` union，register 同 slots 一样推断注册方注入份额）。
+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.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)`，以 `inject: ['slots', 'conversation']` 作加载序缝（conversation 服务在场即保证槽已声明）。会话维差异化在组件内完成——`useSessions` 读 `parentId`——不走注册表谓词；交互草稿等行内状态走普通 store 席位。trajectory/waterfall 得同形槽（槽名按槽名纪律 `<域>.<条目>.<孔位>` 已定死，共用一张 owner 类型），随各自的行渲染点落地——RendersCheck 拒绝无人渲染的声明，两槽无法提前声明。
 
 **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（冻结为只读视窗）。
 
@@ -103,16 +96,16 @@ src/client/
   service.ts   cross-domain orchestration (imports contract only)
   skeleton/    domain: shell components (ConversationRoot/InputBar/EmptyState/DetailsPanel)
   chat/        domain: the chat view
-  toolviews/   domain: the tool-row registry and samples
+  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)
 ```
 
-域实现文件永不 import 兄弟域——共享面一律走 `contract/`（如 chat 经 `ToolViewResolver` 读面接口消费工具注册表，不碰注册表类）。`scripts/verify-client-domain-graph.ts` 把守分层（contract=0、域=1、apply/index=2；import 只准指向 ≤ 自己的层级；兄弟域边即失败）。将来拆包=每个域目录升格为包+机械改写 import 路径。
+域实现文件永不 import 兄弟域——共享面一律走 `contract/`（如 toolviews 样例从契约取 `ToolRowProps`，永不碰 chat 内部）。`scripts/verify-client-domain-graph.ts` 把守分层（contract=0、域=1、apply/index=2；import 只准指向 ≤ 自己的层级；兄弟域边即失败）。将来拆包=每个域目录升格为包+机械改写 import 路径。
 
 ## 怎么开发
 
-- **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot 与 toolview），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；清单与装载随之自动跟上。
+- **新 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` 加字段并守住引用纪律。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
@@ -129,5 +122,5 @@ token 流不再震荡渲染树：帧风暴对未订阅会话只花一个脏位
 | 静态链接的单 SPA bundle | 插件必须由 host 在运行时按配置组合；单体把每个 UI 功能重新耦回一次构建 |
 | window 全局变量 / import map 供共享依赖 | DI require 表让共享显式、大声失败、可替换；全局变量静默泄漏身份与版本 |
 | 业务数据进 zustand 切片 | 事件窗口/累积器是行为状态机，不是扁平切片；对象层保住快照粒度与合批的可控性 |
-| 工具行走字符串键的全局组件注册表 | 工具视图被多个视图共同消费且要按会话差异化——带 scope 过滤的具名服务（`ctx.toolviews`）才是诚实形态 |
+| 工具行走字符串键的全局组件注册表 | per-view keyed 子槽 + 组件内会话分支以唯一注册模型承载同一需求；平行 registry 不复活（[toolview 溶解](2026-07-23-toolview-dissolution.md)） |
 | P-I 就做渐进/Suspense 启动 | 一次成型严格更简单；loader 的按插件状态面已保留，渐进点亮日后可落地而无需重构 |
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 51d3aa867d..ba5bae421d 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
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-19-zstandard-jsonl-session-logs.md: ccfc81dd47504e6a9e9b19cda7c4b9fc40accecc
-2026-07-19-zstandard-jsonl-session-logs.zh.md: de5436a6eaefcb45e52e0ff4fea8592c7efcd127
+2026-07-19-zstandard-jsonl-session-logs.md: 74430624c771a265fb281e588e28733bc55d3eb6
+2026-07-19-zstandard-jsonl-session-logs.zh.md: b22275d1a7c54a743b11f4396318dd87e4f5b42a
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
index ccfc81dd47..74430624c7 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
@@ -36,7 +36,7 @@ EOF inside the final frame is a recoverable torn tail. Node's decoder is given t
 
 ### Consumers and verification
 
-The CLI, ACP, and stdio app bundles expose symmetric `persistenceCompression` pass-through configuration. Snapshot recording and replay compositions select `'none'` explicitly because committed fixtures are raw JSONL inputs to replay and normalization; ordinary runtime compositions use the compressed default.
+The CLI, ACP, and stdio app bundles expose symmetric `persistenceCompression` pass-through configuration. The web host assembly and ordinary app compositions omit the option and use the compressed default. Snapshot recording and replay compositions select `'none'` explicitly because committed fixtures are raw JSONL inputs to replay and normalization.
 
 The shared persistence and coordinator contracts run against both encodings. Backend tests cover standard framing and checksum interoperability, header-only listing, append rollback, encoding mismatch rejection, complete-frame corruption, and final-frame tears through headers, blocks, and checksum trailers. Default runtime, built-bin, headless, ACP, and Python smokes assert the compressed suffix and Zstandard magic or decode the header; raw-content tests opt out explicitly.
 
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 de5436a6ea..b22275d1a7 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
@@ -36,7 +36,7 @@ JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量
 
 ### 消费方与验证
 
-CLI、ACP 与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入；普通运行时组合使用压缩默认值。
+CLI、ACP 与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。web 宿主装配与普通应用组合省略该选项并使用压缩默认值。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入。
 
 共享持久化契约与协调器契约会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、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
new file mode 100644
index 0000000000..d28fb0da87
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-canonical-tool-output-contract.md: 8cd7df98758d6d4ac240fea21e7bbe0c89f26d1b
+2026-07-20-canonical-tool-output-contract.zh.md: 0920e0c2c331a247ecd9a039a05c19c9dd2871bc
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
new file mode 100644
index 0000000000..8cd7df9875
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
@@ -0,0 +1,79 @@
+# Agent Note: Canonical tool output contract
+
+Status: implemented
+
+English | [中文](2026-07-20-canonical-tool-output-contract.zh.md)
+
+## Problem
+
+Tool bodies previously authored model-facing `ContentBlock[]` directly, optionally wrapping it with opaque `meta`. Native function calling therefore had a usable human projection, but a programmatic caller had no stable domain value: Code Mode flattened the blocks back into a string, dynamic tools repeated the content shape, and policy could replace presentation without any way to distinguish that change from replacing the operation's result. Several capability seams already returned richer provider values only to discard them at their model-facing tool boundary.
+
+The durable session contract made that presentation authoritative for replay, but persisting every rich intermediate value would enlarge logs, expose implementation data to compaction and migration, and incorrectly turn an execution-local API into session format. The foundation instead needs one typed value during execution and an explicit projection into the existing durable/model-facing content.
+
+## Decision
+
+Every tool declares a mandatory canonical output and returns only the value described by it:
+
+```ts ignore-check
+output: {
+  schema: OutputSchema
+  render(args, value): ContentBlock[]
+  presentationMeta?(args, value): JsonValue
+}
+```
+
+`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.
+
+```ts ignore-check
+type ToolExecutionResult =
+  | { isError: false; value: JsonValue; content: ContentBlock[]; meta?: JsonValue; additionalContexts?: HookContext[] }
+  | { isError: true; error: { message: string; info?: { name: string; code: string } }; content: ContentBlock[]; meta?: JsonValue; additionalContexts?: HookContext[] }
+```
+
+`tools/post-execute` has two mutually exclusive successful projections. Replacing `content` changes only Native/model presentation and preserves the canonical value and metadata. Replacing `value` revalidates the replacement and recomputes both presentation projections. A block removes the value and becomes a failure. Content replacement is therefore not a confidentiality mechanism: policy that must prevent programmatic access blocks the call or replaces the value.
+
+Canonical values are execution-local. The agent loop persists `tool/result` with only `content`, `error`, and optional `meta`; Code Mode's `tool/code-dispatch` persists only its bounded summary. Neither event stores the intermediate value, so replay reproduces presentation but cannot reconstruct the programmatic result. When a tool declares `presentationMeta`, it is computed only for a direct surface call; a nested Code dispatch gets no metadata or result card. The outer `run_code` card instead reads final post-policy content and declares no presentation metadata. Generic and tool-owned spill projections similarly skip nested dispatches, whose canonical value never enters model context.
+
+The first-party tools preserve their existing Native text while returning domain DTOs:
+
+| Tool family | Canonical value |
+|---|---|
+| `read` | `{ path, offset, lines: [{ number, text }], totalLines }` |
+| `write` | `{ path, operation: "create" | "update", before: string | null, after }` |
+| `edit` | `{ path, before, after }` |
+| `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 }` |
+| `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 |
+| `subagent` | Background task handle or `{ kind: "foreground", runId, output: JsonValue[] }` |
+| `workflow` / `ralph` | `{ runId, agentsStarted, result: JsonValue }` |
+| `skill` | `{ name, provider, resourceBase?, content }` |
+| `todo_write` | `{ todos, counts }` |
+| `ask_user_question` | `{ answers: [{ id, selected, custom? }] }` |
+| `exit_plan_mode` | `{ approved: true }` |
+| `cordis_inspect` / `cordis_mount` / `cordis_unmount` | Inspection text or typed dynamic-mount handles |
+| `structured_output` | `{ recorded: true }` |
+| `run_code` | `{ logs: string[], result?: JsonValue }` |
+
+Provider and executor acquisition limits remain real limits on the canonical value. Formatting-only limits belong in `render`; `glob` and `grep`, for example, keep every acquired item in `value` while their Native projection retains and best-effort spills the configured first page. Generic spill prepends and delegates its post-execute listener so an ordinary tool-owned asynchronous projection completes before generic byte bounding regardless of plugin load order. Filesystem mutations derive replayable diff metadata from `args` and the canonical before/after value rather than returning UI state from the body.
+
+MCP bridges preserve protocol blocks through `McpResult<{...}> = { content: JsonValue[]; structuredContent? }`. An advertised `outputSchema` is enforced when it belongs to the supported raw subset; unsupported schemas fall back to `JsonValue` rather than pretending to validate them. Native rendering still uses the existing MCP-to-`ContentBlock` projection, and MCP `isError` becomes a failed tool result.
+
+## Alternatives considered
+
+- **Return rendered text to Code Mode:** rejected because callers would continue scraping prose for task ids, mount ids, paths, and structured provider results.
+- **Persist canonical values on `tool/result`:** rejected because nested execution values are not model history, need not survive replay, and would create a session-format and storage commitment unrelated to Native reconstruction.
+- **Let tools return both value and content:** rejected because two author-owned results can disagree and policy cannot state which one is authoritative. The renderer makes presentation a deterministic projection of the validated value.
+- **Treat content replacement as value redaction:** rejected because presentation and programmatic access are different consumers; hiding only the former would create a false security boundary.
+- **Require object-rooted tool outputs:** rejected because scalar, array, and null results are legitimate JSON APIs. Object-rooting remains a consumer rule for caller-defined subagent/workflow structured output.
+
+## Consequences
+
+Native and replay behavior remains content-first and byte-compatible, while execution-time callers can use a validated domain value without parsing that content. Failures have one required message plus optional internal class/code information, successful and failed outcomes are discriminated, and a failed result can never promise a value. Tool authors must design the value and Native projection together; the extra declaration is intentional because it prevents accidental programmatic contracts from being inferred from prose.
+
+Intermediate values remain bounded only by the producing capability and process memory. Their omission from the log means replay cannot recover them, and a content-only post policy does not hide them. These are explicit properties of the execution-local contract, not accidental gaps.
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
new file mode 100644
index 0000000000..0920e0c2c3
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
@@ -0,0 +1,79 @@
+# Agent Note：规范工具输出契约
+
+Status: implemented
+
+[English](2026-07-20-canonical-tool-output-contract.md) | 中文
+
+## 问题
+
+工具主体过去直接编写面向模型的 `ContentBlock[]`，并可选择将其与不透明的 `meta` 包装在一起。因此，Native 模式的 Function Calling（函数调用）虽然拥有可供人阅读的投影，但程序化调用方没有稳定的领域值：Code Mode 会将内容块重新展平为字符串，动态工具会重复定义内容形态，策略也可以替换展示内容，却无法区分这项变更究竟是替换展示，还是替换操作结果。多个能力 seam 已经返回了信息更丰富的提供方值，却又在面向模型的工具边界丢弃这些值。
+
+持久会话契约将这份展示内容视为回放时的权威来源，但如果持久化每一个信息丰富的中间值，就会扩大日志、使实现数据进入压缩和迁移流程，还会错误地把执行期本地 API 变成会话格式的一部分。因此，系统底层需要在执行期间保留一个类型化值，并显式将其投影为现有的持久化内容和模型可见内容。
+
+## 决策
+
+每个工具都必须声明规范输出，并且只能返回该声明描述的值：
+
+```ts ignore-check
+output: {
+  schema: OutputSchema
+  render(args, value): ContentBlock[]
+  presentationMeta?(args, value): JsonValue
+}
+```
+
+`defineTool` 从统一的 `ValueSchemaSpec` 推导工具主体返回值和两个投影器的类型。原始定义和动态定义则提供编译后的 `JsonSchemaNode` 形式。注册时会拒绝缺失输出声明或采用不受支持原始 schema 的定义，不提供兼容旧式内容返回值的路径。
+
+每次成功分发时，注册表会将返回值快照为无损 `JsonValue`，依据 `output.schema` 校验并深度冻结，然后调用纯渲染器；对于直接的外层调用，还会调用可选的元数据投影器。渲染器、投影器、schema 或无损 JSON 处理失败都会被收敛为普通 `ToolOutputError` 结果。around `tools/execute` 包装层接收并返回规范的成功／失败联合；包装层自行产生的成功结果会再次通过已解析工具的输出声明完成归一化，而不会信任其独立编写的内容。每个规范结果只归属于一个不可变的分发 token；因此，如果包装层返回来自其他调用或工具的缓存结果，系统会依据当前生效的输出声明重新执行归一化，而不会绕过这一步。
+
+```ts ignore-check
+type ToolExecutionResult =
+  | { isError: false; value: JsonValue; content: ContentBlock[]; meta?: JsonValue; additionalContexts?: HookContext[] }
+  | { isError: true; error: { message: string; info?: { name: string; code: string } }; content: ContentBlock[]; meta?: JsonValue; additionalContexts?: HookContext[] }
+```
+
+`tools/post-execute` 为成功结果提供两种互斥的投影方式。替换 `content` 只改变 Native／模型展示，并保留规范值和元数据。替换 `value` 会重新校验替代值，并重新计算两份展示投影。阻止操作会移除值并转为失败。因此，替换内容并不是保密机制：必须阻止程序化访问的策略，应当阻止调用或替换值。
+
+规范值仅存在于执行期间。agent loop（智能体循环）持久化的 `tool/result` 只包含 `content`、`error` 和可选的 `meta`；Code Mode 的 `tool/code-dispatch` 只持久化其有界摘要。两个事件都不存储中间值，因此回放可以重现展示，却无法重建程序化结果。当工具声明 `presentationMeta` 时，系统只会为直接的外层调用计算它；嵌套 Code 分发没有元数据或结果卡片。外层 `run_code` 卡片则读取最终的 post-policy 内容，并且不声明展示元数据。通用以及工具自有的输出落盘投影同样跳过嵌套分发，因为它们的规范值永远不会进入模型上下文。
+
+第一方工具在保持现有 Native 文本不变的同时返回领域 DTO：
+
+| 工具系列 | 规范值 |
+|---|---|
+| `read` | `{ path, offset, lines: [{ number, text }], totalLines }` |
+| `write` | `{ path, operation: "create" | "update", before: string | null, after }` |
+| `edit` | `{ path, before, after }` |
+| `glob` | `{ paths: string[] }` |
+| `grep` | `{ matches: [{ path, lineNumber, line }] }` |
+| `web_search` ／ `web_fetch` | 归一化后的 `WebSearchResult` ／ `WebFetchResult` |
+| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceRoot }` 或 `{ 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` | 不含所有者或通知账务字段的公开任务快照 |
+| `subagent` | 后台任务句柄或 `{ kind: "foreground", runId, output: JsonValue[] }` |
+| `workflow` ／ `ralph` | `{ runId, agentsStarted, result: JsonValue }` |
+| `skill` | `{ name, provider, resourceBase?, content }` |
+| `todo_write` | `{ todos, counts }` |
+| `ask_user_question` | `{ answers: [{ id, selected, custom? }] }` |
+| `exit_plan_mode` | `{ approved: true }` |
+| `cordis_inspect` ／ `cordis_mount` ／ `cordis_unmount` | 检查文本或类型化的动态挂载句柄 |
+| `structured_output` | `{ recorded: true }` |
+| `run_code` | `{ logs: string[], result?: JsonValue }` |
+
+提供方和执行器的采集上限仍会实际限制规范值。仅用于格式化的限制归 `render` 所有；例如，`glob` 和 `grep` 会在 `value` 中保留所有已采集项，而其 Native 投影仍只保留配置指定的第一页，并尽力将完整展示内容写入落盘文件。通用落盘机制会前置注册其 post-execute 监听器，并让该监听器先向后委托，因此无论插件加载顺序如何，普通工具自有的异步投影都会在通用字节数上限处理之前完成。文件系统变更工具根据 `args` 和规范的变更前／后值推导可回放的 diff 元数据，不再由工具主体返回 UI 状态。
+
+MCP 桥接层通过 `McpResult<{...}> = { content: JsonValue[]; structuredContent? }` 保留协议内容块。当公布的 `outputSchema` 属于受支持的原始子集时，系统会强制校验；不受支持的 schema 则回退为 `JsonValue`，而不会假装已完成校验。Native 渲染仍使用现有的 MCP 到 `ContentBlock` 投影，MCP `isError` 则会变为失败的工具结果。
+
+## 备选方案
+
+- **向 Code Mode 返回渲染后的文本：**不予采纳。调用方仍需从自然语言中提取 task id、挂载 id、路径和结构化提供方结果。
+- **在 `tool/result` 上持久化规范值：**不予采纳。嵌套执行值不属于模型历史记录，无需在回放后继续存在；持久化还会引入与 Native 重建无关的会话格式和存储承诺。
+- **允许工具同时返回值和内容：**不予采纳。由作者分别维护的两份结果可能互相矛盾，策略也无法说明哪一份才是权威结果。渲染器会根据已校验值确定性地产生展示。
+- **将内容替换视为值脱敏：**不予采纳。展示内容和程序化访问面向不同消费方；只隐藏前者会制造虚假的安全边界。
+- **要求工具输出必须以对象为根：**不予采纳。标量、数组和 null 结果都是合理的 JSON API。只有由调用方定义的 subagent／工作流结构化输出仍受消费方的对象根规则约束。
+
+## 影响
+
+Native 和回放行为仍以内容为先，并保持逐字节兼容；执行期调用方则无需解析内容，即可使用经过校验的领域值。失败结果必须包含消息，并可选择附加内部类名／代码信息；成功与失败结果由判别字段区分，失败结果绝不会承诺存在值。工具作者必须一并设计值及其 Native 投影；增加这项声明是有意为之，因为它避免从自然语言内容意外推导出程序化契约。
+
+中间值只受产生它们的能力和进程内存限制。日志不包含这些值，因此回放无法恢复；仅处理内容的 post 策略也无法隐藏这些值。这些都是执行期本地契约的明确属性，并非意外缺口。
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 c9290db5ea..6eeebc9848 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
-2026-07-20-routed-model-context-and-compaction-policy.md: f0b9288d3d864bfcc2964862b1ff294406daa345
-2026-07-20-routed-model-context-and-compaction-policy.zh.md: cda740a5671a3ef8a5bb415e5cc45ca8397c1c59
+2026-07-20-routed-model-context-and-compaction-policy.md: b637ba24d4ba5fc25c8cdd515a821ee97883a326
+2026-07-20-routed-model-context-and-compaction-policy.zh.md: 084e762ec29ddc0aecb0bf422c147b9d3122726b
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 f0b9288d3d..b637ba24d4 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
@@ -16,7 +16,7 @@ Neither obvious configuration owner is sufficient. Compact-basic is optional and
 
 `LlmAdapter.resolveModelContext(provider, model)` optionally returns `LlmModelContext` for one exact route. `LlmService.resolveModelContext()` selects the registered route owner, validates a positive integer `contextWindow`, and returns a detached value. The query is independent of `listModels()`: an unlisted dynamic model may have capacity metadata, and `undefined` means only that the adapter cannot describe capacity.
 
-The hand-rolled DeepSeek adapter accepts optional `contextWindow` on each configured model. Its two default model entries publish 128,000 tokens; an explicit entry without capacity and an unlisted pass-through id return `undefined`. The pi-ai adapter resolves capacity from the same catalog descriptor that authoritatively resolves the request model.
+The hand-rolled DeepSeek adapter accepts optional `contextWindow` on each configured model plus an adapter-wide `defaultContextWindow`. Exact model capacity wins; an entry without capacity and an unlisted pass-through id inherit the adapter default, or return `undefined` when it is absent. The two built-in model entries each publish an exact 128,000-token capacity. The pi-ai adapter resolves capacity from the same catalog descriptor that authoritatively resolves the request model.
 
 ### Token measurement remains model-agnostic
 
@@ -36,7 +36,7 @@ An adapter that lacks capacity metadata remains a valid LLM route. Manual proact
 
 ## Testing
 
-Service tests cover detached context metadata, invalid adapter output, catalog independence, and default absence. Adapter tests cover DeepSeek configured/default/unlisted behavior and pi-ai exact descriptor resolution. Compact tests cover ratio scaling, exact provider/model overrides, load-time rejection of invalid merged ratios, runtime absolute-budget validation, same-model-id provider switches, target-specific warning suppression, and capacity-independent overflow recovery. Loader fixtures reject the removed token-meter capacity setting, and examples configure capacity on adapters.
+Service tests cover detached context metadata, invalid adapter output, catalog independence, and default absence. Adapter tests cover DeepSeek exact/default/unlisted resolution, invalid capacities, and pi-ai exact descriptor resolution. Compact tests cover ratio scaling, exact provider/model overrides, load-time rejection of invalid merged ratios, runtime absolute-budget validation, same-model-id provider switches, target-specific warning suppression, and capacity-independent overflow recovery. Loader fixtures reject the removed token-meter capacity setting, and examples configure capacity on adapters.
 
 ## Alternatives considered
 
@@ -51,7 +51,7 @@ Service tests cover detached context metadata, invalid adapter output, catalog i
 - Capacity has one authoritative owner at the provider seam, 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.
-- Deployments using explicit DeepSeek model lists must provide `contextWindow` for proactive pressure on those entries. Missing metadata is visible instead of silently applying a wrong global fallback.
+- DeepSeek deployments may set exact per-model capacities, or use `defaultContextWindow` for entries without capacity and unlisted pass-through ids.
 - Ratio defaults scale naturally across models, while exact-target absolute retention remains available for deployment-specific behavior.
 
 This note supersedes the global-capacity and no-model-policy parts of the [replay token meter service Agent Note](2026-07-15-replay-token-meter-service.md). Its single-fold measurement decision remains unchanged.
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 cda740a567..084e762ec2 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
@@ -16,7 +16,7 @@ Status: implemented
 
 `LlmAdapter.resolveModelContext(provider, model)` 可以为一条精确路由返回 `LlmModelContext`。`LlmService.resolveModelContext()` 选择已注册的路由所属方，验证 `contextWindow` 为正整数，并返回分离值。该查询独立于 `listModels()`：不在目录中的动态模型也可以拥有容量元数据，而 `undefined` 只表示适配器无法描述容量。
 
-手写 DeepSeek 适配器允许每个已配置模型提供可选 `contextWindow`。两个默认模型项都公开 128,000 token；未提供容量的显式模型项与未列出的透传 id 返回 `undefined`。pi-ai 适配器从同一个目录描述符解析容量，该描述符也用于权威解析请求模型。
+手写 DeepSeek 适配器允许每个已配置模型提供可选 `contextWindow`，并支持适配器级 `defaultContextWindow`。精确模型容量优先；未提供容量的模型项与未列出的透传 id 会继承适配器默认值，若默认值也不存在则返回 `undefined`。两个内置模型项都公开精确的 128,000 token 容量。pi-ai 适配器从同一个目录描述符解析容量，该描述符也用于权威解析请求模型。
 
 ### Token 计量保持模型无关
 
@@ -36,7 +36,7 @@ Compact-basic 拥有消费方策略。顶层字段定义默认值；`modelPolici
 
 ## 测试
 
-服务测试覆盖分离上下文元数据、无效适配器输出、目录独立性与默认缺失行为。适配器测试覆盖 DeepSeek 的配置值、默认值与未列出行为，以及 pi-ai 的精确描述符解析。压缩测试覆盖比例缩放、精确提供方/模型覆盖、加载期拒绝无效合并比例、运行时校验绝对预算、相同模型 id 的提供方切换、目标专用警告抑制与不依赖容量的溢出恢复。Loader fixture 会拒绝已经移除的 token-meter 容量设置，示例则在适配器上配置容量。
+服务测试覆盖分离上下文元数据、无效适配器输出、目录独立性与默认缺失行为。适配器测试覆盖 DeepSeek 的精确容量、默认容量、未列出模型解析及无效容量，以及 pi-ai 的精确描述符解析。压缩测试覆盖比例缩放、精确提供方/模型覆盖、加载期拒绝无效合并比例、运行时校验绝对预算、相同模型 id 的提供方切换、目标专用警告抑制与不依赖容量的溢出恢复。Loader fixture 会拒绝已经移除的 token-meter 容量设置，示例则在适配器上配置容量。
 
 ## 考虑过的替代方案
 
@@ -51,7 +51,7 @@ Compact-basic 拥有消费方策略。顶层字段定义默认值；`modelPolici
 - 容量在提供方 seam 上拥有唯一权威归属方，而压缩策略留在可选消费插件中。
 - 同一个 compact-basic 实例无需查询发现元数据，就能安全处理不同窗口、提供方切换，以及不同提供方下的相同模型 id。
 - 仅 LLM 与仅 meter 的组合仍然有效；加载 compact-basic 不会让适配器产生反向依赖。
-- 使用显式 DeepSeek 模型列表的部署必须为需要主动压力检查的条目提供 `contextWindow`。系统会暴露缺失元数据，而不是静默应用错误的全局回退值。
+- DeepSeek 部署可以设置精确的逐模型容量，也可以让未提供容量的模型项与未列出的透传 id 使用 `defaultContextWindow`。
 - 比例默认值会随模型自然缩放，同时仍可按精确目标使用绝对保留值，以满足部署专用行为。
 
 本记录取代[回放式 token 计量服务 Agent Note](2026-07-15-replay-token-meter-service.md) 中的全局容量与无模型策略部分，单折叠计量决策保持不变。
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
new file mode 100644
index 0000000000..16852c1004
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-unified-json-value-schema-dsl.md: 09945c413ffe5924c74076648cdf3da60c3e18c9
+2026-07-20-unified-json-value-schema-dsl.zh.md: 00a7a199613ea857a7815f1c7794781f143a3896
diff --git a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.md b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.md
new file mode 100644
index 0000000000..09945c413f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.md
@@ -0,0 +1,35 @@
+# Agent Note: Unified JSON-value schema DSL
+
+Status: implemented
+
+English | [中文](2026-07-20-unified-json-value-schema-dsl.zh.md)
+
+## Problem
+
+Tool parameters used a small author DSL while subagent/workflow structured output used a separate raw JSON Schema subset and validator. The two vocabularies disagreed about roots, scalar constraints, and validation, so a typed canonical tool-output contract would either duplicate both paths again or accept schemas that some projection could not enforce.
+
+## Decision
+
+`dsh-tools` owns one JSON-value schema vocabulary with two representations. `ValueSchemaSpec` is the author form for any JSON root; `ParameterSchemaSpec` is its implicit object-property-map form with per-property `required: true`. `JsonSchemaNode` is the raw wire form. Both support string, finite number, integer, boolean, null, array, object, type-correct scalar `enum`/`const`, and exact-one `oneOf`; `{ type: 'json' }` is author-only sugar for an annotation-only unconstrained raw node.
+
+An explicit author object must declare `additionalProperties: true | false`. The implicit parameter root and raw JSON Schema preserve the standard open default. Schema records contain only own enumerable string keys, schema arrays are dense intrinsic arrays, and supported keywords are read as own properties; custom prototypes, inherited constraints, symbols, and JSON-invisible decorations therefore cannot make compilation, projection, and validation observe different declarations. Intrinsic plain Object and Array containers remain plain across JavaScript realms, while subclasses and forged constructor prototypes remain exotic.
+
+`InferValue<S>` and `InferArgs<P>` derive TypeScript values from the same declarations that `valueSchemaSpecToJsonSchema()` and `parameterSchemaSpecToJsonSchema()` compile. Exact inference is bounded to 16 container levels and then uses `JsonValue`, preventing TypeScript's type-instantiation stack from becoming the authoring limit. `assertSupportedJsonSchema()` rejects unsupported or misplaced keywords, and `validateJsonSchemaValue()` enforces the accepted subset against the lossless `JsonValue` boundary: no `undefined`, negative zero, non-finite numbers, sparse arrays, cycles, exotic objects, functions, symbols, or other coercive values. Author compilation, raw-schema assertion, value validation, schema-to-TypeScript rendering, registry detachment, and dynamic Cordis cross-realm normalization and cloning use explicit work stacks, so runtime nesting is limited by available memory rather than the JavaScript call stack.
+
+Object-rooting is a consumer rule rather than a vocabulary restriction. Subagent and workflow caller-defined structured outputs use `assertObjectJsonSchema()` and `ObjectJsonSchema`; tool outputs may use any root. Dynamic Cordis registrations rebuild realm-foreign schemas into host-owned JSON, preserve raw-wrapper openness, and require direct-DSL object openness before calling the same compiler. The dynamic boundary rejects JSON-invisible record keys and exotic schema arrays before normalization, so it cannot silently discard a constraint or consume custom iteration semantics.
+
+## Alternatives considered
+
+- **Keep separate parameter and structured-output schema systems:** rejected because every added output construct would require parallel inference, compilation, validation, and code-generation changes with no useful ownership boundary.
+- **Adopt full JSON Schema or Ajv:** rejected because the harness must fail on every construct it cannot project into its generated SDK and validators; accepting a larger language would make enforcement and model guidance dishonest.
+- **Make every object implicitly open or closed:** rejected because either choice hides a consequential author decision. Only the legacy-shaped implicit parameter root and external raw schema retain an intentional default.
+- **Define `oneOf` as first-match:** rejected because branch ordering would change validation semantics and allow overlapping branches to hide ambiguous values.
+
+## Consequences
+
+- Parameter validation, output validation, schema-to-TypeScript generation, subagent/workflow guards, and dynamic registration share one enforced vocabulary.
+- Output declarations can infer object, array, scalar, or null roots; subagent/workflow structured outputs remain object-rooted at their existing seams.
+- Explicit object openness and type-correct literal constraints make malformed declarations fail during authoring or registration rather than during a later model call.
+- Bounded type inference retains useful exact types for ordinary declarations and degrades unusually deep tails to `JsonValue`; runtime schema enforcement remains exact at every depth.
+- Raw tools may still register broader JSON Schema directly, but unified code generation treats unsupported schemas as unknown instead of pretending to enforce them.
+- Runtime and compile-time tests cover every root, exact-one overlap/no-match behavior, raw open defaults, explicit openness, lossy JSON values, inference, deep nesting across core and dynamic projections, JSON-invisible dynamic keys, and exotic schema arrays.
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
new file mode 100644
index 0000000000..00a7a19961
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md
@@ -0,0 +1,35 @@
+# Agent Note：统一 JSON 值 schema DSL
+
+Status: implemented
+
+[English](2026-07-20-unified-json-value-schema-dsl.md) | 中文
+
+## 问题
+
+工具参数使用一套精简的作者侧 schema DSL，subagent／工作流的结构化输出则使用另一套原始 JSON Schema 子集和校验器。两套词汇在根类型、标量约束和校验方式上并不一致；如果继续沿用这种划分，类型化的规范工具输出契约要么还需重复实现两条路径，要么只能接受部分投影无法强制执行的 schema。
+
+## 决策
+
+`dsh-tools` 以两种表示形式统一管理一套 JSON 值 schema 词汇。`ValueSchemaSpec` 是可描述任意 JSON 根类型的作者侧形式；`ParameterSchemaSpec` 是其隐式对象属性映射形式，每个属性可标记 `required: true`。`JsonSchemaNode` 是原始协议表示。两种形式都支持字符串、有限数值、整数、布尔值、null、数组、对象、类型正确的标量 `enum`／`const`，以及要求恰好匹配一个分支的 `oneOf`；`{ type: 'json' }` 仅是作者侧语法糖，会编译为仅含注解、不施加约束的原始节点。
+
+显式的作者侧对象必须声明 `additionalProperties: true | false`。隐式参数根对象和原始 JSON Schema 保留标准的默认开放语义。schema 记录只能包含自有且可枚举的字符串键，schema 数组必须是稠密的内建数组，系统只从自有属性读取受支持的关键字；因此，自定义原型、继承的约束、symbol 和 JSON 不可见的附加内容都无法让编译、投影和校验观察到不同的声明。内建的普通 Object 和 Array 容器跨 JavaScript 运行域后仍视为普通容器，而子类和伪造构造函数的原型仍视为非普通对象。
+
+`InferValue<S>` 和 `InferArgs<P>` 根据同一份声明推导 TypeScript 值，`valueSchemaSpecToJsonSchema()` 和 `parameterSchemaSpecToJsonSchema()` 也将这些声明编译为 JSON Schema。精确类型推导以 16 层容器为界，超过后使用 `JsonValue`，从而避免 TypeScript 的类型实例化栈限制作者能声明的嵌套深度。`assertSupportedJsonSchema()` 会拒绝不受支持或位置错误的关键字；`validateJsonSchemaValue()` 则以无损 `JsonValue` 边界校验受支持的子集，不允许 `undefined`、负零、非有限数、稀疏数组、循环引用、非普通对象、函数、symbol 及其他需要强制转换的值。作者侧 schema 编译、原始 schema 断言、值校验、schema 到 TypeScript 的渲染、注册表数据分离，以及动态 Cordis 的跨运行域规范化与克隆均使用显式工作栈，因此运行时嵌套只受可用内存限制，不受 JavaScript 调用栈限制。
+
+对象根限制属于消费方规则，不属于 schema 词汇本身。subagent 和工作流中由调用方定义的结构化输出通过 `assertObjectJsonSchema()` 和 `ObjectJsonSchema` 保持对象根限制；工具输出可以使用任意根类型。动态 Cordis 注册会把跨 JavaScript 运行域传入的 schema 重建为当前运行时持有的 JSON，保留原始包装层的默认开放语义，并要求直接使用 DSL 声明的对象明确选择开放方式，然后再调用同一编译器。动态边界会在规范化之前拒绝 JSON 不可见的记录键和非普通 schema 数组，因此不会静默丢弃约束，也不会触发自定义迭代逻辑。
+
+## 备选方案
+
+- **保留两套独立的参数与结构化输出 schema 系统：**不予采纳。每新增一种输出结构，都必须分别修改类型推导、编译、校验和代码生成，而这种重复并未形成有意义的职责边界。
+- **采用完整 JSON Schema 或 Ajv：**不予采纳。harness 必须拒绝所有无法投影到生成 SDK 和校验器中的结构；如果接受更大的语言子集，强制执行能力和模型指引就会与事实不符。
+- **让所有对象默认开放或默认封闭：**不予采纳。这两种选择都会隐藏一项影响重大的作者决策。只有保持旧有形态的隐式参数根对象和外部原始 schema 才有意保留默认值。
+- **把 `oneOf` 定义为首个匹配分支：**不予采纳。这样一来，分支顺序会改变校验语义，重叠分支也会掩盖值的歧义。
+
+## 影响
+
+- 参数校验、输出校验、schema 到 TypeScript 的代码生成、subagent／工作流门禁和动态注册共用一套强制执行的词汇。
+- 输出声明可以推导对象、数组、标量或 null 根类型；subagent／工作流的结构化输出仍在其现有服务边界保持对象根限制。
+- 显式的对象开放方式和类型正确的字面量约束会让格式错误的声明在编写或注册阶段快速失败，而不是拖到后续模型调用时才失败。
+- 有界类型推导会为常规声明保留有用的精确类型，并将异常深的尾部结构退化为 `JsonValue`；运行时 schema 强制执行在任意深度仍保持精确。
+- 原始工具仍可直接注册范围更广的 JSON Schema，但统一代码生成会把不受支持的 schema 视为未知类型，不会假装自己能够强制执行。
+- 运行时和编译期测试覆盖所有根类型、恰好匹配一个分支时的重叠／无匹配行为、原始 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 9e671e3672..0ed8f5d7a4 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
-2026-07-22-slot-type-chain-implementation.md: 1e9bd711e8316e2556fe238eb0a20d76e1d0d5b1
-2026-07-22-slot-type-chain-implementation.zh.md: 0eab839d033faac2f2c3356900c7ca1cd69d2dc9
+2026-07-22-slot-type-chain-implementation.md: 65b4ebb475fe34d71d8d3a08878b40103b3c95bd
+2026-07-22-slot-type-chain-implementation.zh.md: 4c55171ca0118782568e17f349f83d6cf9211617
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 1e9bd711e8..65b4ebb475 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
@@ -34,7 +34,7 @@ ctx.slots.register({
 
 There is no separate slot-definition API. The `children` object both **declares the child slots into existence** and **authorizes this component to render them** — a slot is a hole in the render tree that exists because someone will render it, so its lifecycle is the declaring entry's lifecycle (entry disposed → slots gone, contributions cleared). The values are the runtime spec (`kind`/`scope` drive outlet iteration and binding selection; `SlotMap` is types-only and erased at runtime, which is why an array of keys could not work), statically checked against the `SlotMap` entry so type and value are declared at one point and cross-validated.
 
-Parity rule: **the declaring entry holds the exclusive right to render its child slots**, settled entirely at register time (misconfiguration fails loud at load; the render hot path carries no checks). Loud-at-load cases: a second entry declaring an already-declared slot; registering into an undeclared slot; one store handle mounted under two scopes.
+Parity rule: **the declaring entry holds the exclusive right to render its child slots**, settled entirely at register time (misconfiguration fails loud at load; the render hot path carries no checks). Loud-at-load cases: a second entry declaring an already-declared slot; registering into an undeclared slot; one store handle mounted under two scopes; a chain registration missing its `select`.
 
 `SlotMap` declaration merging remains the type authority, and an entry declares only its own axes plus the **owner share** — the registrant's injected props never enter the global table ("whoever injects it, owns its type").
 
@@ -43,12 +43,20 @@ Parity rule: **the declaring entry holds the exclusive right to render its child
 | Share | Type | Source of truth | Contents |
 |---|---|---|---|
 | runtime | `PropsRuntime<K>` | SlotMap entry for K | `OwnerOf<K>` (render-site params) + session-scope standard `useSession`/`sessionId` + global `useSessions` |
-| child render | `PropsRenderSlots<S>` | register's `children` keys | `renderSlot(key, owner)`, key statically narrowed to S |
+| child render | `PropsRenderSlots<S>` | register's `children` keys | `renderSlot(key, owner)`, key statically narrowed to S; chain keys add `renderSlotChain` |
 | store | `PropsStore<H>` | store factory return type | `useStore` selector hook + `actions.*` (draft-param stripped) |
 | business | `I` | inject return type | plain data + callbacks (hooks banned) |
 
 `sessionId` is framework-supplied wherever `scope: 'session'` is declared — owner params do not carry it. The register call site is the double-lock choke point: a component whose renderSlot keys exceed the `children` declaration, or that misses a declared face, or whose store/inject shapes drift, is a compile error on that line. Delegation is ordinary props passing (hand the `renderSlot` function down, optionally behind a narrower signature) — there is no whitelist face object and no minting API.
 
+### The chain kind: entries self-nominate, first match renders
+
+The fourth `SlotKind`, `'chain'`, inverts routing authority relative to `keyed`: a keyed dispatch site picks its occupant by `entryKey`, while a chain entry nominates itself — the owner dispatches one common currency of owner props and never learns who takes over, so a new takeover package registers with zero owner edits. A chain registration carries a `select` pure selector (`ChainSelect<O, M>`: `(owner) => matched | null`) and an optional `priority` (ascending; ties keep registration = assembly order — the deployment-controllable inject topology — under the same stable sort as list `order`); registering without `select` is one of the loud-at-load cases above. At render, the outlet runs the selectors in chain order: the first non-null return elects its entry and the returned value joins the component's props as `matched` (the component never re-derives its own match), `null` passes the turn to the next entry, and all-null renders the owner's fallback body (`ChainRenderOpts`).
+
+The decline decision lives in `select`, never in a mounted component probing its own props: a component that mounts only to render null still runs its hooks and effects for nothing, and the resulting mount/unmount churn breaks memoization and React key semantics, whereas a selector is a pure function — unit-testable, zero mount side effects — the same discipline as "presentation methods are pure functions of `args`". Purity is the selector's contract: it reads no external mutable state and produces no side effects, so the routing decision is entirely a function of the owner props and safe to run on every dispatch. Selectors route; they never mint — per-dispatch object construction would churn identity every render, so wrapping a matched value in a richer face happens inside the elected component (`useMemo` keyed on `matched`).
+
+In the type chain, a chain entry's SlotMap shape is `{ kind: 'chain'; scope; owner }` with `owner` as the chain's currency; `M` — the `matched` prop's type — is inferred from the select return (a selector narrowing a union member types `matched` automatically), and the component position stays out of `M` inference, the same NoInfer ruling that pins the inject share (rulings below). On the owner side, `renderSlotChain(key, owner, { fallback })` joins `renderSlot` in the `PropsRenderSlots` share, its key domain statically narrowed to the chain-kind keys of the entry's children declaration (`ChainKeysOf`); the dispatch site is one line and holds no derivation or routing logic of its own.
+
 ### The store seat: framework engine, registrant schema
 
 The framework owns exactly one subscription machine: the snapshot store engine (zustand vanilla + immer + optional localStorage persistence) lives in the **runtime package** (`./client` main entry — no subpath), producing bare observable sources; web-react binds them into hooks at the outlet (per-source cached uSES binding). What a store *contains* is the registrant's declaration, written as a factory so no module-level handle exists (a module-scoped handle would be a de-facto singleton surviving plugin reloads):
@@ -93,7 +101,7 @@ Two hardening decisions in the register signature exist because the obvious alte
 
 ## Consequences
 
-Render authority is enforceable rather than conventional: who renders what is a load-time fact, and auditing the UI structure = reading the register calls. Every props surface is statically derived from one source (SlotMap entry, children keys, store factory, inject return), so a schema change propagates by compiler rather than by grep. Plugins carry no subscription machinery of their own — store lifecycle (per-session instances, disposal, persistence) is framework semantics keyed to the entry axis. Costs: registration options are dense (children spec objects); the framework carries real inference machinery (`defineStore`'s init/actions same-round inference may need a curried fallback); and the compile-time double locks mean prototype-stage drift is a hard error, not a warning.
+Render authority is enforceable rather than conventional: who renders what is a load-time fact, and auditing the UI structure = reading the register calls; for chain slots, WHO renders is additionally a render-time fact, but the deciding selectors are register-site declarations, so the audit surface stays the register calls. Every props surface is statically derived from one source (SlotMap entry, children keys, store factory, inject return), so a schema change propagates by compiler rather than by grep. Plugins carry no subscription machinery of their own — store lifecycle (per-session instances, disposal, persistence) is framework semantics keyed to the entry axis. Costs: registration options are dense (children spec objects); the framework carries real inference machinery (`defineStore`'s init/actions same-round inference may need a curried fallback); and the compile-time double locks mean prototype-stage drift is a hard error, not a warning.
 
 ## Alternatives considered
 
@@ -107,3 +115,5 @@ Render authority is enforceable rather than conventional: who renders what is a
 | Module-level store handles | A module-scope handle is a singleton across plugin reloads and test cases; the factory form scopes identity to apply/test invocation |
 | Components receiving the store instance | `update`/`set` in render code makes the mutation surface unauditable; declared actions keep "what can change" a register-site fact |
 | `FC` at the register position / inferring `I` from the component | FC statics generate covariant noise that rejects valid components; component-side inference absorbs props drift silently (see rulings above) |
+| Keyed dispatch with owner-side routing for takeover slots | The owner accumulates per-entry contracts and a hardcoded routing table (`find` + `entryKey` per takeover); the chain currency keeps new takeover registrations at zero owner edits |
+| Components declining by rendering null | Declining requires mounting first — hooks and effects run for nothing, and mount/unmount churn breaks memoization and key semantics; a pure selector decides without a component instance |
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 0eab839d03..4c55171ca0 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
@@ -34,7 +34,7 @@ ctx.slots.register({
 
 不存在独立的坑位定义 API。`children` 对象同时做两件事：**把子坑声明出来**，并**授权本组件渲染它们**——坑是渲染树上的一个洞，因为有人要渲染它才存在，所以坑的生命周期就是声明它的 entry 的生命周期（entry 一经 dispose（资源释放），坑随之消亡、坑内既有贡献清空）。children 的值是运行时 spec（`kind`/`scope` 驱动 outlet 的迭代形态与 binding 选择；`SlotMap` 是纯类型、运行时即被擦除，这正是键数组形行不通的原因），并与对应 `SlotMap` entry 静态对齐校验——类型与值在同一点声明、交叉验证。
 
-对等原则：**声明子坑的 entry 独占渲染这些子坑的权力**，全部在 register 时结清（配置错误在装载时大声失败；渲染热径零校验）。装载即炸的情形：第二个 entry 声明已被声明的坑；向未声明的坑 register；同一个 store 句柄挂到两个 scope 之下。
+对等原则：**声明子坑的 entry 独占渲染这些子坑的权力**，全部在 register 时结清（配置错误在装载时大声失败；渲染热径零校验）。装载即炸的情形：第二个 entry 声明已被声明的坑；向未声明的坑 register；同一个 store 句柄挂到两个 scope 之下；chain 注册缺 `select`。
 
 `SlotMap` 声明合并仍是类型权威，且 entry 只声明自己的轴加 **owner 份额**——注册方注入的 props 永不进入全局表（「谁注入的，类型归谁」）。
 
@@ -43,12 +43,20 @@ ctx.slots.register({
 | 份额 | 类型 | 真源 | 内容 |
 |---|---|---|---|
 | 运行时 | `PropsRuntime<K>` | K 对应的 SlotMap entry | `OwnerOf<K>`（渲染现场传参）+ session scope 标配 `useSession`/`sessionId` + 全局 `useSessions` |
-| 子坑渲染 | `PropsRenderSlots<S>` | register 的 `children` 键集 | `renderSlot(key, owner)`，键参静态收窄到 S |
+| 子坑渲染 | `PropsRenderSlots<S>` | register 的 `children` 键集 | `renderSlot(key, owner)`，键参静态收窄到 S；chain 键另有 `renderSlotChain` |
 | store | `PropsStore<H>` | store 工厂的返回类型 | `useStore` selector hook + `actions.*`（剥去 draft 形参） |
 | 业务 | `I` | inject 的返回类型 | 普通数据+回调（禁 hook） |
 
 凡声明 `scope: 'session'` 之处，`sessionId` 一律由框架供给——owner 传参不携带它。register 调用点是双向锁的收口：组件的 renderSlot 键集超出 `children` 声明、漏接某个已声明的面、store/inject 形状漂移，任何一条都在那一行上报编译错误。转授就是普通的 props 传递（把 `renderSlot` 函数递下去，可按需包一层更窄的签名）——不存在白名单面对象，也不存在铸面 API。
 
+### chain kind：entry 自荐，首中即渲
+
+第四种 `SlotKind`——`'chain'`——把路由权相对 `keyed` 反转：keyed 的分派现场以 `entryKey` 点选占坑者，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`）。
+
+类型链上，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`）；分派现场只有一行，不含任何自有的派生或路由逻辑。
+
 ### store 席位：引擎归框架，schema 归注册方
 
 框架拥有恰好一台订阅机械：快照 store 引擎（zustand vanilla + immer + 可选 localStorage 持久化）住 **runtime 包**（`./client` 主出口——无子路径），产出裸的可观察源；web-react 在 outlet 处把它们绑定成 hook（按源缓存的 uSES 绑定）。store 里*装什么*是注册方的声明，且必须写成工厂函数，使模块级句柄根本无从存在（模块级句柄会成为跨插件重载存活的事实单例）：
@@ -93,7 +101,7 @@ register 签名里的两条硬化裁定之所以存在，是因为显然的替
 
 ## Consequences
 
-渲染权威从此可强制执行，而非仅靠约定：谁渲染什么是装载期事实，审计 UI 结构 = 通读 register 调用。每个 props 面都从单一真源静态推导（SlotMap entry、children 键集、store 工厂、inject 返回值），schema 变更由编译器传播，而不靠 grep。插件不再自带任何订阅机械——store 生命周期（每会话实例、dispose、持久化）是钉在 entry 轴上的框架语义。代价：注册选项稠密（children spec 对象）；框架背上实打实的推断机械（`defineStore` 的 init/actions 同轮推断可能需要柯里化兜底）；编译期双向锁意味着原型阶段的漂移直接是硬错误，而非警告。
+渲染权威从此可强制执行，而非仅靠约定：谁渲染什么是装载期事实，审计 UI 结构 = 通读 register 调用；对 chain 坑，「谁来渲染」额外多出一层渲染期事实，但做决定的选择器全是 register 现场的声明，审计面仍是 register 调用。每个 props 面都从单一真源静态推导（SlotMap entry、children 键集、store 工厂、inject 返回值），schema 变更由编译器传播，而不靠 grep。插件不再自带任何订阅机械——store 生命周期（每会话实例、dispose、持久化）是钉在 entry 轴上的框架语义。代价：注册选项稠密（children spec 对象）；框架背上实打实的推断机械（`defineStore` 的 init/actions 同轮推断可能需要柯里化兜底）；编译期双向锁意味着原型阶段的漂移直接是硬错误，而非警告。
 
 ## Alternatives considered
 
@@ -107,3 +115,5 @@ register 签名里的两条硬化裁定之所以存在，是因为显然的替
 | 模块级 store 句柄 | 模块级句柄是跨插件重载与跨测试用例的单例；工厂形把身份圈定在单次 apply/测试调用内 |
 | 组件直收 store 实例 | 渲染代码里能用 `update`/`set`，变更面就无从审计；声明的 actions 让「什么能变」保持为 register 现场的事实 |
 | 注册位用 `FC` / 从组件推断 `I` | FC 静态位产生协变噪音、拒绝合法组件；组件侧推断静默吸收 props 漂移（见上文裁定） |
+| 接管坑用 keyed 分派 + owner 侧路由 | owner 会不断攒下逐 entry 契约与硬编码路由表（每种接管一份 `find` + `entryKey`）；chain 货币让新增接管注册保持 owner 零改动 |
+| 组件靠渲染 null 表示不接 | 不接也得先挂载——hook 与 effect 白跑，挂载/卸载抖动破坏 memo 化与 key 语义；纯选择器无需组件实例即可裁决 |
diff --git a/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.i18n.yaml
new file mode 100644
index 0000000000..d218c2a0b2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-22-tui-interactive-extension-service.md: 82e7c751b6e5b7500f9f7d7004fda8b905dccabb
+2026-07-22-tui-interactive-extension-service.zh.md: d7340e3f5dcf45e95b2d6e15ce3fc33726a555ae
diff --git a/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md b/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md
new file mode 100644
index 0000000000..82e7c751b6
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md
@@ -0,0 +1,41 @@
+# Agent Note: Effect-owned TUI interactive extensions
+
+Status: implemented
+
+English | [中文](2026-07-22-tui-interactive-extension-service.zh.md)
+
+## Problem
+
+Cordis plugins can register human commands through `ctx.commands`, but a command that needs terminal interaction has no supported presentation boundary. It must either remain non-interactive or capture the TUI's private pi-tui tree, focus state, renderer, and shutdown lifecycle. That coupling makes the extension depend on one front door's internals, lets independently developed overlays compete for focus, and leaves plugin unload with no reliable way to remove queued or visible UI.
+
+## Decision
+
+A mounted `@deepseek-ai/dsh-tui` provides `ctx.tui` after terminal startup succeeds. The service belongs to that exact terminal and agent, disappears before terminal teardown, and causes plugins that inject it to unload and reload with provider availability. Other front doors do not emulate it.
+
+`ctx.tui.openOverlay()` is the first and only interactive extension primitive. It accepts a component factory, constrained layout options, and an optional abort signal. The factory receives a frozen host with the current viewport, semantic theme functions, display-text escaping, redraw, close, and a lifetime signal. It does not receive the pi-tui `TUI`, overlay handle, editor, transcript tree, focus controller, or terminal object.
+
+One private overlay manager serializes built-in and plugin requests in FIFO order. The model selector and `ctx.userInteraction` question panel use the same manager, so all modal interaction has one focus owner. Closing the active overlay restores pi-tui's previous focus before the next request activates. Overlay state is process-local presentation: it is neither appended to the session log nor rebuilt during resume.
+
+The service method runs through Cordis's traceable service proxy. It installs an effect on the calling plugin fiber before admitting the request; caller disposal therefore removes a queued request or closes an active overlay and awaits the same settled outcome. TUI shutdown first rejects admission, then disposes the service fiber so dependent plugins and their effects quiesce, settles remaining built-in work, and only then drains and stops the terminal.
+
+Component construction, rendering, input, and invalidation run behind an exception boundary. A failure closes that request with an `error` outcome, reports a visible terminal error, and lets the queue continue. Components are trusted package code: their rendered lines may contain ANSI styling, and they must call `host.display()` before including untrusted text.
+
+## Verification
+
+Manager tests pin FIFO admission, cancellation, repeated close, shutdown outcomes, guarded callbacks, host capabilities, and per-file coverage. Cordis lifecycle tests pin caller ownership, provider loss and return, unloading-time rejection, and cleanup quiescence. Fake-terminal integration tests exercise plugin overlays alongside built-in questions, restored editor input, terminal remount, startup rollback, and service disappearance. Existing TUI interaction tests continue to exercise the model selector and question panel through the shared path.
+
+## Alternatives considered
+
+**Expose pi-tui objects directly.** This gives plugins maximum freedom but makes private focus, rendering, and teardown state a public compatibility contract. It also cannot arbitrate independently loaded overlays.
+
+**Put interactive callbacks on command definitions.** Commands are shared by TUI and ACP and remain useful without a terminal. Adding terminal state to `ctx.commands` would couple discovery and dispatch to one presentation implementation.
+
+**Create a complete TUI slot and action framework at once.** Actions, editor replacement, transcript renderers, status regions, and completion providers have different composition and conflict rules. Shipping them behind one broad API would freeze those rules before a concrete consumer proves them.
+
+**Persist open overlays in session events.** Modal presentation is not model-visible session state, and arbitrary component state is not replayable. The plugin that owns durable data records that data through its domain service and recreates presentation when appropriate.
+
+## Consequences
+
+Interactive plugins gain a small stable front door with deterministic focus and Cordis-owned cleanup, while the TUI keeps authority over terminal lifecycle and pi-tui internals. Built-in dialogs and extensions cannot overlap or strand focus.
+
+The API deliberately covers modal overlays only. Human command registration remains on `ctx.commands`; actions, slots, editor replacement, event renderers, and completion providers require separate contracts when real consumers establish their ordering and ownership semantics. FIFO serialization also means one stalled overlay blocks later modal work until its owner closes, aborts, or unloads it.
diff --git a/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.zh.md b/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.zh.md
new file mode 100644
index 0000000000..d7340e3f5d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.zh.md
@@ -0,0 +1,41 @@
+# Agent Note: 由 effect 持有的 TUI 交互扩展
+
+Status: implemented
+
+[English](2026-07-22-tui-interactive-extension-service.md) | 中文
+
+## 问题
+
+Cordis 插件可以通过 `ctx.commands` 注册用户命令，但需要终端交互的命令没有受支持的呈现边界。它只能保持非交互，或者捕获 TUI 私有的 pi-tui 树、焦点状态、渲染器和关闭生命周期。此类耦合会使扩展依赖某个入口的内部实现，让各自独立开发的浮层争抢焦点，并导致插件卸载时无法可靠移除排队中或已显示的 UI。
+
+## 决策
+
+挂载的 `@deepseek-ai/dsh-tui` 在终端成功启动后提供 `ctx.tui`。该服务只属于挂载时绑定的终端与 agent（智能体），在终端拆卸前消失，并使注入它的插件随着提供方的可用与否卸载和重新加载。其他入口不会模拟该服务。
+
+`ctx.tui.openOverlay()` 是第一个也是唯一一个交互扩展原语。它接受组件工厂、受限的布局选项，以及可选的中止信号。工厂收到一个冻结的 host，其中包含当前视口、语义化主题函数、显示文本转义、重绘、关闭和生命周期信号。它不会收到 pi-tui `TUI`、浮层句柄、编辑器、transcript（文本记录）树、焦点控制器或终端对象。
+
+一个私有浮层管理器按 FIFO 顺序串行处理内置请求和插件请求。模型选择器与 `ctx.userInteraction` 问题面板使用同一个管理器，因此所有模态交互只有一个焦点所有者。关闭活动浮层时，系统会先恢复 pi-tui 之前的焦点，再激活下一项请求。浮层状态是进程本地的呈现状态：它既不会追加到会话日志，也不会在恢复期间重建。
+
+服务方法通过 Cordis 的可追踪服务代理运行。它在接纳请求前，向调用方插件的 fiber 注册一个 effect；因此，调用方执行 dispose（资源释放）时会移除排队中的请求或关闭活动浮层，并等待同一个结果完成结算。TUI 关闭时会先拒绝新请求，再 dispose 服务 fiber，让依赖插件及其 effect 完全静止，然后结算其余内置工作，最后才排空并停止终端。
+
+组件构造、渲染、输入与失效处理均在异常边界内运行。任何失败都会以 `error` 结果关闭对应请求、在终端中报告一条可见错误，并让队列继续处理。组件属于受信任的包代码：其渲染行可以包含 ANSI 样式，但加入不受信任的文本前必须调用 `host.display()`。
+
+## 验证
+
+管理器测试固定了 FIFO 准入、取消、重复关闭、关闭结果、受保护回调、host 能力和逐文件覆盖率。Cordis 生命周期测试固定了调用方所有权、提供方消失与恢复、卸载期间的拒绝，以及清理达到完全静止。模拟终端集成测试覆盖插件浮层与内置问题的协作、编辑器输入焦点恢复、终端重新挂载、启动回滚和服务消失。既有 TUI 交互测试继续通过共享路径覆盖模型选择器与问题面板。
+
+## 考虑过的替代方案
+
+**直接暴露 pi-tui 对象。** 这会赋予插件最大的自由度，却会把私有的焦点、渲染与拆卸状态变成公开兼容性契约，也无法在独立加载的浮层之间进行仲裁。
+
+**在命令定义中加入交互回调。** 命令由 TUI 与 ACP 共享，即使没有终端也仍然有用。向 `ctx.commands` 添加终端状态，会让发现与分派流程耦合到某一种呈现实现。
+
+**一次性建立完整的 TUI slot 与 action 框架。** action、编辑器替换、transcript 渲染器、状态区域和补全提供方具有不同的组合规则与冲突规则。在具体消费方验证这些规则之前就将其纳入一个宽泛 API，会过早固化这些规则。
+
+**将打开的浮层持久化为会话事件。** 模态呈现并非模型可见的会话状态，任意组件状态也无法回放。拥有持久数据的插件应通过自身的领域服务记录这些数据，并在适当时重新创建呈现。
+
+## 后果
+
+交互式插件获得一个小而稳定的入口，具备确定性的焦点管理和由 Cordis 持有的清理机制；TUI 则继续掌控终端生命周期和 pi-tui 内部实现。内置对话框与扩展无法重叠，也不会遗留失去归属的焦点。
+
+该 API 有意只覆盖模态浮层。用户命令仍然在 `ctx.commands` 上注册；action、slot、编辑器替换、事件渲染器和补全提供方需要另行设计契约，等待实际消费方确定其顺序与所有权语义。FIFO 串行处理也意味着，一个停滞的浮层会阻塞后续模态工作，直至其所有者关闭、中止或卸载该浮层。
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
new file mode 100644
index 0000000000..b0afe427ce
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-22-unified-send-and-coalesced-user-messages.md: bf0ae468c4783b73e2dbd0e1bc50b9bd2f50cb3f
+2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 17913d2636e3ee5e5ae69f9c554935ba861d14d9
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
new file mode 100644
index 0000000000..bf0ae468c4
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
@@ -0,0 +1,46 @@
+# Agent Note: Unify agent delivery and coalesce injected context into user/message
+
+Status: implemented
+
+English | [中文](2026-07-22-unified-send-and-coalesced-user-messages.zh.md)
+
+## Problem
+
+The agent's public driving surface had grown three near-parallel verbs — `send`, `steer`, `inject` — each with its own options type, its own live event story, and its own durable event. `send` and `steer` both queued a frozen inbox record and emitted `agent/queued`; `inject` bypassed the inbox and wrote a separate `context/message` durable event. The three verbs actually vary along only two independent axes: which queue an item joins (a whole new turn versus the active turn) and whether the item makes the model run. Encoding that 2×2 as three hand-written methods hid the symmetry, made "queue a turn without waking the driver" unreachable, and left `cancel()` with no way to abort a turn while preserving queued work.
+
+Separately, `context/message` and `user/message` had converged: the surface projected both as verbatim user-role content, and the only real difference was that injected context carried `source`/`meta` and was "not a prompt." Two event types for one projection meant every consumer branched on event type to answer "is this a human prompt?", and the goal system used the type split as a side channel (round-zero state changes were `context/message`, admitted rounds were `user/message`).
+
+## Decision
+
+**One acceptance mechanism, four intent helpers.** The concrete loop resolves `followup`, `queue`, `steer`, and `inject` into one (`target` × `wakeup`) acceptance mechanism. `followup` is `next-turn`/wakeup, `queue` is `next-turn`/no-wakeup, `steer` is `next-step`/wakeup, and `inject` is `next-step`/no-wakeup. The public structural interface exposes that mechanism as `send(ResolvedAgentInput)` for callers that already have fully resolved routing; every field is mandatory, and the discriminated input type excludes attached contexts from injection. The [intent-named delivery decision](2026-07-24-intent-named-agent-delivery.md) owns that superseding interface choice. Internally, `wakeup` means “make the model run”: wake a parked driver for an ordinary item or force a continuation for running steering.
+
+**inject keeps its mechanism.** `inject` appends durable model-facing context at the current log position (deferred behind an executing tool batch), or opens a one-shot `injection` turn when idle. It bypasses the FIFOs entirely, accepts no attached contexts, and defaults its source to `{ kind: 'plugin', plugin: '' }`, never `{ kind: 'user' }`.
+
+**context/message is gone.** Injected context is now a `user/message` whose `source` is a non-`user` kind (plugin or goal). `PromptMessageData` gained the optional `meta` that `context/message` carried. 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. This keeps goal-authority's human-authority check exactly as strict as before — an injected message defaults to a plugin source and can never satisfy `source.kind === 'user'`.
+
+**Goal replay disambiguates by round, not type.** A goal state change is a round-zero goal-sourced `user/message` carrying `goal/change` metadata; a positive round is an admitted continuation prompt. `decodeGoalEvent` now takes a `user/message` and still fails loud on goal metadata under a non-goal source or a goal source lacking metadata.
+
+**Delivery returns an id.** Each delivery method returns an opaque branded `AgentMessageId` for the accepted input. FIFO methods carry it through their inbox lifecycle events; injection bypasses those events.
+
+**Three inbox events replace agent/queued.** `agent/inbox/enqueue` (an item entered a FIFO), `agent/inbox/dequeue` (the driver claimed one), and `agent/inbox/discard` (`cancel()` dropped pending items) each carry an `AgentMessage` — the accepted message including its returned `id`, steering/wakeup facts, source, and contexts — so a caller can correlate a queued item with its lifecycle. Injection never touches a FIFO and emits none of these. Every FIFO entry publishes an enqueue, including the loop-authored continuation-reason steer (`agent/turn-continuation` returning `{ action: 'continue', reason }`), so the ledger stays balanced with its later dequeue or discard. The `dsh-agent` invariant companion asserts FIFO conservation: a per-agent outstanding count that dequeue and discard can never drive negative.
+
+**cancel gains keepInbox.** `cancel(cause?, { keepInbox? })`; when true it aborts the active turn but preserves queued and steering items (no discard event, and un-started work is not dropped).
+
+## Alternatives considered
+
+- **A dedicated `MessageSource` kind `context`** for injected content. Rejected because `plugin` already means "not a human," so a fourth kind would add a parallel axis the authority checks would have to learn. Injected context defaults to a plugin source instead.
+- **A typed discriminant field on `PromptMessageData`** (e.g. `origin: 'prompt' | 'context'`) to replace the event-type split. Rejected in favor of `source`, which every consumer already carries and which the goal system already keyed on; a second discriminant would duplicate that fact.
+- **Keeping `agent/queued` alongside the inbox events.** Rejected as a mirror: `agent/inbox/enqueue` is the same enqueue-time signal with the accepted routing facts, and the dequeue/discard events complete the FIFO lifecycle the single event could not describe.
+
+## Consequences
+
+The concrete driver has one delivery mechanism. Four common helpers hide its (`target` × `wakeup`) matrix behind caller intent, while `send` exposes the fully resolved matrix for advanced callers. One durable message type serves prompts, injected context, and goal rounds, so the surface projection and every “human prompt?” check simplify to a `source` test. The goal fold's channel split moves from event type to `source.round`, and every consumer that filtered `context/message` filters `user/message` by source. The turn-enclosure and reconstruction invariants are unchanged: an idle injection still wraps a one-shot turn, now emitting `user/message` instead of `context/message`.
+
+Internally, `wakeup` is the “should the model run” signal, so the inbox distinguishes `hasWakingQueued` (drives the loop and idle/quiescence decisions) from `hasQueued` (anything to dequeue): a lone `queue()` item stays parked at idle and rides along the next waking follow-up, and `whenIdle`/`cancel` settle quiescence off the waking signal (a lone quiet item takes `whenIdle`'s fast path, so no waiter is left hanging). `SendOptions.meta` on a queued or steering message is carried onto the durable `user/message`/`steering/message`, matching injection; it is intentionally absent from the live `AgentMessage`, which carries only routing facts. Every enqueued id gets exactly one terminal lifecycle event: a terminal stop that drops pending steering emits `agent/inbox/discard` both at the in-turn stop point and on the post-turn drain of late steering, and disposal discards any still-pending items before the loop exits. The `agent/inbox/*` payload is frozen so a listener cannot mutate the shared correlation object mid-dispatch, and a loop-authored continuation reason is snapshotted and frozen like public steering. Injection validates its payload before opening an idle one-shot turn; `InjectOptions` omits attached contexts, while the non-waking next-step variant of `ResolvedAgentInput` requires an empty context tuple.
+
+## Related
+
+- [one-send-one-turn](../simplification/2026-07-17-one-send-one-turn.md) — the one-claimed-message-per-turn rule this builds on.
+- [remove-agent-steering-mirror](../simplification/2026-07-04-remove-agent-steering-mirror.md) — the precedent for collapsing a mirrored live event.
+- [explicit-turn-cancellation](2026-07-16-explicit-turn-cancellation.md) — the cancel-cause signal `keepInbox` extends.
+- [intent-named-agent-delivery](2026-07-24-intent-named-agent-delivery.md) — the public helpers and fully resolved acceptance interface.
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
new file mode 100644
index 0000000000..17913d2636
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
@@ -0,0 +1,46 @@
+# Agent Note: 统一 agent 投递并把注入的上下文合并进 user/message
+
+Status: implemented
+
+[English](2026-07-22-unified-send-and-coalesced-user-messages.md) | 中文
+
+## 问题
+
+agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`、`steer`、`inject`——各自带有独立的选项类型、独立的实时事件叙事，以及独立的持久事件。`send` 和 `steer` 都会把一条冻结的 inbox 记录入队并发出 `agent/queued`；`inject` 则绕过 inbox，写入一条独立的 `context/message` 持久事件。这三个动词实际上只沿两条独立的轴变化：一个队列项加入哪个队列（一个全新的轮次，还是当前活跃的轮次），以及这个队列项是否让模型运行。把这个 2×2 编码成三个手写方法，掩盖了其中的对称性，让“排入一个轮次但不唤醒驱动器”无法表达，也让 `cancel()` 无从在保留排队工作的前提下中止一个轮次。
+
+另外，`context/message` 与 `user/message` 已经趋同：对外接口把二者都投影为逐字的 user 角色内容，唯一真正的区别是注入的上下文携带 `source`/`meta` 且“不是提示词”。一个投影对应两种事件类型，意味着每个消费方都要根据事件类型分支来回答“这是不是一条人类提示词？”，而 goal 系统把这种类型区分当作侧信道使用（第 0 轮的状态变更是 `context/message`，已准入的轮次是 `user/message`）。
+
+## 决策
+
+**一种接受机制，四种意图辅助方法。** 具体循环把 `followup`、`queue`、`steer` 和 `inject` 解析到同一个（`target` × `wakeup`）接受机制中。`followup` 是 `next-turn`/wakeup，`queue` 是 `next-turn`/no-wakeup，`steer` 是 `next-step`/wakeup，`inject` 是 `next-step`/no-wakeup。公开的结构化接口将该机制暴露为 `send(ResolvedAgentInput)`；调用方若已持有完全解析的路由信息，即可使用该方法。使用时必须提供所有字段，可辨识输入类型也不允许注入携带附加上下文。取代旧接口的选择由[按意图命名的投递决策](2026-07-24-intent-named-agent-delivery.md)负责说明。内部的 `wakeup` 表示「让模型运行」：为一条普通消息唤醒处于停泊状态的驱动器，或强制运行中的 steering 继续执行。
+
+**inject 保留其机制。** `inject` 在当前日志位置追加持久、面向模型的上下文（在执行中的工具批处理之后延迟处理），或在空闲时开启一个一次性的 `injection` 轮次。它完全绕过 FIFO，不接受附加上下文，并把来源默认设为 `{ kind: 'plugin', plugin: '' }`，绝不是 `{ kind: 'user' }`。
+
+**context/message 已移除。** 注入的上下文现在是一条 `user/message`，其 `source` 为非 `user` 类别（plugin 或 goal）。`PromptMessageData` 新增了 `context/message` 原本携带的可选 `meta`。对外接口、派生逻辑和 `SurfaceEventType` 都不再包含 `context/message`；需要判断“这是不是一条人类提示词？”的消费方改为读取 `source.kind === 'user'`，而不是事件类型。这让 goal-authority 的人类授权检查与此前一样严格——注入的消息默认使用 plugin 来源，永远无法满足 `source.kind === 'user'`。
+
+**goal 回放靠轮次而非类型来区分。** 一次 goal 状态变更是一条第 0 轮、来源为 goal 的 `user/message`，携带 `goal/change` 元数据；正数轮次则是一条已准入的继续执行提示词。`decodeGoalEvent` 现在接收一条 `user/message`，并仍会在非 goal 来源携带 goal 元数据、或 goal 来源缺少元数据时立即报错。
+
+**投递返回一个 id。** 每种投递方法都为被接受的输入返回一个不透明的 branded `AgentMessageId`。FIFO 方法通过其 inbox 生命周期事件携带这个 id；注入绕过这些事件。
+
+**三个 inbox 事件取代 agent/queued。** `agent/inbox/enqueue`（一个队列项进入某个 FIFO）、`agent/inbox/dequeue`（驱动器认领了一个）和 `agent/inbox/discard`（`cancel()` 丢弃了待处理项）都携带一条 `AgentMessage`——即被接受的消息，包含其返回的 `id`、steering/wakeup 事实、来源和上下文——因此调用方可以把一个排队项与其生命周期关联起来。注入从不触及 FIFO，也不发出这些事件中的任何一个。每一次 FIFO 入队都会发布一个 enqueue 事件，包括由 loop 生成的携带继续原因的 steer（`agent/turn-continuation` 返回 `{ action: 'continue', reason }`），因此账目会与其后的 dequeue 或 discard 保持平衡。`dsh-agent` 的不变量配套断言 FIFO 守恒：一个按 agent 计的未结算计数，dequeue 和 discard 永远无法把它压到负数。
+
+**cancel 新增 keepInbox。** `cancel(cause?, { keepInbox? })`；当其为 true 时，它中止活跃轮次，但保留排队项和 steering 项（不发出 discard 事件，尚未启动的工作也不会被丢弃）。
+
+## 考虑过的替代方案
+
+- **为注入内容设立专门的 `MessageSource` 类别 `context`。** 不予采纳，因为 `plugin` 已经表示“不是人类”，因此第四种类别会增加一条平行的轴，让授权检查不得不去学习它。注入的上下文改为默认使用 plugin 来源。
+- **在 `PromptMessageData` 上设一个类型化的判别字段**（例如 `origin: 'prompt' | 'context'`）来取代事件类型的区分。不予采纳，转而采用 `source`——每个消费方都已经携带它，goal 系统也已经以它为键；第二个判别字段会重复这一事实。
+- **在 inbox 事件之外保留 `agent/queued`。** 作为镜像而被否决：`agent/inbox/enqueue` 是同一个入队时刻的信号，只是多带了已接受的路由事实，而 dequeue/discard 事件补全了单个事件无法描述的 FIFO 生命周期。
+
+## 后果
+
+具体驱动器只有一个投递机制。四种常用辅助方法以调用方意图封装其（`target` × `wakeup`）矩阵，而 `send` 则向高级调用方暴露完全解析后的矩阵。一种持久消息类型同时服务提示词、注入的上下文和 goal 轮次，因此对外接口的投影和每一处「是否人类提示词？」检查都简化为一次 `source` 判断。goal 折叠的通道区分从事件类型改到 `source.round`，此前过滤 `context/message` 的每个消费方都改为按来源过滤 `user/message`。轮次封闭与重建的不变量保持不变：空闲状态下的一次注入仍然封装成一个一次性轮次，只是现在发出 `user/message` 而非 `context/message`。
+
+在内部，`wakeup` 是“模型是否应当运行”的信号，因此 inbox 区分 `hasWakingQueued`（驱动 loop 以及空闲/静默判定）与 `hasQueued`（是否有任何可 dequeue 的项）：一个孤立的 `queue()` 项会停泊在空闲状态，并随下一条会唤醒驱动器的后续消息一同带出，而 `whenIdle`/`cancel` 依据唤醒信号来结算静默（一个孤立的静默项走 `whenIdle` 的快速路径，因此不会让任何等待者悬而未决）。排队消息或 steering 消息上的 `SendOptions.meta` 会被带到持久的 `user/message`/`steering/message` 上，与注入保持一致；它有意不放在实时的 `AgentMessage` 上，后者只携带路由事实。每个已入队的 id 都恰好得到一个终止性生命周期事件：一次会丢弃待处理 steering 项的终止性停止会为它发出 `agent/inbox/discard`，既在轮次内的停止点，也在轮次结束后对迟到 steering 的清空时；dispose（资源释放）会在 loop 退出前丢弃所有仍在等待的项。`agent/inbox/*` 的事件载荷已被冻结，因此监听器无法在分发中途修改共享的关联对象，而由 loop 生成的继续原因会像公开 steering 一样被快照并冻结。注入会在打开空闲状态的一次性轮次之前校验其载荷；`InjectOptions` 不包含附加上下文，而 `ResolvedAgentInput` 中不唤醒的下一步变体要求使用空上下文元组。
+
+## 相关
+
+- [one-send-one-turn](../simplification/2026-07-17-one-send-one-turn.md)——本决策所依托的“每轮次只认领一条消息”规则。
+- [remove-agent-steering-mirror](../simplification/2026-07-04-remove-agent-steering-mirror.md)——折叠镜像实时事件的先例。
+- [explicit-turn-cancellation](2026-07-16-explicit-turn-cancellation.md)——`keepInbox` 所扩展的取消原因信号。
+- [intent-named-agent-delivery](2026-07-24-intent-named-agent-delivery.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
new file mode 100644
index 0000000000..54df5f07ab
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-client-plugin-loading-model.md: 58651fd258a6b2929c58bb6f93b44adb6e8e1818
+2026-07-23-client-plugin-loading-model.zh.md: f60b06c7bfaa9c70170082ac4384ba2bd899676e
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
new file mode 100644
index 0000000000..58651fd258
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
@@ -0,0 +1,132 @@
+# Agent Note: Client plugin loading — plain packages, dshClient plugins, and the two-phase boot
+
+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.
+
+## 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`.
+
+The browser client runs the same cordis plugin mechanism, so it needs the same substrate underneath — and the browser has no Node module system.
+
+Conventional frontend engineering digests all dependencies at build time: one bundle, externals resolved by the bundler, nothing left to manage at runtime. Runtime module management on top of that is the unusual requirement here. The client therefore splits into two layers: the upper layer is cordis plugin loading through the same vendored Loader, and the lower layer is module-granular dependency management — `dsh-client-modules`.
+
+The lower layer supplies four capabilities: externals (the platform list), remote arrival (bundle fetch plus lazy factory registration), versioning (content-hash revs), and hot update (invalidate/prefetch).
+
+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.
+
+The first-generation client loader (`createClientLoader`) hand-wrote both layers in one function. The fusion left no unload/reload path (loads were one-shot, style tags never removed), hand-copied dependency lists that had already drifted across three files, and a module-table backdoor for cross-plugin imports that duplicated cordis's service mechanism while making load order a correctness constraint. The structure below replaced it.
+
+## Decision
+
+### Two package kinds; `dshClient` means plugin, period
+
+What makes a package a plugin? One rule: **a package is a plugin package once its consumption is cordis dependency injection; until then it is a plain package.** How code reaches the page is not part of the taxonomy — arrival follows from the kind instead of defining it.
+
+- **Plain packages** are the absolute base the module system itself needs, plus libraries not yet converted to DI: the react family, cordis, `@deepseek-ai/dsh-client-modules` (the module system itself — it can never be a plugin, because modules precede all modules), the web shell kernel, and — for now — ui-slots, web-react, ui-primitives. Plain packages are shell-bundled, seeded into the module table, and invisible to the host graph.
+- **Plugin packages** are everything else. Each one carries a `dshClient` manifest declaration (`{ platform, inject, immediately? }`) and one uniform shape: the shared tsdown preset emits `lib/client.js`, and `exports["./client"]` points at that bundle. Each is a governed entry of the host-authored graph. Nine exist today: connection, runtime, ui-theme, i18n, hmr (dev graphs only), ui-layout, ui-sidebar, ui-conversation, ui-trajectory.
+
+The manifest owns the package's loading contract: its `inject` dependency edges, plus the optional `immediately` prefetch mark (absent means lazy). The composing app owns only the roster and the `--dev` switch.
+
+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.
+
+Four edge rules govern imports across the two kinds. None of them depends on any per-package mark:
+
+- **Plugin ↔ plugin value imports are a build error.** This holds regardless of either side's `immediately` declaration — the rule must not depend on a mark someone can flip. Cooperation goes through cordis inject/services. `import type` is exempt; the type chain is untouched. This rule is why `scopeOf` is a `SessionsService` method and why `transportError` lives in `dsh-host-apiproxy`'s wire layer (its `RpcResult` home, inline-safe).
+- **Plugin → plain package value imports are externals**, judged against the platform list. That list is one constant in the shell (`platform.ts`: react family, cordis, ui-slots, web-react, ui-primitives), imported by both the tsdown preset (for the external judgement) and `seed.ts` (for the table warm-up). One constant, two consumers — the hand-sync drift class stays dead.
+- **The purity gate covers all nine plugin packages.** Its three branches: platform imports become externals; INLINE_SAFE wire layers are inlined; any other workspace leak is a build error. The uniform bundle shape is what makes this coverage total — every plugin builds through the same preset, so no package can sit outside the gate.
+- **The shell is self-sufficient.** The kernel (boot + loading page) value-imports no plugin package; its status stores are hand-rolled. The fail-loud presentation must not depend on the system whose failure it reports.
+
+### One module system, one plugin governor
+
+The browser mirrors the host's division of labor. `dsh-client-modules` (`ClientModuleSystem`) takes the module-system seat that Node's internal ESM loader holds host-side; the same vendored `@cordisjs/plugin-loader` keeps the governance seat on both sides. The line between them in one sentence: **the module system owns module identity and bytes — how code arrives, registers, and becomes an export surface; the Loader owns plugin lifecycle — when a plugin mounts, what it waits for, and how it is torn down.**
+
+`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 fetch + execute → 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)` (fetch + execute, registration only; concurrent calls share one in-flight task) and `invalidate(id)` (drop factory, record, and consumed text so the next arrival refetches).
+
+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 loading flow, end to end
+
+What happens between `dsh web` starting and the UI appearing? Three stages: the host composes and serves a graph, the shell prefetches, then cordis orchestrates.
+
+**Host side — compose the graph.**
+
+1. The composing app (`apps/cli`) mounts the roster as in-memory Loader entries via `mountWebPlugins`. The roster is one flat list of the plugin packages, plus the `client-hmr` row under `--dev`. A roster package that fails to import throws loud at mount.
+2. The registry (`createHostWebPluginRegistry`) scans the mounted entries' package.json `dshClient` declarations and composes `window.__DSH_BOOT__`: `{ rev, entries: [{ id, url, rev, inject?, immediately? }] }`. The `inject` edges and the `immediately` mark come from manifests, never hand-copied. It refuses a declared plugin without a built `./client` bundle, and any malformed declaration field — load-time fail loud.
+3. The registry rescans on cordis `internal/plugin`, microtask-debounced; a rescan failure keeps serving the previous graph. Each bundle's content is hashed into its `rev` (cache busting + HMR diff anchor), and the row set into `graph.rev`. Every row is fetch-served: `/plugins/<id>/client.js?rev=…`. The graph types are a wire contract dual-held on both sides, because the webserver keeps zero workspace dependencies.
+
+Why is the roster a hand-written list and not a scan? Because which plugins compose into a deployment is a composition decision, not a package property — a dshClient package existing in the repo does not mean this deployment mounts it, so discovery-by-scan cannot make that call. The roster lives in `apps/cli/web.ts` rather than cordis.yml only because `dsh web`'s host is a hand-assembled `bootHost` with no Loader config tree yet.
+
+**Phase one — the module face.** The shell builds the module system over the graph, then prefetches every `immediately` row in parallel. Prefetch is fetch + execute, which registers factories only. A single row's prefetch failure is swallowed here: phase two's import retries the fetch and owns the loud failure, so one bad row cannot mask the others. `immediately` is a prefetch mark — not a barrier, not an identity. The package declares it, the registry carries it into the row. The infrastructure plugins (connection, runtime, ui-theme, i18n, plus hmr) declare it; UI plugins simply arrive on demand.
+
+**Phase two — the plugin face.**
+
+1. The kernel mounts the vendored Loader and injects the module system as `internal` before any entry exists. Ordering matters: `tree.import`'s bare-import fallback must never run in a browser.
+2. It creates one entry per graph row, plus the app-shell pseudo-row. The assembly entry is shell-own code the kernel appends itself — registered static with the module system, never part of the host graph — so it rides the same entry lifecycle and status coverage as everything else.
+3. Creation order carries no semantics; fibers activate through service waiting.
+4. `settled` = every entry created + `loader.await()` quiescent + an all-ACTIVE sweep. The sweep lists each import-failed, FAILED, or PENDING fiber with its missing services. It exists because cordis inject waits have no timeout — the sweep is the fail-loud floor.
+5. The loading page's boot status is a projection of real fiber states via `internal/status`. The settled flip switches to the real UI in one pass.
+
+### Hot reload: one driver plugin, self-watched bundles
+
+Whether hot reload is active is a composition decision: dev graphs include the `client-hmr` row (a normal plugin package) and turn on bundle watching; prod graphs do neither.
+
+How does a rebuilt bundle become a reload signal? The webserver observes it itself — no builder tells it. The registry scan already holds every plugin's bundle path (`clientPath`), so in dev mode the registry stat-polls each scanned bundle file with `fs.watchFile`. Polling is by design: inotify does not fire on the weka network mount, the same reason the build-side watcher needs `--poll`. On a mtime/size change the registry re-hashes that row (`rebuilt(id)`); when the `rev` actually changed, it broadcasts a `rebuilt` frame on `GET /plugins/events` — a system SSE channel that sends the full graph on connect and `rebuilt` frames on change, presentation-only wire that never enters the session log. Watch set membership follows the table: rescans add watches for new rows and drop them for vanished ones, dispose drops all. The poll interval is a validated config field (default 500ms), not a constant. Rebuilding the bundles is any tsdown watch process's business — `scripts/dev-web.ts` remains as the watch-build entry point, its package list dshClient-discovered by scanning `packages/*/*/package.json` at startup — and builder and host share zero protocol. A torn read of a half-written bundle self-heals: the stats keep changing while the write completes, so the next poll tick re-hashes again and broadcasts the final rev.
+
+On the browser side, the driver reloads one plugin per frame, serialized:
+
+1. `invalidate` — drop the stale factory and record. A live factory would make the next step a no-op.
+2. `prefetch` — fetch + execute + register the fresh factory, while the old fiber still serves.
+3. `registry.delete` — before touching the fiber. A bare fiber dispose trips the vendored Loader's self-dispose branch, which would disable the entry permanently.
+4. Drain the old fiber's disposers.
+5. Remove owned `<style data-plugin>` tags.
+6. `entry.refresh()` — re-imports, materializing the fresh factory. CSS re-injects here, under the same stable tag ids.
+7. `fiber.await()` — rethrows loud.
+
+All nine plugins share this one semantics; an `immediately` row reloads exactly like a lazy one. Dependency cascade costs zero client code: a fiber's activation epoch strings its service providers' uids, so replacing a provider's fiber re-loads every dependent through cordis itself. Reloading connection or runtime cascades the whole UI — correct, if heavy.
+
+The support boundary, stated honestly. Reload is coarse by design: fresh fiber, fresh components, React state lost, data layer untouched — react-refresh-grade state preservation conflicts with "re-executing the bundle re-runs the factory" and is deliberately out. Plain packages (react family, shell kernel, not-yet-promoted libraries) are not entries: changing them means a shell rebuild and a full page reload. No rollback in v1: an import failure leaves the entry fiberless and the next rebuilt frame retries from scratch; an apply failure leaves a FAILED fiber for the status projection; both log loudly. Self-reload works — the in-flight reload finishes in the old bundle's closure and the new apply opens a fresh SSE channel — but frames arriving in the gap are lost, and the next rebuild renotifies. One 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 frame self-heals.
+
+## Package inventory (today → long term)
+
+| Package | Role | Today | Long term |
+|---|---|---|---|
+| react family / cordis | platform singletons | shell-bundled, seeded | plain forever (absolute base) |
+| vendored `@cordisjs/plugin-loader` | entry governance (same code both sides) | compile-time browserization, kernel-mounted | untouched (vendor policy) |
+| `dsh-client-modules` | the client module system | lazy CJS table; two-phase boot | plain forever (modules precede modules) |
+| `dsh-client-web` | shell kernel + AppRoot + app-shell assembly | self-sufficient (hand-rolled status stores, no plugin value imports) | keeps shrinking |
+| `dsh-client-ui-slots` | slot registry core | plain, seeded | promote to plugin; receive runtime's slots machinery |
+| `dsh-client-web-react` | ctx↔React glue | plain, seeded | promote to plugin; renderer install moves into its apply |
+| `dsh-client-ui-primitives` | base components | plain, seeded | promote to plugin (components via slots/services) |
+| `dsh-client-connection` | wire layer | plugin (dshClient + bundle), declares `immediately` | transport swap (Electron IPC carrier) |
+| `dsh-client-runtime` | session object layer + slots service + store engine | plugin, declares `immediately` | keeps shrinking toward a pure session object layer |
+| `dsh-client-ui-theme` | theme tokens/service | plugin, declares `immediately`, plus the `./styles/*` source channel | Theme Registry (separate ruling) |
+| `dsh-client-i18n` | I18nService | plugin, declares `immediately` | per-deployment locale composition |
+| `dsh-client-hmr` | hot reload driver | plugin, declares `immediately`; dev graphs only | rollback; reconnect handshake |
+| ui-layout / ui-sidebar / ui-conversation / ui-trajectory | UI features | plugins, on-demand | conversation domain split; trajectory real implementation |
+
+## 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.
+
+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; and the three not-yet-promoted libraries keep their static-import export surface until their DI conversions land.
+
+Roster endgame: when `dsh web` moves to config-tree boot, the roster lands in cordis.yml — client plugin packages become ordinary config-tree entry rows, `mountWebPlugins` and the `CLIENT_PACKAGES` constant disappear, and recomposing a deployment means swapping the yml/overlay. The registry needs zero changes for that move, since its `internal/plugin` subscription already discovers whatever entries the tree mounts.
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| Two-axis taxonomy (entry × arrival) with non-dshClient infrastructure packages | Erased manifest dependency edges (inject leaked to the composer), split the plugin shape in two, blinded the purity gate to half the plugins |
+| Keep evolving the hand-written loader into a governor | Re-implements entry/fiber lifecycle the vendored Loader owns; HMR would have no shared skeleton with the host side |
+| Reuse `@cordisjs/plugin-hmr` in the browser | ~80% solves problems the browser doesn't have (fs watching, deep graph coloring, Node's dual caches); the reload skeleton is copied as a shape |
+| Module federation | Independently built remote bundles are exactly the form vite federation does not support |
+| 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 |
+| 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
new file mode 100644
index 0000000000..f60b06c7bf
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -0,0 +1,132 @@
+# Agent Note: client 插件装载——普通包、dshClient 插件与双层 boot
+
+Status: implemented
+
+[English](2026-07-23-client-plugin-loading-model.md) | 中文
+
+> 范围：浏览器侧的插件装载机件——什么是插件、代码怎么到达、热重载如何搭在这套模型上。装载链归本篇所有；[Web 客户端架构 RFC](2026-07-19-gui-web-client-architecture.md) 在装载问题上以本篇为准，继续拥有 slot、数据对象层与 React 面。
+
+## Problem
+
+host 侧，cordis 插件装载站在 Node 的模块机制之上——require cache 与内部 ESM loader 拥有模块身份与字节。vendored `@cordisjs/plugin-loader` 在这层基座之上实现插件治理与热重载，二者在唯一一道 seam 相接：`Loader.internal`。
+
+浏览器客户端跑同一套 cordis 插件机制，因此底下需要同样的基座——而浏览器没有 Node 模块系统。
+
+常规前端工程在构建期消化全部依赖：单一 bundle，external 由打包器解决，运行时无物可管。在此之上再做运行时模块管理，正是这里的特殊需求。client 因此拆成两层：上层是经同一份 vendored Loader 的 cordis 插件装载，下层是模块粒度的依赖管理——`dsh-client-modules`。
+
+下层供给四项能力：external（平台清单）、远程到达（bundle 拉取加惰性工厂登记）、版本化（内容哈希 rev）、热更新（invalidate/prefetch）。
+
+在此之上，client 与 host 插件以一致的方式注册与装载：包声明一次 `dshClient`，host 把声明扫描进 boot 图，同一套 Loader 语义在两侧治理 entry。
+
+第一代 client loader（`createClientLoader`）把这两层手写进了同一个函数。这一融合留下的是：没有卸载/重载路径（装载一次性，style 标签从不移除）、在三个文件间人肉抄写且早已漂移的依赖清单、一条供跨插件 import 走的模块表后门——既复制了 cordis 的服务机制，又把装载顺序变成正确性约束。下文的结构取代了它。
+
+## Decision
+
+### 两类包；`dshClient` 即插件，别无他义
+
+什么让一个包成为插件？只有一条规则：**一个包的消费方式一旦是 cordis 依赖注入，它就是插件包；在此之前它是普通包。**代码怎么到达页面不属于分类体系——到达方式由包的类别推得，而不是反过来定义类别。
+
+- **普通包**是模块系统自身所需的绝对基座，加上尚未转成 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-trajectory。
+
+manifest 拥有包的装载契约：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
+
+新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
+
+普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（将接收现居 runtime 的 slots 机件——SlotsService、渲染器 seam、root slot）、web-react（将把渲染器安装收进自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
+
+四条边规则治理横跨两类包的 import。没有一条依赖任何单包标记：
+
+- **插件 ↔ 插件的值 import 是构建错误。**与两侧的 `immediately` 声明无关——规则不得依赖一个人人可翻转的标记。协作走 cordis inject/服务。`import type` 豁免；类型链分毫未动。这条规则正是 `scopeOf` 是 `SessionsService` 方法、`transportError` 住在 `dsh-host-apiproxy` wire 层（它的 `RpcResult` 老家，内联安全）的原因。
+- **插件 → 普通包的值 import 外置为 external**，按平台清单判定。清单是壳里的一个常量（`platform.ts`：react 家族、cordis、ui-slots、web-react、ui-primitives），tsdown 预设（external 判定）与 `seed.ts`（模块表预热）都 import 它。一个常量、两个消费方——人肉同步这一漂移缺陷类死透。
+- **纯度门禁覆盖全部九个插件包。**它的三条分支：平台 import 外置为 external；INLINE_SAFE wire 层内联；其余任何 workspace 泄漏即构建错误。正是统一的 bundle 形态让这一覆盖不留死角——每个插件都经同一预设构建，没有包能坐在门禁之外。
+- **壳自足。**内核（boot + loading 页）对任何插件包零值 import；其状态 store 为手写。大声失败的呈现不得依赖它所报告失败的那个系统。
+
+### 一套模块系统，一个插件治理器
+
+浏览器复刻 host 侧的分工。`dsh-client-modules`（`ClientModuleSystem`）坐上 host 侧由 Node 内部 ESM loader 占据的模块系统席位；同一份 vendored `@cordisjs/plugin-loader` 在两侧都坐治理席。二者的分界线一句话说尽：**模块系统拥有模块身份与字节——代码怎么到达、怎么登记、怎么变成导出面；Loader 拥有插件生命周期——插件何时挂载、等待什么、如何拆除。**
+
+`ClientModuleSystem` 是一张 lazy CJS 表。执行 bundle 只**登记**其工厂——bundle 调用 `window.__ModuleLoader__.load({ id, factory })`，此外什么都不发生。模块体的一切副作用（包括 CSS 注入）都住在工厂闭包里，在物化时运行：物化即该 id 的首次 `require`/import，此后记忆化。工厂若 require 一个已登记未物化的同伴，就递归物化它，因此任何地方都不存在排序。被要求 import 一个 id 时，表按固定分支顺序解析：种子词条 → 记忆化的记录 → 静态登记（壳自有模块，如 app-shell）→ 已登记的工厂 → 图行 fetch + 执行 → 大声抛错。最后这一抛是构建期纯度门禁在运行期的镜像。系统还保管逐模块的簿记——名下 `<style data-plugin>` 标签 id、观测到的 require 边——并暴露 HMR（热模块替换）需要的两个动词：`prefetch(id)`（fetch + 执行、只登记；并发调用共享同一在途任务）与 `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`。
+
+### 装载流程，端到端
+
+从 `dsh web` 启动到 UI 出现之间发生了什么？三个阶段：host 组合并供给一张图，壳预取，然后 cordis 编排。
+
+**host 侧——组合这张图。**
+
+1. 负责组合的 app（`apps/cli`）经 `mountWebPlugins` 把名册挂载为内存中的 Loader entry。名册是插件包的一张平铺清单，`--dev` 下外加 `client-hmr` 行。名册里 import 失败的包在挂载时大声抛错。
+2. 注册表（`createHostWebPluginRegistry`）扫描已挂载 entry 的 package.json `dshClient` 声明，组合出 `window.__DSH_BOOT__`：`{ rev, entries: [{ id, url, rev, inject?, immediately? }] }`。`inject` 边与 `immediately` 标记都来自 manifest，永不人肉抄写。它拒绝声明了插件却没有已构建 `./client` bundle 的包，也拒绝任何畸形的声明字段——装载期大声失败。
+3. 注册表在 cordis `internal/plugin` 上重扫，微任务去抖；重扫失败则继续供给上一张图。每个 bundle 的内容哈希进其 `rev`（缓存失效 + HMR diff 锚点），行集合哈希进 `graph.rev`。每一行都经 fetch 供给：`/plugins/<id>/client.js?rev=…`。图的类型是两侧各持一份的 wire 契约，因为 webserver 保持零 workspace 依赖。
+
+为什么名册是手写清单而不是扫描？因为哪些插件组合进一次部署是组合决策，不是包属性——一个 dshClient 包存在于仓库里，不代表这次部署要挂载它，扫描发现无从替人做这个决定。名册住在 `apps/cli/web.ts` 而非 cordis.yml，只是因为 `dsh web` 的 host 还是一个手工装配的 `bootHost`，没有 Loader 配置树。
+
+**第一层——模块面。**壳在图之上建起模块系统，然后并行预取每个 `immediately` 行。预取即 fetch + 执行，只登记工厂。单行预取失败在这里被吞下：第二层 import 时会重试 fetch 并拥有那次大声失败，因此一个坏行藏不住其他行。`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 等待没有超时——这次扫描就是大声失败的兜底线。
+5. loading 页的启动状态是经 `internal/status` 对真实 fiber 状态的投影。settled 翻转即一次性切换到真实 UI。
+
+### 热重载：一个驱动插件，自行监视的 bundle
+
+热重载是否启用是一项组合决策：dev 图包含 `client-hmr` 行（一个常规的插件包）并开启 bundle 监视；prod 图两者皆无。
+
+重建好的 bundle 怎么变成重载信号？webserver 自己观察——没有构建器来通知它。注册表扫描本就握有每个插件的 bundle 路径（`clientPath`），因此 dev 模式下注册表用 `fs.watchFile` 对每个已扫描的 bundle 文件做 stat 轮询。轮询是刻意选择：inotify 在 weka 网络挂载上不触发，构建侧监视器需要 `--poll` 也是同一原因。mtime/size 一变，注册表就重哈希该行（`rebuilt(id)`）；当 `rev` 真的变了，才在 `GET /plugins/events` 上广播 `rebuilt` 帧——这是一条系统级 SSE（Server-Sent Events）通道，连接即发全量图，变更时发 `rebuilt` 帧，仅供呈现的 wire，永不进会话日志。监视集合的成员随表走：重扫为新行添加监视、为消失的行撤下监视，dispose（资源释放）撤掉全部。轮询间隔是一个经校验的配置字段（默认 500ms），不是常量。重建 bundle 则是任意一个 tsdown watch 进程的事——`scripts/dev-web.ts` 仍作为 watch 构建入口保留，其包清单在启动时扫描 `packages/*/*/package.json` 按 dshClient 发现——构建器与 host 共享零协议。写一半的 bundle 被撕裂读取会自愈：写入完成期间 stat 持续变化，下一个轮询节拍会再次重哈希并广播最终的 rev。
+
+浏览器侧，驱动插件每帧重载一个插件，串行执行：
+
+1. `invalidate`——丢弃陈旧的工厂与记录。工厂还活着会让下一步变成 no-op。
+2. `prefetch`——fetch + 执行 + 登记新工厂，旧 fiber 此刻仍在服役。
+3. `registry.delete`——先于任何 fiber 操作。裸做 fiber dispose 会触发 vendored Loader 的自 dispose 分支，把 entry 永久停用。
+4. 排空旧 fiber 的各 disposer。
+5. 移除名下的 `<style data-plugin>` 标签。
+6. `entry.refresh()`——重新 import，物化新工厂。CSS 在这里重新注入，沿用同一批稳定标签 id。
+7. `fiber.await()`——让失败大声重抛。
+
+九个插件共享这同一套语义；`immediately` 行的重载与 lazy 行分毫不差。依赖级联不花一行 client 代码：fiber 的激活纪元串接着它各服务提供方的 uid，因此换掉提供方的 fiber，每个依赖方都会经 cordis 本身重新装载。重载 connection 或 runtime 会级联整个 UI——正确，虽然重。
+
+支持边界，如实陈述。重载粒度刻意做粗：全新 fiber、全新组件、React 状态丢失、数据层不动——react-refresh 级的状态保留与「重执行 bundle 即重跑工厂」相冲突，属刻意不做。普通包（react 家族、壳内核、尚未升格的库）不是 entry：改它们意味着壳重建加整页刷新。v1 不做回滚：import 失败让 entry 失去 fiber，下一个 rebuilt 帧从头重试；apply 失败留下 FAILED fiber 交给状态投影；两者都大声记录。自我重载可行——在途的重载在旧 bundle 的闭包里跑完，新的 apply 再开一条新 SSE 通道——但空窗期到达的帧会丢失，下次重建会再次通知。一处已知的仅限 dev 竞态：rebuilt 帧与仍在途的 boot 到达重叠时共享那次到达的任务，可能物化重建前的字节；下一帧自愈。
+
+## 包盘点（现状 → 长期）
+
+| 包 | 角色 | 现状 | 长期 |
+|---|---|---|---|
+| react 家族 / cordis | 平台单例 | 打进壳，已播种 | 永为普通包（绝对基座） |
+| vendored `@cordisjs/plugin-loader` | entry 治理（两侧同一份代码） | 编译期浏览器化，内核挂载 | 不动（vendor 政策） |
+| `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 |
+| `dsh-client-ui-primitives` | 基础组件 | 普通包，已播种 | 升格为插件（组件经 slot/服务供给） |
+| `dsh-client-connection` | wire 层 | 插件（dshClient + bundle），声明 `immediately` | 传输替换（Electron IPC 载体） |
+| `dsh-client-runtime` | 会话对象层 + slots 服务 + store 引擎 | 插件，声明 `immediately` | 持续缩向纯会话对象层 |
+| `dsh-client-ui-theme` | 主题 token/服务 | 插件，声明 `immediately`，外加 `./styles/*` 源码通道 | Theme Registry（另行裁定） |
+| `dsh-client-i18n` | I18nService | 插件，声明 `immediately` | 按部署组合语言包 |
+| `dsh-client-hmr` | 热重载驱动 | 插件，声明 `immediately`；仅进 dev 图 | 回滚；重连握手 |
+| ui-layout / ui-sidebar / ui-conversation / ui-trajectory | UI 功能 | 插件，按需到达 | conversation 域拆分；trajectory 真实现 |
+
+## Consequences
+
+wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模块系统加一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册与 `--dev` 开关。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。
+
+接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面。
+
+名册的终局：当 `dsh web` 迁到配置树 boot，名册落进 cordis.yml——client 插件包变成普通的配置树 entry 行，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量消失，重组一次部署等于换 yml/overlay。注册表为这次迁移零改动，因为它的 `internal/plugin` 订阅本就发现配置树挂载的任何 entry。
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| 两轴分类体系（entry × 到达），基础设施包不带 dshClient | 抹掉了 manifest 依赖边（inject 泄漏给组合方）、把插件形态拆成两种、让纯度门禁对一半插件失明 |
+| 继续把手写 loader 演化成治理器 | 重新实现 vendored Loader 已拥有的 entry/fiber 生命周期；HMR 将与 host 侧毫无共享骨架 |
+| 在浏览器复用 `@cordisjs/plugin-hmr` | 约 80% 在解决浏览器没有的问题（fs 监听、深度图着色、Node 的双缓存）；只按形状抄用其重载骨架 |
+| 模块联邦（module federation） | 独立构建的远端 bundle 恰是 vite 联邦不支持的形态 |
+| import map | 早已排除；DI require 表是终局机制 |
+| 现在就彻底 ctx 化（react 与库全走服务，不设模块表） | 模块轴上的极端形态；搁置——升级法则改为一次一包走向它 |
+| 冻结表 + 到达即实例化 | 要求按到达时刻排序；lazy CJS 登记让递归 `require` 自行定序，且与朴素拉取器的分层相合 |
+| 构建器推送重建通道（编排器在 `onSuccess` 里 POST `/plugins/rebuilt`） | 把重载耦合到一个钦定的构建器进程和第二套 wire 协议；webserver 本就握有每个 bundle 路径，stat 轮询（每次 stat 变化即重哈希）已兜住当年为推送辩护的撕裂写竞态 |
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
new file mode 100644
index 0000000000..6de82d1c9b
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-toolview-dissolution.md: a420c5945d0272cf8087d5f623e9c383c286d7c2
+2026-07-23-toolview-dissolution.zh.md: 47c1f392f5f7ddbf4e6c686b2574faa7987e6126
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
new file mode 100644
index 0000000000..a420c5945d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
@@ -0,0 +1,37 @@
+# Agent Note: Toolview dissolution — tool rows are per-view keyed slots
+
+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.
+
+## Problem
+
+After the view ring dissolved into the slot system, the client kept exactly one parallel registration model: the tool ring — a named registry (`ctx.toolviews`) with its own register grammar, its own resolve semantics (scoped-beats-global predicate dispatch), its own subscribe/version pair, its own inject cache, and its own render outlet with a private error boundary. Every one of those was a second implementation of something the slot machinery already owned, and every future capability (a store seat for row drafts, i18n injection, cross-bundle identity) would have had to be built twice or drift. The ring's one honest justification was that tool names are a runtime-open set while `SlotMap` is a closed declaration table — a registry keyed by arbitrary strings seemed structurally necessary.
+
+## Decision
+
+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: `ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)` with `inject: ['slots', 'conversation']` as the load-order seam — apply mounts `ConversationService` *after* the chat registration, so the service being present guarantees the slot is declared, by construction. Session-dimension differentiation happens inside the component (`useSessions` reading `parentId` — the decision sits where all the information already is); the bash sample is the third-party-posture exemplar. 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.
+
+## 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 moved from registry predicates into the component. 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.
+
+**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.
+
+**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.
+
+## 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), plus one subtlety the load-order seam carries: registrant plugins must declare `inject: ['conversation']` to sequence after the slot declaration, a convention the seam makes correct by construction but does not statically force on third parties.
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
new file mode 100644
index 0000000000..47c1f392f5
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: toolview 溶解——工具行即 per-view keyed slot
+
+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) 所有。
+
+## Problem
+
+视图环溶解进 slot 体系之后，client 侧恰好还剩一套平行注册模型：工具环——一个具名注册表（`ctx.toolviews`），带自己的 register 文法、自己的 resolve 语义（scoped 压 global 的谓词分发）、自己的 subscribe/version 对、自己的 inject 缓存、自己带私有错误边界的渲染出口。其中每一件都是 slot 机器已经拥有之物的第二份实现，而每一项未来能力（行草稿的 store 席位、i18n 注入、跨 bundle 身份）都将不得不建两遍或漂移。这条环唯一像样的存在理由是：tool 名是运行时开放集，而 `SlotMap` 是封闭声明表——以任意字符串为键的注册表看似结构上必需。
+
+## Decision
+
+工具环作为独立基础设施已消失：工具行是**各视图为自己声明的 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.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)`，以 `inject: ['slots', 'conversation']` 作加载序缝——apply 把 `ConversationService` 挂在 chat 注册*之后*，故服务在场即保证槽已声明，构造使然。会话维差异化在组件内完成（`useSessions` 读 `parentId`——决策放在已有全部信息的地方）；bash 样例即第三方姿态的样板。trajectory/waterfall 的 toolview 槽共用这套形状（槽名按槽名纪律 `<域>.<条目>.<孔位>` 定死，共用一张 owner 类型），随各自的行渲染点落地——RendersCheck 拒绝无人渲染的声明，挡住提前空声明的是类型系统而非约定。
+
+registry 时代的职责各有后继居所：inject 缓存与行错误隔离乘框架渲染器（entry×scope 缓存、per-entry `SlotErrorBoundary`）；subscribe/getVersion 乘 slot core 的 per-key 版本机；将来的「store 席位」就是 keyed slot 本就拥有的普通 store 席位（交互草稿耐久性是其首个具名消费者）；miss 兜底即调用点 `fallback` 选项。
+
+## 接受的语义变化
+
+四项行为增量是刻意接受而非疏漏。跨视图出场=逐视图注册——行本须适配各视图版式，一视图一注册是正确耦合，复用即同一组件写两次 register。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发从注册表谓词移入组件。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。
+
+## Alternatives considered
+
+**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——视图维归各视图自己声明的子槽（declaring is claiming，特化面权属自然落对），会话维归已持有标配 kit 的组件内部。两步移完后剩下的只是一份没有任何独有能力的 slot 机器副本。
+
+**把 `renderToolView` 提进标配 kit、注册表迁入 runtime 包。** 拒绝：「工具行」是 conversation 域概念；上提进 runtime 会把域词汇泄漏进框架层，且依然留着两套注册模型。
+
+**以订阅 refCount 推导槽声明**（首个注册方订阅时隐式声明槽）。拒绝：隐式耦合加去抖复杂度；记为将来真出现多观看面时的备选。
+
+**slots.register 之上的薄 `registerToolView` 门面。** 缓建而非拒绝：溶解后该门面只剩编译期三糖（槽名字面量收窄、tool→key 词汇翻译、props 预组合），运行时为零。按「enforce at the operation boundary」（门面不是强制点）与「don't split preemptively」（今天注册方人口只有一个 bash 样例）保持不建；类型糖以导出的 `ToolRowProps` 别名兑现。后悔药条款：注册方长到三五家或出现批量注册模式时，门面十行可补，不扰直注。
+
+## Consequences
+
+client 只有一种注册模型；审计谁渲染工具行 = 读 register 调用，与其他所有 slot 同一套审计。注册方免费获得框架的错误隔离、inject 缓存与 store 席位——没有能力要建两遍。代价即上文接受的语义变化（主要是：跨视图行要逐视图注册、第三方无 registry 级覆盖），外加加载序缝携带的一处微妙：注册方插件须声明 `inject: ['conversation']` 才排在槽声明之后，这条约定由序缝构造保证正确、但不对第三方静态强制。
diff --git a/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.i18n.yaml
new file mode 100644
index 0000000000..2a27e6432f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-unified-session-query-service.md: 0a466e1c36ff1796c858666b0eb36bbd0f480bb0
+2026-07-23-unified-session-query-service.zh.md: 448122b8e6951058b9f633cd56112b0391e1912e
diff --git a/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.md b/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.md
new file mode 100644
index 0000000000..0a466e1c36
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.md
@@ -0,0 +1,35 @@
+# Agent Note: Unified session query service
+
+Status: implemented
+
+English | [中文](2026-07-23-unified-session-query-service.zh.md)
+
+## Problem
+
+Exact reads, semantic filters, relationship traces, and full-text search operate on the same live-preferred session corpus. Exposing full-text search under a second context key makes consumers and app compositions treat one capability as two services, even though the SQLite implementation is the only backend-specific part.
+
+The interface package already owns the shared record, filter, trace, search-request, cursor, and error contracts. A provider registry or coordinator would add runtime selection semantics unsupported by any current consumer.
+
+## Decision
+
+`SessionQueryService` is the single abstract service registered as `ctx.sessionQuery`. It concretely implements listing, title and event reads, surface reads, filtering, and relationship tracing through its backend-independent `SessionCorpus`. Its only abstract methods are `searchSessions()` and `searchEvents()`.
+
+`SessionQuerySqlite` extends that service and is the sole concrete backend. One mounted instance therefore exposes every operation through `ctx.sessionQuery`; its inherited exact operations use the shared corpus implementation, while its SQLite-owned lifecycle observes sources, reconciles the derived FTS index, ranks matches, and owns cursor generations. The interface package has no standalone concrete plugin, search-provider registry, or second context key.
+
+Backend configuration includes the inherited `readWindowMax` setting alongside its own index path, journal mode, page limits, and snippet limit. First-party apps that need session queries mount the SQLite backend and place its disposable index beside their configured persistence root.
+
+This service topology supersedes the separate-key portion of the [exact query decision](../feature/2026-07-10-session-query-service.md) and [SQLite search decision](../feature/2026-07-10-sqlite-session-query-provider.md); their corpus, query, tokenizer, reconciliation, and safety decisions remain in force.
+
+## Alternatives considered
+
+- **Keep `ctx.sessionQuery` and `ctx.sessionSearch` separate** — rejected because both expose operations over one logical corpus, force consumers to discover two keys, and let apps accidentally mount only a partial query surface.
+- **Keep a concrete base service and let the SQLite plugin register or mutate two search methods** — rejected because method availability would depend on plugin order and teardown, and the service would need a provider registration protocol for one implementation.
+- **Move every query implementation into the SQLite package** — rejected because exact reads, filters, and traces require no index and are shared behavior that belongs with their provider-independent contracts.
+
+## Consequences
+
+Consumers inject one service and can combine exact and full-text operations without a second capability lookup. A production composition must choose a concrete backend even when one consumer currently calls only inherited exact methods; tests may use a minimal subclass when backend behavior is outside their scope.
+
+The unified object deliberately retains two internal observation strategies: exact operations read authoritative live/persisted sources per call, while full-text operations reconcile a disposable index. Sharing the context key does not make the derived index authoritative or couple exact-read availability to an FTS query.
+
+Unit coverage pins inherited and abstract behavior on one key, SQLite coverage exercises both operation families on the concrete backend, and the real Loader path verifies that one exported plugin registers the combined service.
diff --git a/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.zh.md b/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.zh.md
new file mode 100644
index 0000000000..448122b8e6
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-23-unified-session-query-service.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 统一会话查询服务
+
+Status: implemented
+
+[English](2026-07-23-unified-session-query-service.md) | 中文
+
+## 问题
+
+精确读取、语义过滤、关系追踪与全文搜索都作用于同一个实时源优先的会话语料库。将全文搜索暴露在第二个上下文键下，会让消费方与应用组合把同一项查询功能视为两个服务，尽管只有 SQLite 实现是后端特有的部分。
+
+接口包已经拥有共享的记录、过滤、追踪、搜索请求、游标与错误契约。提供方注册表或协调器会引入运行时选择语义，而目前没有任何消费方支持这种语义。
+
+## 决策
+
+`SessionQueryService` 是注册为 `ctx.sessionQuery` 的唯一抽象服务。它通过后端无关的 `SessionCorpus` 具体实现列表查询、标题与事件读取、表层读取、过滤和关系追踪。仅有 `searchSessions()` 与 `searchEvents()` 两个方法为抽象方法。
+
+`SessionQuerySqlite` 扩展该服务，并且是唯一的具体后端。因此，一个挂载实例便可通过 `ctx.sessionQuery` 暴露全部操作；其继承的精确操作使用共享的语料库实现，而由 SQLite 管理的生命周期负责观察数据源、对齐派生 FTS 索引、对匹配项排序并管理游标代际。接口包不提供独立的具体插件、搜索提供方注册表或第二个上下文键。
+
+后端配置除了自身的索引路径、日志模式、分页限制与文本片段长度上限外，还包含继承的 `readWindowMax` 设置。需要会话查询的第一方应用挂载 SQLite 后端，并将其可丢弃索引放在已配置的持久化根目录旁。
+
+这一服务拓扑取代了[精确查询决策](../feature/2026-07-10-session-query-service.md)和 [SQLite 搜索决策](../feature/2026-07-10-sqlite-session-query-provider.md)中关于分离上下文键的部分；其中关于语料库、查询、分词器、对齐与安全性的决策仍然有效。
+
+## 已考虑的替代方案
+
+- **保留相互独立的 `ctx.sessionQuery` 与 `ctx.sessionSearch`**：不予采纳，因为二者都针对同一逻辑语料库提供操作，迫使消费方识别两个键，还可能让应用误挂载一组不完整的查询接口。
+- **保留具体的基础服务，再由 SQLite 插件注册或修改两个搜索方法**：不予采纳，因为方法是否可用将取决于插件顺序与资源释放时机，而且该服务需要为唯一的实现定义一套提供方注册协议。
+- **将所有查询实现移入 SQLite 包**：不予采纳，因为精确读取、过滤与追踪不需要索引，并且都属于应与提供方无关契约放在一起的共享行为。
+
+## 后果
+
+消费方只需注入一个服务，无需再次查找其他功能，便可组合精确操作与全文操作。生产环境的组合必须选择一个具体后端，即使当前某个消费方只调用继承的精确方法；如果后端行为不在测试范围内，测试可以使用最小子类。
+
+统一后的对象有意保留两种内部观察策略：精确操作在每次调用时读取权威的实时源或持久化源，全文操作则使可丢弃索引与数据源对齐。共用上下文键不会让派生索引成为权威来源，也不会使精确读取的可用性依赖 FTS 查询。
+
+单元测试在同一个键上同时固定继承实现与抽象方法的契约，SQLite 测试在具体后端上覆盖两类操作，真实 Loader 路径则验证单个导出的插件能够注册组合后的服务。
diff --git a/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.i18n.yaml
new file mode 100644
index 0000000000..ec8c9d105f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-24-intent-named-agent-delivery.md: 32b0502350063610efff746cbef779e8225055eb
+2026-07-24-intent-named-agent-delivery.zh.md: ce8860b397497f4de587a9373d1cd300cf7dab29
diff --git a/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.md b/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.md
new file mode 100644
index 0000000000..32b0502350
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.md
@@ -0,0 +1,52 @@
+# Agent Note: Name public agent delivery by intent
+
+Status: implemented
+
+English | [中文](2026-07-24-intent-named-agent-delivery.zh.md)
+
+## Problem
+
+A configurable `send(content, { target?, wakeup?, ... })` makes every caller learn the loop's routing matrix, its defaults, and the interaction between active-turn targeting and model activation. Optional routing fields also let advanced-looking calls silently become ordinary sends. Most callers have one semantic intent, while some adapters already possess exact routing facts and should not have to reverse-map them into a helper name.
+
+Sharing helper implementations through an abstract `Agent` class also makes the public seam nominal in practice. Object-literal adapters and tests must inherit prototype methods even though the package promises a swappable structural handle. The shared base exists only to forward fixed arguments, while the concrete loop remains the sole production adapter.
+
+## Decision
+
+`Agent` is a structural interface with four intent-named delivery helpers:
+
+- `followup()` queues an ordinary turn and wakes the driver.
+- `queue()` queues an ordinary turn without waking an idle driver.
+- `steer()` targets the running turn and requests another step; while idle it becomes a waking ordinary turn.
+- `inject()` appends model-facing context without running the model.
+
+`followup`, `queue`, and `steer` accept `SendOptions`; `inject` accepts `InjectOptions`, which omits attached contexts because injection has no inbox item to own them. `followup` names the waking next-turn operation used for both initial prompts and later independent prompts.
+
+`Agent` also exposes `send(ResolvedAgentInput)` for callers that already hold the complete route. Every field is mandatory: content, source, contexts, metadata (possibly `undefined`), target, and wakeup. The discriminated union requires the empty context tuple for non-waking next-step injection. `ReactLoopAgent` implements this method once, and all four helpers resolve their defaults before delegating to it. The method accepts the delivery facts as one resolved input; acceptance can still lead to later dequeue, discard, or durable injection rather than eventual delivery.
+
+The target/wakeup matrix is an explicit advanced part of the structural `Agent` interface, not the ordinary helper options and not a base-class implementation seam. With one concrete adapter, a protected subclass seam would be hypothetical; callers and tests use the same public interface.
+
+## Alternatives considered
+
+**Keep the resolved primitive private.** This minimizes the public method count, but forces adapters that already hold exact target/wakeup facts to reverse-map them into helper calls and removes the reusable type for that resolved state.
+
+**Use configurable `send(content, options)` as the primitive.** Optional routing fields would let advanced-looking calls silently become ordinary sends. One mandatory discriminated input keeps the resolved route explicit and rejects attached contexts on injection.
+
+**Name the primitive `acceptInput`, `sendInternal`, or `addMessageAdvanced`.** `acceptInput` describes the synchronous acceptance boundary but not the caller's delivery action. A public method must not describe itself as internal, and `addMessageAdvanced` is inaccurate because the input may later be discarded.
+
+**Use `send(content, options)` as the waking-turn helper.** This reserves the shortest delivery name for one preset and forces callers with complete target/wakeup facts through a less direct primitive name. `followup` distinguishes the next-turn/wakeup intent while leaving `send` for the resolved operation.
+
+**Bind source first through a public sender object.** A source-bound adapter can make attribution explicit for repeated producers, but it adds another public object and does not simplify one-off human input. The existing source default remains, with the standing requirement that non-human producers label their content.
+
+## Verification
+
+Focused agent-loop coverage exercises direct fully resolved acceptance, waking sends, quiet queues, active and idle steering, injection, source/context snapshots, cancellation, and inbox lifecycle correlation through the public methods. Type-level coverage uses structural `Agent` fakes, requires every `ResolvedAgentInput` field, requires empty contexts on its injection variant, and keeps routing fields out of `SendOptions`. The keyless Cordis inspection snapshot pins the structural interface without an abstract-class implementation.
+
+## Consequences
+
+Ordinary callers choose one verb instead of encoding two routing axes; advanced callers may submit the exact discriminated route. The concrete loop retains one acceptance path and one ownership boundary, while the structural interface preserves simple adapters and fakes. Adding a common delivery intent still requires an explicit public helper and mapping rather than another optional matrix combination.
+
+The advanced method adds interface surface and requires structural fakes to implement it. In return, resolved routing has one typed representation, while helper defaults and mappings stay beside the only implementation that owns them.
+
+## Related
+
+- [unified delivery and coalesced user messages](2026-07-22-unified-send-and-coalesced-user-messages.md) owns the shared acceptance mechanism, inbox lifecycle, and durable event convergence this decision narrows at the public seam.
diff --git a/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.zh.md b/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.zh.md
new file mode 100644
index 0000000000..ce8860b397
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.zh.md
@@ -0,0 +1,52 @@
+# Agent Note: 按意图命名公开的 agent 投递
+
+Status: implemented
+
+[English](2026-07-24-intent-named-agent-delivery.md) | 中文
+
+## 问题
+
+可配置的 `send(content, { target?, wakeup?, ... })` 会迫使每个调用方理解循环的路由矩阵、默认值，以及活跃轮次目标与模型激活之间的相互作用。可选路由字段还会让看似高级的调用悄然变成普通投递。大多数调用方只有一种语义意图，而有些适配器已经持有确切的路由信息，不应再被迫将这些信息反向映射为某个辅助方法名称。
+
+通过抽象 `Agent` 类共享辅助方法的实现，实际上也会让公开 seam 具有名义类型约束。对象字面量适配器和测试必须继承原型方法，尽管该包承诺提供一个可替换的结构化句柄。共享基类只负责转发固定参数，而具体循环仍是唯一的生产适配器。
+
+## 决策
+
+`Agent` 是一个结构化接口，提供四种按意图命名的投递辅助方法：
+
+- `followup()` 将一个普通轮次入队并唤醒驱动器。
+- `queue()` 将一个普通轮次入队，但不唤醒空闲驱动器。
+- `steer()` 以运行中的轮次为目标并请求另一个步骤；空闲时，它会变成一个唤醒式普通轮次。
+- `inject()` 追加面向模型的上下文，但不运行模型。
+
+`followup`、`queue` 和 `steer` 接收 `SendOptions`；`inject` 接收 `InjectOptions`，后者不包含附加上下文，因为注入没有 inbox 项来拥有它们。`followup` 为唤醒式下一轮操作命名，这项操作既用于初始提示词，也用于后续的独立提示词。
+
+`Agent` 还公开 `send(ResolvedAgentInput)`，供已经持有完整路由的调用方使用。每个字段都必须提供：内容、来源、上下文、元数据（可以是 `undefined`）、目标和唤醒标志。对于目标为下一步且不触发唤醒的注入，可辨识联合类型要求上下文为空元组。`ReactLoopAgent` 统一实现这个方法；四个辅助方法都会先解析各自的默认值，再委托给它。调用方以一个解析后的输入向该方法提交各项投递事实；接受之后，工作仍可能在稍后出队、被丢弃或持久注入，而不是最终必然送达。
+
+结构化 `Agent` 接口显式包含面向高级用法的 target/wakeup 矩阵；该矩阵不属于普通辅助方法的选项，也不是基类实现 seam。只有一个具体适配器时，protected 子类 seam 只是假想的；调用方和测试使用同一个公开接口。
+
+## 考虑过的替代方案
+
+**让解析后的原语保持私有。** 这会把公开方法数量降到最低，但会迫使已经持有精确 target/wakeup 路由信息的适配器将其反向映射为辅助方法调用，也会移除表示该解析后状态的可复用类型。
+
+**使用可配置的 `send(content, options)` 作为原语。** 可选路由字段会让看似高级的调用悄然变成普通投递。一个各字段均为必填项的可辨识输入既能让解析后的路由保持显式，也会拒绝为注入附加上下文。
+
+**把原语命名为 `acceptInput`、`sendInternal` 或 `addMessageAdvanced`。** `acceptInput` 描述了同步接受边界，却没有描述调用方的投递操作。公开方法不应在名称中把自己称为内部方法，`addMessageAdvanced` 也不准确，因为输入可能在之后被丢弃。
+
+**使用 `send(content, options)` 作为唤醒轮次的辅助方法。** 这会让最简短的投递名称只表示一种预设操作，并迫使持有完整 target/wakeup 信息的调用方改用一个不够直接的原语名称。`followup` 明确区分下一轮/唤醒意图，并把 `send` 留给解析后的操作。
+
+**先通过公开的发送方对象绑定来源。** 对于重复产生消息的来源，来源绑定适配器可以明确标注归属，但它会增加一个公开对象，也不会简化一次性的人类输入。现有的来源默认值予以保留，同时继续要求非人类生产方标注其内容。
+
+## 验证
+
+聚焦的 agent-loop 覆盖率测试通过公开方法覆盖直接接受完全解析的输入、唤醒式投递、静默排队、活跃与空闲状态下的 steering（中途引导）、注入、来源与上下文快照、取消，以及 inbox 生命周期关联。类型级覆盖使用结构化 `Agent` 测试替身，要求提供 `ResolvedAgentInput` 的每个字段，要求其注入变体的上下文为空，并确保 `SendOptions` 不包含路由字段。无密钥的 Cordis 检查快照固定了不采用抽象类实现的结构化接口。
+
+## 后果
+
+普通调用方选择一个动词即可，无需编码两条路由轴；高级调用方则可提交经过判别的精确路由。具体循环保留一条接受路径和一个归属边界，而结构化接口保留了对简单适配器和测试替身的支持。新增一种常见投递意图时，仍需要显式提供公开辅助方法及其映射，而不是再增加一种可选的矩阵组合。
+
+这个高级方法会扩大接口范围，并要求结构化测试替身实现它。作为回报，解析后的路由只有一种类型化表示，而辅助方法的默认值和映射仍留在拥有它们的唯一实现旁边。
+
+## 相关
+
+- [统一投递并合并 user 消息](2026-07-22-unified-send-and-coalesced-user-messages.md)负责定义共享的接受机制、inbox 生命周期和持久事件趋同；本决策只收窄它们的公开 seam。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.i18n.yaml
new file mode 100644
index 0000000000..8453907b5c
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-code-mode-result-card-completeness.md: 03c14cd780832fa03977dade2c7d14feb0399369
+2026-07-20-code-mode-result-card-completeness.zh.md: 45047cc5bcb8b74668702302077ff91fd3ff6bdc
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.md b/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.md
new file mode 100644
index 0000000000..03c14cd780
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.md
@@ -0,0 +1,39 @@
+# Agent Note: Keep the Code Mode result card complete
+
+Status: implemented
+
+English | [中文](2026-07-20-code-mode-result-card-completeness.zh.md)
+
+## Problem
+
+The outer `run_code` tool persisted complete rendered content, but its editor presenter ignored that content and rebuilt the card body from a logs-only `presentationMeta` projection. A result-only run appeared correct because an empty presenter body let ACP and TUI fall back to `tool/result.content`. Once the program emitted a log, the presenter supplied non-empty content, that fallback stopped, and the returned value disappeared from the completed card. A spill policy's final head/tail preview was vulnerable to the same split ownership whenever captured logs made the stale projection non-empty.
+
+Nested Code calls never owned cards, so producing metadata for the outer call solely to reconstruct one incomplete card also obscured the intended one-card boundary.
+
+## Decision
+
+The canonical tool registry pipeline owns the final model-facing outer content. On success, the `run_code` output renderer renders captured logs followed by the return value or the explicit no-output marker. Runtime failures and pre-execution policy denials are normalized into error content by `ToolRegistry` without invoking that renderer. A post-execute block runs after successful rendering and replaces the result with error content; other post-execute policy and spill decisions may replace content before persistence.
+
+`run_code` omits `presentResult`. The established generic result fallback keeps the pending program title and renders the raw final `tool/result.content`; that durable, replayable, post-policy projection is the card's only result-content source. The host API proxy therefore omits a separate result view instead of serializing the same content in both `event.data.content` and `view.view.content`. The redundant logs-only `presentationMeta` projection remains removed.
+
+Nested dispatch remains unchanged. Calls marked by `exec.parent` emit bounded `tool/code-dispatch` diagnostics but no `tool/call` or `tool/result` surface cards, so one outer `run_code` invocation still produces exactly one card.
+
+## Testing
+
+Tool unit coverage drives logs-only, result-only, logs-plus-result, no-output, spilled-result, and failure outcomes through the canonical registry, then pins the durable content and absence of a result presenter. A host-mux regression uses a call-only presenter to prove the result frame carries raw content exactly once and no view. These cases prove stale metadata cannot replace final content without making the host duplicate that content.
+
+The keyless ACP and TUI Code Mode snapshots execute one outer program that performs two nested bash calls, logs `captured output`, and returns `CODE_ONE+CODE_TWO`. Both surfaces show one completed outer card containing both lines and no nested cards.
+
+## Alternatives considered
+
+**Append the return value to logs metadata.** Rejected because metadata would duplicate the renderer, need a second stable formatting contract for every JSON root, and still miss post-policy content replacement or spill previews.
+
+**Merge presenter metadata with `result.content`.** Rejected because the rendered content already contains the logs; merging would duplicate them and require brittle deduplication.
+
+**Forward `result.content` through a generic result presenter.** Rejected because the durable event already carries that content and ACP/TUI already have a generic raw-content fallback. The host mux serializes a tool-owned result view beside the event, so forwarding would duplicate the rendered content in one frame merely to recreate the fallback; the default worker alone admits a 64 MiB variable-payload budget before rendering.
+
+**Create one card per nested dispatch.** Rejected because intermediate values are intentionally execution-local and never model-facing. Multiple cards would expose an implementation trace instead of the single Code Mode operation the model and user invoked.
+
+## Consequences
+
+ACP and TUI display the same complete content the model receives and replay persists, including post-policy spill previews, through their generic result fallback. The host API retains the pending program title without duplicating the raw result in a separate view payload. New `run_code` results no longer carry the optional logs metadata, but this requires no session-format bump: existing records remain valid because presentation reads their durable rendered content.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.zh.md
new file mode 100644
index 0000000000..45047cc5bc
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-code-mode-result-card-completeness.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 保证 Code Mode 结果卡片内容完整
+
+Status: implemented
+
+[English](2026-07-20-code-mode-result-card-completeness.md) | 中文
+
+## 问题
+
+外层 `run_code` 工具会持久化完整的渲染内容，但编辑器的卡片展示逻辑忽略了这些内容，转而根据仅含日志的 `presentationMeta` 投影重新构建卡片正文。仅有结果的运行看似正确，是因为展示逻辑未提供正文时，ACP 和 TUI 会回退到 `tool/result.content`。只要程序输出一条日志，展示逻辑就会提供非空内容，回退随即停止，返回值便会从完成态卡片中消失。当已捕获的日志使陈旧投影变为非空时，输出落盘策略最终生成的头尾预览也会受到同一职责拆分的影响。
+
+嵌套 Code 调用从不生成自己的卡片。因此，仅仅为了重建这一张不完整卡片而给外层调用生成元数据，还掩盖了每次外层调用只生成一张卡片的预期边界。
+
+## 决策
+
+规范的工具注册表流水线负责最终面向模型的外层内容。成功时，`run_code` 输出渲染器先渲染已捕获的日志，然后渲染返回值或显式的无输出标记。运行时失败和执行前策略拒绝由 `ToolRegistry` 归一化为错误内容，过程中不会调用该渲染器。Post-execute 阻断发生在成功渲染之后，并把结果替换为错误内容；其他 post-execute 策略与输出落盘决策可以在持久化之前替换内容。
+
+`run_code` 不提供 `presentResult`。既有的通用结果回退机制会保留待完成的程序标题，并渲染原始的最终 `tool/result.content`；这一持久、可回放且经过 post-policy 处理的投影是卡片中结果内容的唯一来源。宿主 API 代理因此不提供单独的结果视图，而不会在 `event.data.content` 与 `view.view.content` 中重复序列化同一内容。冗余的仅含日志的 `presentationMeta` 投影继续保持移除状态。
+
+嵌套分发保持不变。带有 `exec.parent` 标记的调用会发出有界的 `tool/code-dispatch` 诊断，但不会生成与 `tool/call` 或 `tool/result` 对应的界面卡片，因此一次外层 `run_code` 调用仍然只会生成一张卡片。
+
+## 测试
+
+工具单元测试通过规范注册表覆盖仅有日志、仅有结果、日志与结果并存、无输出、结果落盘和失败的结果，然后固定持久内容以及结果展示器不存在这一事实。宿主 mux 回归测试使用仅有调用的展示器，证明结果帧恰好携带一次原始内容，且不含视图。这些案例证明陈旧元数据无法替换最终内容，同时不会让宿主重复该内容。
+
+无密钥的 ACP 与 TUI Code Mode 快照会执行一个外层程序：程序进行两次嵌套 bash 调用，记录 `captured output`，并返回 `CODE_ONE+CODE_TWO`。两个界面都只显示一张完成态外层卡片，其中包含这两行内容，且没有嵌套卡片。
+
+## 备选方案
+
+**把返回值追加到日志元数据：**不予采纳。元数据会与渲染器重复，并且需要为每一种 JSON 根另行维护稳定的格式化契约；post-policy 内容替换或输出落盘预览仍然会被遗漏。
+
+**把展示元数据与 `result.content` 合并：**不予采纳。渲染内容已经包含日志；合并会造成重复，还需要依赖脆弱的去重逻辑。
+
+**通过通用结果展示器转发 `result.content`：**不予采纳。持久事件已经携带该内容，ACP 和 TUI 也已有通用的原始内容回退机制。宿主 mux 会在事件旁序列化工具拥有的结果视图，因此转发仅仅是为了重建该回退机制，却会在一个帧中重复渲染内容；仅默认 worker 在渲染前允许 64 MiB 的可变载荷预算。
+
+**为每次嵌套分发创建一张卡片：**不予采纳。中间值有意只存在于执行期间，永远不面向模型。多张卡片会暴露实现轨迹，而不是模型与用户调用的单次 Code Mode 操作。
+
+## 影响
+
+ACP 和 TUI 通过通用结果回退机制显示与模型接收及回放持久化相同的完整内容，其中包括 post-policy 输出落盘预览。宿主 API 保留待完成的程序标题，同时不在单独的视图负载中重复原始结果。新的 `run_code` 结果不再携带可选的日志元数据，但无需提升会话格式版本：现有记录仍然有效，因为展示逻辑会读取其中持久化的渲染内容。
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
new file mode 100644
index 0000000000..b16ef70d7c
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-config-hot-reload-resilience.md: 1a8e29c603ede50b60199e9151fca58dadcc3d40
+2026-07-20-config-hot-reload-resilience.zh.md: 6c7a421bfa84504a36d5329e13a485bf72cc6b6c
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
new file mode 100644
index 0000000000..1a8e29c603
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
@@ -0,0 +1,38 @@
+# Agent Note: A config hot-reload must not kill or degrade a live app
+
+Status: implemented
+
+English | [中文](2026-07-20-config-hot-reload-resilience.zh.md)
+
+## Problem
+
+The demo apps mount `@cordisjs/plugin-hmr` as a leaf so a running agent picks up `cordis.yml` edits. One bad edit killed the process: `Include.refresh()` rethrew the YAML parse error, the HMR watcher awaits `refresh()` inside an async chokidar callback nobody catches, and the resulting unhandled rejection tripped `dsh-app-boot`'s fail-loud handler — `exit(1)` mid-session, losing the live TUI. Two adjacent defects made even *valid* reloads wrong: a file that parses to `undefined` (empty or mid-write truncated — editors and `sed -i` routinely produce these states) crashed the entry walk instead of reading as invalid, and a re-read never re-applied the include's `config.patches`, so any hot-reload of an overlay-based tree (Code Mode, personal overlays) silently reverted patched entries and removed inserted ones.
+
+## Decision
+
+Harden the vendored `@cordisjs/plugin-include` (logged as local modification 8 in [vendor/README.md](../../../../vendor/README.md)) rather than the callers:
+
+- `refresh()` awaits the whole read-and-update and catches failures, logs a warning, and keeps the last good entry tree. A hot-reload is advisory; the invariant is that no file state reachable by an editor may take the process down.
+- `read()` rejects a non-array parse result with a `TypeError`, folding the `undefined`-parse case into the same "invalid file" signal, and commits `content`/`data` only after a successful parse — so reverting an edit to the exact last good content correctly reads as "unchanged".
+- `refresh()` and the `internal/update` listener apply `this.applyPatches(...)` before `root.update()`, restoring parity with `[Service.init]`. `applyPatches` deep-copies the cached parse (`structuredClone`) instead of mutating it, so repeated application converges and removing a patch reverts to the file's own values. The listener uses the incoming config's `patches` and persists that config itself: it vetoes the fiber restart (children update in place), and `Fiber.update` only assigns `this.config` behind `next()`, so without the explicit assignment the next re-read would re-apply the old overlay.
+
+Boot-time behavior stays fail-loud and gets a sharper diagnostic: `[Service.init]` falls back to `initial` (or "config file not found") only on `ENOENT`; an existing-but-invalid file now fails with its real parse error instead of being mislabelled as absent or silently overwritten by `initial`.
+
+## Alternatives considered
+
+**Catch in the HMR watcher callback instead of `refresh()`.** Rejected: it would leave `refresh()` a trap for every other caller (the `internal/update` path shares the same tree-update logic), and it cannot fix the `undefined`-parse or patch-loss defects, which live inside the include.
+
+**Filter config-file rejections in `installFailLoud`.** Rejected: the fail-loud handler exists to make late load failures visible; teaching it to classify exceptions by origin would silently swallow genuine boot failures and leave the stale-`data` crash in place.
+
+**A PTY e2e proving the TUI survives a bad edit.** Rejected as the primary gate: the PTY smoke reads the repo's committed `cordis.yml`, so corrupting it in-place is not test-safe, and a temp copy cannot resolve the tree's bare package specifiers. The unit spec drives the exact `refresh()` entry point the watcher calls; the fix was additionally verified manually against the live TUI (bad YAML, empty file, restored file).
+
+## Consequences
+
+- A bad `cordis.yml` edit now logs `ignoring config reload at <file>` and the agent keeps running on the last good tree; the next valid edit applies normally. With no logger exporter mounted in the TUI demos the warning is currently invisible on screen — surfacing loader warnings in the TUI is deferred.
+- Overlay trees survive base-file reloads with patches intact instead of silently reverting to the unpatched base.
+- The vendored include diverges further from upstream; the divergence is logged in the vendor manifest and re-applies on the next sync.
+- Known gap, out of scope here: the HMR watcher only handles chokidar `change` events, so editors that replace the file by rename (BSD `sed -i`, `git checkout`) do not trigger a config reload at all; and a reloaded app-entry config does not visibly restart the running TUI (pre-existing on the unmodified tree).
+
+## Testing
+
+`packages/ui/app-boot/tests/config-reload.spec.ts` boots real Loader trees against temp configs and pins: an invalid-YAML edit and an empty-file edit both resolve `refresh()` without rejection and keep the previous entry config; a subsequent valid edit applies; an overlay tree re-applies both entry patches and inserted entries on re-read; a hot-update of the include entry's own `patches` applies immediately, survives the next file re-read, and reverts cleanly when the patches are removed. The assertions fail on the unpatched vendored include.
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
new file mode 100644
index 0000000000..6c7a421bfa
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
@@ -0,0 +1,38 @@
+# Agent Note: 配置热重载不得杀死或降级正在运行的应用
+
+Status: implemented
+
+[English](2026-07-20-config-hot-reload-resilience.md) | 中文
+
+## Problem
+
+各示例应用把 `@cordisjs/plugin-hmr` 挂载为叶子配置项，让运行中的 agent 能感知 `cordis.yml` 的编辑。一次错误的编辑就会杀死进程：`Include.refresh()` 把 YAML 解析错误原样抛出，HMR 的文件监听器在一个无人捕获的异步 chokidar 回调里 await `refresh()`，产生的未处理 rejection 触发 `dsh-app-boot` 的快速失败处理器——会话中途 `exit(1)`，正在运行的 TUI 就此丢失。另有两个相邻缺陷让*合法*的重载也出错：解析结果为 `undefined` 的文件（空文件或写入中途被截断的文件——编辑器和 `sed -i` 常态性地产生这类中间状态）会让配置项遍历直接崩溃，而不是被判定为无效文件；并且重新读取时从不重新应用 include 的 `config.patches`，因此对基于 overlay 的配置树（Code Mode、个人 overlay）做任何热重载，都会悄悄把打过补丁的配置项回退、并把插入的配置项移除。
+
+## Decision
+
+加固 vendor 的 `@cordisjs/plugin-include`（在 [vendor/README.md](../../../../vendor/README.md) 中记录为本地修改第 8 条），而不是修改调用方：
+
+- `refresh()` await 整个「读取并更新」过程并捕获失败，记录一条警告，并保留上一份完好的配置树。热重载是尽力而为的；不变式是编辑器可能产生的任何文件状态都不得导致进程退出。
+- `read()` 对非数组的解析结果抛出 `TypeError`，把 `undefined` 解析结果并入同一个「无效文件」信号，并且只在解析成功后才提交 `content`/`data`——因此把编辑撤销回与上一份完好内容完全一致时，会正确地判定为「无变化」。
+- `refresh()` 与 `internal/update` 监听器在 `root.update()` 之前调用 `this.applyPatches(...)`，与 `[Service.init]` 保持一致。`applyPatches` 对缓存的解析结果做深拷贝（`structuredClone`）而不是就地修改，因此重复应用会收敛，移除补丁会回退到文件自身的值。监听器使用传入配置中的 `patches` 并自行持久化该配置：它否决 fiber 重启（子配置项就地更新），而 `Fiber.update` 只在 `next()` 之后才赋值 `this.config`，若不显式赋值，下一次重新读取会重新应用旧的 overlay。
+
+启动期行为保持快速失败并获得更准确的诊断：`[Service.init]` 只在 `ENOENT` 时回退到 `initial`（或「config file not found」）；存在但无效的文件现在会以真实的解析错误失败，而不是被误标为文件缺失、或被 `initial` 静默覆盖。
+
+## Alternatives considered
+
+**在 HMR 监听回调里捕获，而不是在 `refresh()` 里。** 否决：这会让 `refresh()` 继续成为其他所有调用方的陷阱（`internal/update` 路径共享同一套树更新逻辑），而且无法修复 `undefined` 解析结果与补丁丢失这两个位于 include 内部的缺陷。
+
+**在 `installFailLoud` 里过滤配置文件相关的 rejection。** 否决：快速失败处理器的存在意义就是让延迟出现的加载失败可见；教它按来源给异常分类会悄悄吞掉真正的启动失败，并且原样保留陈旧 `data` 导致的崩溃。
+
+**用 PTY e2e 证明 TUI 能在错误编辑后存活。** 否决其作为主要门禁：PTY 冒烟测试读取仓库中已提交的 `cordis.yml`，就地破坏它对测试不安全，而临时副本无法解析该配置树的裸包说明符。单元测试直接驱动监听器所调用的 `refresh()` 入口；此外还对运行中的 TUI 做了人工验证（错误 YAML、空文件、恢复文件）。
+
+## Consequences
+
+- 现在错误的 `cordis.yml` 编辑会记录 `ignoring config reload at <file>`，agent 继续运行在上一份完好的配置树上；下一次合法编辑正常生效。TUI 示例没有挂载任何日志导出器，这条警告目前不会显示在屏幕上——在 TUI 中呈现 loader 警告的工作暂缓。
+- overlay 配置树在基础文件重载后补丁保持完整，不再悄悄回退到未打补丁的基础配置。
+- vendor 的 include 与上游进一步分叉；该分叉已记录在 vendor 的 manifest 里，下次同步时重新应用。
+- 已知缺口，不在本次范围内：HMR 监听器只处理 chokidar 的 `change` 事件，因此通过重命名替换文件的编辑方式（BSD `sed -i`、`git checkout`）完全不会触发配置重载；应用配置项重载后也不会可见地重启运行中的 TUI（未修改的代码树上即已如此）。
+
+## Testing
+
+`packages/ui/app-boot/tests/config-reload.spec.ts` 用真实 Loader 树加载临时配置并固定以下行为：无效 YAML 编辑和空文件编辑都让 `refresh()` 正常 resolve 而不产生 rejection，并保留之前的配置项配置；随后的合法编辑正常生效；overlay 配置树在重新读取时重新应用配置项补丁和插入的配置项；对 include 配置项自身 `patches` 的热更新立即生效、在下一次文件重读后依然保持、并在补丁移除后干净地回退。这些断言在未打补丁的 vendor include 上会失败。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.i18n.yaml
new file mode 100644
index 0000000000..f907cf276b
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-jsonl-storage-identity.md: 1ada16791f411a54fbcf9271c7d7963223bbe683
+2026-07-20-jsonl-storage-identity.zh.md: 8027c51dbf6c7d01463b7851d859a40890bf03e1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.md b/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.md
new file mode 100644
index 0000000000..1ada16791f
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.md
@@ -0,0 +1,29 @@
+# Agent Note: Bind JSONL session identity before mutation
+
+Status: implemented
+
+English | [中文](2026-07-20-jsonl-storage-identity.zh.md)
+
+## Problem
+
+JSONL lookup selects a physical log from the requested session id across cwd buckets, while the parsed `SessionHeader` supplies the metadata used by later repair and append operations. Without binding those two facts, a log selected for session A can declare session B's id or cwd and redirect a repair or later append to B's path. The bucket scan also needs a defined result when the same encoded id exists in more than one bucket. SQLite does not share this ambiguity because its primary-key query binds metadata and events to the requested id.
+
+## Decision
+
+`loadStored(id)` is the coordinator's single stored-prefix lookup. The JSONL backend scans every cwd bucket, requires at most one matching encoded filename, parses that file, then validates both `header.id === id` and `selectedPath === logPath(root, header.cwd, header.id)` before returning metadata. `list()` applies the same path validation and rejects duplicate ids across buckets.
+
+The coordinator independently asserts the returned id and compares the stored cwd with a live session's cwd before repair, state publication, or suffix persistence. It keeps a detached copy of validated metadata; JSONL append and repair derive their path from that copy. The `PersistenceBackend<TornMarker>` interface therefore needs neither a scope-specific live lookup nor a storage-locator type.
+
+An existing configured JSONL root must be a readable directory when the plugin loads. An absent root remains valid and is created on first materialization. The backend supports one live writer per session; another backend instance or process must not mutate that session until the owner finishes disposal and all writes stop.
+
+## Alternatives considered
+
+**Flatten storage by session id.** A flat namespace makes duplicate publication collide on one path, but path validation and duplicate rejection close the identity defect without changing the project-grouped cwd layout or its consumers.
+
+**Carry an opaque storage locator through the coordinator.** A locator binds JSONL mutations directly to a selected path, but JSONL can reproduce that path from metadata it has already validated. Adding another generic and argument to SQLite, test backends, append, and repair makes every implementation carry a concept only the file backend needs.
+
+**Coordinate multiple live writers.** A dedicated coordination service, process-global registry, or cross-process lock would define a new deployment topology rather than repair identity validation. The supported topology has one live writer; no-overwrite hard-link publication still arbitrates an initial same-id creation race.
+
+## Consequences
+
+Mismatched, misplaced, and duplicate JSONL logs fail before repair or coordinator state mutation. The cwd-bucket format stays unchanged and needs no migration. Lookup remains proportional to the number of buckets, and one-live-writer ownership remains an explicit limitation. Coordinator and JSONL tests pin rejection before repair, unchanged bytes for both affected logs, path validation during listing, duplicate-id rejection, cwd collision handling, and load-time root validation.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.zh.md
new file mode 100644
index 0000000000..8027c51dbf
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 在变更前绑定 JSONL 会话身份
+
+Status: implemented
+
+[English](2026-07-20-jsonl-storage-identity.md) | 中文
+
+## 问题
+
+JSONL 查找会根据请求的会话 id 在各个 cwd 分桶目录中选出物理日志，而解析得到的 `SessionHeader` 会提供后续修复和追加操作使用的元数据。如果这两个事实没有绑定，为会话 A 选中的日志就能声明会话 B 的 id 或 cwd，并将修复或后续追加重定向到 B 的路径。当同一个编码后 id 出现在多个分桶目录中时，分桶扫描也必须给出确定的结果。SQLite 不存在这种歧义，因为主键查询会将元数据和事件绑定到请求的 id。
+
+## 决策
+
+`loadStored(id)` 是协调器唯一的已存前缀查找操作。JSONL 后端扫描所有 cwd 分桶目录，要求匹配编码文件名的日志至多有一个，解析该文件，然后在返回元数据前同时验证 `header.id === id` 和 `selectedPath === logPath(root, header.cwd, header.id)`。`list()` 执行相同的路径验证，并拒绝跨分桶目录重复的 id。
+
+协调器会独立断言返回的 id，并在修复、发布状态或持久化后缀之前比较已存 cwd 和活动会话的 cwd。协调器保留一份已验证元数据的独立副本；JSONL 的追加和修复操作根据该副本派生路径。因此，`PersistenceBackend<TornMarker>` 接口既不需要限定范围的活动会话查找，也不需要存储定位器类型。
+
+如果配置的 JSONL 根目录已存在，插件加载时该路径必须是可读目录。根目录不存在仍然是有效配置，首次物化时会创建该目录。后端对每个会话只支持一个活动写入方；在所有者完成资源释放且所有写入停止之前，另一个后端实例或进程不得变更该会话。
+
+## 考虑过的替代方案
+
+**按会话 id 扁平化存储。** 扁平命名空间会让重复发布在同一路径上冲突，但路径验证和重复项拒绝无需改变按项目分组的 cwd 布局及其消费方，也能消除身份缺陷。
+
+**通过协调器传递不透明存储定位器。** 定位器可以将 JSONL 变更直接绑定到选定路径，但 JSONL 可以根据已经验证的元数据重新得到该路径。为 SQLite、测试后端、追加和修复操作增加一个泛型和参数，会让每个实现都承担只有文件后端需要的概念。
+
+**协调多个活动写入方。** 专用协调服务、进程级全局注册表或跨进程锁会定义新的部署拓扑，而不是修复身份验证。受支持的拓扑只有一个活动写入方；禁止覆盖的硬链接发布仍会裁决初始的同 id 创建竞争。
+
+## 后果
+
+JSONL 日志的身份不匹配、位置错误和重复会在修复或协调器状态变更前失败。cwd 分桶格式保持不变，无需迁移。查找开销仍与分桶目录数量成正比，单一活动写入方的所有权仍是明确限制。协调器和 JSONL 测试固定了修复前拒绝、两个受影响日志的字节均保持不变、列出时的路径验证、重复 id 拒绝、cwd 冲突处理以及加载时的根目录验证。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.i18n.yaml
index 9d8ccb1790..19e9446f50 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent 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-collapsed-sidebar-control-rail.md: e959eef37a9e9c0fea79b82ff970daddd9257609
-2026-07-22-collapsed-sidebar-control-rail.zh.md: 7f6d6529a8aa4a655a1d3292e7f41bfb822f05a3
+2026-07-22-collapsed-sidebar-control-rail.md: 940fcabf126941cc0e411b01c337e45831e442aa
+2026-07-22-collapsed-sidebar-control-rail.zh.md: 70ace36fafcb28aa714000262e31c8555d394854
diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.md b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.md
index e959eef37a..940fcabf12 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.md
@@ -10,11 +10,11 @@ The sidebar close action persisted a zero width preference, and the layout mappe
 
 ## Decision
 
-The layout maps a closed sidebar (persisted width `0`) to the fixed `SIDEBAR_COLLAPSED` width of 56px: a 24px icon column between the sidebar's 16px horizontal paddings. The compact rail participates in the concession solver and retains its right border, while the stored expanded width remains untouched.
+The layout maps a closed sidebar (persisted width `0`) to the fixed `SIDEBAR_COLLAPSED` width of 56px: a 24px icon column between the sidebar's 16px horizontal paddings. The sidebar track is fixed-width in the solver — open or collapsed it never concedes to viewport pressure (only details shrinks, then auto-closes) — and the rail retains its right border while the stored expanded width remains untouched.
 
 `AppFrame` marks the sidebar collapsed from the persisted width preference rather than from the resolved track width, removes the resize handle while collapsed, and passes `collapsed` to the sidebar slot as owner props from the render site. Collapse and expand animate: the frame transitions `grid-template-columns` (and the remaining handle its `left`) on the deepsuite sider curve — `--ds-ease-in-out` over `--ds-transition-duration-slow`, both supplied by ui-theme's base sheet; transitions pause during drags and under `prefers-reduced-motion`.
 
-`SidebarRoot` reads the owner `collapsed` prop and morphs in place rather than swapping renders: the four control rows persist into the rail — expand toggle, new session, new workspace, search, in the same top-down order as their expanded rows — animating their geometry (heights, paddings, margins, capsule borders) on the same curve, each aligned with its expanded counterpart's behavior (the search icon expands the sidebar and focuses the search box). Wide-only content (brand, labels, input, session tree) cross-fades out over 200ms, stays mounted while the collapse animates, and unmounts once the 300ms settle passes — dropping the sessions subscription and leaving the rendered and accessibility trees. The search query lives with the root and survives the round trip.
+`SidebarRoot` reads the owner `collapsed` prop and transitions as a slide + crossfade: the expanded content freezes at its width (inline style) and fades out in place over 150ms while the sliding grid column clips it — nothing reflows mid-slide. At settle the wide-only content (brand, labels, input, session tree) unmounts — dropping the sessions subscription and leaving the rendered and accessibility trees — and the control rows snap to the rail (open toggle, new session, new workspace, search, the same top-down order as their expanded rows) fading in as the slide ends. Each rail control keeps its expanded counterpart's behavior (the search icon expands the sidebar and focuses the search box after the slide), carries a tooltip, and the toggle rests as the whale mark with the panel icon on hover. The search query lives with the root and survives the round trip.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.zh.md b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.zh.md
index 7f6d6529a8..70ace36faf 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.zh.md
@@ -10,11 +10,11 @@ Status: implemented
 
 ## 决策
 
-布局将关闭的侧边栏（持久化宽度为 `0`）映射为固定的 `SIDEBAR_COLLAPSED` 宽度 56px：在侧边栏两侧各 16px 的水平内边距之间放置一列 24px 的图标控件。紧凑控制栏参与空间收缩求解，并保留右侧边框；已存储的展开宽度保持不变。
+布局将关闭的侧边栏（持久化宽度为 `0`）映射为固定的 `SIDEBAR_COLLAPSED` 宽度 56px：在侧边栏两侧各 16px 的水平内边距之间放置一列 24px 的图标控件。侧边栏轨道在求解器中是定宽的——无论展开还是折叠都不向视口压力让步（只有 details 会收缩、继而自动关闭）；控制栏保留右侧边框，已存储的展开宽度保持不变。
 
 `AppFrame` 根据持久化的宽度偏好标记侧边栏是否折叠，而不是根据求解后的轨道宽度来判断；折叠时移除尺寸调整手柄，并在渲染点把 `collapsed` 作为 owner props 传给侧边栏插槽。折叠与展开带动画：frame 对 `grid-template-columns`（以及余下手柄的 `left`）应用 deepsuite 侧栏曲线过渡——`--ds-ease-in-out` 配 `--ds-transition-duration-slow`，两个变量由 ui-theme 的 base 表提供；拖拽期间和 `prefers-reduced-motion` 下过渡暂停。
 
-`SidebarRoot` 读取 owner 的 `collapsed` 属性，原地 morph 而非切换渲染：四个控件行持续存在并演变为控制栏——展开开关、新建会话、新建工作区、搜索，自上而下与展开态各行顺序一致——几何（行高、内边距、外边距、胶囊边框）走同一条曲线动画，行为与展开态对应控件对齐（搜索图标会展开侧边栏并聚焦搜索框）。宽态专属内容（品牌标识、文字标签、输入框、会话树）以 200ms 交叉淡出，折叠动画期间保持挂载，300ms settle 后卸载——随之退订会话列表并离开渲染树与可访问性树。搜索关键词由根组件持有，折叠往返后保留。
+`SidebarRoot` 读取 owner 的 `collapsed` 属性，过渡是滑动 + 交叉淡变：展开内容以内联样式冻结在原宽度、150ms 原地淡出，滑动中的网格列裁切它——滑动途中不发生任何重排。settle 时宽态专属内容（品牌标识、文字标签、输入框、会话树）卸载——随之退订会话列表并离开渲染树与可访问性树——控件行落位到控制栏（打开开关、新建会话、新建工作区、搜索，自上而下与展开态各行顺序一致），随滑动结束淡入。每个控制栏控件保持与展开态对应控件一致的行为（搜索图标展开侧边栏并在滑动结束后聚焦搜索框）并带 tooltip；开关静止时显示鲸鱼标，悬停切换为面板图标。搜索关键词由根组件持有，折叠往返后保留。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.i18n.yaml
new file mode 100644
index 0000000000..49482469f1
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-demo-web-builds-client-bundles.md: a7d21987d4544246fd3c53864cedfc86279e9440
+2026-07-23-demo-web-builds-client-bundles.zh.md: f10184642b0c7869378802d3040ebf4dbe67d4e0
diff --git a/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.md b/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.md
new file mode 100644
index 0000000000..a7d21987d4
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.md
@@ -0,0 +1,27 @@
+# Agent Note: demo:web builds the client plugin bundles
+
+Status: implemented
+
+English | [中文](2026-07-23-demo-web-builds-client-bundles.zh.md)
+
+## Problem
+
+`dsh web` serves each web-client plugin's bundle from `GET /plugins/<id>/client.js`, resolving the path from the package's `exports["./client"]` (`lib/client.js`). Those bundles are produced only by the root `pnpm run build` (`tsc -b` then the per-package `tsdown.client.ts` configs); the Vite `build:web` step builds the frontend shell alone. `demo:web` and the README's Web UI instructions ran only `build:web`, so on a checkout without a prior full build every plugin bundle 404s, the client loader marks every plugin failed, and the boot screen shows "Failed to load plugins". The frontend shell built fine, hiding the missing artifact behind a runtime browser failure.
+
+## Decision
+
+`demo:web` runs `npm run build` before `npm run build:web`, so the plugin `lib/client.js` bundles exist before `dsh web` serves them. The README's Web UI section runs `pnpm run build && pnpm run build:web` for the installed `~/.dsh/source` checkout, which the installer never builds.
+
+## Verification
+
+After the full build, all eight `/plugins/<id>/client.js` endpoints return 200 and a headless Chromium load of `http://127.0.0.1:3080` renders the shell with no "Failed to load plugins" state.
+
+## Alternatives considered
+
+**Build the bundles inside `dsh web` at startup.** The app runs from source via tsx and owns no build step; folding an artifact build into the server boot crosses the source/artifact separation and slows every launch.
+
+**Widen the tsdown root config to emit client bundles from `pnpm run build:web`.** `build:web` is the Vite frontend build; the client bundles are a separate tsdown pass over `lib/types`. Merging the two conflates the shell build with the package build and still leaves the root `build` as the only producer.
+
+## Consequences
+
+`demo:web` now pays the full `tsc -b && tsdown` cost on every invocation instead of only the Vite build. That is the price of a runnable web demo from a clean tree; a caller who already built can invoke `dsh web` directly.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.zh.md b/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.zh.md
new file mode 100644
index 0000000000..f10184642b
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-23-demo-web-builds-client-bundles.zh.md
@@ -0,0 +1,27 @@
+# Agent Note: demo:web 构建客户端插件的打包产物
+
+Status: implemented
+
+[English](2026-07-23-demo-web-builds-client-bundles.md) | 中文
+
+## Problem
+
+`dsh web` 通过 `GET /plugins/<id>/client.js` 提供每个 web 客户端插件的打包产物，其路径由包的 `exports["./client"]`（`lib/client.js`）解析得到。这些打包产物只由根目录的 `pnpm run build`（先 `tsc -b`，再执行各包的 `tsdown.client.ts` 配置）生成；Vite 的 `build:web` 步骤只构建前端外壳。`demo:web` 与 README 的 Web UI 说明只运行了 `build:web`，因此在未预先完整构建的检出上，每个插件的打包产物都返回 404，客户端 loader 将所有插件标记为失败，启动界面显示 "Failed to load plugins"。前端外壳能正常构建，把缺失的产物掩藏在浏览器运行时的失败背后。
+
+## Decision
+
+`demo:web` 在 `npm run build:web` 之前先运行 `npm run build`，使插件的 `lib/client.js` 打包产物在 `dsh web` 提供它们之前已经存在。README 的 Web UI 小节针对已安装的 `~/.dsh/source` 检出运行 `pnpm run build && pnpm run build:web`，因为安装器从不构建它。
+
+## Verification
+
+完整构建后，全部八个 `/plugins/<id>/client.js` 端点均返回 200，无头 Chromium 加载 `http://127.0.0.1:3080` 能渲染出外壳，不再出现 "Failed to load plugins" 状态。
+
+## Alternatives considered
+
+**在 `dsh web` 启动时构建打包产物。** 该应用通过 tsx 从源码运行，本身没有构建步骤；把产物构建塞进服务器启动流程会越过源码与产物的分离，并拖慢每次启动。
+
+**扩大 tsdown 根配置，使 `pnpm run build:web` 也产出客户端打包产物。** `build:web` 是 Vite 前端构建；客户端打包产物是对 `lib/types` 的另一趟独立 tsdown 处理。把两者合并会混淆外壳构建与包构建，而且根目录的 `build` 仍是唯一的产出者。
+
+## Consequences
+
+`demo:web` 现在每次调用都要付出完整的 `tsc -b && tsdown` 代价，而不再只是 Vite 构建。这是从干净的代码树运行 web 演示所要付出的代价；已经完成构建的调用方可以直接调用 `dsh web`。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.i18n.yaml
new file mode 100644
index 0000000000..cae5b75cb4
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-24-recursive-python-sdk-session-notifications.md: c90213659391b565acd043a1be64e225f8babd31
+2026-07-24-recursive-python-sdk-session-notifications.zh.md: 214a5ef924dcc9da3a97aab6385837acd2b364d9
diff --git a/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.md b/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.md
new file mode 100644
index 0000000000..c902136593
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.md
@@ -0,0 +1,29 @@
+# Agent Note: Recursive Python SDK session notifications
+
+Status: implemented
+
+English | [中文](2026-07-24-recursive-python-sdk-session-notifications.zh.md)
+
+## Problem
+
+The Python SDK filtered turn notifications by comparing each payload directly with the root session id. This admitted a direct child's lifecycle because its parent id named the root, but rejected a grandchild's lifecycle and every descendant `session.event`. The JSON-RPC server still emitted those notifications, so they accumulated on the low-level global queue while high-level consumers lost nested trajectory relationships and completion states.
+
+## Decision
+
+`HarnessClient` records every valid `subagent.started` child-to-parent edge before dispatching the notification. A later `subagent.finished` routes by its immutable parent id but never rewrites current ancestry, so an older run that settles after its child id has been reused cannot displace the replacement session. Other session notifications resolve their session id by walking that client-lifetime ancestry graph to the requested root. The graph survives successive subscriptions so a descendant that outlives one `Session.run()` remains attributable when it emits during a later turn, and it resets when the client starts a new runtime process.
+
+`Session.run()` delivers the complete discovered session-tree notification stream through `TurnResult.notifications` and `on_notification`. Only `session.event` notifications whose `sessionId` equals the requested root enter `TurnResult.events` or final-response reconstruction. Descendant events are therefore observable without allowing a child response to replace the root response.
+
+## Alternatives considered
+
+**Add a root session id to every JSON-RPC notification.** The server already provides exact immediate-parent edges, and duplicating transitive ancestry on the wire would make every producer responsible for client subscription state.
+
+**Limit subagents to one level.** A deployment can set `maxDepth: 1`, but changing the SDK to depend on that policy would silently misreport valid recursive compositions.
+
+**Subscribe only to descendant lifecycle notifications.** This would repair relation and completion reporting, but descendant session events would continue accumulating on the global queue and callbacks would expose an incomplete tree.
+
+**Expose and index every subagent run id on the JSON-RPC wire.** Exact run identity is useful when a client must correlate two concurrent outcomes for the same child, but session-tree routing already has the authoritative start edge and each terminal notification's immutable parent. Expanding the protocol is unnecessary for this ownership decision.
+
+## Consequences
+
+High-level consumers receive nested lifecycle and session notifications in wire order while root turn results preserve their prior response semantics. The client retains one current parent entry per observed child until the runtime restarts; ancestry lookup is cycle-safe, and unrelated session notifications remain available through the global queue. Keyless Python tests cover two-level delegation, root-response isolation, absence of tree-notification queue buildup, ancestry reuse across subscriptions, and reused child ids whose older runs settle out of order.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.zh.md b/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.zh.md
new file mode 100644
index 0000000000..214a5ef924
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: Python SDK 递归会话通知
+
+Status: implemented
+
+[English](2026-07-24-recursive-python-sdk-session-notifications.md) | 中文
+
+## 问题
+
+Python SDK 过去通过将每条通知的 payload 与根会话 ID 直接比较来过滤轮次通知。直接子 agent 的生命周期通知因 parent ID 指向根会话而能够通过，但孙级生命周期通知与所有后代 `session.event` 都会被拒绝。JSON-RPC 服务器仍会发出这些通知，因此它们会堆积在底层全局队列中，而高层消费者会丢失嵌套轨迹的关系与结束状态。
+
+## 决策
+
+`HarnessClient` 会在分发通知前，记录每条有效 `subagent.started` 所包含的 child-to-parent（子到父）关系。后续的 `subagent.finished` 会依据自身不可变的 parent ID 路由，但不会改写当前祖先关系，因此旧 run 即使在其 child ID 已被复用后才结束，也无法覆盖替代它的新会话。其他会话通知会沿客户端生命周期内保存的祖先关系图回溯自身 session ID，判断它们是否属于请求的根会话。该关系图会跨连续订阅保留，因此某个后代即使跨过一次 `Session.run()`，在后续轮次中发出通知时仍能正确归属；客户端启动新的运行时进程时会重置关系图。
+
+`Session.run()` 通过 `TurnResult.notifications` 与 `on_notification` 提供已发现会话树的完整通知流。只有 `sessionId` 等于请求根会话的 `session.event` 才会进入 `TurnResult.events` 或参与最终回复重建。因此调用方能够观察后代事件，同时子会话回复不会覆盖根会话回复。
+
+## 考虑过的替代方案
+
+**在每条 JSON-RPC 通知中加入根会话 ID。** 服务器已经提供精确的直接父子关系；在线路协议中重复传递祖先关系，会迫使每个生产者承担客户端订阅状态的职责。
+
+**把 subagent 限制为一层。** 部署可以设置 `maxDepth: 1`，但让 SDK 依赖该策略，会对合法的递归组合产生静默误报。
+
+**只订阅后代生命周期通知。** 这可以修复关系与结束状态的上报，但后代会话事件仍会堆积在全局队列中，回调看到的会话树也不完整。
+
+**在 JSON-RPC 线路上公开并索引每个 subagent run ID。** 当客户端必须关联同一 child 的两个并发结果时，精确 run 身份很有价值；但会话树路由已经拥有权威 start 关系和每条终止通知中不可变的 parent。没有必要为这一归属决策扩展协议。
+
+## 后果
+
+高层消费者会按线上的原始顺序收到嵌套生命周期与会话通知，同时根轮次结果保持原有回复语义。客户端会为每个已观察到的子会话保留一条当前父关系，直到运行时重启；祖先回溯能够安全处理环，无关会话通知仍可从全局队列获取。无密钥 Python 测试覆盖两层派生、根回复隔离、会话树通知不堆积、跨订阅复用祖先关系，以及旧 run 乱序结束的复用 child ID。
diff --git a/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.i18n.yaml b/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.i18n.yaml
new file mode 100644
index 0000000000..a3a3e3b72f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-14-acp-agent-client-protocol.md: c6976ed28a254684fca62e2d309cdde7ea90340d
+2026-06-14-acp-agent-client-protocol.zh.md: 6bd234f2aa3f43f4fc6cbd921161253c46aab73e
diff --git a/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.md b/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.md
index 7c47fc78e9..c6976ed28a 100644
--- a/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.md
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-14-acp-agent-client-protocol.zh.md)
+
 ## Problem
 
 The harness originally exposed agents only through a readline loop. That surface could carry text, but it gave an editor no structured way to create or resume sessions, correlate prompt completion, stream reasoning and tool activity, render tool-specific UI, ask for permission, or cancel one conversation without disturbing another. ACP defines those interactions as JSON-RPC over stdio, and Zed is the target client used to make concrete compatibility decisions.
diff --git a/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.zh.md b/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.zh.md
new file mode 100644
index 0000000000..6bd234f2aa
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.zh.md
@@ -0,0 +1,59 @@
+# Agent Note: Agent Client Protocol（ACP）支持——从外部编辑器驱动编码 agent
+
+Status: implemented
+
+[English](2026-06-14-acp-agent-client-protocol.md) | 中文
+
+## 问题
+
+harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本，但编辑器无法以结构化方式创建或恢复会话、关联提示词完成、流式输出推理（reasoning）与工具活动、渲染工具专属 UI、请求权限，或在不干扰其他对话的前提下取消某个对话。ACP（Agent Client Protocol）将这些交互定义为基于 stdio 的 JSON-RPC，Zed 是用于做出具体兼容性决策的目标客户端。
+
+桥接层必须保持 harness 既有的所有权边界。它不能依赖具体的 agent loop（智能体循环），不能绕过工具注册表，不能在编辑器中执行 shell 命令，也不能发明第二个会话真源。stdout 同时也是协议传输通道，因此任何意外的日志输出都会破坏连接。
+
+## 决策
+
+`@deepseek-ai/dsh-acp` 是位于 `packages/ui/acp` 的 UI/客户端驱动插件。它使用 `@agentclientprotocol/sdk` 的 `AgentSideConnection`（基于 stdin/stdout），仅编排接口服务：agent 创建/恢复工厂、会话持久化、工具注册表、用户交互，以及可选的审批/bash 能力。它不修改 agent loop，也不是能力 seam 的实现。
+
+桥接层实现以下稳定的会话路径：
+
+- `initialize` 协商协议版本，声明支持 text 与 `resource_link` 类型的提示词，并声明 `loadSession` 能力。
+- `session/new` 校验绝对路径 `cwd`，将其存入 `SessionHeader`，通过 `ctx.agents` 创建 agent，并返回由组合层支持的配置选项。
+- `session/load` 在构造 agent 之前校验请求的 cwd 与持久化元数据是否一致，在异步恢复期间保留 id，将用户/助手/工具事件作为 ACP update 回放，并报告恢复后的 config-option 折叠结果。
+- `session/prompt` 接受文本和 resource link，拒绝不支持的或空的内容，每个会话同时只允许一个 in-flight 提示词，并在该提示词所属的 `turn/end` 时结算。错误轮次拒绝 RPC；其他关闭轮次的原因通过一个全覆盖的 ACP stop-reason 编解码器映射。
+- `session/cancel` 调用队列感知的 agent 取消路径，仅结算被寻址会话的提示词。
+
+工具调用的展示仍由工具自身负责。工具的 `presentCall` 和 `presentResult` 返回 `generic`、`terminal` 或 `diff` 渲染意图变体；桥接层对该联合类型做 switch 并映射到 ACP。没有 presenter 的工具获得通用回退。Bash 终端卡片使用 Zed 的能力门控约定 `_meta.terminal_info`、`_meta.terminal_output` 和 `_meta.terminal_exit`；harness 仍通过 `ctx.bash` 执行命令，保留沙箱、环境清洗、所有权和 cwd。不支持该扩展的客户端收到普通文本内容。文件系统工具提供 diff 卡片和文件位置，桥接层中无需硬编码工具名分支。
+
+权限处理是[用户审批 seam](2026-07-06-approval-seam.md)上的一个 answerer，而非 ACP 中的「每次工具调用都询问」策略。对桥接层所属 agent 且带有 call id 的 `approval/request`，会变为该 agent 编辑器会话上的 `session/request_permission`，提供一次性允许/拒绝选项。外部请求或无 call id 的请求委托给下游；缺失或失败的 answerer 会在故障时保持拒绝。发起询问的插件（如预执行策略或 bash 升级）拥有「是否询问」的决策权。
+
+当 `ctx.permission` 被组合时，桥接层从部署的预设表中暴露一个 `permission` select。已发布的 `workspace-write` 和 `danger-full-access` 预设各自捆绑一个沙箱模式与一条审批策略；无法匹配的有效旋钮组合产生只能切走的 `custom` 状态。`session/set_config_option` 通过 `PermissionService.set()` 校验并写入两个所属旋钮事件。在开放轮次中的切换立即追加；空闲时的切换叠加在响应中，并在下一次 `agent/prompt-submit` 时锚定到开放轮次之前的请求组装阶段。在此之前它仅存于内存，因此崩溃后恢复的是持久化的折叠结果。ACP session mode 不被建模，因为 config option 是面向未来的协议表面；`AcpConfig.model` 保持连接级别。
+
+桥接层还提供基于 ACP 的 `UserInteractionProvider`：`ask_user_question` 请求变为所属会话上的表单引导。select、multi-select、选项描述与自定义回答覆盖语义均被保留。
+
+生命周期所有权是显式的。桥接层为每个活跃会话持有一个 `AgentHandle`。断连和 Cordis dispose（资源释放）会取消待处理的提示词，并行 dispose 所有 handle，等待循环完全停稳与持久化刷写，然后移除记录。流通知失败被隔离，因此消失的客户端不会破坏 agent 轮次。ACP 应用组合不加载 stdout logger；一个测试守卫 stdout 仅包含帧化的 JSON-RPC。
+
+精确的已支持与已推迟的协议行列表见 [`packages/ui/acp/acp-feature-support.md`](../../../../packages/ui/acp/acp-feature-support.md)；包 README 是操作契约。
+
+## 曾考虑的替代方案
+
+**在 `tools/execute` 监听器前置一层，对每个 ACP 所属调用都询问权限**：否决。这会将权限策略硬编码到 UI 桥接层，即使没有策略要求也会询问，且无法服务于执行开始后才产生的审批请求。共享的 user-approval seam 将机制、询问策略和 UI answerer 分离。
+
+**注入具体的 `agentLoop`**：否决。agent 的创建、恢复、空闲观察与释放是 `dsh-agent` 上的接口级所有权操作；UI 插件不需要依赖规则例外。
+
+**通过 ACP `terminal/*` 执行 bash**：否决。这会将执行移到 harness 之外，绕过其沙箱、凭证清洗、任务所有权、cwd 解析与会话日志。终端元数据仅用于展示。
+
+**将权限预设表示为 ACP session mode**：否决。部署定义的预设已经是一个 config-option select，而 session mode 是 ACP v2 计划移除的遗留接口。
+
+**防御性劫持 stdout**：否决。进程级 monkey-patching 超出 Cordis 副作用所有权范围，且与协议传输存在竞争。应用组合拥有 stdout 纯净性。
+
+## 后果
+
+编辑器可以通过一条 ACP 连接创建、加载、提交提示词、取消、渲染、询问和重新配置多个 harness 会话，无需依赖特定的循环实现。会话事件日志仍是回放、提示词结算、cwd 与每会话配置的持久真源。工具展示与人工回答通道仍是可扩展的插件契约，而非 ACP 专属行为。
+
+桥接层有意不实现会话列表/删除/恢复/关闭能力、MCP 透传、附加目录、图片/音频/嵌入资源提示词、plan、斜杠命令、用量更新、编辑器文件系统委托或 ACP 终端执行子协议。后续已通过标准会话配置选项加入运行时模型选择，见 [LLM 目录与 ACP 选择 Agent Note](../architecture/2026-07-15-llm-model-catalog-and-acp-selection.md)。
+
+空闲时的配置选择在实时响应中是真实的，但在下一次 `agent/prompt-submit` 将其锚定到开放轮次之前不具持久性。在该边界之前崩溃会丢失待定选择；这是保持会话事件封闭于轮次内且回放安全的代价。
+
+## 验证
+
+ACP 测试套件覆盖内存协议编解码器、创建/加载回放、精确的提示词结算、取消竞争、不支持的内容、工具展示、终端能力回退、权限结果映射、config-option 校验与持久化、多会话隔离、断连/释放后的完全停稳，以及 HMR（热模块替换）清理。快照测试与 built-bin 测试验证应用组合，真实 API 的 e2e 测试在无 key 时自动跳过。
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
new file mode 100644
index 0000000000..4969861f15
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-14-acp-multi-session.md: 43aa32a43fef7aa69f5efd45d4c8176da9f459cd
+2026-06-14-acp-multi-session.zh.md: 6835f9623b89dc20d6c7b3054365cd9c39402aeb
diff --git a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.md b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.md
index 91d85aeded..43aa32a43f 100644
--- a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.md
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-14-acp-multi-session.zh.md)
+
 ## Problem
 
 An ACP editor can keep several conversations alive over one agent subprocess. A single-active-session bridge would force extra processes and would not match Zed's client model, which tracks multiple session ids and concurrent loads. Multiplexing introduces isolation risks: events, prompt completion, cancellation, permission prompts, config selections, and predictable background-task ids must never cross session boundaries.
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
new file mode 100644
index 0000000000..6835f9623b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md
@@ -0,0 +1,47 @@
+# Agent Note: 在单个连接上多路复用并发 ACP 会话
+
+Status: implemented
+
+[English](2026-06-14-acp-multi-session.md) | 中文
+
+## 问题
+
+一个 ACP（Agent Client Protocol）编辑器可以在同一个 agent（智能体）子进程上保持多个对话。如果桥接层只支持单活跃会话，就不得不启动额外进程，也无法匹配 Zed 的客户端模型——该模型跟踪多个会话 id 和并发加载。多路复用引入了隔离风险：事件、提示词完成、取消、权限提示、配置选择以及可预测的后台 task id 绝不能跨越会话边界。
+
+## 决策
+
+ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agent 作用域的回调使用 `ownedRecord`：在正向 map 中查找 `agent.session.id`，且仅当该记录拥有精确的 agent 对象时才接纳它，使外部的同 id 对象无法冒领会话。一条记录拥有其 agent 句柄、进行中的提示词、活跃的工具调用展示状态、待处理的空闲配置切换、会话 cwd 以及客户端能力快照。一个独立的 loading-id 集合在异步恢复之前预留每个 id，使两个流水线化的加载请求无法构造出重复的 agent；不同 id 可以并发加载。
+
+每个 `session/event` 和 `agent/status` 回调在发送或结算任何内容之前，先解析出所属记录。每个会话独立允许一个进行中的提示词。提示词记录一个日志水位线，捕获自己的 `turn/start`，并仅在匹配的 `turn/end` 到达时结算；来自已取消的前一轮次的迟到 end 不能 resolve 更新的提示词。`session/cancel` 定位到一条记录，只调用该 agent 的队列感知取消路径。
+
+权限归属使用对正向 map 的同一精确 agent 检查。ACP `approval/request` 应答器只向拥有发起请求的 agent 的编辑器会话发起提示，并将外部请求委托出去。用户交互引出同样按 agent 归属路由。每会话的沙箱和审批配置值只折叠该会话自身的事件，待处理的空闲切换存储在该记录上，直到下一轮次将其锚定。
+
+后台 bash 任务携带一个不透明的 owner token，其值等于所属会话 id。`bash_output` 和 `bash_kill` 在读取或终止之前，将调用方的 token 与执行器的任务归属进行比较；仅凭可预测的 task id 不能获得访问权。归属信息与执行器任务一起存储，因此工具插件重载不会擦除它。
+
+连接拆除时清空活跃 map，将每个待处理的提示词以取消状态结算，并并行 dispose（资源释放）所有 `AgentHandle`。每个句柄停止并等待其循环完成、在仍然附着时刷新会话、注销 agent 并移除会话。拆除操作被 memoize 化，由客户端断连和插件 dispose 共享。
+
+## 协议与工作区作用域
+
+[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)。[Zed 仅在 agent 公布该能力时发送其余项目工作目录](https://github.com/zed-industries/zed/blob/ea77ca2818f3e059a2b61ecc7e63b67e01e1cec5/crates/agent_servers/src/acp.rs#L1139-L1145)，否则会[从会话请求中丢弃这些目录](https://github.com/zed-industries/zed/blob/ea77ca2818f3e059a2b61ecc7e63b67e01e1cec5/crates/agent_servers/src/acp.rs#L1454-L1472)。如其[已知限制](../../../../packages/ui/acp/README.md#known-limitations-and-deferred-work)所记录，桥不公布该能力，并拒绝非空值，因此当前 Zed 多根项目到达桥时只携带第一个工作目录。
+
+[标准传输是每个 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`；它只是从已经支持的「每会话一个主根目录」路径中移除了进程级根目录限制。
+
+## 曾考虑的替代方案
+
+**每连接单活跃会话**：否决。增加进程开销，与目标客户端的多会话形态相矛盾，且并未消除编辑器端的多路复用需求。
+
+**每会话 `ctx.extend()`**：否决。子上下文本身不会创建子插件 fiber，因此监听器仍属于桥接层 fiber。实际实现的桥接层使用全局监听器加显式 O(1) 解复用，以及每会话拥有的记录；agent 生命周期由 `AgentHandle` 管理。
+
+**以 Agent 对象标识作为 bash 任务归属**：否决。恢复或替换后的 agent 对象可能合法地代表同一个持久会话。不透明的会话 token 才是跨边界的标识，应当在插件重载后仍然存活。
+
+## 后果
+
+N 个会话可以并发地进行流式输出、提示词、权限请求、配置切换和后台任务运行，而不会交错或跨会话结算。一个会话中的取消或 dispose 不影响相邻会话。桥接层为此付出了显式 map 和隔离测试的代价，但它不会为每个会话添加一组监听器，从而避免了长连接期间的监听器扇出。
+
+桥接层目前仍未暴露独立关闭单个活跃会话的协议方法。当前所有记录在连接拆除时一起离开；会话关闭/恢复的生命周期能力在 ACP 功能清单中仍处于延期状态。
+
+## 验证
+
+多会话测试套件通过交错更新、独立的进行中提示词、定向取消、相同 id 与不同 id 的加载竞争、权限路由、配置隔离以及拆除来驱动并发会话。工具 bash 测试证明一个会话无法读取或终止另一个会话的后台任务。
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
new file mode 100644
index 0000000000..9375a02315
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-15-code-mode.md: 94a95ba2c5760c0fed6ebfe09330546f401c42c4
+2026-06-15-code-mode.zh.md: 0ba5d69258bce23a24db9a0b470ddb074840cba7
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 329eaf2d0a..94a95ba2c5 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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.
@@ -20,6 +22,8 @@ Three decisions, each elaborated in its own section below:
 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.
 
+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.
+
 ### The registry owns the mode
 
 `ToolRegistry` gains a schemastery-validated config (`static Config`), its first: `mode: 'native' | 'code' | 'both'`, default `'native'`. A deployment flips it from `cordis.yml` (`tools: { mode: code }`) — no code edit, per the no-hardcoded-tunables convention.
@@ -36,17 +40,17 @@ Three decisions, each elaborated in its own section below:
 
 ### The run_code tool and the dispatch bridge
 
-Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentation transport with one required parameter, `{ code: string }`. It is represented by a normal `ToolDefinition` for dispatch but stays outside the filterable capability layers, so restrictions cannot accidentally remove Code Mode's only entry point. Calls traverse the complete tool pipeline — `tools/pre-execute` → monotonic guards → `tools/execute` around dispatch → `tools/post-execute` → immutable `tools/result` notification — exactly like native calls; a permission plugin can inspect the program text before it runs, and final-result observers see the normalized outer outcome. Its `execute(args, exec)`:
+Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentation transport with one required parameter, `{ code: string }`. It is represented by a normal `ToolDefinition` for dispatch but stays outside the filterable capability layers, so restrictions cannot accidentally remove Code Mode's only entry point. Calls traverse the complete tool pipeline — `tools/pre-execute` → monotonic guards → `tools/execute` around dispatch → `tools/post-execute` → optional definition-owned `finalizeContent` → immutable `tools/result` notification — exactly like native calls; a permission plugin can inspect the program text before it runs, and final-result observers see the normalized outer outcome. Its `execute(args, exec)`:
 
-1. **Build bindings.** One run-scoped signal follows outer cancellation and is aborted whenever the run settles. Each visible tool binding JSON-normalizes its arguments—rejecting lossy values before dispatch—waits on the serialization queue, executes with a deterministic call id and the outer token as `parent`, defers returned contexts through the outer execution, and logs `tool/code-dispatch`. Successful text becomes a string and non-text blocks become placeholders; tool errors reject the binding promise. Every sub-call retains its own immutable execution identity and traverses the full tool pipeline.
+1. **Build bindings.** One run-scoped signal follows outer cancellation and is aborted whenever the run settles. Each visible tool binding snapshots lossless-JSON arguments, waits on the serialization queue, executes with a deterministic call id and the outer token as `parent`, defers returned contexts through the outer execution, and logs `tool/code-dispatch`. Success returns the tool's final canonical JSON value; failure becomes the program-visible `ToolCallError`. Every sub-call retains its own immutable execution identity and traverses the full tool pipeline.
 2. **Runs the program**: `ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`. The runtime receives the run-scoped signal, not only the caller's outer signal, so any way the outer run settles also aborts work inside the runtime.
-3. **Settle after quiescence.** When the runtime settles, the bridge aborts outstanding work and drains the dispatch queue before returning. Success returns captured output and presentation metadata. A runtime failure becomes `CodeRunFailedError`; backend rejection uses the registry's normal error boundary. Both produce structured error results, and no sub-call can append after `run_code` settles.
+3. **Settle after quiescence.** When the runtime settles, the bridge aborts outstanding work and drains the dispatch queue before returning. Success returns captured logs and the completion value as canonical output; the registry renders that value into durable `tool/result.content`, which the result card reads directly. A runtime failure becomes `CodeRunFailedError`; backend rejection uses the registry's normal error boundary. Both produce structured error results, and no sub-call can append after `run_code` settles.
 
 **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.
 
-**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` → a `generic` card, `kind: 'execute'`, title = the program text, `rawInput` = the same program text; `presentResult` → a `generic` card whose content is the captured output (from `meta`). The program is the title because ACP execute cards reliably render that field while some clients omit body and raw-input content. This is not a `terminal` card: that card's semantics are "a shell command in a working directory", which a program is not.
+**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 ACP and TUI 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. The program is the title because ACP execute cards reliably render that field while some clients omit body and raw-input content. 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](../bug-fix/2026-07-20-code-mode-result-card-completeness.md).
 
 ### Observability: `tool/code-dispatch`
 
@@ -57,10 +61,9 @@ Each sub-dispatch appends a log-only `tool/code-dispatch` event containing paren
 `packages/code-runtime/code-runtime/` — `@deepseek-ai/dsh-code-runtime`, depending only on `cordis`. An abstract `CodeRuntime extends Service` (`super(ctx, 'codeRuntime')`) plus the vocabulary:
 
 - `CodeRunRequest = { program: string; bindings: CodeBindingNamespace[]; signal?: AbortSignal }`
-- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<unknown>> }` — the runtime exposes each namespace as a global object of async functions inside the program; binding arguments and resolutions must be structured-cloneable (a runtime may cross a serialization boundary; ours does).
-- `CodeRunResult = { value?: unknown; logs: CodeLogEntry[]; error?: CodeRunFailure }` — program execution outcomes, including exception, timeout, abort, and worker exit, 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.
-- `CodeLogEntry = { source: 'console' | 'stdout' | 'stderr'; level?: 'log' | 'info' | 'warn' | 'error' | 'debug'; text: string }`
-- `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit'; 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.
+- `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).
 
 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.
@@ -71,9 +74,9 @@ Requests contain every runtime input; implementations own validated timeout and
 
 1. **Type-strip host-side** with Node's built-in `stripTypeScriptTypes` (`node:module`; present across the repo's whole engines range, `^22.19.0 || >=24.0.0`, and position-preserving, so runtime error line numbers match the model's source). Strip-only mode rejects non-erasable syntax (`enum`, namespaces) — that rejection returns as `error.kind: 'exception'` with Node's message, the SDK instructions say "erasable TypeScript only", and the model self-corrects like any other program error. A syntax-level failure never spawns a worker.
 2. **Spawn one fresh `Worker` per run** from the package's own bootstrap module: `env: {}` (truly empty — stronger than the scrubbed-env rule for spawned commands), `resourceLimits` from config, `stdout`/`stderr` captured into `logs` rather than inherited. No pooling and no cross-run state: a program's world dies with its worker, which keeps runs reconstructable from the log alone and makes state bleed unrepresentable.
-3. **Execute** in the bootstrap: the stripped program becomes the body of an `AsyncFunction` whose parameters are the binding globals and a capturing `console` shim, so top-level `await` and `return` work and the program's completion value is the run's `value` (structured-cloneable values cross as-is; anything else is replaced by its `util.inspect` rendering, documented).
+3. **Execute** in the bootstrap: the stripped program becomes the body of an `AsyncFunction` whose parameters are the binding globals, any consumer-declared rejection classes, and a capturing `console` shim, so top-level `await` and `return` work. Code Mode declares `ToolCallError` with member property `toolName`; the runtime materializes that real constructor without hardcoding tools. A lossless JSON completion crosses exactly; `undefined` remains absence, a lossy value is `invalid-output`, and an oversized outer result is `output-limit` rather than an inspected-string substitute.
 4. **Bridge bindings over the message port**: each binding function in the worker posts `{ id, global, name, args }` and awaits the reply; the host validates the name against the request's bindings, invokes, and replies `{ id, ok, value }` or `{ id, ok: false, message }` (a host-side binding rejection becomes a program-side rejection). The worker-side namespace objects are built null-prototype via `defineProperty`, so a binding named `__proto__`, `constructor`, or `toString` is an ordinary own property, not a prototype collision. Unknown names, duplicate ids, and post-settlement messages are rejected or ignored — the port protocol assumes a hostile peer, because the peer runs model code.
-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. Expiry, cancellation, and completion terminate the worker. Heap exits and truncation are reported explicitly; compute, wall, heap, log, and return-value caps are validated configuration.
+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).
 
 ### Trust posture
@@ -90,7 +93,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Testing
 
-- **Worker runtime:** Real-worker tests cover output and value capture, failure kinds, compute and wall budgets, hostile binding traffic, empty environment, structured-clone fallback, output caps, and disposal to quiescence. A built-package test runs the worker entry under plain Node.
+- **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.
@@ -123,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`.
 
-**Structured-clone values can exceed JSON.** Tool bindings therefore JSON-normalize arguments before dispatch, ensuring every executed call can be logged. The lower-level runtime keeps its wider port contract, while stricter consumers validate at their boundary. Non-text sub-results become placeholders.
+**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
new file mode 100644
index 0000000000..0ba5d69258
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -0,0 +1,133 @@
+# Agent Note: Code Mode——模型针对工具注册表编写 TypeScript
+
+Status: implemented
+
+[English](2026-06-15-code-mode.md) | 中文
+
+## 问题
+
+在注册表的原生呈现方式下，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 开销大且串行。模型无法组合工具——遍历结果集、根据中间值分支、扇出、后处理——每次调用都需要一次完整的模型往返，而每次往返都会把完整的中间结果拖回上下文，不管模型是否需要。
+
+Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一种替代方案，基于一个简单的观察：LLM（大语言模型）编写代码的能力优于发出工具调用，因为它们见过数百万行真实代码，而人为构造的工具调用 trace 相对很少。模型不再每步发出一次工具调用，而是针对工具生成的 API 编写一段 TypeScript 程序，程序在沙箱运行时中执行，模型只策展返回的内容——仅限它 print 或 return 的部分——而非所有中间结果。
+
+工具呈现属于掌管工具可见性的注册表：如果把第二种呈现方式实现为事后的 waterfall（瀑布式事件）变换，正确性将依赖监听器顺序，并与[可重建请求](../architecture/2026-07-05-reconstructable-requests.md)冲突。执行基底同样属于基础设施而非占位实现：Node `worker_threads` 提供独立 isolate、空环境、堆上限以及对热同步循环的终止能力，同时契合 harness 既有的信任模型（§信任姿态）。
+
+## 决策
+
+三项决策，各自在下方独立小节中展开：
+
+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 命令。
+
+本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
+
+### 注册表拥有模式
+
+`ToolRegistry` 获得一个经 schemastery 校验的配置（`static Config`），这是它的第一个配置：`mode: 'native' | 'code' | 'both'`，默认 `'native'`。部署通过 `cordis.yml` 翻转模式（`tools: { mode: code }`），无需改代码，遵循 no-hardcoded-tunables 约定。
+
+**协议工具列表。** 注册表在 `'native'` 下贡献可见能力，在 `'code'` 下仅贡献 `run_code`，在 `'both'` 下两者都贡献。最终的 `PromptAssembly.tools` 列表记录在请求头中。`run_code` 是一个保留的呈现传输通道，位于注册和限制层之外；直接提示词提供方和组装 waterfall 仍各自负责自己的贡献。
+
+**与 `toolOrder` 的交互，预先说明：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
+
+**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 会覆盖有意的组合。
+
+**代码生成。** `jsonSchemaToTs()` 将 `defineTool` 的 JSON Schema 子集映射为 TypeScript，将 schema 描述带入 JSDoc，不支持的构造降级为 `unknown`。SDK 将工具暴露为带引号的对象键，支持任意名称而无需别名或冲突处理。类型是建议性的，因为运行时在执行前会剥离类型。
+
+### run_code 工具与分发桥
+
+在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带一个必需参数 `{ code: string }`。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
+
+1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，等待序列化队列，以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `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` 结算后不允许子调用追加。
+
+**子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute 阻止会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
+
+**并发被序列化。** 每次 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`，因此 ACP 和 TUI 会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。程序作为标题是因为 ACP execute 卡片可靠地渲染该字段，而某些客户端会省略 body 和 raw-input 内容。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
+
+### 可观测性：`tool/code-dispatch`
+
+每次子分发追加一个仅日志的 `tool/code-dispatch` 事件，包含父子 call id、工具标识、规范化参数和结果摘要。它不进入模型历史，但可供持久化和 UI 使用。追加发生在开放的 `run_code` 轮次内。没有 agent 的直接执行仍然运行，但无法记录该事件。
+
+### code-runtime seam
+
+`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 类型，因此绑定参数与解析值可以完整跨越实现的序列化边界。
+- `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`）。
+
+请求包含所有运行时输入；实现方拥有经校验的超时和上限默认值。注册表仅在组装 Code Mode 时查找可选的运行时，因此 native 模式不依赖它。缺失或语言不兼容的运行时会大声失败。替代基底或语言可以在同一 seam 背后替换实现，配对相应的 SDK 生成器。
+
+### worker-thread 运行时
+
+`@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。
+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)。
+
+### 信任姿态
+
+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'` 下，但对提供方缓存保持稳定。
+
+## 后果
+
+切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发保持序列化，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
+
+## 测试
+
+- **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 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
+
+## 曾考虑的替代方案
+
+**一个零核心改动的附加消费方插件。** 否决，因为 `agent/request` 在[可重建请求](../architecture/2026-07-05-reconstructable-requests.md)下仅限 call-config，而变换已组装的工具列表需要在不拥有其配置的情况下撤销 `toolOrder` 规范化，并依赖监听器顺序。向模型提供哪些工具、以何种表示形式提供，是注册表的单一关注点：原生 schema 和 SDK 是同一个可见存储的两种投影。
+
+**`node:vm` 作为参考运行时，加固推迟。** 否决：`node:vm` 不是隔离（原型链逃逸可达宿主 realm）且无法中断热循环。worker 线程提供独立 isolate、空环境、`resourceLimits` 和可靠的 `terminate()`，信任等级等同于 bash，因此参考实现和生产实现是同一个包，无需 unsafe-acknowledgement 仪式。
+
+**在原生工具调用上做结果省略/摘要。** 仅解决问题的上下文膨胀一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
+
+**循环中的并行原生分发。** 往返成本的另一个答案；仍是有效的未来工作（open TODO），仍被并发安全元数据阻塞，且仍无组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的序列化队列决策保持两者兼容：当元数据就绪时，原生并行分发和每工具绑定并行化一起解锁。
+
+**始终排他（忠于 Cloudflare，无模式）。** 否决，因为本 SDK 的主要消费方是编码 agent：其日常的单次调用（`bash`、`read`、`edit`）作为原生调用已经是最优的，强制每次编辑都通过程序会给常见场景增加负担。mode 配置让忠实形式（`'code'`）只需一行配置即可启用，而不强加于人。
+
+**每工具可见性分层（此工具 native，彼工具 code-only）。** 推迟：它需要每工具元数据和 `'native' | 'code' | 'both'` 不提供的呈现拆分，且其设计取决于模型在 `'both'` 下如何分配使用的证据。
+
+**SDK 中的清洁化标识符别名**（`my-tool` → `my_tool`，Cloudflare 的做法）。否决：`declare const` 上的带引号键使每个名称可达，零别名碰撞逻辑；模型能正常处理 `tools["my-tool"](…)`。
+
+**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 全新保持了这一点。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
+
+## 风险
+
+**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` 之后。
+
+**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
+
+**仅序列化的子分发。** `Promise.all` 尚未获得挂钟并行性，仅减少往返次数；模型可能过度期望。说明中已声明；解除此限制与原生并行分发 TODO 所需的并发安全元数据绑定。
+
+**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）对恶意程序是承重的。两侧都有单元测试（带 pending 诱饵分发的热循环在 `computeMs` 处死亡；在慢绑定上空闲的程序存活到 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。
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
new file mode 100644
index 0000000000..60a0b50006
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-17-filesystem-tool-schemas.md: 9941b3916b361a916c8148eb099eb8cfd46371c8
+2026-06-17-filesystem-tool-schemas.zh.md: 47e43c47db83b1fcc292b17cf0113d9abd9293d1
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 a318956ddf..9941b3916b 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-17-filesystem-tool-schemas.zh.md)
+
 ## Problem
 
 [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`.
@@ -68,7 +70,7 @@ The first pass rejects Codex-style patch grammars and multi-mode edit APIs. It u
 
 ## Result shape
 
-The first implementation returns `ContentBlock[]` through the existing `ToolDefinition.execute()` contract. `ctx.fs` returns structured filesystem results and owns file-state recording/refreshing; `tool-fs` formats those results into the model projection.
+The first implementation formatted `ContentBlock[]` in `execute`. The [canonical tool-output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) now keeps `ctx.fs` result facts as the tool's validated value and derives the same model text through `output.render`; file-state recording/refreshing remains on `ctx.fs`.
 
 Default native projections:
 
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
new file mode 100644
index 0000000000..47e43c47db
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
@@ -0,0 +1,112 @@
+# Agent Note: 文件系统工具 schema——面向模型的读/写/编辑接口形状
+
+Status: implemented
+
+[English](2026-06-17-filesystem-tool-schemas.md) | 中文
+
+## 问题
+
+[文件系统能力 seam Agent Note](../architecture/2026-06-17-filesystem-capability-seam.md) 定义了文件系统能力 seam（`ctx.fs`）、包（package）拆分（`dsh-fs`、`dsh-fs-local`、`dsh-tool-fs`，加上 `dsh-fs-policy` 策略插件），以及针对 read-before-write/edit 检查的 observed-file/stale-version 策略——[拆分文件系统 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 为原型选择最小的共有接口。
+
+## 决策
+
+`@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 使用 snake_case 字段名（`file_path`、`old_string`、`new_string`、`replace_all`），与 Claude Code 及现有 DeepSeek Harness 工具 schema 示例保持一致。消费方包将这些面向模型的名称转换为 `ctx.fs` 调用和 `fs/*` 事件分发。
+
+## 工具 schema
+
+### `read`
+
+`read` 检视一个 UTF-8 文本文件并返回带行号的内容。
+
+参数：
+
+- `file_path: string`——必填。要读取的路径，由 `ctx.fs` 解析。
+- `offset?: number`——可选。返回的第一行，从 1 开始。默认为第一行。
+- `limit?: number`——可选。返回的最大行数。默认值与上限是 `dsh-tool-fs` / `ctx.fs` 的实现细节。
+
+首次实现不涉及的内容：
+
+- 无 PDF `pages` 参数。
+- 无图片或多模态文件读取。
+- 不通过 `read` 列出目录；如有需要，目录列表将作为单独的后续工具。
+
+### `write`
+
+`write` 创建或完整替换一个 UTF-8 文本文件。
+
+参数：
+
+- `file_path: string`——必填。要写入的路径，由 `ctx.fs` 解析。
+- `content: string`——必填。要写入的完整 UTF-8 文本内容。
+
+在默认 fs-policy 下，使用 `write` 更新已有文件需要同一执行上下文先前对该文件有过一次观测（read/write/edit）；`dsh-fs-policy` 插件将观测到的版本作为 `fs/write-intent` 上的 stale guard 提供。创建新文件不需要先前观测。如果策略插件不存在，`write` 是无条件的裸提供方 create-or-overwrite。
+
+schema 不将 `expected_hash`、`expected_version` 或 `create_only` 作为面向模型的参数暴露。陈旧版本检查由后端产生的版本和策略插件的观测状态驱动，而非要求模型通过 schema 复制版本令牌。
+
+### `edit`
+
+`edit` 通过替换字面文本来更新已有的 UTF-8 文本文件。
+
+参数：
+
+- `file_path: string`——必填。要编辑的路径，由 `ctx.fs` 解析。
+- `old_string: string`——必填。要替换的字面文本。首次实现中空字符串无效。
+- `new_string: string`——必填。字面替换文本；空字符串表示删除匹配内容。
+- `replace_all?: boolean`——可选。默认为 false。为 false 时，`old_string` 必须恰好匹配一处。
+
+`edit` 要求同一执行上下文先前对该文件有过一次观测（任何窗口化的 read 都算——授权基于版本新鲜度，而非全文查看要求），或该上下文先前对该文件做过 write/edit。`dsh-fs-policy` 策略插件推导所有者并将记录的版本作为 stale guard 提供；提供方的 mutation lock 负责执行。
+
+首次实现拒绝 Codex 风格的 patch 语法和多模式 edit API。它使用一种严格的字面替换模式，使面向模型的契约保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
+
+## 结果形状
+
+首次实现曾将 `ContentBlock[]` 格式化逻辑放在 `execute` 中。[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)如今将 `ctx.fs` 的结果事实保留为工具经校验的值，并通过 `output.render` 派生相同的模型文本；文件状态的记录/刷新仍归 `ctx.fs` 所有。
+
+默认原生投影：
+
+| 工具 | `tool-fs` 使用的结构化 `ctx.fs` 结果 | 默认模型投影 |
+|---|---|---|
+| `read` | 返回的行、返回行数、总行数、目标显示路径、文件版本、部分视图标记 | 带行号的文本及分页页脚 |
+| `write` | 创建/更新操作、目标显示路径、新文件版本 | 简洁的创建/更新成功文本 |
+| `edit` | 替换次数、全量替换标记、目标显示路径、新文件版本 | 简洁的编辑成功文本 |
+
+结构化结果不会重复模型参数（如 `file_path`、`old_string` 或 `content`），除非后端已将其解析为新信息（如 `displayPath`、`targetKey` 或新版本）。面向 token 的截断属于模型投影的职责，而非后端规范结果的一部分。
+
+## 延后事项
+
+以下内容被明确排除在首次文件系统 schema 实现之外：
+
+- 面向模型的 `expected_hash`、`expected_version` 或 `create_only` 参数。
+- 目录列表、glob、grep 和搜索工具。
+- 二进制安全的读/写操作。
+- PDF/图片/多模态 `read`。
+- 文件系统工具的 Code Mode 投影值。
+- 规范的 edit diff 格式。
+
+## 测试
+
+schema 测试固定每个工具的必填/可选参数集、空 `old_string` 拒绝、`replace_all` 默认值、snake_case 字段名、描述文字中对观测策略的说明，以及根插件套件注册；集成测试通过 `ctx.tools.execute()` 对真实的 `dsh-fs-local` 提供方执行全部三个工具，并验证模型参数被正确转换为预期的 `ctx.fs` 调用和 `fs/*` 分发。
+
+## 曾考虑的替代方案
+
+- **Codex 风格的 patch 语法或多模式 edit API**：否决。一种严格的字面替换模式使面向模型的契约保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
+- **camelCase 参数名（OpenCode 风格）**：snake_case 与 Claude Code 及现有 harness 工具 schema 示例一致，且命名一旦发布即成为公开接口。
+- **面向模型的 `expected_hash` / `expected_version` / `create_only` 参数**：否决。陈旧检查由后端产生的版本和策略插件的观测状态驱动，从不依赖模型复制的脆弱令牌。
+
+## 后果
+
+**首版 schema 有意小于 Claude Code 的。** 去掉 PDF pages、多模态 read、丰富的 grep/list flag 和 expected hash 字段使实现保持聚焦，但用户可能很快就会提出这些需求。它们将以独立 Agent Note 或聚焦的后续工作形式到来，而非对初始 schema 的重载。
+
+**v1 中没有显式的面向模型的 stale guard。** schema 不要求模型提供 expected hash/version。这是有意为之：陈旧检查来自后端产生的版本和 `dsh-fs-policy` 插件的观测状态，而非模型复制的脆弱令牌。文件系统安全失败通过 `dsh-fs` 拥有的结构化 `FsError` 代码浮现，而非模型提供的版本字段。
+
+**命名成为公开接口。** 一旦发布，将 `file_path` 改为 `filePath` 或 `old_string` 改为 `oldString` 会搅动提示词、示例和下游客户端。本 Agent Note 预先选择 snake_case，并将其视为稳定的面向模型的契约。
diff --git a/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.i18n.yaml
new file mode 100644
index 0000000000..0852385897
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-18-acp-terminal-and-tool-rendering.md: 166e52f8e659a78b1347279c61956ca1001e4939
+2026-06-18-acp-terminal-and-tool-rendering.zh.md: 1623c8f51f9a1e0aacf374d182ab1c74dfa407cc
diff --git a/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md b/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md
index 8d9c0197eb..166e52f8e6 100644
--- a/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md
+++ b/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-18-acp-terminal-and-tool-rendering.zh.md)
+
 ## Problem
 
 The ACP bridge lets each tool own its call rendering via `presentCall`/`presentResult` (see [tool-call UI presentation](2026-06-14-acp-agent-client-protocol.md) and `packages/core/tools`). For `bash` we surface the exact command as the `tool_call` title, the model's `description` as a content text block, `kind: 'execute'`, and the completed output wrapped in a fenced ` ```console ` text block.
diff --git a/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.zh.md b/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.zh.md
new file mode 100644
index 0000000000..1623c8f51f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.zh.md
@@ -0,0 +1,48 @@
+# Agent Note: 富 ACP bash 渲染——通过 `_meta` 约定实现终端卡片
+
+Status: implemented
+
+[English](2026-06-18-acp-terminal-and-tool-rendering.md) | 中文
+
+## 问题
+
+ACP（Agent Client Protocol）桥接层允许每个工具通过 `presentCall`/`presentResult` 自行控制调用渲染（见[工具调用 UI 呈现](2026-06-14-acp-agent-client-protocol.md)与 `packages/core/tools`）。对于 `bash`，我们将确切命令作为 `tool_call` 标题呈现，模型的 `description` 作为一个内容文本块，`kind: 'execute'`，完成后的输出包裹在 ` ```console ` 围栏文本块中。
+
+参考编辑器将终端元数据渲染为一张专用卡片，包含 cwd、命令、实时风格的输出和退出状态；纯文本则丢失了这些结构。命令之所以作为标题，是因为执行卡片隐藏原始输入，而人类可读的描述保留为卡片上方的独立块。
+
+## 关键发现：agent 执行的终端使用 `_meta` 约定，而非 `terminal/create`
+
+ACP 规范有一个*客户端侧*终端子协议：agent（智能体）调用客户端的 `terminal/create`（传入 `{ command, args, cwd, env }`），由**编辑器**执行进程，然后 agent 读取 `terminal/output` / `wait_for_exit`。这个模型不适合我们：我们的 harness 通过 `dsh-bash` 自行执行 bash（沙箱化的环境清理、后台任务所有权、按会话的 cwd）。将执行路由到编辑器会绕过所有这些机制，并将执行分叉到两个后端。
+
+研究两个参考 agent（2026-06-18）发现，二者都没有为自己的 shell 工具使用 `terminal/create`——**两者都保持 agent 侧执行，并发出一套 `_meta` 约定**，由 Zed 特殊处理：
+
+- **`claude-agent-acp`**（`tools.ts`、`acp-agent.ts`）：以 `clientCapabilities._meta.terminal_output` 为门控。`tool_call` 携带 `content: [{ type: 'terminal', terminalId }]` 与 `_meta.terminal_info.{ terminal_id, cwd }`；输出和退出通过 `tool_call_update` 的 `_meta.terminal_output.{ terminal_id, data }` 与 `_meta.terminal_exit.{ terminal_id, exit_code, signal }` 到达。
+- **`codex-acp`**（`CodexToolCallMapper.ts`、`TerminalOutputMode.ts`）：调用上同样携带 `terminal_info`；输出通过 `_meta.terminal_output`（完整）或 `_meta.terminal_output_delta`（增量），由同一个 `_meta.terminal_output` 能力选择。
+
+Zed 侧（`crates/agent_servers/src/acp.rs`，已验证）：收到 `ToolCall` 且其 `_meta.terminal_info.terminal_id` 已设置时，注册一个**仅展示**的终端（header = `terminal_info.cwd`，label = `tool_call.title`）；收到 `ToolCallUpdate` 时，`_meta.terminal_output.data` 写入该终端，`_meta.terminal_exit.{exit_code,signal}` 设置状态。客户端通过 `clientCapabilities._meta.terminal_output = true` 声明此能力。`_meta` 本身是 ACP 规范认可的扩展点（在 `ToolCall`/`ToolCallUpdate` 上类型为 `{[k]: unknown} | null`）；这里的*具体键*（`terminal_info`/`terminal_output`/`terminal_exit`）是 Zed 约定，不属于 ACP 规范，但它们是 Zed 集成的事实契约，也是在保持 agent 侧执行的前提下获得终端卡片的唯一方式。
+
+## 决策
+
+保持 `dsh-bash` 的 agent 侧执行；通过 `_meta` 约定渲染终端卡片，以能力声明为门控，以 ` ```console ` 文本块作为保底回退。
+
+1. **能力声明。** `initialize` 读取 `clientCapabilities._meta.terminal_output`，桥接层按连接记住它。
+2. **提供方无关的展示词汇。** `dsh-tools` 新增一种终端形态的展示结构，工具可返回它——提供方无关（`cwd`、输出 `data`、`exitCode`/`signal`），不含 ACP 类型。`dsh-tool-bash` 为 `bash` 返回该结构（cwd 来自解析后的工作目录；输出与退出从运行结果解析）。
+3. **桥接映射。** 当客户端声明了该能力时，桥接层将展示结构映射为：在 `tool_call` 上，`content:[…, {type:'terminal', terminalId}]`（工具的任何 `content`，如描述，渲染在终端块之前）+ `_meta.terminal_info.{terminal_id,cwd}`；在 `tool_call_update` 上，`_meta.terminal_output.{terminal_id,data}`（捕获的输出）+ `_meta.terminal_exit.{terminal_id, exit_code|signal}`（解析后的退出），且 update 的文本 `content` 被省略（ACP 的 `tool_call_update.content` 会替换调用的 content 集合，因此重新发送围栏块会覆盖终端内容块）。`terminalId` 由 harness 的 `callId` 派生（稳定、每次调用唯一）。当能力未声明时，桥接层在调用上发送描述内容块，在 update 上发送既有的 ` ```console ` 文本内容——行为不变。
+4. **退出信息从渲染输出中解析；无新执行路径，无实时流式传输。** 输出在完成时附加（来自 agent 自身的 `tool/result`），不逐 token 流式传输。退出状态（`_meta.terminal_exit.{exit_code,signal}`）确实会发出：纯 `presentResult(args, result)` seam 只能看到内容块，因此 `dsh-tool-bash` 通过解析 `renderResult` 追加的状态标记（`[exit code: N]` / `[killed by signal: …]`）来恢复结构化退出信息——解析是标记发出的精确逆操作，二者在同一文件中共同演进，一个往返测试守护这对关系。资源释放不受影响：无需新增拆除逻辑，因为桥接层从未创建客户端侧终端。
+
+## 曾考虑的替代方案
+
+- **ACP 客户端侧终端子协议（`terminal/create`）**：明确否决。编辑器将执行进程，绕过 `dsh-bash` 的环境清理、后台任务所有权和按会话的 cwd，并将执行分叉到两个后端。两个参考 agent 以同样的方式否决了它（见上述关键发现）；agent 侧执行加 `_meta` 约定是在保持 harness 执行策略的同时获得终端卡片的唯一形态。
+- **通过事件 schema 传递结构化退出信息**：否决，改用标记往返方案。纯 `presentResult(args, result)` seam 只能看到内容块，而解析是标记发出的精确逆操作，二者在同一文件中共同演进，由往返测试守护。
+
+## 后果
+
+- **Zed 约定的 `_meta` 键。** 终端卡片依赖 Zed 特有的键（`terminal_info`/`terminal_output`/`terminal_exit`），位于 ACP 规范认可的 `_meta` 扩展点内，而非 ACP 终端子协议。不识别这些键的客户端仍然获得文本回退（能力门控确保我们仅在客户端通过 `_meta.terminal_output` 声明支持时才发出这些键），因此非 Zed 客户端不会变差。如果 ACP 日后标准化了 agent 执行的终端，则迁移到该标准并移除约定键。
+- **能力诚实。** 仅在客户端声明了 `_meta.terminal_output` 时才发出终端元数据；文本回退是对其他所有客户端的契约，绝不可退化。由一个无能力测试覆盖，断言 ` ```console ` 路径。
+- **terminalId 冲突。** 从每次调用的 `callId` 派生，保证在会话内唯一且在 call/result 对之间稳定；绝不跨调用复用。
+- **退出信息从渲染文本解析。** 退出信息通过解析 `renderResult` 的状态标记恢复 `exit_code`/`signal`，而非通过事件 schema 传递结构化退出（纯 `presentResult` seam 看不到后者）。解析是标记发出的精确逆操作，且位于同一文件中；往返测试固定了这对关系，标记格式变更若破坏解析则测试套件失败。如果标记格式日后需要与退出信息分道扬镳，则改为在 result 事件上暴露结构化退出。
+- **提供方无关词汇的蔓延。** 终端展示结构扩大了 `dsh-tools` 的接口面；保持其中立性（不让 ACP 类型泄漏到 `dsh-tools`），且只提供第二个 UI 消费方同样需要的丰富度。
+
+## 超出范围 / 非目标
+
+文本块基线仍为无能力声明时的默认行为。以下两项后续工作有意不在此处构建，各自需要单独的 Agent Note：**实时增量流式传输**（在分片到达时发出 `_meta.terminal_output_delta`，需要在 `dsh-bash` 上新增增量输出 seam）；**命令分类**（将 `cat`/`sed` 解析为带文件位置的 `read` 卡片，将 `grep` 解析为 `search`，回退到终端卡片——仅展示，绝不改变实际执行内容）。
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
new file mode 100644
index 0000000000..7998dc3257
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-18-compaction-capability-seam.md: a263b5e7d0245bd1279024a50e05b2f33edad521
+2026-06-18-compaction-capability-seam.zh.md: df0cf9d9131978e608d47124ba0f0db0343ee12a
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 f5beab3eb4..a263b5e7d0 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-18-compaction-capability-seam.zh.md)
+
 ## Problem
 
 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.
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
new file mode 100644
index 0000000000..df0cf9d913
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -0,0 +1,132 @@
+# Agent Note: 压缩作为能力 seam（抽象契约 + 基础后端）
+
+Status: implemented
+
+[English](2026-06-18-compaction-capability-seam.md) | 中文
+
+## 问题
+
+长时间运行的 agent（智能体）对话会无限增长。随着事件日志不断累积轮次，派生出的消息历史最终逼近模型的上下文窗口，模型随即截断响应（`max-tokens`）或性能退化。**上下文压缩（context compaction）** 是对此的缓解手段：用一段简洁的摘要替换一批较早的历史，保持近期上下文完整。
+
+[会话接口面](../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`、`context/message`、`steering/message`）；只有这些类型可以携带 `surfaceOp`。因此一个专用的 `compaction/*` 事件**不能**出现在 surface 上，编译器与 Session 始终启用的 append/seed 边界都会拒绝在其上附加 `surfaceOp`。
+
+## 决策
+
+### 压缩是一个能力 seam，接口与实现分离
+
+遵循[能力 seam Agent Note（agent 决策记录）](../architecture/2026-06-13-capability-seams.md)，压缩以独立包（package）发布，使契约、算法和（后续的）消费方 surface 各自独立演进：
+
+1. **接口** — `@deepseek-ai/dsh-compact`：抽象 `CompactService`，拥有 `ctx.compact` 键、`CompactionResult` 词汇、`compact/*` 会话事件以及规范的检查点消息来源。它将 `compactIfNeeded()` 和 `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. **消费方** — 推迟。一个 `/compact` 工具和斜杠命令将 `inject: ['compact']` 并调用契约；它们被有意排除在本 Agent Note 范围之外，以便 seam 先稳定下来。
+
+### 契约依赖 `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`），契约就无法表达。
+
+这不是耦合异味，而是契约的领域所在。「仅 cordis」的指导原则一直是「接口仅依赖契约真正需要命名的东西，绝不依赖实现」的简写。`dsh-session` 和 `dsh-llm` 本身是接口/词汇包，不是实现；`dsh-compact` 仍然不导入任何后端。seam 的真正不变式——*消费方和实现在抽象服务背后独立演进*——完好无损。
+
+### 抽象 `compactIfNeeded` / `compactRegion`，算法在后端
+
+早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将契约重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将两个核心方法都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
+
+`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`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`。
+
+### 成功的持久步骤工作完成后运行自动压力检查
+
+成功调用的压力检查不能在步骤前运行，因为最终的 `agent/request` 路由、提供方输出、工具结果、缓冲上下文与 steering 当时尚不存在。串行的 `agent/post-step(agent, turn, step, signal)` 会在这些事实持久化后、`step/end` 之前触发。`dsh-compact-basic` 通过 `ctx.tokenMeter` 测量规范的已记录请求，因此下一个请求无需推测性覆盖信封即可看到任何替换。压力达到条件后，可选的 `ctx.toolResultPrune` 重写在摘要范围选择前运行；compact-basic 重新测量持久 surface，如果修剪恢复到安全压力便跳过摘要生成。
+
+规范的提供方上下文溢出走另一条路径。失败步骤先关闭，`agent/request-error` 接收原始请求错误与连续重试次数，compact-basic 在强制执行一次有效且平衡的缩减前先修剪。仅当 `session.surface.replaceGeneration` 增加时，它才返回 retry；这包括没有摘要范围时仅修剪取得的进展。随后循环开启新的编号步骤，并从持久日志重建请求。没有替换、任何替换前的恢复失败、取消、耗尽的上限或无关错误都会保留原始提供方失败。如果修剪已经推进 generation，而后续摘要工作失败，恢复会从该持久的已修剪 surface 重试，除非取消或资源释放胜出。完整生命周期决策见[调用后恢复 Agent Note](../architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)。
+
+```
+assistant/message → tool/result/context/steering
+await serial agent/post-step          ⟵ pressure compaction inside the successful step
+step/end
+
+provider overflow → step/end
+await waterfall agent/request-error  ⟵ forced compaction between attempts
+retry → next numbered step/start      ⟵ derives from the replacement surface
+```
+
+### 保留是轮次无关的；工具配对平衡是唯一的结构守卫
+
+自动压缩在**每个成功的**步骤之后检查，而非每轮一次。这对失控轮次存活至关重要：工具密集型的 ReAct 轮次每步追加一个 `assistant/message` + 一个 `tool/result`，因此 surface 会在一轮之内增长。步骤后检查可以在后续步骤开启前压缩早期已关闭的工具对；如果请求率先越过限制，由提供方确认的溢出仍是兜底机制。
+
+`compactIfNeeded` 保留估算大小达到解析后保留 token 预算的最小完整 surface 单元尾部，压缩更早的节点。一个单元是一个完整的已关闭步骤或一条无步骤消息。如果 token 截断点落在步骤内部，保留范围会扩展直到切割点满足工具配对平衡。平衡按 surface 顺序检查，而非日志序号，因为替换摘要在旧的 surface 位置拥有新的序号。`dsh-compact` 导出前后边缘辅助函数；只要 `replaceGeneration` 不变，其逐会话缓存就只折叠新增的 surface 尾部节点，面对仅日志增长时不读取事件，并在替换后重建当前成员关系与平衡。`compactRegion` 拒绝将工具调用与其结果拆分的边界。进行中的轮次不享受特殊保留。
+
+因此失控轮次的压缩方式与其他历史完全相同：其早期*已关闭*步骤被摘要，近期步骤保持原样。当唯一可压缩的内容只剩一个不可拆分的开放尾部步骤（其工具调用尚无结果）时，压缩拒绝执行（返回 `null`）并在该步骤关闭后重试。
+
+**部分单单元溢出仍不在范围内。** 摘要范围选择无法拆分不可分割的单元。当可移除的文本型工具结果内容占据大部分空间，且修剪后的余量能够容纳时，可选修剪器可以修复一个已关闭的工具对。仅信封压力、粘贴的 `user/message` 等不可分割的超大非工具节点，以及不可修剪余量仍然过大的工具单元，依旧不属于压缩范围；限制这些单元是另一个关注点。
+
+### 头部锚定：一个自动检查点，始终在头部
+
+自动压缩始终从 surface 头部开始，将先前的检查点与新压缩的历史合并，因此只保留一个自动检查点。`shadowedRange` 因此是位置性的而非数值序号区间：一个较新的摘要序号可能占据较旧的 surface 位置。`shadowedSeqs` 记录权威的 surface 顺序。手动的中间范围压缩可能留下多个检查点。
+
+### 近似收敛不变式
+
+`resolveConfig` 提供可用默认值：阈值比例 `0.8`、保留尾部比例 `0.16`、空的摘要提供方/模型覆盖、`maxTokens: 8192`、`compactionRetries: 1`、`maxOverflowRetries: 1` 以及 `auto: true`。可选的精确提供方/模型策略会部分覆盖顶层默认值；压力根据拥有该路由的 LLM 适配器所报告容量缩放比例，而 `retainTokens` 可以替代按比例保留。保留量必须低于最终阈值。收敛仍然是动态的，因为提供方输出上限可能被隐藏或显式的推理 token 消耗，摘要大小也不可预测。如果压力仍高于阈值，`compactIfNeeded()` 会按配置的重试次数再次压缩头部检查点，但每次提交的摘要必须小于其遮蔽的内容。溢出不需要容量元数据，并会绕过阈值和保留尾部策略，执行一次最大且平衡的头部缩减，留下最新的不可分割单元。所有权划分由[已路由模型上下文与压缩策略 Agent Note](../architecture/2026-07-20-routed-model-context-and-compaction-policy.md)规定。
+
+### Surface 替换：`compact/*` 事件仅存在于日志；一条 `user/message` 承载摘要
+
+由于 `SurfaceEventType` 是封闭的，摘要不能搭载在 `compact/*` 事件上。后端改为追加一条**单独的 `user/message`**，带有 `source: COMPACT_CHECKPOINT_SOURCE` 和 `surfaceOp: { op: 'replace', start, end }`；其 `content` 是（带框架的）摘要，`sourceEventSeqs` 覆盖被遮蔽的条目*和*簿记事件。接口导出该来源和 `isCompactCheckpointSource()`，使消费方无需依赖后端包身份，即可识别持久化或克隆得到的检查点。`compact/*` 事件是纯日志记录（锁 + 溯源信息）。surface 变更位于锁**内部**，`compact/end` 是最后追加的事件：
+
+```
+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.
+user/message     → canonical checkpoint source + surfaceOp { op:'replace', start, end }.
+                   THE surface mutation (framed summary).
+                   deriveMessages() renders it as a user-role message.
+compact/end      → log-only. Releases the lock (carries `error` on a recoverable failure).
+```
+
+`deriveMessages()` 随后产出 `[summary_as_user_message, ...retained_entries]`。复用 `user/message` 是诚实的而非变通：摘要确实*是* user 角色的上下文。
+
+### 检查点框架 + 增量合并（后端私有）
+
+基础后端将摘要包装为已建立的检查点上下文，并标记以便下一轮增量合并。原始摘要保留在 `compact/summary` 上。框架是后端策略；seam 承诺由一条替换 user 消息承载可能带框架的摘要，并使用规范的检查点来源。
+
+### 通过日志记录的锁实现阻塞，加上崩溃/可恢复失败的分类
+
+`compact/start … compact/end` 括号的存在理由，按当前实际承担的职责排序：
+
+1. **可检测的崩溃孤儿 + 来源追溯**（首要）。摘要生成是一次慢速模型调用，持久化在 `compact/start` *之后*。摘要生成中途崩溃会留下一个没有匹配 `compact/end` 的 `compact/start`——一个可检测的孤儿。最后释放锁（而非最先）将崩溃窗口从*静默损坏*转变为可检测的孤儿。
+2. **防止并发压缩。** 如果当前轮次持有未匹配的 `compact/start`，`compactRegion` 拒绝启动。（循环在任一 awaited 自动 seam 上都是单线程的，因此这也是重入绊线——抛出「already in progress」表示真正的 bug。）
+
+该锁只排除另一项压缩，不排除无关的仅日志事实。基础后端会在 `compact/start` 之后对 token meter 的 surface 节点取快照，并在异步摘要后再次比较；任何 surface 变更都会使替换前的检查失败，而标题或其他仅日志追加不会使已选范围失效。
+
+两种失败路径，均有文档记录：
+
+- **崩溃**（循环在摘要生成中途死亡）：悬空的 `compact/start`，无关闭事件。由于 `compact/*` 是**仅日志**事件，孤儿是**惰性的**，不会落地摘要替换。派生 surface 保持为 `compact/start` 时已经持久化的 surface：如果修剪未产生替换，就是完整历史；如果已经修剪，就是已修剪历史。通用轮次修复（`interruptedTurnClosers`）用合成的 `turn/end` 关闭轮次；孤儿位于该 `turn/end` *之前*，因此轮次范围内的进行中检查永远看不到它，崩溃不会卡住未来的压缩。
+- **可恢复**（摘要生成抛出异常但循环存活）：后端追加设置了 **`error`** 字段的 `compact/end`，但不落地摘要替换。步骤后压力处理发出警告，并从最新的持久 surface 继续：如果尝试前没有替换，就是完整历史；如果修剪已经落地，就是已修剪 surface。溢出恢复只会在没有任何替换前委托；先前修剪带来的 generation 进展允许从该持久 surface 重试，除非取消或资源释放胜出。
+
+`compact/end` 保留其 `error?` 字段（与 `tool/result` 的自包含错误一致——一个事件即可区分成功与失败，无需关联兄弟事件）。没有单独的 `compact/error` 事件。
+
+**核心会话修复保持对压缩无感知——这是有意为之。** `interruptedTurnClosers` 从不被教导 `compact/*`。如果教导它，每个未来的 `xxx/start … xxx/end` 插件对都必须修补核心模块——这恰好是能力 seam 架构存在的意义所要避免的耦合。由于仅日志的孤儿是惰性的，不需要特殊修复：通用轮次修复加上未落地 surface 变更的惰性就足够了。
+
+## 曾考虑的替代方案
+
+- **完整算法作为接口的具体方法**——否决，因为它将契约重新耦合到一种保留策略。两个核心方法都是抽象的；可复用测量属于单独的 LLM 系列服务，`summarize()` 是 basic 唯一的钩子。
+- **在 `agent/request` 或临时 `agent/pre-step` 输入上执行压缩**——否决，因为两者都无法证明最终的持久请求，而且都会将通用生命周期耦合到压缩专属的信封数据。步骤后回放与规范溢出恢复同时覆盖成功和被拒绝的调用。
+- **`compact` 布尔值或无类型的请求元数据 map**——否决，因为多个辅助调用种类会变成互斥标志，而开放 map 会丢弃由编译器检查的词汇。一个类型化的 `purpose` 判别字段可以扩展其他调用种类，而无需再为 `GenerateOptions` 添加字段。
+- **单独的 `compact/error` 事件**——否决：`compact/end` 保留 `error?` 字段，与 `tool/result` 的自包含错误一致——一个事件即可区分成功与失败，无需关联兄弟事件。
+- **教导核心轮次修复识别 `compact/*`**——否决：仅日志的孤儿是惰性的，为每个未来的 `xxx/start … xxx/end` 插件对修补核心模块恰好是能力 seam 架构存在的意义所要避免的耦合。
+
+## 后果
+
+- **包**：`packages/compact/compact` 提供接口，`compact-basic` 提供后端，`compact-tool-result-prune` 提供可选的确定性重写。`packages/llm/token-meter` 独立拥有回放感知的测量。消费方层推迟。
+- **自动 seam**：`agent/post-step`（`@mode serial`）处理成功调用的压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。通用 `agent/pre-step` 保持为四参数检查点，不携带压缩专属的提示词/前缀 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` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用；已校验的替换仍是位于轮次内的重写。
+- **接线**：`examples/tui-agent/cordis.yml` 依次加载零配置的 `dsh-token-meter`、`dsh-compact-tool-result-prune` 和 `dsh-compact-basic`；服务级默认值使组合无需重复数值策略即可使用。
+
+## 测试
+
+- **单元测试：** 使用真实 Loader 和 invariant 插件覆盖完整单元保留、修剪配置与回放、富块顺序、元数据保留、收敛、`compact/end` 的两种结果、开放尾部拒绝、仅修剪与带摘要的溢出恢复、generation 证明、上限和原始错误保留。
+- **循环测试：** 测试固定步骤后处理发生在持久工具结果之后、`step/end` 之前，使用实际 `agent/request` 路由，关闭失败步骤，分配新的重试编号，并覆盖完整的抛出/带内溢出 → 压缩 → 重建重试组合。
+- **带密钥 e2e：** 真实模型和 bash 会话在降低的限制下触发压缩，记录完整的 `compact/start…end` 对，缩小 surface，并完成任务。
+- **快照缺口：** 失控轮次压缩尚无法回放，因为摘要调用未记录 `assistant/chunk` 事件或 `sessionId`；交错摘要调用的回放仍是后续工作。
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
new file mode 100644
index 0000000000..3d1140f5cf
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-21-subagent-capability-seam.md: 9c17a93751de209e5e4e5a0ca7d7b1d8e5656a47
+2026-06-21-subagent-capability-seam.zh.md: 6294c84a8fa11e492316f4b69048aa5f477aa04f
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 3ed2090b22..9c17a93751 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-21-subagent-capability-seam.zh.md)
+
 > The full seam is shipped: the `dsh-subagent` interface and `dsh-tool-subagent` consumer; the two in-process backends (`dsh-subagent-spawn`, `dsh-subagent-fork`); the nested-agent snapshot infrastructure ([per-session snapshot replay](../testing/2026-06-22-subagent-snapshot-replay.md)); and the out-of-process `dsh-subagent-acp` backend ([its Agent Note](2026-06-22-acp-subagent-backend.md)).
 
 ## Problem
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
new file mode 100644
index 0000000000..6294c84a8f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -0,0 +1,73 @@
+# 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)）；以及进程外后端 `dsh-subagent-acp`（[其 Agent Note](2026-06-22-acp-subagent-backend.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；上方横幅列出了已交付的内容。
+
+决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP（Agent Client Protocol））。我们预见的传输方式：
+
+- **进程内**：在同一个 `Context` 上创建一个具体的子 `Agent`（最廉价，且鉴于现有 agent 工厂几乎零成本）；
+- **ACP**：作为 ACP *客户端*驱动另一个 agent 进程（可以是自身的另一个实例）；
+- 后续：**A2A**、**Codex app-server** 与 **Claude Code Agent SDK**——每种都与 ACP 后端相同的进程外形状：「启动子 agent、发送提示词、流式接收更新、取消」。
+
+## 曾考虑的替代方案
+
+### 为何不采用 bash seam 的形状
+
+bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口 / 实现 / 消费方）；只是「一个 vs. 多个实现」这个维度不同。
+
+## 决策
+
+### 由三个包构成的 seam
+
+新建包（package）组 `packages/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 客户端驱动已配置的子进程 |
+| `@deepseek-ai/dsh-tool-subagent` | 消费方：基于 `ctx.subagents` 的面向模型的 `subagent` 工具 |
+
+### 原语：异步 `start → SubagentRun`
+
+提供方暴露 `start(request) → Promise<SubagentRun>`。完成时发布一个就绪的子 agent 并将其运行句柄转交给调用方。一个信号覆盖就绪前后的取消；`dispose()`（资源释放）取消剩余工作并等待完全停稳。启动失败时清理部分资源，不发出生命周期事件。`start` 与传输方式无关；`spawn` 仅指代全新的进程内后端。
+
+### 两类可选能力，两种发现方式
+
+- **启动时功能**（`outputSchema`、`depthLimit`、`toolFilter`、`persona`）挂在静态的 `provider.capabilities` 描述符上。服务在委派之前检查每个被请求的功能，如果提供方不支持则**大声拒绝**（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不接受后静默忽略。这些功能必须在 run 存在之前检查，因此不能是运行时方法。
+- **运行时功能**（通过 `sendMessage` 进行 steering、通过 `resume` 进行后续对话）是 `SubagentRun` 上的**可选方法**。方法的存在本身即为能力，TypeScript 类型收窄即为发现机制：消费方不经收窄就无法调用不存在的方法，因此不存在静默降级路径，也不需要额外的 flags 对象来保持同步。
+
+### Fork 与 fresh 是独立后端，而非一个 flag
+
+全新子 agent 与 fork 子 agent 是独立的提供方，而非请求中的一个 flag。`dsh-subagent-spawn` 启动隔离的子 agent；`dsh-subagent-fork` 用一个平衡前缀初始化子 agent，该前缀仅包含已完成的父轮次。进行中的轮次被排除，因为其 subagent 调用尚无结果，无法构成有效的回放历史。
+
+### 子 agent 隔离与父日志
+
+每个 subagent 运行在**自己的 `Session`** 中（独立 id、`parentSession` 谱系），独立持久化。父日志仅记录 spawn `tool/call` 及其 `tool/result`（子 agent 的最终输出）——子 agent 的内部步骤和工具调用留在子 agent 自己的会话中，绝不注入父日志。这是唯一在所有传输方式下行为一致的设计：ACP 子 agent 的内部事件在物理上无法注入我们的父日志，因此让进程内行为保持一致，使 seam 真正与传输方式无关。
+
+### 同步收集（首版）
+
+`dsh-tool-subagent` 将其执行信号传给 `start()`，等待子 agent 结果，并在 `finally` 中 dispose 该 run。非完成态的结果变为错误结果，而非成功的部分输出。这个前台消费方不使用 run 的可选 steering 方法。
+
+### 提供方选择是配置，不面向模型
+
+`dsh-tool-subagent` 绑定到恰好一个提供方名称（`Config.provider`）；模型只看到 `{ description, prompt }`。若要暴露多种传输方式，请多次加载该工具插件，每次绑定不同的提供方和不同的 `toolName`（工具注册表拒绝重名）。*服务*持有多提供方注册表；*工具*选择其中一个——本版 schema 中没有提供方/type 参数。
+
+## 测试
+
+注册表与工具测试仅用包内脚本化提供方替换非确定性的子进程边界，同时运行真实的 `SubagentService`、生命周期、任务集成和面向模型的工具。提供方与消费方的 export 形状仍保留 Loader 回归覆盖，以防止[事后分析 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) 中描述的失败。注册表测试覆盖重载安全性、重名和启动时能力拒绝；嵌套 agent 场景通过[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)进行无密钥回放；进程内后端还有真实循环的单元测试和带密钥的 e2e 测试。
+
+## 后果
+
+- **递归。** 如果不设限制，进程内子 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
new file mode 100644
index 0000000000..64d1f57f51
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-22-acp-subagent-backend.md: a45ce5e34873249969bbe4dabb87a89d10246b3d
+2026-06-22-acp-subagent-backend.zh.md: 3b6a11efc1ae0427eb5ce3b30029b77b00d6801a
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 d1b61b0af8..a45ce5e348 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-22-acp-subagent-backend.zh.md)
+
 ## Problem
 
 The subagent seam ([the seam Agent Note](2026-06-21-subagent-capability-seam.md)) was built so multiple backends coexist by name on `ctx.subagents`. The in-process backends (`-spawn`/`-fork`) run a child as a second `Agent` on the SAME cordis context — cheap, but the child shares the parent's process, model client, and tools. The seam's whole point was to also support an OUT-OF-PROCESS child reached over a protocol, proving the abstraction generalizes across a process boundary. This Agent Note adds the first such backend: an Agent Client Protocol (ACP) client.
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
new file mode 100644
index 0000000000..3b6a11efc1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
@@ -0,0 +1,62 @@
+# Agent Note: ACP subagent 后端（进程外委派）
+
+Status: implemented
+
+[English](2026-06-22-acp-subagent-backend.md) | 中文
+
+## 问题
+
+subagent seam（[seam Agent Note](2026-06-21-subagent-capability-seam.md)）的设计使多个后端可以按名称共存于 `ctx.subagents`。进程内后端（`-spawn`/`-fork`）将子 agent（智能体）作为第二个 `Agent` 运行在同一个 Cordis 上下文上：开销低，但子 agent 与父 agent 共享进程、模型客户端和工具。seam 的核心意义在于同时支持通过协议到达的进程外子 agent，以证明该抽象能跨越进程边界泛化。本 Agent Note 添加第一个此类后端：一个 ACP（Agent Client Protocol）客户端。
+
+## 决策
+
+`@deepseek-ai/dsh-subagent-acp` 注册一个 `SubagentProvider`，将每个子 agent 运行在一个派生的子进程中，并以 ACP *客户端*身份驱动它。它是现有服务端桥接 `@deepseek-ai/dsh-acp`（ACP *agent*）的方向反转孪生体：桥接应答 `initialize`/`newSession`/`prompt`；本后端调用它们并实现 `Client` 回调（`sessionUpdate`、`requestPermission`）。将配置的 spawn 命令指向 `acp-agent` 示例，即可让 harness 与自身进程通信。
+
+### 每次运行启动全新进程
+
+每次 `start` 都 spawn 一个新的子进程，运行恰好一个 ACP 会话（`initialize` → `newSession` → `prompt`），`dispose` 杀死子进程并等待其退出。这是最简单的生命周期，与进程内「每次运行一个子 agent」的形态一致。
+
+### 最小化客户端桩
+
+客户端不声明任何可选能力（无 `fs`、无 `terminal`）：子 agent 在自己的进程中自行处理文件/终端访问。`session/update` 通知被消费：后端将 `agent_message_chunk` 文本累积为结果输出，在本阶段忽略其余内容（思考、工具调用卡片），仅暴露子 agent 的最终回答。`session/request_permission` 由配置的策略自动应答（`reject` 拒绝所有提示，`allow` 通过第一个允许形态的选项批准）——本阶段不向人类暴露任何权限提示。将 `fs`/`terminal` 代理回父进程（共享工作区模式）仍为后续工作，如 seam Agent Note 所述。
+
+### 无启动时能力
+
+提供方的 `capabilities` 全部为 `false`。进程外子 agent 无法遵守父 agent 的 `maxDepth`（它无权访问 `parent.options.subagentDepth`）或 `toolFilter`（它拥有自己的工具注册表），本阶段也未实现 `outputSchema`。如果请求需要其中任何一项，服务在 `start` 运行前即拒绝。后端仅注入 `subagents`（而非 `ctx.agents`）；它从 `request.parent` 读取的唯一内容是会话 header 的 cwd（见下方工作区解析）——对话上下文、深度和工具状态都不会跨越进程边界。
+
+### 工作区 cwd 解析
+
+子进程工作目录来自显式解析，绝不使用 harness 进程的 cwd：若已配置部署 `cwd` 覆盖，则相对于启动目录将其转为绝对路径并在加载时验证；否则使用父会话 header 的 cwd 并在启动时验证；如果两者都不存在，则在生成任何进程前大声拒绝。一个 ACP 服务端进程会服务来自多个工作区的会话，因此 `process.cwd()` 不能代替会话工作区——旧的隐式回退会让子进程在服务端启动目录中运行。候选路径必须是 harness 可以进入的绝对目录（要求 `X_OK`；仅 `statSync().isDirectory()` 会接受 mode-600 的目录，而 spawn 会因 EACCES 失败）；解析出的同一路径同时用作子进程 cwd 与 ACP `session/new` 工作区。
+
+### 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。
+
+### 安全：清洗子进程环境
+
+子 agent 是独立进程，因此会继承环境变量。形如凭证的环境变量（`/KEY|SECRET|TOKEN/i`）默认不转发——父 harness 自身的密钥不得隐式泄露到派生进程中（与 bash 执行器采用的策略相同）。子 agent 自己的凭证（它需要模型密钥）通过 `config.env` 显式提供，在清洗之后叠加，因此有意传入的 `DEEPSEEK_API_KEY` 得以保留，而偶然存在的 `AWS_SECRET_ACCESS_KEY` 则不会。子进程的 stderr 继承到父进程的 stderr（诊断信息自然浮现）；spawn 级别的 `error` 事件（如命令不存在时的 ENOENT）被捕获并与 ACP 驱动竞速，因此错误命令解析为 `error` 而非以未处理错误崩溃父进程。
+
+## 测试
+
+- **无需密钥的单元/集成测试：** 一个脚本化的 ACP 子进程通过真实 stdio 测试提示词/输出流、所有 stop-reason 映射、信号与 dispose 取消（包括 pre-abort、会话前竞态和管道断裂场景）、两种权限策略、被忽略的非消息更新、命令缺失时的清理、提供方重载以及命名空间导出。
+- **无需密钥的 Loader 组合测试：** 仅用于测试的 cordis.yml 通过真实 Loader 启动 stdio 应用，并省略后端的 `cwd`；脚本化模型委派一次，脚本化子进程则证明它在父会话工作区中运行，且 ACP 也对外公布了该工作区，从而端到端覆盖 cwd 继承分支。
+- **需要密钥的 e2e 测试：** 后端 spawn 真实的 ACP 示例；其模型回答 `PONG`，写入 `proof.txt`，父进程验证该文件。
+- **快照缺口：** 每个 ACP 子 agent 是独立进程，拥有自己的回放会话，不同于进程内的按会话回放。确定性 mock 服务器覆盖率已具备；`TODO(acp-subagent-replay)` 跟踪父进程对回放中子 agent 的回放支持。
+
+## 曾考虑的替代方案
+
+### 为何继续使用 SDK 0.25.1？
+
+后端只需要 `ClientSideConnection`、`ndJsonStream`、`PROTOCOL_VERSION` 和客户端协议类型，0.25.1 全部支持。0.28 的 fluent API 需要在 ACP 层同时迁移客户端和服务端连接类，却不会改善本后端，因此升级作为独立变更保留。
+
+### 为何不使用持久子进程？
+
+持久进程池（跨运行复用热子进程）是一项性能优化，推迟到后续工作。它增加了会话生命周期和崩溃恢复的复杂度，本阶段不需要；每次 `start` spawn 全新子进程与进程内「每次运行一个子 agent」的形态一致。
+
+## 后果
+
+每次运行都要付出一个全新子进程的代价（spawn + `initialize` + `newSession`）。父进程仅暴露子 agent 的最终回答：`session/update` 中的思考和工具调用卡片被消费后丢弃，权限提示从不到达人类——由配置的策略应答。子进程环境默认经过凭证清洗，因此其自身的模型密钥需通过 `config.env` 显式提供。
+
+## 后续提供方
+
+同样的进程外启动/提示词/流式输出/取消形态可泛化到 seam Agent Note 中列出的其他传输方式——A2A、Codex app-server 和 Claude Code Agent SDK——每个都是按名称注册的兄弟提供方。ACP 后端证明了 seam 支持跨进程边界；其余在机制上类似。
diff --git a/.agents/notes/implemented/feature/2026-06-25-ask-user-question.i18n.yaml b/.agents/notes/implemented/feature/2026-06-25-ask-user-question.i18n.yaml
new file mode 100644
index 0000000000..cd85b98708
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-25-ask-user-question.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-25-ask-user-question.md: 9eab7aeb17774961dfc40224accdcfcbd5eb9d5f
+2026-06-25-ask-user-question.zh.md: eb166acfef7ed8f7ab4eb3018bf161a9ecc3549e
diff --git a/.agents/notes/implemented/feature/2026-06-25-ask-user-question.md b/.agents/notes/implemented/feature/2026-06-25-ask-user-question.md
index e1c5d03c08..9eab7aeb17 100644
--- a/.agents/notes/implemented/feature/2026-06-25-ask-user-question.md
+++ b/.agents/notes/implemented/feature/2026-06-25-ask-user-question.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-25-ask-user-question.zh.md)
+
 ## Problem
 
 The agent sometimes cannot proceed safely from model inference alone: it needs the human to choose a path, confirm a risky/default action, or provide missing information. Before this change, the only way to get that answer was for the model to ask in assistant text and then stop, which broke the normal tool-call loop: the agent had no structured way to pause, no option metadata for UIs, no abort/error taxonomy, and no way for non-stdio front doors to present the question consistently.
@@ -14,12 +16,16 @@ Introduce `dsh-user-interaction` as the provider-neutral interface package for `
 
 The model-facing request vocabulary is deliberately aligned with the product-research schema: `ask_user_question({ questions: [{ id, question, header?, options?: [{ label, description? }], multi_select? }] })`. `id` is supplied per question and echoed in the result so a batch can be routed without relying on question text. `label` is both user-facing display text and the selected value returned to the model; there is no separate `value`, no `recommended`, no `allow_custom`, and no `desc` alias.
 
-Providers return `{ answers: [{ id, selected, custom? }] }`. `selected` is always an array of selected option labels, so single-select and `multi_select` answers share one result shape. `custom` carries a free-text "Other" answer; optionless questions collect `custom` directly. When `custom` is present, it overrides any selected choices and `selected` is empty.
+Providers return `{ answers: [{ id, selected, custom? }] }`. `selected` is always an array of selected option labels, so single-select and `multi_select` answers share one result shape. `custom` carries a free-text "Other" answer; optionless questions collect `custom` directly. When `custom` is present, it overrides any selected choices and `selected` is empty. A provider that supports partial completion represents a deliberately skipped item with the existing `{ id, selected: [] }` shape, preserving the other answers without extending the tool result vocabulary.
 
 `UserInteractionError` extends `HarnessError`, so failures such as `NO_PROVIDER`, `ASK_ABORTED`, ACP cancellation, or missing session routing survive `ctx.tools.execute()` as machine-routable `{ name, code }` tool errors. This matches the structured-error taxonomy and lets the model or a wrapping plugin distinguish "user cancelled" from a generic thrown exception.
 
 ## UI mappings
 
+`dsh web` mounts `dsh-client-ui-question`, whose host half opts the Web product into the model-facing tool and whose browser half registers a `question` entry in the conversation-owned keyed composer slot. `createApiProxy` implements the Web provider with a process-memory pending table keyed by a host-minted rpcId. It registers the wait before broadcasting `question/requested`, replays the same id on every mux reopen, validates the session and complete answer batch before claiming it, and broadcasts `question/resolved` after answer, cancellation, abort, or disposal. Claiming deletes the entry synchronously, so the first valid response wins and duplicate or late responses return `not-pending`.
+
+The Web composer shows one question at a time while retaining every request in the session object layer. It supports single-select, multi-select, optionless or explicit custom answers, description text, and a visual recommendation badge without selecting the recommendation automatically. Single-select choices advance to the next item immediately, and Enter submits when every item is answered or explicitly skipped; Enter during IME composition only confirms the input candidate. The footer skips only the current item and preserves earlier drafts; the close control rejects the whole tool call with `ASK_CANCELLED`. The normal composer returns only after the host's resolved frame removes the pending item.
+
 `dsh-tui` renders each question as a keyboard overlay, shows option descriptions, supports single- and multi-select choices plus free-form custom answers, and rejects pending questions on abort, provider disposal, or terminal shutdown. Batched and simultaneous requests are queued so one overlay owns keyboard focus at a time.
 
 `dsh-acp` provides the same seam for ACP sessions. It resolves the calling `Agent` through `ownedRecord`, requiring the forward session-map record at `agent.session.id` to own that exact agent object, and calls ACP `unstable_createElicitation` with a session-scoped form for each question. Single-select options become a `choice` string enum; `multi_select` options become a `choice` array enum; optionless questions use a required `custom` text field. If the client returns both `choice` and non-empty `custom`, the custom answer wins. ACP `decline`/`cancel`, a missing answer, a missing session, and a client without elicitation support all become structured `UserInteractionError`s.
@@ -42,8 +48,8 @@ ACP elicitation is currently marked unstable in the SDK. The fallback is still s
 
 The feature gives the model a powerful pause primitive, so prompt guidance matters. The tool description tells the model to ask concise questions and use options when possible. Product policy can later wrap `tools/execute` to restrict when the tool is allowed, but the loop should not special-case it.
 
-`dsh-user-interaction` and `dsh-tool-ask-user` both live in `packages/ui` because they form one product-facing human-interaction capability. `agent-core` does not load either the tool or a provider. `dsh-tui-demo` opts into the seam, TUI provider, and model-facing tool. `acp-agent` keeps only the `userInteraction` seam/provider by default: ACP elicitation support is still client-dependent, so an ACP leaf must opt into the model-facing tool deliberately once its client can complete elicitation requests.
+`dsh-user-interaction` and `dsh-tool-ask-user` both live in `packages/ui` because they form one product-facing human-interaction capability. `agent-core` does not load either the tool or a provider. `dsh-tui-demo` opts into the seam, TUI provider, and model-facing tool. `dsh web` boots the seam/provider in the host runtime and exposes the tool through the selected Web question plugin. `acp-agent` keeps only the `userInteraction` seam/provider by default: ACP elicitation support is still client-dependent, so an ACP leaf must opt into the model-facing tool deliberately once its client can complete elicitation requests.
 
 ## Testing
 
-Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, empty-question rejection, structured tool errors through `ctx.tools.execute()`, batched answers, multi-select answers, custom answers, and the model schema including the removal of `value`, `recommended`, `allow_custom`, and `desc`. TUI tests cover option descriptions, queued requests, shutdown/abort cleanup, optionless free-form input, invalid choices, duplicate multi-select selections, and batched question flows. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify selected-option, custom-overrides-choice, multi-select, and optionless free-form elicitation paths continue the agent loop.
+Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, empty-question rejection, structured tool errors through `ctx.tools.execute()`, batched answers, multi-select answers, custom answers, explicit per-item skips, and the model schema including the removal of `value`, `recommended`, `allow_custom`, and `desc`. TUI tests cover option descriptions, queued requests, shutdown/abort cleanup, optionless free-form input, invalid choices, duplicate multi-select selections, and batched question flows. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify selected-option, custom-overrides-choice, multi-select, and optionless free-form elicitation paths continue the agent loop. Web tests pin stable-id replay, response validation, first-wins settlement, duplicate and late responses, whole-request cancellation versus owner abort, single-select advance, IME-safe Enter submission, per-item skip preservation, composer takeover, structured batch submission, and restoration of the normal composer.
diff --git a/.agents/notes/implemented/feature/2026-06-25-ask-user-question.zh.md b/.agents/notes/implemented/feature/2026-06-25-ask-user-question.zh.md
new file mode 100644
index 0000000000..eb166acfef
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-25-ask-user-question.zh.md
@@ -0,0 +1,55 @@
+# Agent Note: ask-user 提问能力
+
+Status: implemented
+
+[English](2026-06-25-ask-user-question.md) | 中文
+
+## 问题
+
+agent（智能体）有时仅凭模型推理（inference）无法安全地继续执行：它需要人类选择路径、确认有风险的或默认的操作，或者提供缺失的信息。在此变更之前，获取答案的唯一方式是模型在 assistant 文本中提问然后停止，这打断了正常的工具调用循环：agent 没有结构化的暂停方式，没有供 UI 使用的选项元数据，没有中止/错误分类体系，也没有让非 stdio 前端一致地呈现问题的途径。
+
+这是一个面向用户的能力，但它也跨越了包（package）边界。面向模型的工具需要一套提供方无关的请求词汇；每个 UI 界面需要决定如何展示和收集答案；agent loop（智能体循环）应保持不变，因为工具调用本身已具备正确的异步形状。
+
+## 决策
+
+引入 `dsh-user-interaction` 作为 `ctx.userInteraction` 的提供方无关接口包，与面向模型的消费方 `dsh-tool-ask-user` 一同放在 `packages/ui` 下。这一分组是有意为之的：向人类提问是一种由 UI 支撑的产品功能，不属于无提供方的核心主干。seam 仍然拥有稳定的请求/应答/错误词汇，而 UI 产品界面提供收集答案的具体提供方。该工具注册 `ask_user_question`，转发 `{ questions, agent, signal }`，并将提供方计算出的结构化答案作为工具结果返回。
+
+面向模型的请求词汇有意与产品调研 schema 对齐：`ask_user_question({ questions: [{ id, question, header?, options?: [{ label, description? }], multi_select? }] })`。`id` 按问题提供并在结果中回传，使批量请求无需依赖问题文本即可路由。`label` 既是面向用户的显示文本，也是返回给模型的选中值；没有单独的 `value`，没有 `recommended`，没有 `allow_custom`，也没有 `desc` 别名。
+
+提供方返回 `{ answers: [{ id, selected, custom? }] }`。`selected` 始终是选中选项 label 的数组，因此单选和 `multi_select` 的答案共享同一种结果形状。`custom` 承载自由文本的「其他」答案；无选项的问题直接收集 `custom`。当 `custom` 存在时，它覆盖任何已选择的选项，`selected` 为空。支持部分完成的提供方使用现有的 `{ id, selected: [] }` 形状表示某项被有意跳过，在不扩展工具结果词汇的前提下保留其他答案。
+
+`UserInteractionError` 继承 `HarnessError`，因此 `NO_PROVIDER`、`ASK_ABORTED`、ACP（Agent Client Protocol）取消或会话路由缺失等失败会以机器可路由的 `{ name, code }` 工具错误形式通过 `ctx.tools.execute()` 传出。这与结构化错误分类体系一致，使模型或包装插件能够区分「用户取消」与一般的抛出异常。
+
+## UI 映射
+
+`dsh web` 挂载 `dsh-client-ui-question`：其 host 侧使 Web 产品选择性加载面向模型的工具，浏览器侧则在 conversation 拥有的具名输入区 slot 中注册 `question` 项。`createApiProxy` 使用以 host 生成的 rpcId 为键的进程内 pending 表实现 Web 提供方。它先注册等待项，再广播 `question/requested`；每次 mux 重开时以相同 id 重放；在受理前校验会话和完整答案批次；并在回答、取消、中止或资源释放后广播 `question/resolved`。受理会同步删除该条目，因此首个有效响应胜出，重复或迟到的响应返回 `not-pending`。
+
+Web 输入区一次显示一个问题，同时在会话对象层保留每个请求。它支持单选、多选、无选项问题或显式自定义答案、描述文本与可视化推荐标记，但不会自动选中推荐项。选择单选项后会立即进入下一项；当所有项都已回答或显式跳过时，按 Enter 提交；IME 组字期间按 Enter 只会确认输入候选项。页脚只跳过当前项并保留先前的草稿；关闭控件以 `ASK_CANCELLED` 拒绝整个工具调用。常规输入区只有在 host 的 resolved 帧移除待处理项后才会恢复。
+
+`dsh-tui` 将每个问题渲染为键盘叠层，展示选项描述，支持单选、多选和自由格式自定义答案，并在中止、提供方 dispose（资源释放）或终端关闭时拒绝待处理的问题。批量请求和并发请求都会排队，确保同一时刻只有一个叠层占用键盘焦点。
+
+`dsh-acp` 为 ACP 会话提供同一 seam。它通过 `ownedRecord` 解析调用方 `Agent`，要求位于 `agent.session.id` 的正向会话 map 记录拥有该精确 agent 对象，并为每个问题调用 ACP `unstable_createElicitation`（附带会话范围的表单）。单选选项变为 `choice` 字符串枚举；`multi_select` 选项变为 `choice` 数组枚举；无选项的问题使用必填的 `custom` 文本字段。如果客户端同时返回 `choice` 和非空 `custom`，以 custom 答案为准。ACP `decline`/`cancel`、缺失答案、缺失会话以及客户端不支持 elicitation，都会转为结构化的 `UserInteractionError`。
+
+ACP 映射有意使用 elicitation 而非 `session/request_permission`。`request_permission` 仍保留给独立的权限门禁：它是围绕工具执行的 yes/no 或策略式授权协议。`ask_user_question` 是一个通用的信息收集工具，支持可选的自由格式答案，因此 ACP 表单 elicitation 是更贴合的协议。bridge 的会话路由与未来的权限门禁共享，但用户意图不同。
+
+## 曾考虑的替代方案
+
+**Assistant 文本后跟一个停止的轮次。** 模型可以在纯 assistant 文本中向用户提问然后停止。这会丢失结构化选项元数据，UI 没有提供方无关的方式来渲染选择，且下一条人类回答只能作为新的 user 提示词到达，而非作为需要答案的那次操作的结果。
+
+**核心拥有的 ask-user 包。** 最初实现将 seam 和面向模型的工具分别放在 `packages/core` 和 `packages/ui`，但两者描述的是同一个由 UI 支撑的人机交互功能。seam 仍然是提供方无关的，但它不是像会话、工具或 agent 注册表那样的无提供方核心基础设施。将 `dsh-user-interaction` 和 `dsh-tool-ask-user` 一起放在 `packages/ui` 下，使包的划分与产品边界一致：应用和 bridge 提供人类答案的提供方，stdio 应用选择性加载面向模型的工具。
+
+**ACP `session/request_permission`。** 权限请求是围绕工具执行的授权；`ask_user_question` 是带可选自由格式答案的信息收集。将权限用于通用提问会混淆两个不同的产品概念，并使未来的权限门禁更难推理。
+
+**循环级别的暂停原语。** agent loop 已经知道如何等待工具调用并从工具结果恢复。添加新的循环特殊分支会重复这一异步形状，并迫使每个循环实现都了解一个 UI 关注点。
+
+## 后果
+
+ACP elicitation 目前在 SDK 中标记为 unstable。回退仍然是结构化的：如果客户端未实现它，工具返回 `ASK_FAILED` 而非挂起。后续 ACP 稳定化可能重命名或重塑该方法；该迁移应限制在 `dsh-acp` 内部，因为核心 `ctx.userInteraction` 词汇是提供方无关的。
+
+该功能赋予模型一个强大的暂停原语，因此提示词引导很重要。工具描述告诉模型：提问要简洁，尽可能使用选项。产品策略后续可以包装 `tools/execute` 来限制工具何时可用，但循环不应对其做特殊处理。
+
+`dsh-user-interaction` 和 `dsh-tool-ask-user` 都位于 `packages/ui`，因为它们共同构成一个面向产品的人机交互能力。`agent-core` 不加载工具或提供方。`dsh-tui-demo` 选择性加载 seam、TUI 提供方和面向模型的工具。`dsh web` 在 host 运行时启动 seam/提供方，并通过选定的 Web question 插件暴露该工具。`acp-agent` 默认只保留 `userInteraction` seam/提供方：ACP elicitation 支持仍取决于客户端，因此 ACP 叶节点必须在其客户端能完成 elicitation 请求后才有意加载面向模型的工具。
+
+## 测试
+
+单元覆盖率固定了以下场景：提供方注册/释放、重复提供方拒绝、提供方就绪前中止、空问题拒绝、通过 `ctx.tools.execute()` 传出的结构化工具错误、批量答案、多选答案、自定义答案、显式按项跳过，以及模型 schema（包括移除 `value`、`recommended`、`allow_custom` 和 `desc`）。TUI 测试覆盖选项描述、排队请求、关闭/中止清理、无选项自由格式输入、无效选择、重复多选和批量问题流。ACP bridge 测试驱动一个真实的内存 ACP 连接（使用真实的 `ask_user_question` 工具），验证选中选项、custom 覆盖 choice、多选和无选项自由格式 elicitation 路径能继续 agent loop。Web 测试固定稳定 id 重放、响应校验、首个响应胜出的结算、重复和迟到响应、整个请求的取消与拥有方中止的区别、单选后前进、IME 安全的 Enter 提交、按项跳过保留、输入区接管、结构化批量提交，以及常规输入区的恢复。
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
new file mode 100644
index 0000000000..e6fc4aba97
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-29-todo-write-tool.md: bf5fceaafd475224914212beb460fdbc42e3dd68
+2026-06-29-todo-write-tool.zh.md: 3afc03a393284e2a9c2d6e234bc95f0faebbfb48
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 ab9421c2ed..bf5fceaafd 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-29-todo-write-tool.zh.md)
+
 ## Problem
 
 The harness gives the model bash and subagent tools but no way to record a structured task list. A todo list serves two co-equal purposes: it steers the model to plan multi-step work and keep the active task unambiguous (at most one active, exactly one while work remains), and it gives the human a live progress checklist. The ACP protocol has a native `plan` sessionUpdate that editors (Zed) already render, but the bridge never emitted one. Every reference coding agent surveyed (claude-code, opencode, codex, oh-my-pi, pi) ships some form of this; the harness had nothing.
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
new file mode 100644
index 0000000000..3afc03a393
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
@@ -0,0 +1,64 @@
+# Agent Note: `todo_write` 工具——将模型任务列表作为事件溯源的会话状态
+
+Status: implemented
+
+[English](2026-06-29-todo-write-tool.md) | 中文
+
+## 问题
+
+harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃任务明确（最多一个活跃，有剩余工作时恰好一个）；同时为人类提供实时进度清单。ACP（Agent Client Protocol）协议原生支持 `plan` sessionUpdate，编辑器（Zed）已能渲染它，但 bridge 从未发出过。调研的所有参考编码 agent（智能体）（claude-code、opencode、codex、oh-my-pi、pi）都提供了某种形式的此功能；本 harness 此前没有。
+
+## 决策
+
+新增一个面向模型的 `todo_write(todos: [{ content, status }])` 工具，其整列表状态作为新的 `todo/write` `SessionEventMap` 变体存储在事件溯源的会话日志上。stdio UI 和 ACP bridge 均从现有的 `session/event` 渲染；ACP bridge 将列表映射为 `plan` sessionUpdate。
+
+### 整列表替换，三态 status
+
+模型每次调用发送完整列表；新列表替换旧列表（回放时 last-write-wins）。这是 claude-code V1、opencode 和 codex `update_plan` 共同采用的形状，也是模型训练最多的形状——没有逐项 id，没有 delta 协议。`status` 恰好是 `pending | in_progress | completed`：与 codex `update_plan` 相同的三元组，且关键的是**与 ACP `PlanEntryStatus` 完全一致**，bridge 因此可以 1:1 映射，无需有损转换。
+
+### 状态在会话日志上，而非服务
+
+列表作为 `todo/write` 事件追加到日志，携带完整的 `{ todos }` 快照。harness 是事件溯源的——LLM（大语言模型）历史、工具调用和轮次结构都在日志上——所以 todo 列表也在那里。这免费获得了持久性、回放和 `session/load` 重建：重新打开的会话从最后一条 `todo/write` 重新推导当前列表，ACP bridge 在加载时重新发出 `plan`，无需独立的持久化后端、无需重新注水的内存服务、无需额外接线。一个内存中的 `ctx.todos` 服务需要重新发明以上所有。
+
+### 不是 surface 事件
+
+`todo/write` 被有意排除在 `SurfaceEventType` 之外。surface 是产出 LLM 消息历史（`deriveMessages()`）的投影；todo write 不产生对话消息。因此它不携带 `surfaceOp`，不加入有序 surface，不进入 `deriveMessages()`——它是持久、可回放的 *UI* 状态，与对话并行传输但不属于对话的一部分。（dev-mode 不变式仍要求它位于一个打开的轮次内，而它始终如此：它在工具调用的步骤中途追加。）
+
+### Priority 仅在 ACP 边界合成
+
+ACP 的 `PlanEntry` 要求 `content` + `priority` + `status`，但 `TodoItem` 没有 priority——模型从不推理它。与其在 schema 中增加一个模型每次都必须提供的字段，bridge 在构建 `plan` 时为每条条目合成常量 `priority: 'medium'`。Priority 是 ACP 协议格式（wire format）的要求，不是 harness 概念，因此它恰好存在于需要它的边界上。
+
+### 相比 claude-code V1 舍弃的字段：`activeForm`、id、priority
+
+claude-code V1 的条目是 `{ content, status, activeForm }`；后来（V2）增加了 id、依赖和所有权——但仅为支持 agent *集群*（磁盘持久、锁保护、逐项变更）。本工具将条目保持在最小集：`{ content, status }`。不要 `activeForm`（现在进行时标签）——UI 直接展示 `content`；不要 id——整列表替换不需要稳定标识；不要 priority——见上文。每舍弃一个字段，模型每次调用就少产出一项。
+
+### 单一所有者——无集群机制（YAGNI）
+
+每个列表属于调用它的 agent 会话，非 agent 调用被拒绝。没有共享作用域、resolver 或 delta 协议。跨 agent 列表需要逐项日志 delta 和显式作用域选择，因此留作未来独立设计。
+
+### 校验：低成本的中间路线
+
+schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，以及超过一个 `in_progress` 任务。claude-code 将单一 in_progress 交给提示词约束；oh-my-pi 在代码中强制。我们取中间路线：强制执行使计划*连贯*的低成本不变式（无空任务、无重复、最多一个活跃），但将排序和保持列表最新的纪律通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。
+
+## 为何没有 cordis-catalog 条目 / 没有 `@mode`
+
+`todo/write` 是 `SessionEventMap` 的成员，不是一等的 cordis `interface Events` 事件。catalog 生成器（`scripts/gen-cordis-catalog.ts`）扫描 `interface Events` 声明；`SessionEventMap` 变体搭载现有的 `session/event` emit，不产生新的 catalog 行。因此它不携带 `@mode` 标签（生成器仅对 `interface Events` 成员要求该标签）——添加一个毫无意义。
+
+## 测试
+
+四个层级，预先设计：
+- **单元测试**——会话事件（append/snapshot-clone/last-write-wins/not-on-surface）；工具（schema 形状、通过真实 `ctx.tools.execute` 的参数校验、值校验、事件追加与替换、非 agent 拒绝、`presentCall`、HMR（热模块替换）安全性）；ACP `todosToPlan` 映射；stdio 渲染分支。
+- **真实 Loader 路径**——插件通过 `Loader.unwrapExports` 运行，断言命名空间导出形状存活（它有 `inject`，因此一个意外的 default 导出会在加载时崩溃——postmortem/0001）。
+- **全循环集成**——一个脚本化的 mock 模型通过真实 agent loop（智能体循环）调用 `todo_write`；`todo/write` 事件落地，第二次调用替换它。
+- **`session/load` 回放**——持久化的 `todo/write` 在新的 ACP bridge 加载会话时重新发出 `plan` 更新。
+- **带密钥 e2e + 快照**——真实提示词诱导一次 `todo_write`；快照预期输出获得 `plan` 通知和日志事件。
+
+## 曾考虑的替代方案
+
+- **内存中的 `ctx.todos` 服务**——需要重新发明日志免费提供的持久性、回放和 `session/load` 重建。
+- **逐项 delta 协议**——仅在共享多所有者列表时需要，超出当前范围；整列表替换更简单，且与参考实现一致。
+- **工具放在 `core/` 中**——`todo_write` 是注册在 `ctx.tools` 上的扩展工具，不属于主干；它像其他工具族一样位于自己的 `packages/todo/` 分组中。
+
+## 后果
+
+todo 列表是持久、可回放的会话状态：持久化的 `todo/write` 在 `session/load` 时重新发出编辑器的 `plan` 更新，日志（而非插件内存）是唯一真源。整列表替换意味着每次更新一次工具调用，last-write-wins；没有需要协调的 delta 协议。事件不进入 surface，因此 todo 更新永远不会扰动推导出的模型历史——模型只看到自己的工具调用和结果。
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
new file mode 100644
index 0000000000..cfcf477426
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-30-hook-bridges.md: b6b0894e5551563187b1631e8c641e326fa166b0
+2026-06-30-hook-bridges.zh.md: 5f3adef958738d9d23c159c388be35b89f321828
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 0c3c1e13ef..b6b0894e55 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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/prompt-submit`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation`, `subagent/start`, `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)).
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
new file mode 100644
index 0000000000..5f3adef958
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
@@ -0,0 +1,70 @@
+# Agent Note: dsh-hooks-claude + dsh-hooks-codex —— Claude Code / Codex 钩子桥接插件
+
+Status: implemented
+
+[English](2026-06-30-hook-bridges.md) | 中文
+
+## 问题
+
+harness 的扩展面是其类型化的拦截 seam（见[拦截 seam Agent Note](2026-06-30-interception-seams.md)）：所谓「原生钩子」不过是一个普通的 Cordis 插件，订阅 `agent/session-start`、`agent/prompt-submit`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-continuation`、`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)）。
+
+贯穿整个设计的定位：**桥接是兼容性适配器，不是高级工具。** 桥接能做的事（阻止工具、注入上下文、强制继续、观察 subagent），原生 Cordis 插件都能做得更强——类型化返回值、完整 `ctx`、无序列化边界。桥接存在的理由是运行外部 CC/Codex 命令钩子中被明确支持的子集。这使每个桥接保持精简：解析配置、选择匹配模式、构建每事件的 payload、调用共享库的 `runHook` + `mergeHookOutputs`，再将中性结果映射为 seam Decision。各包的 README 维护着当前不支持的事件和部分字段的完整清单，以官方协议为参照。
+
+## 决策
+
+`packages/hooks/` 组下两个独立插件，各为 function/namespace 插件（`name`/`inject`/`Config`/`apply`，无 default export——见[事后复盘 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)），仅注入 `bash`：
+
+- **`dsh-hooks-claude`**——CC 方言。Claude Code 当前七个钩子点中的七个：`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop`、`SubagentStart` 和 `SubagentStop`。拥有 CC 形态的每事件 stdin payload（基础字段 `session_id`/`transcript_path`/`cwd`/`hook_event_name` 加每事件字段）、`CLAUDE_PROJECT_DIR` 环境变量加 `${CLAUDE_PLUGIN_ROOT}`/`${CLAUDE_PROJECT_DIR}` 替换，以及字面量或正则的匹配模式。`transcript_path` 是持久化定位器结果或 `''`；stdin 带有**尾部换行**。
+- **`dsh-hooks-codex`**——Codex 当前五个钩子点中的五个：`PreToolUse`、`PostToolUse`、`SessionStart`、`UserPromptSubmit` 和 `Stop`。使用始终为正则的匹配模式、Codex 形态的 snake_case payload（含 `turn_id`/`model`/`permission_mode` 额外字段），写入时不带尾部换行，不注入 Codex 插件环境变量，不做配置时占位符替换，也没有 pre-tool 审批或重写路径。`transcript_path` 是同一定位器结果或 `null`；工具 payload 在精简后的 `tool_input: { command }` 形态中携带真实的 `tool_name`。
+
+### Outcome → Decision 映射
+
+每个桥接将共享库返回的中性 `MergedHookOutcome` 映射到 seam 的类型化 Decision：
+
+| Seam | CC | Codex |
+|---|---|---|
+| `agent/session-start`（emit） | additionalContext → `agent.inject()` | 纯 stdout 输出 → additionalContext → `agent.inject()` |
+| `agent/prompt-submit` | `deny`→`block`；仅上下文→delegate+fold | `block`→`block`；仅上下文→delegate+fold |
+| `tools/pre-execute` | `deny`→`deny`；`ask`→`ask` | `block`→`deny`（无 allow/ask） |
+| `tools/post-execute` | `deny`→`block`+feedback；仅上下文→delegate+fold | 同上 |
+| `agent/turn-continuation` | 阻塞的 Stop → `continue`（reason = 下一步 steering（中途引导）） | 同上 |
+| `subagent/start`（emit） | additionalContext → 注入到存活的进程内 subagent；远程 subagent 无本地注入目标 | 本桥接不支持 |
+| `subagent/end`（emit） | 仅观察 | 本桥接不支持 |
+
+CC 桥接的 `ask` 结果是一条真正的权限路径，而非终态桥接决策：`dsh-tools` 通过可选的[审批 seam](2026-07-06-approval-seam.md) 来解析它。组合式 ACP 应答器向拥有该会话的编辑器会话发起提示，`allowed-once` 后继续执行；如果没有 ApprovalService 或应答器，调用以 `deny` 安全关闭。
+
+### 上下文来源始终是插件（误标签防护）
+
+`agent.inject()` 在缺少 `MessageSource` 时默认为 `{ kind: 'user' }`，因此每个桥接的 `inject()` 和 `HookContext` 都传入 `{ kind: 'plugin', plugin: 'hooks-claude' | 'hooks-codex' }`。单元测试覆盖率固定验证结果中的 `context/message.source` 为插件而非用户。
+
+### 添加上下文不是否决——先 delegate，再 prepend
+
+仅附加 `additionalContext`（没有 block/deny）的钩子并不是桥接可以独自返回的决策：在 waterfall 监听器中不调用 `next()` 就返回 `allow`/`accept`，会短路其后的每个 `agent/prompt-submit` / `tools/post-execute` 监听器，使注册在桥接之后的策略/沙箱插件看不到该提示词。因此，每个桥接都会先通过 `next()` 委托，再将自身上下文加入下游决策。两个 seam 都携带有序的 `additionalContexts` 数组，因此桥接会在保留所有下游来源、信封和元数据字段的同时，前置加入其独立来源的条目；下游提示词阻止仍会丢弃所有上下文，因为提示词从未到达模型，而工具后阻止语义可以显式保留上下文。Code Mode 会通过外层 `run_code` 结果转送同一数组。只有钩子本身真正返回 `deny`/`block` 才会短路。测试断言：上下文钩子允许后，较晚的监听器仍能阻止提示词，且保留的提示词和工具后上下文仍彼此分离。
+
+### CLAUDE_PROJECT_DIR 默认为会话工作区
+
+Claude Code 始终导出 `CLAUDE_PROJECT_DIR`，常见的未修改钩子引用 `$CLAUDE_PROJECT_DIR` 来构造项目相对路径。显式的 `config.projectDir` 优先；当它被省略时（默认 ACP 接线只配置 `configPath`），桥接将该环境变量按每次运行默认为 agent（智能体）的会话工作区——即钩子已经在其中运行的 `session.header.cwd`——而非留空。这样，一个标准的项目相对路径钩子在默认配置下即可正常工作。
+
+### 隔离
+
+配置在加载时一次性解析；读取/解析失败时记录日志并不注册任何内容，而非崩溃启动（一个拼错的路径不应拖垮 agent）。CC 桥接只运行 shell 形式的 `type: 'command'` 钩子；`http`、`mcp_tool`、`prompt` 和 `agent` 处理器被解析后跳过。Codex 桥接只运行同步命令处理器，跳过 `async: true` 或非命令条目。emit 监听路径（`session-start`、`subagent/start`）以 detached 方式运行，其 `inject` 包裹在 `.catch` 中记录日志（抛异常的 inject 不得中断会话启动或循环）。
+
+### 钩子在哪里运行，配置从哪里来
+
+钩子在 agent 的会话工作区中运行，因此相对路径指向用户的项目。`configPath` 相对于进程启动时的 cwd 解析一次，适用于所有会话。按会话的项目本地发现仍推迟在 `TODO(per-session-hook-config)` 下。
+
+## 推迟的兼容性缺口
+
+- **工具输入重写。** 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` 历史和 ACP/tool-bash 展示共同读取，诚实的重写是一个设计单元，而非一个字段。
+- **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` 日志中，钩子在此期间保留其逐点效果（决策/上下文）。
+- **配置发现。** 路径在 `cordis.yml` 中显式指定且为进程级（见上文）；完整的多层 CC/Codex 优先级遍历、按会话的项目本地发现以及信任/hash 模型未被重新实现（`TODO(per-session-hook-config)`）。
+- **Session-start / subagent-start 上下文为尽力而为（`TODO(session-start-gating)`）。** 两个钩子以 detached 方式运行于启动过程之外，因此其上下文在就绪时注入，但可能错过首个请求或短命的 subagent。要保证首请求送达，需要一个 awaited 的启动 seam。
+
+## 曾考虑的替代方案
+
+**每点钩子并发执行。** 参考引擎对一个点匹配到的钩子并发运行并折叠结果。本桥接**串行**运行（匹配循环内每个钩子 `await`），并以相同的最严格合并策略折叠。串行是刻意的：它使每个钩子的 `hook/invoked`/`hook/result` 对在会话日志中相邻且顺序确定，而折叠对决策是顺序无关的（`deny > ask > allow`），因此结果一致。代价是延迟（钩子 *N* 等待钩子 *N−1*）以及每钩子超时不重叠——对真实配置中的钩子数量可以接受；如果某配置的扇出大到影响总耗时，再重新评估。
+
+## 后果
+
+匹配语义、退出码处理和合并优先级位于 `dsh-hook-protocol`；每个桥接只负责解析配置、构建方言 payload 和映射结果。逐文件覆盖率包含配置分支以及通过真实循环、`dsh-bash-local` 和 shell 脚本的端到端映射，同时一个真实 Loader 冒烟测试守护包的导出形态。原生插件绕过协议格式，直接返回类型化决策。
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
new file mode 100644
index 0000000000..de9949114b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-30-hook-protocol-lib.md: 19a69119befde99417b736edf38923ec6ac5fa7c
+2026-06-30-hook-protocol-lib.zh.md: f4950eea2b02e86ed7109f8ebdaab29dd77428d8
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 bb1822504a..19a69119be 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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.
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
new file mode 100644
index 0000000000..f4950eea2b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: dsh-hook-protocol——Claude Code / Codex 钩子协议格式共享核心库
+
+Status: implemented
+
+[English](2026-06-30-hook-protocol-lib.md) | 中文
+
+## 问题
+
+钩子子系统提供两个桥接插件：一个运行用户既有的 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`，一个**库**（不是插件——它不注册也不注入任何东西），持有两个桥接插件共同依赖的真正相同的原语。共享与方言专属之间的分界是本设计的重心。
+
+## 决策
+
+在 `packages/hooks/` 分组下新建 `hook-protocol` 作为纯库。它拥有四个原语族和 `hook/*` 会话事件；每个桥接插件（`dsh-hooks-claude`、`dsh-hooks-codex`）拥有真正不同的部分。
+
+**共享（本库）：**
+- **Matcher** — `matchesMatcher(pattern, query, mode)`。两种方言唯一不同的轴被收敛为 `mode` 参数：`claude` 将纯 `[A-Za-z0-9_|]+` 模式视为字面量（管道符 = 精确匹配的多选），其余视为正则；`codex` 始终是无锚定正则。缺省/`''`/`'*'` 匹配一切；无效正则匹配空集（绝不向 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)）。
+- **合并** — `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`、`PromptDecision`、`ContinuationDecision`、`PostToolDecision`）。
+
+## 曾考虑的替代方案
+
+**单一参数化引擎。** 否决，因为 payload 构建与 decision 映射在方言间确实不同。Matcher、编解码器、执行、合并规则和事件保持共享；每个桥接插件保留自己的 payload 和映射，使其协议格式行为在代码中可就地阅读。
+
+## 后果
+
+每个桥接插件解析配置、构建方言 payload、调用共享的 runner 与合并逻辑、映射 decision、追加 `hook/*`。协议测试覆盖每种 matcher 模式、exit-code 与编解码器字段、runner 管道、合并优先级和审计辅助函数，逐文件 100% 覆盖率；桥接插件测试验证库的真实加载路径。`updatedInput` 已解析但仅记录日志并发出警告，直到 [input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)落地。
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
new file mode 100644
index 0000000000..639a586e7c
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-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
+2026-06-30-interception-seams.md: 8af489d3f575dd457e1981e433330f08cefa2043
+2026-06-30-interception-seams.zh.md: 3886ed21504abfe14a2ccb344d7aa0d3f8d25064
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 08edfae386..8af489d3f5 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-30-interception-seams.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).
@@ -20,15 +22,16 @@ The canonical surface separates transformable policy, around-dispatch control, a
 
 ### The tool pipeline gives each phase one kind of authority
 
-Every call follows `tools/pre-execute` → guards → `tools/execute` → dispatch → `tools/post-execute` → `tools/result`. The registry snapshots caller input, materializes and freezes arguments, and assigns an opaque token. Nested calls carry only the parent token. Identity remains immutable; only `signal` may change around dispatch. The log, UI, and tool body therefore agree on what ran.
+Every call follows `tools/pre-execute` → guards → `tools/execute` → dispatch → `tools/post-execute` → definition-owned `finalizeContent` → `tools/result`. The registry snapshots caller input, materializes and freezes arguments, assigns an opaque token, and snapshots the visible definition's final-content callback before policy begins. Nested calls carry only the parent token. Identity remains immutable; only `signal` may change around dispatch. The log, UI, and tool body therefore agree on what ran.
 
-- **`tools/pre-execute`** is the extensible waterfall gate. Its `PreToolDecision` allows, denies, or asks. Deny skips `tools/execute` and core dispatch. Ask resolves through the optional approval seam: only `allowed-once` continues through guards and dispatch; rejection, cancellation, an unavailable channel, a missing approval service, or an agent-less call becomes a normalized denial. Every outcome still reaches post-policy and final observers.
+- **`tools/pre-execute`** is the extensible waterfall gate. Its `PreToolDecision` allows, denies, or asks. Deny skips `tools/execute` and core dispatch. Ask resolves through the optional approval seam: only `allowed-once` continues through guards and dispatch; rejection, cancellation, an unavailable channel, a missing approval service, or an agent-less call becomes a normalized denial. Every resolved decision still reaches post-policy; a throwing listener becomes a final normalized failure.
 - **`ctx.tools.guard()`** installs synchronous scope-aware policy after the whole pre-execute waterfall. A guard may deny or abstain, never force-allow, so listener ordering cannot resurrect an operation that a final invariant forbids.
-- **`tools/execute`** is the around-dispatch waterfall for timeout, retry, and metrics plugins. A wrapper delegates to core dispatch with `next()`, may replace and restore the required `exec.signal` before doing so but cannot remove it, and receives the already-normalized result of a thrown or unknown tool; returning its own valid result short-circuits dispatch.
-- **`tools/post-execute`** is the inspect/transform waterfall. Its `PostToolDecision` accepts, blocks with feedback, optionally replaces content, or attaches `additionalContexts`. The returned decision is the supported transform channel; after the waterfall, the registry materializes the complete outcome once before final observation.
+- **`tools/execute`** is the around-dispatch waterfall for timeout, retry, and metrics plugins. A wrapper delegates to core dispatch with `next()`, may replace and restore the required `exec.signal` before doing so but cannot remove it, and receives the already-normalized canonical success/failure result of a thrown or unknown tool; a wrapper-authored success short-circuits dispatch and is re-normalized through the resolved output declaration.
+- **`tools/post-execute`** is the inspect/transform waterfall. Its `PostToolDecision` accepts, blocks with feedback, replaces either presentation content or canonical value, or attaches `additionalContexts`. Value replacement revalidates and recomputes presentation; content replacement preserves programmatic value and is not a confidentiality boundary. The returned decision is the supported transform channel.
+- **`ToolDefinition.finalizeContent`** is an optional synchronous, total, content-only boundary snapshotted with the visible definition at call creation. It runs exactly once after the registry has normalized and losslessly snapshotted the candidate outcome, including pre-, around-, or post-listener failures that bypass later waterfalls and errors discovered while snapshotting another result field. It may replace `content` or preserve it with `undefined`, but cannot rewrite `isError`, structured error identity, contexts, or presentation metadata. This is where a tool enforces its own last-mile content invariant without converting policy failures into weaker block decisions.
 - **`tools/result`** is the synchronous contained notification after every transform, lossless-JSON materialization, and the outer error boundary. It receives the same frozen execution identity and an immutable snapshot of the authoritative result; observer failures are contained per listener and cannot change or reject `ToolRegistry.execute()`'s returned outcome.
 
-Core dispatch and the tool body sit inside normalization boundaries, so tool, listener, malformed-result, non-JSON result, and identity-shape failures resolve as JSON-safe `isError` results rather than escaping the turn. A post-execute listener can therefore inspect a thrown tool, and a final observer sees exactly what the caller receives and the session log can persist.
+Core dispatch and the tool body sit inside normalization boundaries, so tool, listener, invalid canonical value, renderer/projector, non-JSON presentation, and identity-shape failures resolve as JSON-safe `isError` results rather than escaping the turn. A post-execute listener can therefore inspect a thrown tool; definition-owned final content invariants also cover outer pipeline and candidate-materialization failures; and a final observer sees the execution-local canonical value beside exactly the presentation fields the session log can persist. The [canonical tool-output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) owns the value/projection and durability rules.
 
 **`TurnEndReason.rejected`** (`dsh-session`): a zero-step turn whose claimed prompt was blocked by `prompt-submit`.
 
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
new file mode 100644
index 0000000000..3886ed2150
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
@@ -0,0 +1,61 @@
+# Agent Note: 拦截 seam——钩子编程所面对的类型化 Decision 表面
+
+Status: implemented
+
+[English](2026-06-30-interception-seams.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。
+
+## 决策
+
+规范表面将可变换策略、环绕调度控制与仅观测通知分离。策略 waterfall（瀑布式事件）返回小型的、seam 专属的**类型化 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/prompt-submit(agent, content, source, signal, next) → PromptDecision` ——waterfall，在轮次唯一取得所有权的排队消息追加为 `user/message` 之前触发。显式轮次 signal 位于最后的 `next` 之前；`allow` 可以重写提示词 `content` 或附加来源各自独立的 `additionalContexts[]`，而 `block` 会追加一条持久的 `prompt/blocked`，并拒绝这个零步骤轮次。
+
+**`agent/turn-continuation`** 接收并返回一个 `ContinuationDecision`。`{action:'continue', reason?}` 可携带面向模型的内容和来源，记录为同一轮次内的下一步 steering（中途引导）——与 `/goal` step-end-steer 模式互为类型化孪生。它不是 `context/message`，因此其类型不提供持久上下文元数据。
+
+### 工具流水线为每个阶段赋予一种权限
+
+每次调用遵循 `tools/pre-execute` → guards → `tools/execute` → dispatch → `tools/post-execute` → 由定义拥有的 `finalizeContent` → `tools/result`。注册表对调用方输入创建快照、实体化并冻结参数、分配一个不透明 token，并在策略开始前对可见定义的最终内容回调创建快照。嵌套调用仅携带父 token。身份始终不可变；只有 `signal` 可在环绕调度时改变。日志、UI 和工具体因此对「执行了什么」达成一致。
+
+- **`tools/pre-execute`** 是可扩展的 waterfall 门禁。其 `PreToolDecision` 允许、拒绝或询问。拒绝跳过 `tools/execute` 与核心调度。询问通过可选的审批 seam 解析：只有 `allowed-once` 继续通过 guards 和调度；拒绝、取消、通道不可用、审批服务缺失或无 agent 调用均规范化为拒绝。每个已解析的 decision 仍会到达后策略；抛出异常的监听器会成为最终的规范化失败。
+- **`ctx.tools.guard()`** 在整个 pre-execute waterfall 之后安装同步的、作用域感知的策略。guard 可以拒绝或弃权，永远不能强制允许，因此监听器顺序无法复活一个被最终不变式禁止的操作。
+- **`tools/execute`** 是用于超时、重试和指标插件的环绕调度 waterfall。包装层通过 `next()` 委托给核心调度，在此之前可以替换并恢复必需的 `exec.signal`，但不能移除它；包装层接收抛出异常或未知工具产生的、已完成规范化的规范成功／失败结果。包装层自行产生的成功结果会短路调度，并通过已解析的输出声明重新规范化。
+- **`tools/post-execute`** 是检查/变换 waterfall。其 `PostToolDecision` 接受、以反馈阻止、替换呈现内容或规范值，或附加 `additionalContexts`。替换值会重新校验并重新计算呈现；替换内容会保留程序化值，且不构成保密边界。返回的 decision 是受支持的变换通道。
+- **`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)定义值／投影与持久性规则。
+
+**`TurnEndReason.rejected`**（`dsh-session`）：取得所有权的提示词被 `prompt-submit` 阻止的零步骤轮次。
+
+### 三个承重的循环决策
+
+1. **在提示词策略之前开启轮次。** 被阻止的提示词成为零步骤的 `rejected` 轮次，保持封闭性并为 ACP（Agent Client Protocol）提供持久的终结事件。否决记录 `prompt/blocked`（含原始提示词和原因），而每个允许的 `additionalContexts` 条目都注入到已开启的轮次中。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个取得所有权的 ordinary-send 条目都是其轮次中的唯一消息；启动前丢弃不会创建轮次。
+
+2. **工具执行后的 `additionalContexts` 与异步注入进入活跃批次 FIFO，并在该批次结算时追加。** `content`/`feedback` 塑造 `execute()` 返回的结果，但每项上下文都是独立的 `context/message`，而单个步骤或组合工具可以产生许多上下文。立即追加上下文会产生 `result(c1) → context → result(c2)` 的交错，或把嵌套上下文放在外层结果之前，破坏工具调用/结果邻接性。因此 `ToolRunContext.deferContext()` 会在失败路径上也收集嵌套调度上下文，`execute()` 在 `ToolExecutionResult` 上暴露有序数组，循环再把它接纳到与执行期间 `agent.inject()` 调用相同的 FIFO 中。FIFO 在批次结算时，于每个已记录结果之后追加，其中也包括被中断轮次关闭之前。被接受的外层调用将 deferred contexts 保留在 decision contexts 之前；被外层阻止时则丢弃 deferred contexts，只暴露阻止 decision 显式提供的上下文。
+
+3. **强制 `continue` 的 `reason` 通过 steering 通道入队**，使得下一步骤在循环顶部排空时将其记录为当前轮次的 steering——同一轮次内的下一*步骤* steering，而非下一*轮次*的提示词（与现有的 `hasSteering` 强制继续覆盖一致）。
+
+### 工具执行前输入重写是一个独立的一致性决策
+
+`PreToolDecision` 不能重写参数。历史和审计调用在执行前记录，ACP 展示读取相同的输入，因此注册表在策略之前封存参数。有效的重写必须在身份创建之前同时更新历史、审计、展示和执行；该契约属于[输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)。
+
+### 边界
+
+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-stop` 独立负责。
+
+## 曾考虑的替代方案
+
+- **将工具执行前输入重写作为本 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 表面。
+
+## 后果
+
+规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、prompt-submit、工具执行后上下文缓冲和 continuation；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/core-data-structures/core.md#interception-decisions) 与[工具结构](../../../../docs/core-data-structures/tools.md)中。ACP 桥接将 `rejected` 轮次映射为其 `cancelled` 编解码值，而钩子驱动的快照端到端验证可观测的桥接行为。
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
new file mode 100644
index 0000000000..b1ad660010
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-30-session-store-fork-api.md: 4e4ea7f1d3aa3290bdb21999a292dbdfd016302e
+2026-06-30-session-store-fork-api.zh.md: d17daa464ad59c6b5ac4d5041b4af30c44321fa7
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 ee67af7d96..4e4ea7f1d3 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-30-session-store-fork-api.zh.md)
+
 ## Problem
 
 The event-sourced session log already has the primitive a fork needs: create a new session with a seed event prefix, then derive model history from that seeded log exactly as replay does. That primitive is intentionally low-level: `ctx.sessions.create(id, { seed, meta })` accepts any valid seed, but ordinary live-session branching needs policy around which prefix can be copied, which metadata is stamped on the child, and how errors are classified.
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
new file mode 100644
index 0000000000..d17daa464a
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
@@ -0,0 +1,43 @@
+# Agent Note: SessionStore fork API
+
+Status: implemented
+
+[English](2026-06-30-session-store-fork-api.md) | 中文
+
+## 问题
+
+事件溯源的会话日志已经具备 fork 所需的原语：创建一个带有种子事件前缀的新会话，然后像回放一样从该种子日志推导模型历史。这个原语有意保持底层：`ctx.sessions.create(id, { seed, meta })` 接受任何合法种子，但常规的活跃会话分支需要围绕以下问题制定策略：哪些前缀可以被复制、子会话应打上哪些元数据、以及错误如何分类。
+
+语义上的风险在于 fork 边界。一个合法的用户可见 fork 种子必须是连续的且封闭在轮次内。如果在一个活跃轮次内部 fork，会复制一个未关闭的 `turn/start`、可能还有一个未关闭的 `step/start`，以及可能悬空的工具调用。这违反了轮次封闭性与提供方 transcript 不变式，并且会创建一段误导性的子历史——看起来子会话参与了父会话中一个尚未完成的轮次。现有的 [subagent seam](2026-06-21-subagent-capability-seam.md) 有意解决的是另一个问题：工具触发的 subagent fork 通常发生在父轮次仍然打开时，因此 `dsh-subagent-fork` 会将种子裁剪到父会话最后一个已完成轮次的前缀。通用的会话 fork 不应静默裁剪；它应当要么在请求的边界处 fork，要么拒绝请求。
+
+## 决策
+
+`dsh-session` 直接在 `ctx.sessions` 上拥有常规活跃会话 fork 的能力。不设独立的 `dsh-session-fork` 包（package），也不设 `ctx.sessionFork` 服务：该 API 没有独立的后端、事件词汇、生命周期或持久化行为，所有持久化工作都委托给现有的会话存储和持久化后端。
+
+store 暴露一个操作：
+
+```ts ignore-check
+type SessionForkSource = Session | SessionId
+
+class SessionStore extends Service {
+  fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+}
+```
+
+`boundary` 是要复制到的源事件 `seq`（含该序号）。省略时默认为源会话当前的最后一个事件；对空源会话省略 `boundary` 则创建一个空的子会话。fork 特有的校验仅检查请求的边界是否存在且为 `turn/end`。选定的前缀随后被深拷贝到子会话的种子中。子会话继承源会话的 `cwd`，将 `parentSession` 设为源会话 id，并将 `seedLength` 设为已复制前缀的长度。省略 `childSessionId` 时，`SessionStore` 使用其现有的 id 策略生成一个。
+
+空前缀可以被 fork；任何非空边界都必须是一个安全的、已存在的、位于 `turn/end` 的序号，无论结束原因为何。类型化的错误区分源缺失、对象陈旧、子 id 重复和边界无效等情况。更广泛的日志校验与崩溃恢复仍由其现有的负责方处理。
+
+## 曾考虑的替代方案
+
+**独立的 `ctx.sessionFork` 服务。** 这是最初的实现，但评审表明它过度套用了 capability-seam 模式。代码没有可替换的后端、没有额外的事件面、没有独立的所有权生命周期，也没有超出 `ctx.sessions.create({ seed, meta })` 的持久化行为。保留独立包会迫使调用方为了在会话存储原语之上执行一层策略而去发现并安装第二个服务。
+
+**两个函数：`snapshot()` 加 `fork()`。** 这保留了一个可复用的种子/元数据计算，但唯一支持的消费方会立即创建会话。它还使接口看起来比用户实际需要的具体操作更抽象。单一的 `fork()` 加显式 `boundary` 使 API 保持直接，同时仍支持对先前时间点的 fork。
+
+**静默裁剪未关闭轮次到最后一个已完成边界。** 这对 `dsh-subagent-fork` 是正确的——委托通常在父轮次仍然打开时开始，子会话应只继承已完成的前缀。但对常规的用户/会话分支而言是错误的，因为它隐藏了请求的 fork 点实际上不是合法边界这一事实，并且静默丢弃了父轮次的尾部。
+
+## 后果
+
+公开接口保持精简且易于发现：活跃会话分支是 `ctx.sessions` 的一部分，紧邻 `create({ seed })`，而非一个独立服务或一对两步辅助函数。持久化继续通过现有的 `session/created` 和 `session/flush` 行为运作：fork 出的子会话以种子事件开始生命，因此现有后端只需持久化该种子一次，并在 header 中保存 `parentSession`／`seedLength`。
+
+v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备 transcript（文本记录）/快照覆盖后才广播该能力；本 Agent Note 不添加面向编辑器的更新，因此当前不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖，而本 API 则获得专门的 `dsh-session` 单元测试加 JSONL 持久化覆盖。
diff --git a/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.i18n.yaml
new file mode 100644
index 0000000000..c7281e3189
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-30-subagent-observe-enrich.md: a07cef95630689d1ca8cacd3eb7c50e691cb304a
+2026-06-30-subagent-observe-enrich.zh.md: 578aae0a7273defcc1f88fb2a50c83ef454e3c16
diff --git a/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.md b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.md
index 861779fc50..a07cef9563 100644
--- a/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.md
+++ b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-30-subagent-observe-enrich.zh.md)
+
 ## Problem
 
 The hooks subsystem ([interception seams Agent Note](2026-06-30-interception-seams.md)) lets a plugin observe and gate the agent at lifecycle points. Claude Code and Codex both expose **SubagentStart / SubagentStop** hooks, and CC's carry the subagent's final message. The harness already emits `subagent/start` and `subagent/end` lifecycle events ([the subagent capability-seam](2026-06-21-subagent-capability-seam.md)), but their payloads were minimal (`provider`, `id`, and on end `stopReason`) — not enough for a hooks bridge to report WHAT a subagent produced without separately reaching for the live run.
diff --git a/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.zh.md b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.zh.md
new file mode 100644
index 0000000000..578aae0a72
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: Subagent 生命周期丰富化——lastAssistantMessage（仅观察）
+
+Status: implemented
+
+[English](2026-06-30-subagent-observe-enrich.md) | 中文
+
+## 问题
+
+钩子子系统（[拦截 seam Agent Note](2026-06-30-interception-seams.md)）允许插件在生命周期节点观察和拦截 agent（智能体）。Claude Code 和 Codex 都暴露了 **SubagentStart / SubagentStop** 钩子，且 CC 的钩子携带 subagent 的最终消息。harness 已经发出 `subagent/start` 和 `subagent/end` 生命周期事件（[subagent 能力 seam](2026-06-21-subagent-capability-seam.md)），但其载荷极为精简（`provider`、`id`，以及 end 时的 `stopReason`），不足以让钩子桥接层在不单独访问活跃 run 的情况下报告 subagent 产出了什么。
+
+本 Agent Note 丰富 end 载荷。它刻意限定为**仅观察**：不改变控制流，不引入 waterfall（瀑布式事件）。影响 run 的 subagent-stop 决策（续行、改变 run 的注入）属于另一个更大的重设计，不在本 Agent Note 范围内。
+
+## 决策
+
+**在 `SubagentRunEndInfo` 中添加 `lastAssistantMessage`——子 agent 的最终输出。** 在正常结束路径上，它是只读的类型化 `SubagentResult.output`，观察者无需持有 run 即可看到子 agent 产出了什么。在基础设施拒绝（不存在 `SubagentResult`）的情况下，该字段缺失，事件报告 `stopReason: 'error'`。提供方与监听方是受信任的同进程协作者，遵守借用不可变载荷的契约。
+
+两个事件仍为普通 **`emit`**。异步的 `SubagentService.start()` 将结果观察附加到就绪的提供方 run 上，发出 `subagent/start`，然后返回该 run；进程内监听方因此可以通过 `ctx.agents.get(info.id)` 访问已发布的子 agent，而远程提供方无需在本地注册表中有对应条目。提供方启动被拒绝时不发出任何事件。回调保持仅观察，且逐监听方隔离确保一个异常订阅者不会阻塞活跃 run 或饿死后续监听方。
+
+## 曾考虑的替代方案
+
+**`agentType` subagent 类别标签**（CC 的 `subagent_type` 在 harness 中的对应物），放在请求与两个生命周期载荷上。早期草案曾包含它；评审中移除，因为它是 Claude Code 的概念，不适合我们自己的 seam（此处没有任何逻辑解释它，唯一消费方是 CC 方言桥接层）。CC 桥接层改为直接为其 SubagentStart/Stop 的 `agent_type` matcher 填入 Claude Code 自身的默认值 `"general-purpose"`，因此本 Agent Note 只交付**一项**丰富化：`lastAssistantMessage`。
+
+**控制流式 `subagent/end`**：推迟；见下文。
+
+## 为何仅观察，以及推迟了什么
+
+控制流式 `subagent/end`（一个被 await 的 waterfall，返回停止/继续决策，与其他拦截 seam 一致）需要：将 `subagent/end` 从 emit 改为 waterfall、重构 `SubagentService.start` 使其在结算前 await 监听方、在进程内提供方中实现 `resume` 能力以便「继续」能真正重新运行子 agent。这属于[能力 seam Agent Note](2026-06-21-subagent-capability-seam.md) 已推迟的后台/steering（中途引导）subagent 重设计（同一个重设计还将统一 subagent 与 bash 之间的长时间运行工具处理）。本 Agent Note 交付钩子桥接层当前所需的仅观察丰富化；`FIXME(subagent-continuation)` / `TODO` 锚点标记了控制流版本在重设计发生时的落点。
+
+## 后果
+
+钩子桥接层（或原生插件）现在可以通过订阅既有 emit 将子 agent 的 `lastAssistantMessage` 转发给 SubagentStop 处理器，无需新的控制流接口。词汇新增记录在 [docs/core-data-structures/subagent.md](../../../../docs/core-data-structures/subagent.md)（事件行文部分）与两个 subagent README 中；catalog 已重新生成。生产行为无变化——事件触发方式与之前完全一致，end 载荷上多了一个可选字段——因此无需更新快照或 e2e 测试。
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
new file mode 100644
index 0000000000..2b02053f05
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-05-dynamic-workflows.md: 4c8606fb617b3fb6b2e8ad9c35d77c585b1fe8b1
+2026-07-05-dynamic-workflows.zh.md: 757eafb5d21f42b2ca529ebeb6b16eb8205e823d
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 599c895ae2..4c8606fb61 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-05-dynamic-workflows.zh.md)
+
 ## Problem
 
 The harness can delegate ONE task to ONE child (`dsh-tool-subagent`), but work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — forces the model to orchestrate turn by turn: every intermediate result lands in the parent context, the plan lives nowhere durable, and coordination costs a model round-trip per step. Claude Code ships this capability as [dynamic workflows](https://code.claude.com/docs/en/workflows): the model writes a JavaScript orchestration script, a runtime executes it, and the script — not the conversation — holds the loop, the branching, and the intermediate results.
@@ -44,7 +46,7 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai
 
 An output schema makes a schema-valid committed capture mandatory for successful child completion. The scoped runtime presents the capture tool and instruction, commits only a successful final outcome—including the enclosing `run_code` outcome for an SDK call—denies later side effects after capture becomes pending, and stops the child without another model step after commit. A validation failure remains a retryable tool error; clean completion without a committed capture settles as an error.
 
-`StructuredOutputSchema` is the raw enforceable JSON-Schema subset in `dsh-tools` (single-string `type`, `properties`/`required`/`additionalProperties`, `items`, scalar `enum`/`const`), and unsupported keywords fail loudly because that wire data becomes the capture tool's parameters verbatim. The [agent-scope runtime-design Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#structured-output-commits-only-authoritative-outcomes) owns the assembly, commit, guard, and terminal-stop correctness algorithms.
+`ObjectJsonSchema` is the object-rooted consumer view of the unified enforceable raw JSON Schema subset in `dsh-tools`; unsupported keywords fail loudly because that wire data becomes the capture tool's parameters verbatim. The [unified JSON-value schema Agent Note](../architecture/2026-07-20-unified-json-value-schema-dsl.md) owns the vocabulary and validation semantics, while the [agent-scope runtime-design Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#structured-output-commits-only-authoritative-outcomes) owns the assembly, commit, guard, and terminal-stop algorithms.
 
 ## Testing
 
@@ -68,7 +70,7 @@ Worker-side logic runs through an in-process `MessageChannel` so V8 coverage mea
 - **Background execution as the default** (CC's shape): deferred; foreground-synchronous matches `dsh-tool-subagent`'s cut, and background semantics should be designed ONCE across bash/subagent/workflow rather than per-tool.
 - **Workflow-layer JSON parsing for `agent({schema})`**: duplicating a seam concern at one consumer while the seam's capability flag stayed dishonestly `false`.
 - **Meta embedded in the script as `export const meta = {...}`** (CC's exact format): keeps scripts self-contained and CC scripts drop-in, but obtaining meta requires evaluating model-written text on the host. Even an empty timed vm context cannot bound script-controlled getters when the host reads the resulting object. A JSON parameter removes the scanner, evaluation, and host-spin hole; the cost is that a CC script's meta header must move into the parameter (the body stays drop-in).
-- **`SchemaSpec` as the outputSchema type**: the author-facing DSL cannot express what arrives as data and cannot be validated against without conversion loss.
+- **`ValueSchemaSpec` as the `outputSchema` wire type**: the author form now has equivalent vocabulary, but a workflow supplies realm-foreign raw JSON Schema data; pretending that runtime data is a trusted author declaration would skip the raw-schema assertion boundary.
 - **A schema-object library (zod, or the repo's schemastery) for the structured-output subset**: the schema is wire data — plain JSON that crosses the vm realm boundary in `agent({schema})` and lands verbatim in the forced tool's parameters — exactly where live schema objects cannot sit; consuming raw JSON Schema at runtime would need a third-party converter on top (zod core only emits JSON Schema, not the reverse), and it would put a second schema language beside schemastery's config role.
 - **ajv for value validation**: it validates FULL JSON Schema, so the subset gate — the module's actual point, since every accepted keyword must be one the harness enforces — would remain hand-written regardless; it compiles validators through `new Function`; and it would be dsh-tools' first runtime dependency, all to replace the ~70-line value walker while the path-qualified, every-violation error reporting stays custom either way.
 - **Provider JSON mode instead of the capture tool:** it guarantees valid JSON, not schema conformance, and its interaction with tool calling is unclear. The capture tool preserves in-turn validation retries. Provider-side strict tool schemas can later narrow the accepted subset without changing this design.
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
new file mode 100644
index 0000000000..757eafb5d2
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -0,0 +1,80 @@
+# Agent Note: 动态工作流——脚本驱动的多 agent 编排 seam
+
+Status: implemented
+
+[English](2026-07-05-dynamic-workflows.md) | 中文
+
+## 问题
+
+harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`），但需要扇出到多个独立部分的工作——跨多文件审计、迁移、多角度调研、对抗式验证——迫使模型逐轮次编排：每个中间结果都落入父上下文，计划无处持久存储，每一步的协调都要消耗一次模型往返。Claude Code 以[动态工作流](https://code.claude.com/docs/en/workflows)的形式提供了这一能力：模型编写一段 JavaScript 编排脚本，运行时执行它，由脚本（而非对话）持有循环、分支和中间结果。
+
+## 决策
+
+在 `packages/workflow/` 下以 bash seam 的形态（接口／实现／消费方）提供一组工作流能力，以及它在 subagent seam 上所需的结构化输出基础。
+
+### 脚本契约（兼容 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 头移入参数后可以使用时钟和随机数。
+
+与 CC 有一处刻意的严格性差异：钩子误用——未知或延迟的选项（`effort`/`isolation`/`agentType`）、格式错误的参数、超出支持子集的 schema、触发上限、seam 启动失败——会抛出带 `fatal: true` 的 `WorkflowError`，组合器会重新抛出 fatal 错误而非将 item 置为 null。如果不这样做，一个拼错的选项会悄然变成一个与子 agent 失败无法区分的 `null`——这正是本仓库禁止的「被接受后被忽略」的失败模式。另有一处新增：工具的 `args` 参数是一个 JSON 对象（裸列表被包装为一个字段），使协议格式（wire format）保持诚实。
+
+### 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)。
+
+### 引擎（dsh-workflow-workerthread）：每次运行一个 worker 线程
+
+**信任前提**：工作流脚本与模型的 bash 访问具有相同的信任级别。引擎容纳有缺陷的脚本，并保证结果已 settled、值为 JSON 安全、取消后完全停稳；它不防御恶意代码。vm 上下文和 worker 线程不是安全边界：脚本可以逃逸到具有进程级权限的 Node API。沙箱化需要在此 seam 背后使用独立进程或 isolated-vm 引擎。
+
+**为何选择 `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)所有。
+
+引擎暴露一条进程内 `MessageChannel` 测试路径，因为主进程 V8 覆盖率无法观测 worker 执行。
+
+**Meta 是数据**：经 schema 校验的 `meta` 字段以 JSON 形式到达 seam，仅做形状校验。宿主从不执行元数据字面量，否则脚本控制的访问器可以在 worker 隔离之外运行。
+
+**值边界**：`materializeFromRealm` 复制出站值，并拒绝函数、symbol、嵌套 `undefined`、异域原型、循环引用、稀疏数组和非有限数字。数据属性复制使 `"__proto__"` 安全；getter 正常读取，抛出异常的 getter 会大声失败。`args` 通过 `workerData` 传入，暴露前再次克隆。realm 函数被调用而非复制，抛出的值使用全量渲染器，因此 `result` 不会 reject。钩子错误是宿主 realm 的 `WorkflowError`，脚本应基于 `name` 或 `code` 分支而非 `instanceof Error`，如引擎 README 所述。并发、total-agent、item、超时和宽限限制均为经校验的配置。
+
+### 消费方（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 门控。
+
+### 基础：subagent seam 上的结构化输出
+
+`SubagentStartRequest.outputSchema` 由 `dsh-subagent-inprocess` 为两个进程内后端实现。每个结构化子 agent 在 `child.ctx` 上获得自己的作用域捕获工具、指令和强制注册；并发子 agent 可以使用不同的 schema 而不共享可变策略，dispose 子 agent 时移除整个附件。
+
+输出 schema 使一次 schema 有效的已提交捕获成为子 agent 成功完成的必要条件。作用域运行时呈现捕获工具和指令，仅提交成功的最终结果（包括 SDK 调用时外层 `run_code` 的结果），在捕获变为 pending 后拒绝后续副作用，并在提交后不再进行模型步骤即停止子 agent。校验失败仍是可重试的工具错误；没有已提交捕获的正常完成以错误结算。
+
+`ObjectJsonSchema` 是 `dsh-tools` 统一且可强制执行的原始 JSON Schema 子集所提供的对象根消费方视图；不支持的关键字会大声失败，因为该协议数据会逐字成为捕获工具的 parameters。[统一 JSON 值 schema Agent Note](../architecture/2026-07-20-unified-json-value-schema-dsl.md)定义词汇与校验语义，[agent 作用域运行时设计 Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#structured-output-commits-only-authoritative-outcomes)则定义组装、提交、守卫和终止停止算法。
+
+## 测试
+
+worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够度量它。单元测试覆盖脚本辅助函数、fatal 与 nullable 失败、JSON 边界、上限、取消、子 agent 所有权和通过真实循环的结构化输出。built-bin 冒烟测试在纯 Node 下运行单独打包的 `lib/worker.cjs`，带密钥的 e2e 驱动真实子 agent，面向模型的工作流行为通过其所属示例进行快照覆盖。
+
+## 延迟（本轮明确的非目标）
+
+- **后台收集**（启动工具 → run id → 完成通知 → 收集），与 bash/subagent 后台统一一起设计。
+- **日志化 + 恢复**（`resumeFromRunId`、缓存的 agent() 前缀）：实现它会以脚本契约收紧的形式重新引入 CC 的确定性禁令（脚本目前可以读取时钟）。
+- **保存/打包的工作流**（`.deepseek/workflows/` 注册表、斜杠命令界面）和**脚本持久化到运行目录**（工具调用事件已经持久记录了脚本）。
+- **嵌套 `workflow()`**、**token `budget`**，以及 `effort`/`isolation`/`agentType` agent 选项（每个都以命名延迟的消息大声拒绝）。
+- **整体运行的挂钟超时**：取消总能释放调用方（result 在宽限期内 settle），因此总运行时间上限是后台重设计的策略旋钮，不是此处的正确性需求。
+- **超越 worker 线程的引擎加固**：在同一 seam 背后使用 isolated-vm 或独立进程引擎（真正的沙箱化；内存限制）。
+- **ACP 进度 UI**（基于 `workflow/*` 事件的 `/workflows` 风格视图）；事件已为此而存在。
+- **ACP 后端结构化输出**和 **`toolFilter`**（两者仍以能力标志 `false` 门控）。
+
+## 曾考虑的替代方案
+
+- **宿主侧的恶意值防护**（无 trap 代理拒绝、从不调用访问器的描述符遍历、realm 侧预渲染抛出值、realm 构建的 promise/array/error 克隆加结构化 fatal 识别）：否决。每项防御针对的都是信任前提所接受的作者，而线程的序列化边界已经从构造上使跨 realm 值全量化。
+- **进程内 `node:vm` 执行**：机械上最简——无 RPC、无线程——但 `start()` 会在脚本的初始同步切片期间阻塞调用方，第一个 await 之后的同步自旋无法在进程内终止（vm `timeout` 仅覆盖第一个切片），且 `dispose()` 只能在宿主循环上放弃一个未 settle 的脚本。worker 线程引擎保持相同的 vm 上下文脚本表面，同时解除宿主阻塞并使终止成为现实。
+- **后台执行作为默认**（CC 的形态）：延迟。前台同步与 `dsh-tool-subagent` 的当前形态一致，后台语义应在 bash、subagent 和工作流之间统一设计一次，而非逐工具设计。
+- **工作流层为 `agent({schema})` 做 JSON 解析**：在一个消费方重复 seam 关注点，而 seam 的能力标志仍不诚实地为 `false`。
+- **Meta 嵌入脚本中作为 `export const meta = {...}`**（CC 的确切格式）：保持脚本自包含且 CC 脚本可直接使用，但获取 meta 需要在宿主上执行模型编写的文本。即使一个空的限时 vm 上下文也无法约束脚本控制的 getter（当宿主读取结果对象时）。JSON 参数消除了扫描器、执行和宿主自旋漏洞；代价是 CC 脚本的 meta 头必须移入参数（正文保持可直接使用）。
+- **`ValueSchemaSpec` 作为 `outputSchema` 协议类型**：面向作者的形式如今具有等价词汇，但工作流提供的是来自其他 realm 的原始 JSON Schema 数据；将这类运行时数据假装成可信的作者声明，会跳过原始 schema 断言边界。
+- **schema 对象库（zod 或本仓库的 schemastery）用于结构化输出子集**：schema 是协议数据——纯 JSON，跨越 `agent({schema})` 中的 vm realm 边界并逐字落入强制工具的 parameters——正是活 schema 对象无法存在的位置；在运行时消费原始 JSON Schema 需要在其上加一个第三方转换器（zod core 只输出 JSON Schema，不能反向），且会在 schemastery 的配置角色旁边放置第二种 schema 语言。
+- **ajv 用于值校验**：它校验完整 JSON Schema，因此子集门控——模块的真正要点，因为每个被接受的关键字都必须是 harness 强制执行的——无论如何仍需手写；它通过 `new Function` 编译校验器；且它将成为 dsh-tools 的第一个运行时依赖，仅为替换约 70 行的值遍历器，而路径限定的、报告每一处违规的错误报告无论如何都是自定义的。
+- **提供方 JSON 模式代替捕获工具**：它保证有效 JSON，不保证 schema 一致性，且它与工具调用的交互不明确。捕获工具保留了轮次内的校验重试。提供方侧的严格工具 schema 后续可以在不改变本设计的情况下收窄接受的子集。
+
+## 后果
+
+扇出计划现在存在于可重运行的脚本中，`outputSchema` 提供权威的结构化子 agent 结果。每次运行付出 worker 启动和消息端口 RPC 成本，但宿主启动保持非阻塞，取消可以终止 worker，序列化强制执行值边界。worker 线程不是安全边界。无效选项快速失败而非退化为 Claude Code 的 `null`；消费方通过 run handle 保持控制权，观察者仅接收快照。
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
new file mode 100644
index 0000000000..b5882ad5ea
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-05-skill-system.md: 3c328adf09ab0f6ad3388a01bac3661d45c9247e
+2026-07-05-skill-system.zh.md: ba30a3735b73b00afb46baa24f969fd687a759b5
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 eccc58f7c2..3c328adf09 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-05-skill-system.zh.md)
+
 ## Problem
 
 Agent products have converged on a skill pattern: keep the request prompt small by listing only available instruction bundles, then load the full body when the model decides a task matches. Codex, Claude Code, OpenCode, and Kimi Code differ in details, but all separate discovery metadata from complete instructions so a workspace can carry reusable behavior without paying the full prompt cost on every turn.
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
new file mode 100644
index 0000000000..ba30a3735b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -0,0 +1,55 @@
+# Agent Note: Skill 系统——面向 agent 的渐进式指令披露
+
+Status: implemented
+
+[English](2026-07-05-skill-system.md) | 中文
+
+## 问题
+
+Agent（智能体）产品已趋同于一种 skill（技能）模式：保持请求提示词精简，仅列出可用的指令包，当模型判定某任务匹配时再加载完整正文。Codex、Claude Code、OpenCode 与 Kimi Code 在细节上各有不同，但都将发现元数据与完整指令分离，使工作区能承载可复用的行为而无需在每个轮次支付全量提示词开销。
+
+DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和工具使用指南存放在工作区或用户的 agent 配置旁，而非硬编码到 agent loop（智能体循环）中。
+
+## 决策
+
+`@deepseek-ai/dsh-skill` 是纯提供方注册表（`ctx.skills`），`@deepseek-ai/dsh-skill-local` 是随附的本地文件系统提供方，`@deepseek-ai/dsh-tool-skill` 负责会话前缀目录与面向模型的 loader 工具。`dsh-agent-spine-demo` 默认加载注册表、本地提供方和消费方，使 stdio 与 ACP（Agent Client Protocol）应用获得相同行为，同时嵌入式或远程提供方可在不修改注册表或消费方的前提下贡献 skill。其 `skills` 配置将 `registry`、`local` 和 `tool` 分支分别转发给对应的所有者。
+
+提供方插件在 `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。
+
+每个 skill 是 `<name>/SKILL.md` 或带 YAML frontmatter 的 `<name>.md`。`name` 和 `description` 为必填；`whenToUse`、`disableModelInvocation` 和 `metadata` 为可选。名称采用 kebab-case。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 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方契约。
+
+`dsh-tool-skill` 通过 [`agent/session-prefix`](2026-07-07-session-prefix.md) 贡献一个 user-role `<system-reminder>` 目录。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。session-prefix seam 将仅用于请求的目录按 loop 实例冻结，并记录在请求头中，在不将其加入持久化历史的前提下保持可重建性。完整的 skill 正文从不包含在目录中。
+
+`skill({ name })` 工具为当前 agent cwd 加载一个完整 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和标记了 `disableModelInvocation` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
+
+数据结构与目录/工具契约记录在 [skills.md](../../../../docs/core-data-structures/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。
+
+## 曾考虑的替代方案
+
+**将完整 skill 正文注入每条系统提示词。** 否决，因为这破坏了渐进式披露，使每个请求都为可能不适用的指令付出代价。
+
+**仅以斜杠命令暴露 skill。** 否决，因为模型主动加载是核心能力；斜杠/ACP 命令广播不改变发现机制。
+
+**将本地文件系统扫描直接放入 `ctx.skills`。** 否决，因为编码 agent、Web agent 和未来的插件生态需要不同的 skill 来源。提供方注册表与 subagent seam 镜像：注册表拥有冲突解决和消费方，实现拥有加载。
+
+**使用系统提示词段落。** 否决，因为渲染后的系统提示词是单一字符串，而目录是一条具有仅请求生命周期要求的 user-role `<system-reminder>` 消息。[`agent/session-prefix`](2026-07-07-session-prefix.md) 是选定的机制：它将目录置于派生历史之前，并将组合后的消息记录在请求头中。
+
+**在 `~/.dsh/skills/.system` 下物化内置 DSH 编写 skill。** 否决，因为打包的 skill 不应在启动时写入用户主目录，嵌入式或远程提供方在配置后提供 skill。
+
+**递归发现嵌套的 `**/SKILL.md`。** 否决。扁平文件和一级目录包覆盖了配置的根目录，同时使重复处理和目录顺序易于推理。
+
+**手写 frontmatter 解析器。** 否决，因为已接受的 schema 包含一个开放的 `metadata` 对象。窄解析器要么拒绝用户预期可用的合法 YAML，要么膨胀为一个未经评审的 YAML 子集。
+
+## 后果
+
+agent-core 主干包含一个 session-prefix 贡献者、一个本地提供方和一个面向模型的工具。Skill 发现是 cwd 敏感的，因此以不同会话 cwd 值创建 agent 的调用方可以按设计观察到不同的项目 skill 覆盖。
+
+目录对于固定的根目录集合和运行时注册修订版本是确定性的，但不监视磁盘变化；发现结果被缓存，直到运行时注册使缓存失效或进程重启。
+
+## 延后
+
+Fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的契约范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不执行这些字段，`user-invocable` frontmatter 字段同样不会被解析。直接用户调用本身则作为消费方层面的能力交付：TUI 前门基于注册表现有的 `list()` 与 `get()` 方法提供手动 `/skill:<name>` 命令，无需变更注册表、提供方或工具契约——见 [TUI skill 斜杠命令](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
new file mode 100644
index 0000000000..ec785c65c4
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-06-approval-seam.md: e28587e0185530164f300562f7dd5e57255ac515
+2026-07-06-approval-seam.zh.md: 94ffb330cd36ae88975e8ae9d579b3b4606a5c25
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 af063895e2..e28587e018 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-approval-seam.zh.md)
+
 ## Problem
 
 Two callers need to put one question — "may this specific action proceed?" — to a human: `tools/pre-execute`'s `ask` decision (including the Claude-Code hook bridge's `permissionDecision: ask`) and the [sandbox Agent Note](2026-07-06-sandbox.md)'s post-denial one-shot escalation retry. A shared seam keeps them from inventing separate outcome vocabularies, UI routing, cancellation, and audit trails, while guaranteeing that a deployment with no UI can never grant an unanswerable request.
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
new file mode 100644
index 0000000000..94ffb330cd
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
@@ -0,0 +1,139 @@
+# Agent Note: 审批 seam——基于 waterfall（瀑布式事件）应答者的一次性权限决策
+
+Status: implemented
+
+[English](2026-07-06-approval-seam.md) | 中文
+
+## 问题
+
+两个调用方需要向人类提出同一个问题——「这个具体操作可以继续吗？」：`tools/pre-execute` 的 `ask` 决策（包括 Claude-Code 钩子桥的 `permissionDecision: ask`）以及[沙箱 Agent Note](2026-07-06-sandbox.md) 中拒绝后的一次性升级重试。一个共享的 seam 使它们无需各自发明独立的结果词汇、UI 路由、取消机制和审计轨迹，同时保证没有 UI 的部署永远不会批准一个无法应答的请求。
+
+路由问题的核心是归属：审批提示必须到达拥有发起请求的 agent（智能体）的编辑器会话（ACP（Agent Client Protocol）桥在一条连接上多路复用 N 个会话），对无人拥有的 agent（进程内 subagent、测试）失败关闭，并且不侵入没有组合 UI 的部署（headless、CI）。
+
+## 决策
+
+一个包 `dsh-user-approval`（`packages/ui/user-approval`），拥有词汇表和 `ctx.approval` 服务——即机制。策略——谁来应答、某个会话是否需要被询问——不在其中：应答者是 `approval/request` waterfall 监听器，由拥有通道的插件注册（ACP 桥、未来的终端 UI、测试脚本），而每会话的策略层可以在任何人类介入之前做出决定。消费方（`dsh-tools` 的 ask 路由、沙箱升级门禁）将问题解析为一个封闭结果，并从中派生各自的工具结果。刻意设计为一个包，而非能力 seam 的三包拆分（见「替代方案」）。
+
+### 部署如何使用它
+
+一条 `cordis.yml` 条目挂载该 seam。不加载它就是失败关闭的退出方式：消费方在没有注册任何审批代码的情况下拒绝无法应答的请求。
+
+```yaml
+- id: approval
+  name: '@deepseek-ai/dsh-user-approval'
+  # config:
+  #   policy: never   # deployment default for sessions without an override; 'ask' when omitted
+```
+
+仅有这条条目只提供机制，不提供通道：没有组合应答者时，每次 ask 都解析为 `unavailable`，发起请求的工具调用被拒绝——失败关闭无需配置。组合 ACP 应用（`@deepseek-ai/dsh-acp-demo`，如 [acp-agent 示例的默认树](../../../../examples/acp-agent/README.md)）即可闭环：其桥注册一个应答者，通过 `session/request_permission` 向拥有该会话的编辑器发出提示，于是钩子的 `ask` 或升级请求会以一次性 Allow/Reject 提示的形式呈现，附着在已流式输出的工具调用上。`policy: never` 是无人值守姿态：每次 ask 确定性地自动拒绝，在系统提示词中声明，无人类参与。`policy` 在插件加载时对照封闭列表校验；非法值直接抛异常。
+
+组合部署的可观测行为：`allowed-once` 仅允许该次调用继续；拒绝、关闭和通道缺失以三种不同原因拒绝，模型可以区分；轮次内成功的请求会在发起请求的 agent 的会话日志上落一对持久的 `approval/asked`/`approval/decided` 事件；授权不会在发起请求的调用结束后继续存在。空闲时的请求或审计追加失败会拒绝，而不会返回未经审计的决策。
+
+以下是该组合下的一次 ask，逐字取自沙箱示例录制的 `escalation-approved` 场景——模型请求沙箱升级，门禁发起 ask，桥向拥有该会话的编辑器发出提示，用户点击 Allow once：
+
+```
+tool/call        bash {"command": "printf 'escalated\n' > escalated.txt && cat escalated.txt",
+                       "sandbox_permissions": "workspace-write",
+                       "justification": "the user asked to write escalated.txt in the workspace"}
+approval/asked   {"toolName": "bash", "callId": "call_00_…",
+                  "reason": "escalate sandbox to workspace-write: the user asked to write escalated.txt in the workspace"}
+  → session/request_permission {"toolCall": {"toolCallId": "call_00_…"},
+                  "options": [{"optionId": "allow-once", "name": "Allow once", "kind": "allow_once"},
+                              {"optionId": "reject-once", "name": "Reject",     "kind": "reject_once"}]}
+  ← the user picks "Allow once" on the prompt the editor attaches to the streamed bash call
+approval/decided {"outcome": "allowed-once"}
+tool/result      "escalated" — this one call ran under the wider mode; the grant died with it
+```
+
+`escalation-rejected` 孪生场景以 `{"outcome": "rejected"}` 结束：不执行任何操作，模型的结果携带发起方的逐字失败关闭文本（`the user rejected escalating this command to "workspace-write"`）。钩子的 `permissionDecision: ask` 走完全相同的协议；只有发起方和拒绝文本不同（§ dsh-tools 中的 Ask 路由）。在 headless 环境下，同一请求完全跳过提示，直接结算为 `unavailable`。
+
+### 设计细节
+
+#### seam：机制与策略分离
+
+经过校验并成功追加 `approval/asked` 后，服务将 `approval/request` waterfall 解析为 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`。服务借用只读的请求标识和 signal，将中止视为 `cancelled`，把应答者失败和无效返回容纳为 `unavailable`，丢弃迟到的应答，并追加配对的 `approval/decided` 事件。提交前的审计失败会拒绝；追加后的观察者失败无法撤销权威事件。`allowed-once` 仅授权所询问的操作，而 `request()` 会拒绝打开轮次之外的调用，以保证审计对留在持久提交边界内。
+
+应答者是 `approval/request` waterfall 监听器。零监听器会一路委派至 `unavailable`；识别该 agent 的监听器占用先到先得的决策槽，而不识别的监听器必须调用 `next()` 委派。监听器随其 fiber dispose，因此卸载通道会失败关闭。由于兄弟插件的注册顺序不确定，部署应组合一个终端应答者，并保留 `prepend` 给「决策或委派」门禁。
+
+`ApprovalRequest` 携带发起请求的 `agent`、`toolName`、可选的精确 `callId`、人类可读的 `reason` 和可选的 `signal`。它使用 `CallId` brand 而不导入依赖本 seam 的 `dsh-tools`。工具参数仍留在 UI 通过 `callId` 引用的、已流式输出的调用上。
+
+#### dsh-tools 中的 Ask 路由
+
+`ToolRegistry.execute()` 在派发前解析 `ask`：`allowed-once` 继续执行，而拒绝、取消和通道不可用产生三种不同的拒绝原因。机会性消费 `ctx.get('approval')`，让缺失或未挂载的服务失败关闭而不阻塞注册表 fiber。无 agent 的执行同样失败关闭，因为它既没有审计会话，也没有 UI 所有者。
+
+#### 每会话策略层
+
+seam 还拥有[沙箱 Agent Note](2026-07-06-sandbox.md) 所描述的会话级 `'ask' | 'never'` 策略。生效策略由日志中记录的切换在部署默认值之上折叠而成。`'never'` 会在任何应答者运行之前，于 `request()` 内部解析为 `rejected`；`'ask'` 则派发请求，否则一路委派至 `unavailable`。提示词仅声明确定性的 `'never'`，切换叙述会被合并，每个请求仍记录审计对。
+
+#### ACP 应答者
+
+ACP 桥只应答其正向会话映射所拥有的精确 agent 对象。它把 `session/request_permission` 附着到既有 `callId`，声明一次性的 allow/reject 选项，单独映射取消，并且绝不批准未知选项。外部或无调用标识的请求会委派；客户端 RPC 失败变为 `unavailable`。钩子和 `tools/pre-execute` 决定一次调用是否需要询问。
+
+应答者通过 [ACP 支持 Agent Note](2026-06-14-acp-agent-client-protocol.md) 描述的桥精确 agent 归属检查进行路由，实现了[多会话 Agent Note](2026-06-14-acp-multi-session.md) 要求的每会话权限归属。
+
+#### 审计，以及模型看到什么
+
+`approval/asked` 和 `approval/decided` 是持久的仅日志事件；模型只看到从结果派生出的普通工具结果。成功完成时，每个 `asked` 都提交一个 `decided`，包括取消和被容纳的应答者失败。空闲时的请求不追加任何事件；提交前失败会拒绝，而第二次追加失败可能留下一个已经提交但未匹配的 `asked`。
+
+#### 实体与依赖
+
+`dsh-user-approval` 依赖 Cordis，以及会话、agent 和带 brand 的调用契约；`dsh-tools` 与 `dsh-acp` 消费它。沙箱执行器保持独立，因为升级请求归 `dsh-tool-bash` 所有。固定的派发与审计服务仍是一个包；可替换的应答者留在各自的通道所有者中。静态能力授权和 `subagent-acp` 子侧权限应答仍是独立关注点。
+
+### 测试
+
+单元测试固定结果、先到先得的委派、错误容纳、取消、作用域路由、审计配对、不可绕过的 `'never'` 策略、工具拒绝原因，以及通过真实脚本化桥实现的 ACP 归属/结果映射。
+
+快照记录通过 `session/request_permission` 批准和拒绝沙箱升级，以及 `'never'` 提示词与策略切换通知。没有脚本化应答的权限提示会取消并失败关闭。
+
+## 延后
+
+- **`allow_always` 授权存储**：兑现持久授权意味着设计存储、作用域标识（调用？路径？前缀？会话？时间窗口？）和撤销；在设计完成之前，只展示一次性选项（[沙箱 Agent Note](2026-07-06-sandbox.md) § Escalation 记录了开放的作用域问题）。
+- **通过组合应答者录制由钩子驱动的 `ask`**：人类提示协议格式已通过沙箱示例的升级分支录制。钩子矩阵中的 `hook-cc-pretool-ask` 固定无 ApprovalService 时的后备拒绝，而钩子生产者与应答者的组合仍留在单元测试层。
+- **将子 agent 的审批路由到父会话**：`subagent-acp` 的子侧自动应答自己的 `permission` 请求；将其呈现给父会话的编辑器是独立的设计。
+
+## 曾考虑的替代方案
+
+- **单一注册提供方而非 waterfall 监听器**：否决。`registerProvider()` 接口迫使所有组合问题——允许列表预过滤、外部钩子决策者、脚本化测试应答、人类前面的策略门禁——都塞进一个提供方实现。waterfall 从运行时已有的机制中获得组合能力、缺失时失败关闭和 HMR（热模块替换） dispose（资源释放）；seam 的 JSDoc 以约定固定单决策槽语义，而非发明一个提供方注册表。
+- **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进 UI 插件，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
+- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的契约在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/ui/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、抛异常、无效或断开连接的应答路径都会失败关闭。
+- 成功的请求按精确 agent 归属路由，并追加一对可回放、对模型不可见的审计事件；空闲时和提交前失败的请求会拒绝。
+- ACP 归属把提示限制在其会话内，而没有该服务的部署不产生提示或审计事件。
+
+代价与已接受的局限：
+
+- **两个急于决策的应答者竞争同一槽位。** 兄弟插件的监听器顺序不确定，seam 无法仲裁竞争的终端应答者。通过约定缓解（每个部署一个终端应答者；仅对「先决策或委派」门禁使用 `prepend`），而非事件总线不具备的优先级机制。
+- **生产环境验证依赖单一组合。** `ask` 有两个生产者家族——钩子桥通过 `tools/pre-execute`，沙箱升级通过自己的门禁——协议格式录制在沙箱示例的快照套件中；因此在更多部署组合它之前，seam 的真实覆盖面就是这一种组合。
+- **归属以 `Agent` 对象标识为键。** 应答者先在 `agent.session.id` 处解析正向会话映射记录，再要求该记录拥有精确的 agent 对象；当前所有路径在 loop 和各 seam 之间传递同一对象，但未来如果某个边界克隆或代理了 agent，桥会委派并失败关闭——安全，但静默无 UI——届时需要另一种归属契约。
+
+## FAQ
+
+- **在完全没有应答者的部署中（headless、CI）会发生什么？** 每次 ask 穿过空的 waterfall 降级为 `unavailable`，工具调用以「no approval channel is available」原因被拒绝。失败关闭是零监听器的默认行为，不是配置。
+- **授权能持久化吗——「始终允许」？** 不能。`allowed-once` 仅授权单次被询问的操作，服务在请求之间不存储任何内容；`allow_always` 在授权存储设计完成之前刻意不展示（§ 延后）。
+- **模型看到审批的什么？** 只看到发起方从结果派生的工具结果——审计对永远不进入 transcript（文本记录）。三种非授权原因各不相同，模型可以区分人类说「不」、提示被关闭、通道缺失。
+- **谁决定一次调用是否需要 ask？** 策略生产者：返回 `permissionDecision: ask` 的钩子、任何 `tools/pre-execute` 监听器、或沙箱升级门禁。seam 和桥只负责路由和应答；二者都不注入自己对「什么值得弹出提示」的判断。
+- **用户关闭提示或轮次在 ask 进行中中止时会发生什么？** 关闭映射为 `cancelled` 并携带自己的拒绝文本。已中止的 signal 直接结算为 `cancelled` 而不派发；ask 进行中的中止丢弃迟到的应答。当两个审计追加都提交时，任一路径都记录恰好一对事件，绝不会两对。
+- **如果客户端以 harness 从未提供的选项应答呢？** 除已提供的 `allow_once` 之外的任何选项都映射为 `rejected`——来自不合规客户端的未知 optionId 永远不能授权。
+- **subagent 的审批如何路由？** 没有应答者拥有的 agent 穿过整个 waterfall 委派并失败关闭——进程内 subagent 被刻意设计为不可应答。`subagent-acp` 的子侧自动应答是独立的；将子 agent 的 ask 路由到父会话的编辑器已延后（§ 延后）。
+- **`policy: 'never'` 在运行时实际改变了什么？** 服务在派发任何应答者之前，将该会话的每次 ask 解析为 `rejected`（在服务内部，因此没有注册顺序能绕过它）；系统提示词声明该策略；切换在边界处被叙述；每次成功的自动拒绝都会记录审计对。
+- **热重载或 UI 插件在会话中途卸载时会发生什么？** 应答者随其拥有的 fiber 一起 dispose，因此下一次 ask 降级为 `unavailable` 而非挂在死通道上；重新挂载会重新注册应答者，无需追赶状态。
+- **用户在哪里看到自己在批准什么？** 在工具调用本身：提示通过 `callId` 附着在已流式输出的调用上（包含参数），并添加发起方的人类可读 `reason`；请求本身不携带参数副本。
+
+## 先例
+
+本设计复用或对照的仓库内先例：
+
+- `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](2026-06-14-acp-agent-client-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
new file mode 100644
index 0000000000..1c1ae2daf2
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-06-explicit-tool-order.md: bd6d0a04aa470ca33e618957ae1f08c1ef15fcfe
+2026-07-06-explicit-tool-order.zh.md: 5cdecc0e59ff00b6dce7134819f8230072d084cb
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 c78126e92a..bd6d0a04aa 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-explicit-tool-order.zh.md)
+
 ## Problem
 
 Model-facing tool order followed plugin registration order, which depends on concurrent module loading for otherwise independent plugins. That race produced different request headers in CI and snapshot recordings. Because order affects request bytes, caching, and the durable header, it needs an explicit deterministic policy.
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
new file mode 100644
index 0000000000..5cdecc0e59
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
@@ -0,0 +1,51 @@
+# Agent Note: 显式的模型侧工具顺序
+
+Status: implemented
+
+[English](2026-07-06-explicit-tool-order.md) | 中文
+
+## 问题
+
+模型侧的工具顺序此前跟随插件注册顺序，而注册顺序取决于相互独立的插件的并发模块加载。这种竞态在 CI 和快照录制中产生了不同的请求头。由于顺序影响请求字节、缓存和持久化的 header，因此需要一个显式的确定性策略。
+
+## 决策
+
+系统提示词的组装逻辑拥有模型侧工具顺序的权威定义，正如它已经拥有 section 顺序的权威定义一样。`dsh-system-prompt` 上的 `toolOrder?: string[]` 是可选的显式策略：
+
+- 列表中已注册的工具按列表位置排列。
+- 列表中的名称没有对应的已注册工具，属于配置错误。形状错误（缺少 rest 条目或名称重复）在服务构造器中快速失败；未注册的名称则在每次 `assemble()` 时拒绝——这是已注册工具集存在并可供检查的最早时刻（工具插件在服务构造之后才注册），也是唯一的通用时刻（注册随时可能变化；Cordis 没有「所有插件已加载」事件）。在已交付的 agent loop（智能体循环）下，第一个轮次在发出任何模型请求之前就会失败——确切的影响范围见下文「后果」。
+- 已注册但不在列表中的工具，插入到 `'<unlisted-tools>'` rest 条目（`TOOL_ORDER_REST`）的位置，与其他未列出的工具按名称字典序排列。
+- 任何已收集的工具不得使用 `TOOL_ORDER_REST` 作为其 `ToolSchema.name`；组装逻辑在排序之前就会拒绝这个保留名称。
+- 列表必须恰好包含一个 rest 条目，且不得有重复名称。
+- 当 `toolOrder` 未设置时，权威顺序为纯字典序（code-unit 比较，与 locale 无关），因此无需配置即可保证确定性。
+
+`assemble()` 在 `system-prompt/assemble` waterfall（瀑布式事件）之前对提供方工具进行规范化排序，从源头消除注册顺序的差异。waterfall 从这个确定性列表开始；不变的顺序随后流入请求头、冻结的请求和重建检查，无需 loop 特有的排序逻辑。
+
+范围刻意收窄：本 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`。
+
+## 曾考虑的替代方案
+
+- **注册顺序（现状）**：并发导入竞态，依赖宿主环境（上述 CI 抖动），评审中不可见。
+- **插件依赖图的线性化**：该关系是偏序的，独立的工具插件不可比较；抖动发生时偏序已完全满足。
+- **每个插件在其工具贡献上标注 `weight`**：将顺序分散到各插件中，仍需一个无人拥有的全局编号约定（section 的 `order` 分段已经展示了这种协调成本需要手工承担）。
+- **在 `ToolRegistry.schemas()` 中排序（注册表层）**：同样确定，但注册表是一个成员存储，被组装之外的多方消费；排序是提示词组合的关注点，而组装逻辑已经拥有 section 的组合策略。
+- **在 `LlmService` 上加配置 + `orderTools()` 方法，由 loop 在记录 header 前调用**：可行，但仅为在远处应用一个策略就增加了一个公开服务方法和一处 loop 改动；每个未来的请求组合者都必须记得调用。在列表诞生处进行规范化使得无序列表不可表示，且零新增接口。
+- **在 `llm.stream()` 内部规范化**：在 header 事件已记录之后才运行（抖动仍然存在），且需要重建深度冻结的信封，静默地解除了重建不变式。
+- **穷举列表（无 rest 条目）**：每个新加载的工具插件都会导致启动失败；强制的 rest 条目使未列出的工具保持确定性，且其位置是显式的。
+- **启动时校验（由 `dsh-app-boot` 在 `loader.await()` 之后调用 `SystemPrompt.assertToolOrderSatisfied()`）**：能将错误配置变为启动时死亡而非首轮次失败，但代价是一个公开服务方法加上通用启动胶水对单个服务的结构耦合，且无法替代组装时检查（嵌入式调用者从不运行 app boot；注册在 boot 之后仍会变化）。也没有现成事件可以承载该检查：Cordis v4 没有 ready 类事件，`loader/entry-init`/`internal/status` 在加载中途触发（与工具注册存在竞态——正是本 Agent Note 要消除的熵源），而 agent 生命周期事件不会早于组装。在 `assemble()` 设置单一执行点被判定值得接受较晚的失败时刻。
+
+## 后果
+
+- 每个由注册表构建的组装在任何宿主上都以确定性工具顺序开始；在没有专家监听器刻意改变的情况下，每个 `request/header` 事件和模型请求都继承该顺序。CI 与本地之间的注册顺序翻转从结构上被消除，默认为字典序。
+- 初始 `PromptAssembly.tools` 是权威的，因此 waterfall 监听器从模型侧顺序开始；提供方注册顺序在该协作 seam 之前无处可观测。
+- 快照套件中唯一固定请求头的 fixture（`text-turn`）携带新的权威工具顺序；按照固定请求头设计，其他 ACP 快照仍将大块 header 清洗为 `{{system}}`/`{{tools}}`。
+- 步骤之间的纯工具重排与其他 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 位置、提供方顺序无关性、共享名称、无效列表、未知或保留名称、waterfall 前的权威列表，以及监听器添加的工具不被重新排序的规则。Loop 测试固定：跨注册排列的已记录与已分发顺序一致、通过 agent-core 和两个 app 的转发、深度冻结的请求，以及在配置了未知名称时的平衡轮次失败（无步骤、无 header、无适配器调用）。快照回放仅在固定的 `text-turn` header 中保留完整的权威列表；其他 fixture（测试前置数据）继续使用 `{{tools}}`。
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
new file mode 100644
index 0000000000..287deaff20
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-06-sandbox.md: c1307a7201ed1bc331a86d4ffee002d69fd1d5e5
+2026-07-06-sandbox.zh.md: 4e3d4951f71a602bc78551c90dda04317d0f8284
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index d5d0c6d5aa..c1307a7201 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-sandbox.zh.md)
+
 ## Problem
 
 A coding agent needs this product path: bash subprocesses — and the hook commands that ride them — execute under a restricted file sandbox by default; if and only if the sandbox actually denies an operation, the model may request one user approval for that same operation and, once granted, retry it once with wider permissions. An every-tool boundary is deliberately NOT the claim: fs/web/todo execute in-process where an `execve` wrapper is meaningless (§ In-process tools), and the cross-family boundary is staged follow-up work (§ Deferred phases). Without a shared vocabulary, every tool reinvents approval fields, denial parsing, retry matching, and permission-state hints.
@@ -117,7 +119,7 @@ fs/web/todo execute in-process, so their sandbox semantics are policy at their s
 
 - **Unit:** pin platform selection and profiles, fail-closed runner classification, per-call mode/root resolution, per-process facts, escalation validation and outcomes, permission preset folding and write-through, narrator coalescing, ACP advertisement and validation, and turn-enclosed config writes.
 - **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. The real ACP composition pins permission switching and rejects unknown presets. CI rejects a silent all-skip.
-- **With-key:** drive a real model, runner, bridge answerer, and disk effect through granted and rejected escalation; unavailable credentials or runners self-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 permission config-option wire, preset and knob events, prompt deltas and notices, 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 a successful workspace-write mutation; this distinguishes session-root resolution from the process fallback without depending on runner-specific denial text. Other snapshots start unconfined so unrelated fixtures remain platform-independent, and policy scenarios switch explicitly.
 
 ## Deferred phases
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
new file mode 100644
index 0000000000..4e3d4951f7
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -0,0 +1,207 @@
+# Agent Note: 子进程沙箱——约束 seam、原生 runner、升级机制与按会话模式
+
+Status: implemented
+
+[English](2026-07-06-sandbox.md) | 中文
+
+## 问题
+
+一个编码 agent 需要如下产品路径：bash 子进程（以及依附其上的钩子命令）默认在受限的文件沙箱下执行；当且仅当沙箱实际拒绝了某个操作时，模型可以为同一操作请求一次用户批准，获批后以更宽的权限重试一次。本设计刻意不声称覆盖所有工具：fs/web/todo 在进程内执行，`execve` 包装对它们毫无意义（§ 进程内工具）；跨工具族的统一边界属于分阶段后续工作（§ 延迟阶段）。如果没有共享词汇，每个工具都会各自重新发明批准字段、拒绝解析、重试匹配和权限状态提示。
+
+harness 是一个 SDK，因此约束必须是开发者可组合的能力：是否启用沙箱、每个平台使用哪个后端，都应作为一等条目写在叶子 `cordis.yml` 中，而非藏在某个执行器的私有机制里。而首选 runner `bwrap` 恰恰在沙箱最重要的主机上不可用（精简容器、禁用了非特权 userns、LSM 拒绝 `mount`），因此备选 runner 必须随 SDK 一起交付，而不能假设主机已有。
+
+仅有约束还留下两个缺口。拒绝后没有升级路径就是死路：模型只能放弃，这会迫使运维人员全局配置 `workspace-write` 或 `danger-full-access`，从而使沙箱形同虚设。而模型可见的旋钮（沙箱模式、批准策略）在 agent 生命周期内会变化——ACP 用户切换按会话设置、运维人员在进程停止期间编辑 `cordis.yml`——模型绝不能基于过时的信念行动：每次请求时的实际状态是什么、agent 存活期间发生了什么变化、无人看管时又发生了什么变化，都需要有明确答案。
+
+## 决策
+
+一个 seam、一条按平台的本地后端链、一个消费方，加上两个上层杠杆：按调用的升级路径与按会话的运行时模式。以下所有内容均从叶子 `cordis.yml` 组合而来；不触及 `agent-loop`。跨工具族 fs 强制与按会话工作区根目录已经作为后续设计落到同一策略载体上；剩余阶段——`subagent-acp` 消费方、更多环境与 Windows 链——仍列在 § 延迟阶段。
+
+### 部署方式
+
+四条 `cordis.yml` 条目即可将一个无约束的编码 agent 转变为沙箱产品路径；[`examples/acp-agent`](../../../../examples/acp-agent/README.md) 默认使用此组合：
+
+```yaml
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'   # the per-platform runner provider (ctx.sandbox)
+- id: bash
+  name: '@deepseek-ai/dsh-bash-sandbox'    # the confined executor, replacing dsh-bash-local behind ctx.bash
+  config:
+    mode: workspace-write                  # the deployment default every session starts from
+    workspaceRoot: !!js process.cwd()      # the boundary workspace-write may write under
+- id: approval
+  name: '@deepseek-ai/dsh-user-approval'        # the escalation gate's channel (the approval Agent Note)
+  config:
+    policy: ask
+- id: permission
+  name: '@deepseek-ai/dsh-permission'      # one product-facing select over both mechanism knobs
+```
+
+这一替换对 `ctx.bash` 的所有消费方透明：bash 工具、钩子命令和后台任务照常运行，通过提供方返回的包装 argv spawn。删除 `sandbox` 和 `permission` 条目、将 `bash` 替换为 `@deepseek-ai/dsh-bash-local` 即为退出——执行恢复为无约束，升级字段从工具 schema 中消失，因为它们是基于已挂载执行器的能力门控，而非基于配置。仅省略 `approval` 则保留约束但以自身错误文本关闭每次升级；`permission` 还要求 approval seam 和约束执行器同时存在，因此部分组合的 preset 层在加载时即大声失败。
+
+配置错误大声失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段（命令 spawn 之前）抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner seam。
+
+被拒绝的文件操作返回 `[sandbox: file access denied under <mode> mode]` 标记，并附带不要绕过拒绝的指令。约束执行器添加配对的 `sandbox_permissions` 和 `justification` 字段，用于一次经批准的重试，该重试必须严格宽于会话的有效模式。授权仅放宽该次重试；拒绝则不执行任何内容，返回 `the user rejected escalating this command to "<mode>"`，且不允许再次请求。提示词不声明沙箱模式，以避免基于常驻标签的预防性拒绝。当 `dsh-permission` 被组合时，ACP 暴露一个 `Permissions` 选择器，其 preset 同时写入两个旋钮事件；不匹配的旋钮组合显示为仅可切换离开的 `custom`。只有切换到确定性的 `'never'` 批准策略才会在提示词中声明并叙述。
+
+### 设计细节
+
+#### 范围界定
+
+OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还将适用于 ACP subagent 子进程。文件系统、web 和其他工具在进程内执行，需要在各自的 seam 层面实施策略；argv 包装无法约束一个闭包了 `ctx` 的函数。既有的 bash request/spec 拆分承载按调用的覆盖，而 `tools/pre-execute` 和 approval seam 负责人的决策。
+
+#### seam：`ctx.sandbox`
+
+`dsh-sandbox` 拥有词汇和 `SandboxProvider` 契约：`confine(argv, policy)` 返回调用方应当 spawn 的替代 argv（经过包装，使进程及其所有子进程在约束下运行），加上所选后端达到的 `enforcement` 完整度、其拒绝方言（`denialSignatures`，该后端内核在拒绝文件操作时打印到 stderr 的子串）、以及其 runner 失败方言（`runnerFailureSignatures`，runner 本身失败——因而命令从未运行——时的自我标识方式）；没有可用后端时抛出失败关闭的 `SANDBOX_UNAVAILABLE` 错误，绝不静默放行。词汇：`SandboxMode`（`read-only` / `workspace-write` / `danger-full-access`，仅限文件操作——不声称覆盖网络和进程可见性）、`SandboxEnforcement`（`full` / `partial`）、`SandboxExecutionPolicy`（每次能力调用的完整 mode + workspace root）以及 `SandboxPolicy`（提供给约束后端的子集）。
+
+策略随每次调用而非提供方携带：两个消费方可以在同一时刻以不同策略约束（bash 在 `read-only` 下运行，而一个受约束的子 agent 保持其状态目录可写），且经批准的升级重试是一次带有更宽策略的新调用——在配置固定的提供方模式下无法表达。
+
+该 seam 仅约束与宿主机共享文件系统和内核的子进程。容器、microVM 和远程执行器不是此 seam 的后端——它们以环境一致的组替换整个能力实现（`ctx.bash`、`ctx.fs`），因为一个 bash 在容器中运行而 fs 工具写主机的 agent 生活在两个割裂的世界中。
+
+留待需要时再决定：网络限制是作为独立的 `network_mode` 到来，还是在某个 runner 同时强制两者后合并进 `sandbox_mode`；以及 `SandboxPolicy` 是现在就增加额外的可写根授权（launcher 已支持 `--rw <path>`），还是等到升级机制需要时再加。
+
+#### 本地后端与随附 launcher
+
+`dsh-sandbox-local` 在提供方生命周期内选择一个平台 runner 并缓存结论。Linux 功能性探测 `bwrap` 然后 Landlock；macOS 使用 Seatbelt。不支持的平台和不可用的 runner 失败关闭。每次包装携带后端特定的拒绝签名和 runner 失败签名，以便 `dsh-bash-sandbox` 区分被拒绝的文件操作与损坏的沙箱。`runnerCommand` 作为运维人员对 bwrap 形状 runner 的断言跳过选择，但缺失或不可执行的命令仍被归类为沙箱失败，绝不无约束地运行负载。
+
+launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI——除静态链接的 musl 外无其他库，因此审计面仅为该文件加内核的稳定 syscall 契约）：`--ro <path>` / `--rw <path>` 授权，`--`，被包装的 argv；它在自身上安装规则集并 `exec`（规则集跨 `execve` 继承，且它在限制前设置 `no_new_privs`）；`--probe` 在一个短生命周期子进程中强制最大规则集，仅当内核确实强制时才以 0 退出；launcher 失败以 125 退出且不 exec。
+
+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 flag，而 harness 将沙箱模式映射为授权。将入口点与其二进制一起版本化，使探测解析和启动语法保持对齐。
+
+后端 profile 共享模式契约但在必要的主机授权上有所不同。Landlock 和 Seatbelt 在 read-only 模式下仅允许 `/dev/null`；workspace-write 还允许各自所需的主机临时目录根。每次包装携带后端特定的拒绝签名。Landlock 在较旧的 ABI 无法管控所有操作时报告 partial enforcement，而成功的 bwrap 和 Seatbelt profile 报告 full enforcement。
+
+#### bash 消费方
+
+`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，并把即将 spawn 的确切 `['bash', '-c', command]` argv 交给 `ctx.sandbox`。拒绝是与其他结果正交的事实，依据当前 runner 的 stderr 方言保守分类。Runner 失败优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
+
+模型看到的仅是结果事实：静态工具描述解释拒绝标记（`[sandbox: file access denied under <mode> mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试；当升级字段被公布时，被拒绝的结果还额外携带升级提示本身，使被认可的同轮次重试在决策点被提示，而非依赖模型回忆描述（§ 升级机制）。没有提示词段落声明沙箱模式（§ 按会话模式）。
+
+#### 升级机制：拒绝后一次经批准的更宽重试
+
+`BashExecRequest.sandboxPolicy` 是可选的完整按调用输入；解析后的 spec 使该字段显式。`BashExecutor.sandboxMode` 仍是公布已挂载执行器能否兑现该策略的能力事实，因此只有约束组合才暴露升级。seam 接受任何显式策略；工具拥有会话解析和「仅更宽」的升级规则。非沙箱执行器诚实地保持无约束。
+
+`ctx.sandboxPolicy.resolve()` 在执行器运行前盖章完整执行策略——显式升级模式 > 会话覆盖 > 配置默认值，且 `SessionHeader.cwd` > 配置的后备根目录。`SandboxBashExecutor.resolve()` 在 spec 上保留该策略，或为直接的无 agent 调用方提供部署后备值，使 `run()`/`start()` 永不读取可变会话状态。每进程包装事实以返回的 `BashProcess` 为键；`onProcessDone()` 在 `done` 结算前分类 stderr 并给该句柄盖章，因此重叠进程各自保留自己的模式和 runner 方言。
+
+当约束执行器被挂载时，`bash` 公布配对的 `sandbox_permissions` 和 `justification` 字段。schema 暴露完整的封闭升级词汇，因为有效模式是按会话的；执行拒绝任何不严格宽于该调用有效模式的目标。批准在执行之前解析。`allowed-once` 仅将授权模式盖章到该请求上，而 `rejected`、`cancelled`、`unavailable`、缺失的 approval 服务或缺失的 agent 都以各自不同的结果文本失败关闭。授权不持久化。
+
+升级是对被拒绝命令的同轮次重试，使用最窄的足够 `sandbox_permissions` 和一个 `justification`；批准提示是同意步骤。它必须基于实际的拒绝，除非会话已观察到相同的被拒绝访问；禁用或被拒绝的批准终结该命令。重试、批准决策和结果使用既有的工具和批准事件。`dsh-tool-bash` 拥有请求动作，因为执行器 seam 既没有 agent 也没有用户交互所需的 call id。
+
+仍未决定：持久授权超出沙箱模式之外的作用域标识是什么——确切调用、路径、命令前缀、会话或时间窗口——这是公布 `allow_always` 选项之前必须回答的问题。
+
+#### 按会话模式：会话日志即存储
+
+```
+effective(session) = findLast(the session's own knob events)?.value ?? the composition-config default
+```
+
+默认值是组合配置（`cordis.yml`）——运维人员拥有，进程范围。运行时切换是会话范围的覆盖，记录为该会话自身日志中的一条仅日志事件。重启免疫（恢复会话时回放其日志，覆盖自然恢复，无需追赶机制）和多会话隔离（一个编辑器标签页的 `workspace-write` 不会干扰另一个的 `read-only`）都是构造性的自然结果，且不存在任何外部配置存储。
+
+**每个旋钮一种事件，由其领域拥有**——这是每个既有事件族已遵循的可合并扩展 `SessionEventMap` 惯用法（`dsh-user-approval` 中的 `approval/*`、hooks 包中的 `hook/*`）：
+
+```ts
+interface SessionEventMap {
+  'sandbox/mode': { mode: 'read-only' | 'workspace-write' | 'danger-full-access' }
+  'approval/policy': { policy: 'ask' | 'never' }
+}
+```
+
+每个拥有者导出相同的三件套：事件声明、纯 fold（`effectiveSandboxMode(events)` / `effectiveApprovalPolicy(events)`——一个 `findLast`，类型化到领域的封闭联合），以及唯一的写入路径（`setSandboxMode(session, mode)` / `setApprovalPolicy(session, policy)`——切换即其事件；没有任何东西在带外修改状态）。无共享拥有者服务、无通用 facts map、无注册表：第三个旋钮只需将约 40 行模式复制到自己的包中。执行在两侧都遵循 fold——bash 工具的按调用盖章将其作为 § 升级机制优先级链的中间层读取，approval seam 的 `'never'` 门控是[批准 Agent Note](2026-07-06-approval-seam.md) 同一模式的另一侧。
+
+沙箱模式不在提示词中叙述；拒绝结果在需要时报告模式，避免基于常驻标签的预防性拒绝。批准策略不同：只有 `'never'` 被声明，因为自动拒绝在行为上与用户的「不」无法区分。策略变更通知被合并，由下一个步骤前检查点递送，重启后有基于日志的回退。通知来源从事件位置推断：最后一个 request header 之后的旋钮事件是用户驱动的；未记录的漂移是运维人员或配置驱动的。
+
+**编辑器界面**是协议原生的[会话配置选项](https://agentclientprotocol.com/protocol/session-config-options)——该规范对 session modes 的替代（计划在 ACP v2 中移除），已有 SDK 类型。当 `ctx.permission` 被组合时，bridge 在 `session/new` 和 `session/load` 中公布一个 `permission` 选择器（category `mode`）；其选项是部署的 preset 表，其 `currentValue` 是 `PermissionService.current()` 对会话日志加组合默认值的结果。随附的 `workspace-write` 和 `danger-full-access` preset 各自捆绑一个沙箱模式与一个批准策略，并写入两个领域 setter；preset 表之外的旋钮组合报告为仅可切换离开的 `custom`。`session/set_config_option` 通过权限服务验证并切换，然后返回完整的刷新状态（规范契约）。
+
+**轮次封闭是提交边界。** 开放轮次中的切换立即追加。空闲切换保持在 bridge 记录上待定，在下一次提示词提交时、assembly 或执行之前追加到开放轮次中；每个旋钮以最后写入为准。开放性来自日志边界而非 `agent.status`，setter 不从 `session/event` 监听器内追加，因为那会重排后续观察者。锚定之前，响应叠加待定值。崩溃丢弃它，重新加载返回持久 fold。
+
+#### 进程内工具
+
+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 强制，而不是统一包装器。
+
+### 测试
+
+- **单元测试：** 固定平台选择和 profile、失败关闭的 runner 分类、按调用的模式/根目录解析、按进程事实、升级验证和结果、权限 preset fold 和写入透传、叙述器合并、ACP 公布和验证、轮次封闭的配置写入。
+- **Keyless 真实 runner：** 在提供方和 bash 消费方层面对 bwrap、Landlock 和 Seatbelt 执行真实文件系统效果测试；一个真实 Cordis 上下文通过已交付的 bash 和 fs 工具并发驱动两个项目会话，证明在自身根目录写入成功、在兄弟根目录写入被拒绝。Packed-install 覆盖率证明注册表 launcher 保持可执行。真实 ACP 组合固定权限切换并拒绝未知 preset。CI 拒绝静默全跳过。
+- **With-key：** 以只读模式启动真实 ACP 组合，让模型驱动的 bash 写入命中 runner 的拒绝标记，再通过已授权与被拒绝的 workspace-write 重试驱动 bridge 应答器和磁盘效果；不可用的凭证或 runner 自动跳过。
+- **快照：** 固定权限 config-option 协议格式（wire format）、preset 和旋钮事件、提示词 delta 和通知、以及两个脚本化的 approval 分支。一个真实 ACP 示例场景把会话放在用户主目录下，同时让部署后备根目录指向 `/tmp`，然后固定一次成功的 workspace-write 变更；这能区分会话根目录解析与进程后备值，而不依赖 runner 特定的拒绝文本。其他快照以无约束启动，使无关 fixture（测试前置数据）保持平台无关；策略场景显式切换。
+
+## 延迟阶段
+
+每个阶段在被拾起时获得完整设计，对照当时的代码验证，并在其涉及的层级带上单元测试、真实 API e2e 和快照覆盖率落地。
+
+- **第二个消费方**——`subagent-acp` 可选地约束子 agent（按调用策略；默认无约束——子 agent 必须写入自己的持久化）。
+- **更多环境**——环境一致的能力组示例（如 bash+fs 对一个容器）。
+- **Windows 链**——`PLATFORM_CHAINS.win32` 保留为空（失败关闭）；填充它意味着来自 AppContainer/restricted-token 家族的约束 runner，从其自己的仓库按 `node-addon-landlock-run` 模板交付，加上其 profile 方言和拒绝/runner 失败签名。
+
+## 曾考虑的替代方案
+
+- **命令字符串启发式预检**：否决。无法理解展开/子进程/符号链接；严格尝试（运行它，让内核决定）是唯一可信的拒绝信号。
+- **即使平台仅有一个后端也功能性探测**：否决。探测用于在候选者之间仲裁；只有一个时无需决策，且探测开销对每个会话的首次约束命令征税（对未来重量级后端而言代价过高）。runner 自身执行时的失败关闭拒绝加 `runnerFailureSignatures` 分类承载了安全属性。
+- **提交构建好的 launcher 二进制**：否决。diff 中的二进制不可审查且膨胀历史；经审查的源码 + 原生 CI 构建 + launcher 仓库的字节固定发布演练使二进制远离所有代码树。
+- **安装时编译 launcher**：否决。将 C 工具链强加给每个消费方；仅在碰巧有编译器时才存在的备选不是备选。
+- **从一个构建器交叉编译两种架构**：否决。仅为重建两个约 70 KB 的二进制就需要携带一个固定的交叉工具链（rustup targets、zig 或容器镜像）；每架构的原生 runner 已存在，各自构建自己的平台包（`node-addon-require-builtin` 模式，launcher 仓库自己的流水线）。
+- **无备选（bwrap 或失败关闭）**：否决。将失败集中在沙箱最重要的主机上，最终因放弃而降级到 `danger-full-access`。
+- **将机制保留在 `dsh-bash-sandbox` 内部**：否决。阻塞既有的第二个消费方，使未来阶段从一个 bash 插件的配置中读取模式，且无法表达升级。
+- **提供方上的配置固定模式**：否决。每进程一个模式；无法服务具有不同策略的并发消费方，也无法表达一次性放宽重试。
+- **一个接口同时覆盖容器/VM**：否决。`confine(argv)` 预设共享文件系统；环境隔离是作为一致组部署的能力兄弟后端。
+- **通用 ToolRuntime 包装任何工具**：否决。对进程内工具（闭包了 `ctx`）机械上不成立；声明式效果重写对 fs/web/todo 而言不合理。
+- **在执行器内部（`dsh-bash-sandbox`）请求批准**：否决。没有可路由的 `agent`，没有可附加提示词的 `callId`；添加它们会让传输 seam 了解会话和 UI——工具层持有两者并拥有面向模型的词汇。
+- **同一工具调用内自动重试**：否决。日志无法重建的隐藏重入：一个 `tool/call` 会产生两次具有不同策略的执行——重试是一次新的带有自身参数和结果事实的已记录调用。
+- **无条件公布升级字段**：否决。在 `dsh-bash-local` 下它们是死杠杆——公布 harness 无法兑现的选项会制造注定失败的授权；能力门控仅需注册时一次读取。
+- **默认值相对的升级阶梯（仅公布比执行器注册时默认值更宽的模式）**：否决。按会话覆盖使默认值成为错误的基线——切换到比默认值更窄的会话恰恰失去它需要的杠杆，而在 `danger-full-access` 默认值下字段完全消失，同时一个被覆盖为 `read-only` 的会话仍处于约束中却没有升级路径。枚举固定封闭的目标词汇；严格放宽是针对会话有效模式的按调用执行检查。
+- **按会话动态工具 schema**：否决。schema 设计上是注册表全局的（一套 assembly 词汇、固定 header 快照契约），按会话重新注册只能买到执行时严格放宽检查已保证的东西，代价是按会话的 schema 表面和每次切换的 header 变动。
+- **将重试硬匹配到先前的拒绝**：否决。命令字符串同一性脆弱（引号、`workdir`、env 前缀、作为失败阶段重试的管道）——要么误拒诚实的重试，要么被轻易满足；真正的边界是人看到命令 + 理由。仅在 `allow_always` 授权存储需要机器可检查的范围时才重新考虑。
+- **通用 `env/state` facts map 加拥有者服务**：否决。approval 和沙箱独立组合，因此任何一方的状态都不应拖入第三个包；单键 fold 各自是一个 `findLast`，拥有者服务自然消解；没有跨旋钮的不变式，因此原子多键补丁无收益。
+- **通过 `agent/user-message` + 总线事件叙述**：否决。它预设了一个不存在的轮次入口 seam（真正的 seam 是 `agent/prompt-submit`），而步骤前检查点的位置使一个监听器能够同时服务合并的轮次入口通知和轮中即时性约束。
+- **提示词中常驻声明沙箱模式（+ 切换叙述器）**：先交付后移除，基于实际证据：当每个请求中都有 `Bash commands run under the "read-only" file sandbox.` 时，模型拒绝尝试被拒绝后可升级的工作（首次手动会话中十二个轮次有五个以零工具调用结束），将沙箱变成了软锁定。拒绝标记在需要时命名模式，升级字段承载恢复路径；批准旋钮保留其声明，因为自动拒绝在行为上与人的「不」无法区分。
+- **用专门的簿记事件追踪「上次告知」**：否决。`request/header` fold 已记录模型看到的确切提示词；将封闭的候选句子解析回来替代了第二条簿记流——事件仅在它们本身即为存储时才需要。
+- **ACP session modes 而非 config options**：否决。preset 已经是一个部署定义的 config-option 选择器，且 modes 计划在 ACP v2 中移除。
+
+## 后果
+
+已交付并固定的内容——测试中的各层级分别保障：
+
+- 被拒绝的命令以 `sandbox_permissions` + `justification` 重试时，通过组合的应答器链提示用户；授权使该次调用在更宽模式下运行（结果事实如此报告），而其他所有调用保持各自的有效模式；每种非授权结果产生各自不同的错误文本且不执行任何内容。
+- 升级字段恰好在已挂载的执行器约束时存在；不严格宽于调用有效模式的请求以自身文本失败关闭且不提示任何人；没有 ApprovalService 的部署对升级调用失败关闭，对普通调用不影响。
+- 系统提示词从不声明沙箱模式（批准 `'never'` 策略是唯一被声明的旋钮），且整个交互——header、旋钮事件、通知、批准、结果——仅从会话日志即可重建，除两个旋钮事件外无额外事件类型。
+- N 次空闲切换每个旋钮最多产生一个锚定事件（净零序列不锚定任何事件——客户端回显当前选择的无操作推送不记录任何内容）；批准策略切换最多以一条合并通知叙述；轮中沙箱切换由下一次调用的盖章兑现。
+- 恢复的会话的覆盖生效并报告给编辑器，无需特殊处理；进程停止期间变更的默认值在会话的首个新请求前被叙述，归因于运维人员。
+- 两个并发会话永远看不到彼此的状态、通知或配置选项。
+- 同一个 Cordis 上下文中的两个并发项目会话解析各自独立的工作区根目录；bash 和 fs 写入在调用方会话的 cwd 内成功，对其相邻会话的 cwd 则失败。
+- `agent-loop` 未被触及——一切搭载 `systemPrompt.section`、`SessionEventMap` 合并、`agent.inject()`、`agent/pre-step`、`agent/prompt-submit` 和 ACP handler 表面。
+
+代价与已接受的限制：
+
+- **单一包装的幻觉被有意放弃。**`tools/pre-execute` 包装加提示词约定无法解决沙箱批准——正确的设计需要结构化拒绝、原生 runner 探测、按调用策略承载和一致的跨工具族强制，本设计为此付出了代价。
+- **`read-only` 通过后续设计成为跨工具族边界。** 本 Agent Note 最初只交付 bash 强制；[跨工具族 fs 沙箱 Agent Note](2026-07-14-cross-family-fs-sandbox.md) 通过沙箱化的 `ctx.fs` 提供方把同一模式词汇扩展到文件系统工具，并将 mode/root 配置和 `sandbox/mode` 覆盖迁移到 `ctx.sandboxPolicy`（§ 进程内工具）。
+- **Windows 没有后端。** 其链槽保留为空——失败关闭，绝不穿透；填充它是延迟阶段。
+- **Seatbelt 层级依赖 Apple 已弃用但仍交付的 `sandbox-exec` CLI。** 作为 darwin 的唯一候选，它无需探测即被选中，因此未来移除会在执行时作为 runner 失败分类浮现——重新抛出 `SANDBOX_UNAVAILABLE`，命令从未运行；失败关闭，绝不开放。
+- **Landlock 约束的完整度取决于运行内核的 ABI。** 报告为 `enforcement: 'partial'` 而非拒绝——这是有意的权衡，使备选在旧内核主机上仍可用。
+- **launcher 作为注册表依赖到达。** 通过其自身仓库的发布流水线（经审查的 C 源码、原生 CI 构建器、字节固定的发布演练）加上本仓库的版本固定获得信任——真实内核 e2e 测试腿是通过安装字节为行为背书的。
+- **模型可能过度请求。** 在没有拒绝依据的情况下升级，或在 `workspace-write` 足够时选择 `danger-full-access`：描述引导且枚举强制阶梯，但人的提示词是实际门控；`approval/asked` 原因使过度请求可审计，且 `prepend` 策略应答器可以自动拒绝部署永远不想要的模式。
+- **公布的目标集是静态的，而有效模式是按会话的**（schema 是注册表全局的）——已处于最宽模式的会话仍被提供这些字段。构造上无害：执行时的严格放宽检查（而非枚举）是安全边界——非放宽请求以自身文本失败且不提示任何人。
+- **授权的升级不等于可工作的沙箱。** 不可用的后端即使对授权升级到约束模式也仍然失败关闭——在平台没有链或所有探测失败时于 `confine()` 阶段，在未探测的唯一 runner 拒绝时于执行阶段（归类为沙箱失败而非命令失败）——而授权的 `danger-full-access` 运行根本不触及提供方：此时授权（而非探测）是权威。
+- **空闲切换存在于 bridge 内存中，直到下一次提示词提交锚定它。** 该窗口内的崩溃将其回退（在 `session/load` 时报告），且永不再提交提示词的会话永不持久化它——已接受，loop 拥有的空闲提交轮次留作未来工作（如果持久性成为需求）。
+- **批准叙述器的重启基线解析提示词文本。** 封闭的候选句子由写入模块本身拥有，因此措辞变更是同一文件中写入器+解析器的协调编辑；header 早于该段落的会话静默采用当前策略而不发通知。
+- **批准段落仍是动态提示词表面**（`'never'` 切换会破坏该会话的提供方提示词前缀缓存）。已接受：策略切换罕见，且模型基于过时的 `'never'` 行动更糟。沙箱旋钮不再触及提示词。
+- **模型可能持有关于沙箱模式的过时信念**（没有任何东西宣布切换）。有意接受：下一次尝试的标记或成功会纠正它，而宣布的观察到的失败模式——预防性拒绝——比一次浪费的重试更糟。
+
+## FAQ
+
+- **一个命令返回了 `[sandbox: file access denied under read-only mode]`——它失败了吗？** 它运行了，内核拒绝了一个文件操作：拒绝是与退出码正交的结果事实。教学禁止绕过它重试；唯一被认可的动作是以升级请求重试同一命令一次。
+- **如何区分损坏的沙箱与失败的命令？** Runner 失败在分类中优先于拒绝：匹配包装的 `runnerFailureSignatures` 的失败运行意味着命令从未运行——前台重新抛出结构化的 `SANDBOX_UNAVAILABLE` 并附带 runner 的 stderr 行，后台任务盖章 `sandbox.runnerFailed` 并渲染自己的标记。损坏的沙箱永远不会被读作失败的命令，且命令永远不会无约束运行。
+- **在没有后端的平台上会发生什么——今天的 Windows？** `confine()` 抛出失败关闭的 `SANDBOX_UNAVAILABLE`，命令永不 spawn；`win32` 是保留的空链，由测试固定为同样失败关闭，直到 Windows runner 填充它（§ 延迟阶段）。
+- **`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` 呈现，并且可以作为一次新的精确命令重试的依据。
+- **编辑器的模式切换何时生效？** 轮中：立即追加，由下一次调用的盖章兑现。空闲：保持在 bridge 的会话记录上，在下一次 `agent/prompt-submit` 时锚定到其开放轮次中，N 次切换合并为最多一个事件（净零则无）；锚定前崩溃回退它，`session/load` 报告真实状态。模型不被告知——其下一个命令直接在新模式下运行。
+- **重启后什么存活——如果运维人员在进程停止期间改了配置默认值呢？** 覆盖从会话日志回放（`effective = fold ?? config`），因此恢复的会话以零追赶机制保持其模式；离线漂移的默认值以与切换相同的方式改变行为（批准策略因被声明，还额外以运维人员/配置归因叙述）。
+- **结果上的 `enforcement: 'partial'` 是什么意思？** 所选后端强制其内核 ABI 管控的子集——例如 ABI v3 之前的 Landlock 不管控路径 truncate——并以结构化方式如此声明而非拒绝主机；探测的报告行区分各种情况。bwrap 和 Seatbelt profile 构造上管控所有承诺的文件操作，因此始终报告 `full`。
+
+## 先例
+
+本设计复制或对比的仓库内先例：
+
+- [能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)——接口/实现/消费方拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。
+- `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/core-data-structures/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。
+- [批准 seam Agent Note](2026-07-06-approval-seam.md)——升级请求通过的通道；其应答器 waterfall（瀑布式事件）、审计对和单包理由记录在那里。
+- [事件溯源会话](../architecture/2026-06-11-event-sourced-sessions.md)与[轮次封闭不变式](../architecture/2026-06-15-turn-enclosure-invariant.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-07-mcp-client-plugin.i18n.yaml b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
new file mode 100644
index 0000000000..f199fdb731
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-07-mcp-client-plugin.md: 90c43383882034954f33b79459fac273e60b9e0e
+2026-07-07-mcp-client-plugin.zh.md: a60aa537a03dec5add7e91fd78b91fece4e4a259
diff --git a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.md b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.md
index 95cad58b46..90c4338388 100644
--- a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.md
+++ b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-07-mcp-client-plugin.zh.md)
+
 ## Problem
 
 The harness had no way to consume tools from the MCP (Model Context Protocol) ecosystem. MCP is the emerging standard for tool servers — GitHub, filesystem, databases, code search, and hundreds of community servers expose tools via MCP. Users want to point the harness at one or more MCP servers and have their tools appear as native model-facing tools, without writing per-server glue code.
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
new file mode 100644
index 0000000000..a60aa537a0
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md
@@ -0,0 +1,214 @@
+# Agent Note: MCP 客户端插件——连接外部 MCP 服务器并桥接其工具
+
+Status: implemented
+
+[English](2026-07-07-mcp-client-plugin.md) | 中文
+
+## 问题
+
+harness 此前无法消费 MCP（Model Context Protocol）生态中的工具。MCP 是工具服务器的新兴标准——GitHub、文件系统、数据库、代码搜索以及数百个社区服务器都通过 MCP 暴露工具。用户希望将 harness 指向一个或多个 MCP 服务器，让其工具以原生的模型可见工具形式出现，而无需为每个服务器编写胶水代码。
+
+`ToolRegistry` 已经接受原始 JSON Schema 工具定义（`dsh-tools` README 中有记录：「Raw JSON-Schema tool definitions (from MCP servers) are still accepted by `ToolRegistry.register()` directly」），扩展实操手册（cookbook）也勾勒了预期模式（「MCP | one plugin per server: discover tools → `ctx.tools.register()`」）。基础设施已就绪，缺的是桥接插件。
+
+## 决策
+
+### 包
+
+单个包（package） `@deepseek-ai/dsh-mcp-client`，位于 `packages/mcp/mcp-client/`。不做能力 seam 的三包拆分——可预见范围内不会有第二种 MCP 客户端实现，且约定是「不要预防性拆分」（[能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)）。
+
+### SDK
+
+使用官方 [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)（`Client`、`StdioClientTransport`、`StreamableHTTPClientTransport`）。harness 不自行实现 JSON-RPC，与 ACP 委托给 `@agentclientprotocol/sdk` 的做法一致。
+
+### 范围
+
+仅 MCP Client（不含 server 端——ACP 已承担「将 harness 暴露为 agent」的角色）。仅桥接 **Tools**——Resources 和 Prompts 延后处理（它们需要 harness 侧尚不存在的消费机制，且设计空间较大）。
+
+### 插件形态
+
+命名空间插件（具名导出 `name`/`inject`/`Config`/`apply`，无 `export default`）。`inject: ['tools']`。每个 MCP 服务器对应 `cordis.yml` 中的一个插件实例——同一个包以不同配置加载 N 次，与 `dsh-tool-subagent` 相同。
+
+### 配置
+
+以 `transport` 字段为判别的扁平联合类型：
+
+```typescript
+interface StdioConfig {
+  transport: 'stdio'
+  serverName: string          // required namespace, ^[A-Za-z0-9_-]{1,32}$
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+  toolCallTimeoutMs?: number  // default 60_000
+}
+
+interface StreamableHttpConfig {
+  transport: 'streamable-http'
+  serverName: string          // required namespace, ^[A-Za-z0-9_-]{1,32}$
+  url: string
+  headers?: Record<string, string>
+  toolCallTimeoutMs?: number  // default 60_000
+}
+
+type Config = StdioConfig | StreamableHttpConfig
+```
+
+`serverName` 是稳定的本地标识，用于在模型可见名称（见下文）中为该服务器的工具提供命名空间。它有意设计为用户配置，而非远端的 `serverInfo.name`：远端名称是不可信输入、跨部署不唯一（同一服务器的生产和预发布实例报告相同名称）、且可能在服务器升级时变化——这些都不得静默重命名模型可见工具。多个活跃实例使用重复的 `serverName` 属于配置错误：后加载的实例在启动时以可操作的错误消息失败，绝不静默覆盖或跳过。短 `serverName`（如 `gh`）也是缩短公开名称的调节手段。
+
+`cordis.yml` 用法示例：
+
+```yaml
+- id: mcp-github
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: github
+    transport: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+
+- id: mcp-web
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: web
+    transport: streamable-http
+    url: http://localhost:3000/mcp
+    headers:
+      Authorization: !!js `Bearer ${process.env.MCP_TOKEN}`
+```
+
+模型看到的是 `mcp__github__create_issue`、`mcp__github__search_code`、`mcp__web__search`。
+
+### 生命周期
+
+启动时从 `cordis.yml` 加载。HMR（热模块替换）（`@cordisjs/plugin-hmr`）提供热替换：编辑 yml 条目触发旧实例的 dispose（资源释放）（断开连接、注销工具），并创建新实例（连接、发现、注册）。目前不提供运行时动态 API。公开名称是 `(serverName, rawName)` 的纯函数，因此保持 `serverName` 不变的 HMR 替换会重建完全相同的模型可见名称——会话历史和权限规则保持有效——而添加或移除不相关的服务器永远不会重命名已有工具。
+
+### 工具发现与注册
+
+每个 MCP 工具有两个名称：
+
+- `rawName`——MCP `Tool.name` 的原始值，仅用于协议通信（`tools/call`）。
+- `publicName`——在 `ToolRegistry` 中注册的全局唯一模型可见名称：
+
+      mcp__<serverName>__<rawName>
+
+这种按服务器限定的形式是多服务器 agent 客户端的事实标准——所有被调研的终端用户产品都按服务器限定 MCP 工具名（[Claude Code](https://code.claude.com/docs/en/agent-sdk/mcp#tool-naming-convention) `mcp__github__list_issues`、[Codex](https://openai.com/index/unrolling-the-codex-agent-loop/) `mcp__weather__get-forecast`、[Gemini CLI](https://geminicli.com/docs/tools/mcp-server/#3-tool-naming-and-namespaces)、[VS Code](https://github.com/microsoft/vscode/blob/ab9ec62c6a61e429a9abd612ff220c3f4834c9ea/src/vs/workbench/contrib/mcp/common/mcpServer.ts#L217-L260)、[Cline](https://github.com/cline/cline/blob/52fdbb1d72f7324a28142a7ba7678d4b53c902f4/sdk/packages/core/src/extensions/mcp/name-transform.ts#L20-L35)、[Roo Code](https://github.com/RooCodeInc/Roo-Code/blob/b867ec9145750d0ae1ff7f02d35406e9bf2a0b16/src/utils/mcp-name.ts#L117-L140)、[Goose](https://github.com/block/goose/blob/b3a012cbdde854b0fe14f95b1c48543bf6517c0a/crates/goose/src/agents/extension_manager.rs#L1391-L1441)、[OpenCode](https://github.com/anomalyco/opencode/blob/d199b1bff90282a4f9cd6251b5fc7b16875a52f6/packages/opencode/src/mcp/catalog.ts#L117-L120)）；`mcp__<server>__<tool>` 的拼写方式与 Claude Code 和 Codex 一致。`mcp__` 前缀将 MCP 注册与原生工具的命名空间隔离，并为权限/遥测规则提供稳定的匹配模式（`mcp__*`、`mcp__github__*`）。
+
+1. 连接时：遍历 `client.listTools()` 的分页结果，推导每个工具的 `publicName`，然后通过 `ctx.tools.register()` 将其注册为原始 `ToolDefinition`。MCP 的 JSON Schema 和描述原样透传（不做 `defineTool` DSL 转换）；仅替换模型可见的 `name`。
+2. 监听 `notifications/tools/list_changed` → 重新执行同步（dispose 上一代、注册新一代）。确定性命名意味着未变化的工具在重新同步后保持原名。
+3. 执行器闭包持有 `rawName`；公开名称永远不发送给服务器，也永远不被解析以还原原始名称。
+4. 无 `presentCall`/`presentResult`——ACP 桥接的通用卡片兜底负责渲染。
+5. 工具在系统提示词中是透明的——除名称本身外不附加「[via MCP]」标注。
+
+### 公开名称规范化
+
+MCP 允许工具名最长 128 字符且可包含 `.`；DeepSeek 的函数名契约允许 `[A-Za-z0-9_-]` 且最多 64 字符。公开名称按确定性规则规范化：非法字符替换为 `_`，当替换或截断改变了名称时，追加 `(serverName, rawName)` 标识的 12 位十六进制 SHA-256 hash，确保不同的 MCP 标识永远不会坍缩为同一个公开名称：
+
+```typescript
+function publicToolName(serverName: string, rawName: string): string {
+  const joined = `mcp__${serverName}__${rawName}`
+  const normalized = joined.replace(/[^A-Za-z0-9_-]/g, '_')
+  if (normalized === joined && normalized.length <= 64) return normalized
+  const hash = sha256(`${serverName}\0${rawName}`).slice(0, 12)
+  return `${normalized.slice(0, 64 - 13)}_${hash}`
+}
+```
+
+### 名称冲突处理
+
+MCP 仅保证工具名在[单个服务器内](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-names)唯一；跨服务器冲突是常态而非例外（一项[微软研究院调查](https://www.microsoft.com/en-us/research/blog/tool-space-interference-in-the-mcp-era-designing-for-agent-compatibility-at-scale/#namespacing-issues-and-naming-ambiguity)覆盖 1,470 个服务器，发现 775 个冲突的工具名；仅 `search` 就出现在 32 个服务器中，官方 GitHub 服务器发布的是裸名 `create_issue`）。始终启用的命名空间从结构上杜绝冲突，而非在冲突发生时再处理：
+
+- 两个服务器都发布 `search` → 共存为 `mcp__github__search` 和 `mcp__web__search`。
+- 名为 `search` 的原生 harness 工具不受影响。
+- 重复的 `serverName` 配置使后加载的实例在启动时失败（见配置一节）。
+- 服务器列出重复的工具名属于无效工具列表：同步抛出异常，上一代注册保持不变。
+- 替换期间的注册表冲突只可能意味着外部工具占据了该服务器的 `mcp__<serverName>__` 命名空间：部分代注册被回滚（该服务器零工具），并以醒目日志记录错误。
+
+工具永远不会被静默跳过；哪些工具可用永远不取决于插件加载顺序。
+
+### 命名不变式
+
+1. 每个 MCP 工具拥有稳定标识 `(serverName, rawName)`；每个活跃标识恰好对应一个公开名称。
+2. 公开名称是确定性的、全局唯一的，且满足 DeepSeek 64 字符 `[A-Za-z0-9_-]` 契约。
+3. MCP `tools/call` 始终接收原始的 raw name。
+4. 连接、断开或重新同步不相关的服务器永远不会重命名已有工具。
+5. 注册顺序永远不决定哪个工具可用。
+
+### 工具执行
+
+为来自同一个 MCP 服务器的所有工具提供统一的 `execute` 处理器：
+
+1. 解析 `rawName`（执行器闭包持有它），以配置的超时时间调用 `client.callTool({ name: rawName, arguments }, { signal: exec.signal })`——公开名称永远不发送给服务器。
+2. 映射结果：
+   - 多个 `text` 内容块 → 以 `'\n'` 连接为单个 `TextBlock`（必要原因：`flattenText` 使用 `join('')` 无分隔符，多块会丢失块间边界）。
+   - `image` 内容块 → 丢弃并 `ctx.logger.warn`（harness 没有图片内容块类型；[删除图片 Agent Note](../simplification/2026-07-04-drop-image-content-block.md)）。
+   - `isError: true` → 映射到 harness 的 `isError` 结果路径（`{ content: [...], isError: true }`）。
+3. 取消：`exec.signal`（来自 agent loop（智能体循环）的取消）透传给 MCP SDK 的 `callTool`，后者向服务器发送 `$/cancelRequest`。
+
+### 子进程环境（stdio 传输）
+
+复用 `dsh-subagent-acp` 的 `buildChildEnv` + `SENSITIVE_ENV_PATTERN` 清洗逻辑：过滤环境变量（剥离匹配 `/KEY|SECRET|TOKEN/i` 的凭证形变量），然后将 `config.env` 覆盖合并到顶层。显式配置的 env 不受清洗影响。
+
+### 断连 / 崩溃
+
+不自动重连。如果 MCP 服务器进程退出或传输层关闭：
+
+1. effect dispose → 所有已注册工具被注销（fiber 作用域的 disposer）。
+2. 后续模型对这些工具的调用 → `ToolNotFoundError` → `isError: true`。
+3. 恢复：用户编辑 `cordis.yml`（触发 HMR 重载）或重启 harness。
+
+这与 ACP subagent 模式一致：「崩溃即终态，报告错误，清理资源，不重试。」
+
+## 曾考虑的替代方案
+
+### MCP Server 端（将 harness 工具暴露给外部 MCP 客户端）
+
+延后。ACP 桥接已将 harness 暴露为 agent 服务器。再加一层 MCP server 会以不同协议重复这一功能，而用户的首要需求是消费外部工具，而非暴露自身工具。
+
+### 能力 seam 三包拆分（接口 / 实现 / 消费方）
+
+否决。可预见范围内不会有替代的 MCP 客户端实现——MCP 只有一个协议、一个 SDK。约定是「不要预防性拆分」，直到出现第二种实现。
+
+### 指数退避自动重连
+
+v1 否决。引入复杂性（工具已注册但暂时不可用的部分可用状态），且 stdio 进程崩溃通常表明配置问题，重试无法修复。HMR 已提供手动恢复路径。如有需要，可在未来作为 `reconnect: boolean` 配置项添加。
+
+### 桥接 Resources 和 Prompts
+
+延后。Resources 需要 harness 侧的机制来决定何时注入内容（系统提示词？按需？模型触发？）。Prompts 需要 harness 尚不具备的「提示词模板」概念。两者都需要独立设计；Tools 是高价值、低风险的起点。
+
+### 原始模型可见工具名加可选 `toolPrefix`
+
+否决。这是最初的提案，基于「大多数 MCP 服务器已在工具名中使用语义前缀（如 `github_create_issue`）」这一前提。该前提不成立：官方 GitHub 服务器发布的是 `create_issue`，参考文件系统服务器发布 `read_file`，Sentry 发布 `search_issues`——且上述微软调查表明冲突在生态规模下很常见。冲突时再加前缀（或 warn-and-skip）还会使可用工具集取决于插件加载顺序，且添加不相关服务器时工具可能被静默重命名——在对话中途使会话历史和权限规则失效。所有被调研的多服务器 agent 产品都不使用裸名。
+
+### 仅服务器命名空间（`github__create_issue`，无 `mcp__` 前缀）
+
+v1 否决。它能防止跨服务器冲突，但无法将 MCP 注册与原生 harness 工具分离，也丧失了 MCP 全局策略匹配模式（`mcp__*`）。前缀仅多花 5 个字符；`mcp__<server>__<tool>` 拼写与 Claude Code 和 Codex 一致，最大化模型的熟悉度。如果 ToolRegistry 未来引入源感知命名空间，届时可作为命名策略变更重新考虑去掉字面前缀。
+
+### 从服务器公告的 `serverInfo.name` 派生命名空间
+
+否决。远端名称不可信、跨部署不唯一、升级时可变；工具标识和权限规则不得静默跟随它。命名空间是本地配置。
+
+### 在工具结果中保留多个 TextBlock
+
+否决。DeepSeek 序列化器中的 `flattenText()` 在将 `ContentBlock[]` 扁平化为协议格式（wire format）时使用 `join('')`（无分隔符）。多个 text 块会静默丢失块间边界——这是正确性缺陷。所有现有工具返回单个 TextBlock；MCP 桥接遵循同一做法。
+
+## 测试
+
+覆盖率按层级命名；每个行为放在能表达它的最低成本层级。
+
+- **单元测试**（`tests/mcp-client.spec.ts`、`tests/apply.spec.ts`，mock MCP SDK）：`publicToolName` 算法（干净名称、规范化、截断加 hash、确定性、不同标识的分离）、raw 与 public 的协议纪律、跨服务器与原生工具共存、重复 `serverName` 加载失败与预留释放、无效工具列表拒绝、代切换/回滚、重新同步失败时的保留、结果映射、取消、配置 schema 校验。100% 逐文件覆盖率门禁约束该包。
+- **E2E**（`tests/mcp-client.e2e.ts`，无需密钥）：使用真实 MCP 协议对接仓库内的 fixture（测试前置数据）服务器、`@modelcontextprotocol/server-everything` 和 `@modelcontextprotocol/server-filesystem`（stdio 传输），以及进程内 `StreamableHTTPServerTransport` 服务器（Streamable HTTP 传输）——命名空间下的发现、带点号名称的端到端规范化、执行往返、重复 `serverName` 拒绝、dispose。
+- **快照**：刻意不做。MCP 工具不引入新的 transcript（文本记录）呈现面——它们以原始 `ToolDefinition` 注册，通过 ACP 桥接的通用卡片兜底渲染，该兜底已由桥接的单元测试套件固定（`packages/ui/acp/tests/stream-update.spec.ts`）。将 MCP 服务器添加到快照示例的 `cordis.yml` 会改变已固定的 `text-turn` 系统提示词 fixture（迫使每条录制的预期输出都需要带密钥重新录制），且使每次回放依赖于 spawn 外部 MCP 服务器进程——而新增渲染行为为零。如果后续变更为 MCP 工具引入专属渲染意图，该变更届时自行声明快照覆盖。
+
+## 后果
+
+- 每个 MCP 服务器只需 `cordis.yml` 中的一条配置即完成集成：`serverName: filesystem` 加一条 stdio 命令（或一个 Streamable HTTP URL），就能将 `mcp__filesystem__read_file` 放入模型的工具列表，可调用，协议上使用原始的 `read_file`。
+- 公开名称是会话历史和权限/配置表面的一部分；命名算法是由测试固定的 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 原样透传——垃圾进垃圾出；这是服务器作者的责任，不是桥接的。
+- **Stdio 进程管理**：行为异常的 MCP 服务器如果忽略信号，可能卡住 dispose。Cordis fiber 的 dispose 有有界的完全停稳过程；卡住的传输层最终在框架层面超时。
+- 崩溃恢复是手动的（HMR 编辑或重启）——v1 已接受；`reconnect` 配置作为未来工作保持开放。
diff --git a/.agents/notes/implemented/feature/2026-07-07-session-prefix.i18n.yaml b/.agents/notes/implemented/feature/2026-07-07-session-prefix.i18n.yaml
new file mode 100644
index 0000000000..63ac02b35e
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-07-session-prefix.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-07-session-prefix.md: 322413f541706244a8a9a9113c0b79693fe54ccd
+2026-07-07-session-prefix.zh.md: 710cfbd2656d132640d39b1d62374ef2d16be612
diff --git a/.agents/notes/implemented/feature/2026-07-07-session-prefix.md b/.agents/notes/implemented/feature/2026-07-07-session-prefix.md
index 7faf80cf80..322413f541 100644
--- a/.agents/notes/implemented/feature/2026-07-07-session-prefix.md
+++ b/.agents/notes/implemented/feature/2026-07-07-session-prefix.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-07-session-prefix.zh.md)
+
 ## Problem
 
 A plugin often owns a session-stable opener the model must always see — a skills catalog, an AGENTS.md digest, a workspace baseline. Before this seam the harness offered two homes, and both are wrong for that content. The system prompt is one rendered string: message-shaped content (a user-role `<system-reminder>` envelope, a multi-message primer) does not fit it, and providers weight conversation messages differently from system text. Durable history (`agent.inject()`, a `context/message` at session start) makes the opener permanent: every `deriveMessages()` consumer replays it, the compaction retention walk owns it, forks bake it in stale, and a resume cannot refresh it — a catalog captured at session birth outlives the world it described.
diff --git a/.agents/notes/implemented/feature/2026-07-07-session-prefix.zh.md b/.agents/notes/implemented/feature/2026-07-07-session-prefix.zh.md
new file mode 100644
index 0000000000..710cfbd265
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-07-session-prefix.zh.md
@@ -0,0 +1,43 @@
+# Agent Note: 会话前缀——派生历史之前的仅请求消息
+
+Status: implemented
+
+[English](2026-07-07-session-prefix.md) | 中文
+
+## 问题
+
+插件经常拥有一段会话级别稳定的开场内容，模型必须始终看到它：技能目录、AGENTS.md 摘要、工作区基线。在引入本 seam 之前，harness 为这类内容提供了两个归属位置，但两者都不合适。系统提示词是一个渲染后的单一字符串：消息形态的内容（user 角色的 `<system-reminder>` 信封、多消息引导序列）放不进去，而且提供方对会话消息和系统文本的权重处理不同。持久化历史（`agent.inject()`、会话启动时的 `context/message`）使开场内容变为永久：每个 `deriveMessages()` 消费方都会回放它，压缩（compaction）的保留遍历拥有它，fork 会将其以陈旧状态固化，恢复也无法刷新它——会话诞生时捕获的目录会比它所描述的世界活得更久。
+
+显而易见的第三种选项——让插件在请求发出途中编辑 `messages`——被[可重建请求 Agent Note](../architecture/2026-07-05-reconstructable-requests.md)禁止：每个由循环构建的请求都是会话日志的纯函数，因此无论哪个通道承载开场内容，都必须精确记录它所发送的内容。缺失的是一个带有持久记录的仅请求消息通道。
+
+## 决策
+
+`agent/session-prefix` 是 agent 事件映射上的一个 waterfall（瀑布式事件）（[`packages/core/agent/src/types.ts`](../../../../packages/core/agent/src/types.ts)）：监听器接收一个冻结的空种子并返回扩展（规范的贡献方式是前置插入 `[mine, ...await next()]`，在协议格式上产生注册顺序）。agent loop（智能体循环）（[`packages/core/agent-loop/src/loop.ts`](../../../../packages/core/agent-loop/src/loop.ts)）在每个循环实例中触发一次，惰性地在实例首次 `agent/pre-step` 之前执行；组合后的列表被深拷贝、深冻结、缓存在实例上，并在该实例发出的每个请求中置于整个派生历史之前——紧接在提供方的 system 槽位之后（[协议格式顺序](../../../../docs/core-data-structures/core.md#the-request-envelope-llmcallconfig-and-the-logged-header)）。
+
+三个属性承载了这一设计：
+
+- **仅请求，记录在 header 中。** `deriveMessages()` 从不返回前缀；它唯一的持久记录是实例锚定的 `request/header` 快照上的 `EpochHeader.messagePrefix`——可重建请求 Agent Note 已为请求的非历史部分拥有的通道，因此不引入新的会话事件。配套的 [`dsh-agent-loop/invariant`](../../../../packages/core/agent-loop/src/invariant.ts)对每个循环构建的请求重新计算 `messagePrefix + boundary derivation`；启用该贡献时，未记录的前缀无法到达协议格式。
+- **按实例冻结。** 复用是结构性的，而非靠纪律保证：缓存的产物在会话中途不可变，因此提供方的提示词缓存从构造上成立，前缀以每步零边际成本扩展了可缓存区域。进程重启或 `ctx.agents.resume()` 产生新实例：它重新组合，任何漂移都可追溯地落在 `'resume'` header 快照上。这就是本 seam 创建的路由规则：会话冻结的开场内容走前缀；会话中途变化的内容走仅追加历史通道（`agent.inject()` 或工具/prompt-submit 的 `additionalContexts`——[拦截 seam Agent Note](2026-06-30-interception-seams.md)），每条都是一次性支付的持久 `context/message`，之后被前缀缓存覆盖。
+- **在持久请求信封中保持精确。** 组合先于实例的首次 `agent/pre-step` 和请求边界。第一个已路由请求会把当前前缀记录在其 header 上，因此步骤后的 token 压力会将精确前缀与实际提示词、工具和已路由模型一起读取；通用的步骤前检查点 seam 不携带压缩专属参数。被取消/dispose 中断的组合会被丢弃，永不缓存：感知中止的监听器的降级回退不会泄漏到后续请求中，下一轮次在活信号下重新组合。
+
+由于组合在边界快照之前运行，组合监听器的会话追加会加入当前请求的派生历史。压缩在结构上不可能触及前缀（或系统提示词）：它重写的是表面节点，而 header 状态从不进入表面。
+
+## 测试
+
+[拦截测试](../../../../packages/core/agent-loop/tests/interception.spec.ts)固定了以下行为：没有变更 header 时的组合一次复用、前置插入顺序、空前缀省略、不可变性、组合在步骤前检查点之前完成，以及已路由 header 上的前缀；[取消测试](../../../../packages/core/agent-loop/tests/cancel.spec.ts)固定了丢弃与重新组合。Session、不变式、token-meter 和压缩测试覆盖 header 往返、请求重建与持久前缀感知的压力核算。快照归一化保留前缀计数，[固定 header 场景](../testing/2026-07-06-pin-request-header-content-in-one-scenario.md)拥有内容，默认示例保持无前缀。与提供方无关的 seam 无需专门 e2e；带密钥的 [request-cache e2e](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts) 覆盖了其缓存经济性。
+
+## 曾考虑的替代方案
+
+- **每请求 `before`/`after` 槽位，每步重新计算**（最初提出的形态：一个每请求触发的 waterfall，贡献冻结的 `before` 消息置于历史之前、新鲜的 `after` 消息置于历史之后）：否决。每步重新组合 `before` 会引入漂移，必须记录为完整的变更 header；`after` 槽位位于不断增长的历史之后，其 token 在每个请求中重复支付，且其后的所有内容不可缓存。对照各替代方案衡量，当前所有更新模式都能通过持久追加更廉价地满足（支付一次，此后缓存读取），而唯一没有归属的内容是会话稳定的开场——它需要的是冻结，而非重新计算。
+- **系统提示词分段**（`system-prompt/assemble`）：对此类内容否决。assembly 渲染为单一 `system` 字符串，消息形态的开场放不进去；且系统提示词被设计为每步重新组装（变化时带完整的变更 header），而开场内容需要按实例冻结的语义。
+- **持久化历史开场**（会话启动时 `inject()`）：否决。永久历史正是问题陈述中的失败模式——到处被回放、可被压缩、在恢复后仍保持陈旧状态。
+- **按轮次组合而非按实例组合**：否决。轮次边界的重新组合要么与日志静默失同步，要么强制产生变更 header；且它每次触发都会破坏提供方缓存。合理的刷新点是实例边界，`'resume'` 快照已在那里可追溯地记录漂移。
+- **通过 `agent/pre-step` 携带提示词/前缀，用于临时压力估算**：否决，因为它把通用生命周期 seam 耦合到一个消费方，而且仍会遗漏更晚的请求路由和工具；步骤后的回放会从持久的已路由 header 读取请求信封的每个字段。
+- **专用会话事件承载前缀**：否决。header 事件按设计就是请求的非历史记录；第二个事件会为同一事实提供第二个归属，并多出一个需要保持完整的编解码器。
+
+## 后果
+
+- `agent/pre-step` 保持通用的 `(agent, turn, step, signal)` 检查点。压缩不接收 prefix 参数；`ctx.tokenMeter` 在步骤后从规范的已路由 header 折叠前缀。
+- 贡献者的内容在会话中途变化时，直到下一个实例才会被重新读取——这是设计意图。需要会话中途目录更新的部署，应将变更通知路由到仅追加历史通道，支付一条持久 `context/message`。
+- 被放弃的 `after` 槽位意味着请求尾部附近没有仅请求通道；仓库中没有任何功能需要它，且恢复它会重新引入本设计旨在避免的每步重复支付成本。
+- 空组合即为规范缺失：无贡献者的部署不记录额外的 header 字节，其请求就是裸派生。
diff --git a/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.i18n.yaml
new file mode 100644
index 0000000000..95661f953c
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-08-repeat-tool-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
+2026-07-08-repeat-tool-guard.md: 67ec29c6c9fa38bf1d5935c469f3f71b1119dc3a
+2026-07-08-repeat-tool-guard.zh.md: 01037f29810c781c33beee414e50412a0c9b0f89
diff --git a/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.md b/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.md
index 08f5bb01cf..67ec29c6c9 100644
--- a/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.md
+++ b/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-08-repeat-tool-guard.zh.md)
+
 ## Problem
 
 A model stuck in a loop re-issues the same tool call with byte-identical arguments — re-running a failing grep, re-reading an unchanged file, polling a command that already gave its answer — and each round trip burns tokens, wall-clock, and (for paid APIs) money without adding information. The harness has nothing that notices: the loop has no step budget, no plugin tracks call repetition, and the model only escapes when it happens to vary its own behavior. The failure mode is real and cheap to detect — [pi-repeat-tool-guard](https://github.com/Kingwl/pi-repeat-tool-guard) ships exactly this as a pi coding-agent extension: count consecutive identical calls and, past a threshold, append a `<system-reminder>` telling the model to stop repeating itself and change course.
diff --git a/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.zh.md b/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.zh.md
new file mode 100644
index 0000000000..01037f2981
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.zh.md
@@ -0,0 +1,76 @@
+# Agent Note: 重复工具调用守卫插件
+
+Status: implemented
+
+[English](2026-07-08-repeat-tool-guard.md) | 中文
+
+## 问题
+
+模型陷入循环时，会以字节级相同的参数反复发起同一个工具调用——重新运行一条失败的 grep、重新读取一个未变化的文件、轮询一条已经给出答案的命令——每一轮往返都消耗 token、挂钟时间以及（对付费 API 而言）金钱，却不带来新信息。harness 目前没有任何机制能察觉这一点：循环没有步骤预算，没有插件追踪调用重复，模型只有在碰巧改变自身行为时才能跳出。这种失败模式真实存在且检测成本极低——[pi-repeat-tool-guard](https://github.com/Kingwl/pi-repeat-tool-guard) 正是以 pi coding-agent 扩展的形式提供了这一功能：统计连续相同调用次数，超过阈值后追加一条 `<system-reminder>` 告诉模型停止重复并换个方向。
+
+harness 已经具备 pi 扩展所使用的全部 seam，而且更好：[拦截 seam Agent Note](2026-06-30-interception-seams.md)赋予 `tools/post-execute` 一种经过认可的方式，将面向模型的上下文附加到已完成的调用上；循环缓冲并注入该上下文，同时保持调用/结果的邻接关系；注入的上下文是一条已记录的 `context/message`——因此原生守卫无需新增会话事件即可满足「模型可见 ⟺ 已记录」规则。缺少的只是插件本身。
+
+## 决策
+
+该守卫是一个循环卫生插件，而非面向模型的工具。它统计对同一工具以相同规范化参数发起的连续调用次数，并在配置的阈值处注入建议性提醒。它从不延迟、阻止或改写调用；模型自行决定是换种方式重试还是结束。
+
+插件为 `@deepseek-ai/dsh-repeat-tool-guard`，位于 `packages/guard/repeat-tool-guard/`，开辟 `guard/` 分组用于循环卫生插件（单包（package）分组有先例：[todo-write Agent Note](2026-06-29-todo-write-tool.md)发布了 `todo/tool-todo`）。它注册两个监听器，将状态保存在以存活 `Agent` 对象为键的 `WeakMap` 中——工具注册表是上下文级别的单例，其 waterfall（瀑布式事件）交错所有 agent（智能体）的调用（subagent 运行在同一个上下文上），因此按 agent 分键是正确性要求，而非锦上添花；弱对象键还使得纯清理用途的 disposal 监听器不再必要。
+
+- **`tools/post-execute`（waterfall）**——唯一的检测点。监听器同时接收 `(exec, result)`，因此计数和提醒投递无需跨事件的 pending map（pi 扩展需要它，仅因为其 `tool_call`/`tool_result` 钩子是分开的事件）。它始终通过 `next()` 委托，当命中阈值时，将提醒前置到下游决策的 `additionalContexts`——这正是[钩子桥接](2026-06-30-hook-bridges.md)已采用的「观察并丰富」姿态，遵守 waterfall 契约。计数放在此处而非 `tools/pre-execute`，因为 post-execute 也会为被拒绝的调用触发（`ToolRegistry.execute` 将 deny 路由到同一条流水线），而模型反复敲击一个被拒绝的调用恰恰是值得打破的循环。
+- **`agent/prompt-submit`（waterfall）**——纯重置钩子：通过 `next()` 委托，清除提交 agent 的链。用户介入改变了上下文；跨越介入的重复不是循环。
+
+### 检测语义
+
+链的键是 `(tool name, canonical arguments)`；与前一个被追踪调用相同的调用递增该 agent 的连续计数器，不同的被追踪调用将其重置为 1。规范化方式为深度键排序加 `JSON.stringify`：`ToolExecution.arguments` 按构造就是循环中 `JSON.parse` 的输出（或格式错误的参数 JSON 的原始字符串回退，其本身也是可比较的值），因此 pi 原版对 bigint/循环引用/`undefined` 的处理在此没有输入，被有意去除。
+
+两条刻意的规则，均记录在[包 README](../../../../packages/guard/repeat-tool-guard/README.md) 中，因为它们是读者否则只能猜测的行为：
+
+- **未追踪的调用对链透明。** 被 `include`/`exclude` 排除的调用既不递增也不重置计数器，因此 `grep X → todo_write → grep X` 在 `todo_write` 被排除时仍计为两次连续的 `grep X`。这正是排除功能有用的原因——穿插在循环中的簿记工具不得为循环洗白——也是 pi 扩展的（未文档化的）语义，有意保留并明确写下。
+- **没有 agent 的调用被忽略。** 直接调用 `ctx.tools.execute()` 的调用方（测试、非循环消费方）没有可提醒的模型，也没有可作键的存活 agent 对象。
+
+### 提醒投递
+
+提醒作为独立条目搭载在 `additionalContexts` 上（source 为 `{kind: 'plugin', plugin: 'repeat-tool-guard'}`——依照 `HookContext`，该标签承载语义），绝不替换 `content`：`tool/result` 事件仍是工具自身的审计输出，循环则在步骤结果之后把缓冲的上下文追加为 `context/message`，会话将其渲染为带标签的合成 user 信封，并由派生历史回放。阈值逐级升级：第一个配置阈值获得简短的「你正在重复自己，请分析先前结果」提示；后续各阈值获得详细形式，包含工具、重复计数和规范参数（在头部截断到 `argumentsPreviewChars`，默认 500——循环中的 `write` 级 payload 不得无界地进入下一次请求；链键始终比较完整规范字符串），并说明这些调用没有取得进展。pi 原版把温和文本硬编码为字面计数 3；本守卫以 `thresholds[0]` 为键，修复了移植中的这一 bug。下游钩子桥贡献仍是独立数组条目，因此两个插件都保留各自的 source、信封与元数据。
+
+### 配置
+
+```yaml
+- id: repeat-tool-guard
+  name: '@deepseek-ai/dsh-repeat-tool-guard'
+  config:
+    thresholds: [3, 5, 8]        # default; consecutive counts that trigger a reminder
+    include: []                  # tool-name patterns to track; empty ⇒ all tools
+    exclude: [todo_write]        # tool-name patterns transparent to the chain
+    argumentsPreviewChars: 500   # default; cap on arguments quoted in the detailed reminder
+```
+
+`thresholds` 在加载时校验，遇到空列表、非整数、小于 2 的值或重复项时抛出异常——配置错误快速失败，取代 pi 原版的静默回退到默认值。`include`/`exclude` 条目支持 `*` 通配符。模式是对调用时实际存在的工具的谓词，而非对注册表条目的引用，因此匹配不到当前已注册工具的条目不是错误——与 `toolOrder` 的引用检查不同，`exclude: [mcp_*]` 在未加载 MCP 工具的部署中也必须保持有效。
+
+## 测试
+
+- **单元测试：** 使用脚本化适配器的真实循环，覆盖计数与重置规则、未追踪透明性、dispose（资源释放）清理、按 agent 隔离、规范化参数键序、升级、被拒绝的调用、无 agent 执行、通配符转义、无效配置，以及下游阻止或 replacement 决策，达到逐文件 100% 覆盖率。
+- **快照测试：** keyless 的 `repeat-tool-guard` 场景发起五次相同的 `todo_write` 调用，在 ACP 输出和会话日志中固定第三次调用的温和提醒与第五次调用的详细提醒。该插件在实时示例中加载，但在其他场景中保持静默。
+- **E2e 测试：** 无。该插件是确定性的且与提供方无关，其 seam 契约由各自的所有者覆盖。
+
+## 曾考虑的替代方案
+
+- **将提醒追加到工具结果中**（以替换 `content` 的方式 `accept`——pi 扩展的机制，它修补结果内容是因为那是其 API 提供的唯一通道）：否决。这会让已记录的 `tool/result` 对工具实际返回的内容撒谎，而 `additionalContexts` 是 post-execute 评注的独立认可通道，循环级缓冲保持了调用/结果的邻接关系。
+- **在 `tools/pre-execute` 中计数并使用 pending-reminder map**（pi 的两阶段形态）：否决。post-execute 单独就能同时看到 `(exec, result)` 且也为被拒绝的调用触发，因此一个监听器、无跨事件状态即可以更少的机制覆盖严格更多的尝试。
+- **在最高阈值升级为 `block`**：在初始范围内否决。阻止调用会惩罚合法的相同重复（轮询长时间运行的终端、重新检查 agent 预期会变化的文件），而建议性提醒让模型保持控制权。待有证据后重新审视；决策形状（`PostToolDecision`）已支持此选项。
+- **通过 CC/Codex 桥接的逐部署外部钩子**（一个 `PostToolUse` 脚本）：否决作为最终答案。它对单个部署有效，但一个已发布、有单元测试、可通过 `cordis.yml` 配置的插件才是 harness 原生的形式，且没有逐调用的子进程开销。
+- **在 `agent-loop` 中设置循环级步骤或重复预算**：否决。「用插件，不改循环」；硬性步骤预算是一种更粗粒度的正交控制，需要自己的提案。
+- **模糊/近似相同检测**（路径归一化、相似但不完全相同的参数）：否决。规范化后的精确匹配成本低、确定性强、且可向模型解释；相似度阈值引入误报风险，需要证据才能换取复杂度。
+- **将包放在 `core/`**：否决。core 是产品主干；行为守卫是可选的叶子插件，`todo/` 的先例是每个插件族一个小型专属分组。
+
+## 后果
+
+- 提醒在设计上是建议性的：有意重复相同调用的幂等轮询模式仍会在超过阈值后收到提示，减压阀是配置（`thresholds`、`exclude`）加上明确允许「在已收集足够证据时结束」的提醒文本。每次触发在下一次请求中增加提醒 token 的开销；阈值限制了触发频率。
+- 链状态仅存于内存：从持久化恢复的会话以全新的链开始，因此跨越恢复的循环比实时循环更晚收到提醒——可以接受，守卫是启发式提示而非已记录的不变式，持久化计数器状态带来的收益不值得其复杂度。
+- 当多个 post-execute 生产者在同一次调用上附加上下文时，每项贡献保持为独立的 `HookContext`；顺序遵循 waterfall 嵌套关系，每个条目保留自己的溯源信息。
+- 实现快照层时暴露了 suite kit 的一项隐藏假设：fixture guard 把「撰写的模型场景」等同于「由 override 驱动」。`Scenario` 表现在携带显式的 `overridden` 标志，并且 sidecar 是否存在会以双向方式与其核对（未注册的游离 sidecar 会静默替换派生脚本）——suite kit 比本插件出现前更严格。
+
+## 延后事项
+
+- 压缩（compaction）不重置链：压缩后的历史改变了模型所见的内容，但重复风险通常在压缩后仍然存在。
+- 在高阈值升级为 `block` 未实现；`PostToolDecision` 已支持此选项，待证据到来时启用。
+- subagent 的链按 agent 隔离；在出现具体用例之前不提供共享机制。
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
new file mode 100644
index 0000000000..f91e3b5d42
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-08-self-referential-cordis-toolset.md: 80bffa3a2a959939f18fd1d3422607cf61895fc7
+2026-07-08-self-referential-cordis-toolset.zh.md: 2ec79037045fdb040cccf31699789abdd3a12db2
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 144bdd018f..80bffa3a2a 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-08-self-referential-cordis-toolset.zh.md)
+
 ## Problem
 
 Everything in this harness is a cordis plugin, but the agent running inside that plugin runtime cannot see or touch it: it cannot enumerate the services and events around it, cannot extend itself with a new tool mid-session, and cannot compose capabilities it invents. Handing the model that power is worth exploring — a self-referential agent that inspects and modifies its own runtime — but it raises three correctness problems at once, and the design is about answering them rather than the raw "let the model run code" mechanic.
@@ -30,9 +32,9 @@ Mount code runs as an async-function body in a fresh vm realm. Its documented su
 
 Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:<id>] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor.
 
-Mount code crosses the vm boundary through three controls. Dual-realm `instanceof` recognizes both host and vm objects. `harness.defineTool` normalizes results into host-realm JSON and validates the `ToolExecuteReturn` shape before logging. The mounted plugin receives a whitelist context façade, not a raw or pass-through `Context`; framework plumbing and context-valued returns are rejected. Service reads require a declared `inject`, preserving Cordis activation and unload semantics. `ctx.tools.get` exposes only the schema view, so mounted code cannot bypass `ToolRegistry.execute` by calling a definition directly.
+Mount code crosses the vm boundary through three controls. Dual-realm `instanceof` recognizes both host and vm objects. `harness.defineTool` rebuilds the output schema/projectors in the host realm, snapshots the body value as host-owned JSON, and lets the registry enforce the [canonical tool-output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) before observation. The mounted plugin receives a whitelist context façade, not a raw or pass-through `Context`; framework plumbing and context-valued returns are rejected. Service reads require a declared `inject`, preserving Cordis activation and unload semantics. `ctx.tools.get` exposes only the schema view, so mounted code cannot bypass `ToolRegistry.execute` by calling a definition directly.
 
-The boundary normalizes unambiguous JSON-Schema forms into `SchemaSpec`, including object wrappers, `integer`, and optional fields. Invalid vocabulary fails with the accepted alternatives. Parse, TypeScript, missing-return, Node-API, and duplicate-tool errors include the relevant source line or corrective contract without narrating implementation internals.
+The boundary normalizes unambiguous JSON-Schema forms into `ParameterSchemaSpec`, preserving `integer`, raw object openness, and required arrays. Direct DSL object nodes must declare `additionalProperties`; invalid vocabulary fails with the accepted alternatives. Parse, TypeScript, missing-return, Node-API, and duplicate-tool errors include the relevant source line or corrective contract without narrating implementation internals.
 
 ### The dynamic group and mount lifecycle
 
@@ -60,7 +62,7 @@ Model-visible ⟺ logged holds with no new session event type: a mount or unmoun
 
 | Dimension | Structured per-capability tools | Single `cordis_mount` |
 |---|---|---|
-| Schema correctness | `parameters` is still a model-written JSON object needing SchemaSpec validation, merely one step earlier | The same validation runs at the sandbox boundary, with the same instructive errors |
+| Schema correctness | `parameters` is still model-written JSON needing unified-schema validation, merely one step earlier | The same validation runs at the sandbox boundary, with the same instructive errors |
 | The code field | An `execute` body is still model-written JS in a vm; the realm and service-call correctness problems are unchanged | One sandbox, one normalization path, one guarded registration |
 | Capability coverage | Tools only; listeners, services, `inject` relations each need another structured tool — a surface that grows without bound | One vocabulary (a cordis plugin) covers every effect, present and future |
 | Cross-mount composition | Not expressible in a tool-registration payload | Native `provide`/`inject`, ordinary cordis semantics |
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
new file mode 100644
index 0000000000..2ec7903704
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -0,0 +1,82 @@
+# Agent Note: 自引用 cordis 工具集
+
+Status: implemented
+
+[English](2026-07-08-self-referential-cordis-toolset.md) | 中文
+
+## 问题
+
+本 harness 中的一切都是 cordis 插件，但运行在该插件运行时内部的 agent（智能体）既看不到也碰不到它：它无法枚举周围的服务和事件，无法在会话中途为自己添加新工具，也无法组合自己发明的能力。赋予模型这种能力值得探索——一个能审视并修改自身运行时的自引用 agent——但这同时引发三个正确性问题，本设计的核心正是回答这些问题，而非单纯的「让模型执行代码」机制。
+
+第一，模型编写的注册必须在注册发生时就完成校验：格式错误的工具 schema 必须在注册时失败，而不是等到后续请求尝试将其组装进提示词时才报错。第二，模型编写的代码需要调用它从未见过源码的服务 API——靠猜测方法签名、更糟糕的是猜测返回值结构，会消耗大量盲目试探的步骤。第三，模型挂载的一切都必须完全可释放：模型可以按需释放，普通的插件生命周期在宿主插件重载时也会释放，否则长会话会积累遗留的监听器和工具。
+
+## 决策
+
+该工具集以 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) 发布——一个新的顶层 `packages/cordis/` 分组——并由 [`examples/cordis-agent`](../../../../examples/cordis-agent/README.md) 演示。它为模型提供三个工具，操作模型自身运行其中的活跃 cordis 运行时：审视它、将模型编写的插件挂载进去、再将其释放。
+
+vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节。但二者都不限制已暴露服务的权限：一个挂载可以调用 `ctx.bash` 以宿主执行器的权限运行命令，也能访问真实的文件系统和网络服务。这是一个需要显式启用的开发工具，信任等级与 bash 相当，不是安全边界，也不是产品默认配置。
+
+### 三个工具
+
+| 工具 | 契约 |
+|---|---|
+| `cordis_inspect` | 对活跃运行时的只读报告，每个 `what` 值对应一个 Markdown 段落（省略 `what` 则输出全部段落）。精确的 `name` 搭配 `what: "api"` 或 `what: "events"` 可收窄到一个带源码文档的目标。从不产生变更。 |
+| `cordis_mount` | 在 `node:vm` 沙箱中执行 `code`（一个异步 JavaScript 函数的函数体）；代码必须 `return` 一个 cordis 插件，该插件作为 `cordis-dynamic` 分组 fiber 的子节点挂载，并以一个新 id（`dyn-1`、`dyn-2`……）跟踪。 |
+| `cordis_unmount` | 按 id 释放一个动态挂载，并等到释放达到完全停稳后才返回——该插件所做的每一项注册都被撤销，而不仅仅是请求停止。 |
+
+`cordis_inspect` 的段落：`services`（每个已提供的 ctx 服务及其所属 fiber，非活跃的所有者会被标记）、`plugins`（来自 `ctx.registry` 的所有已加载插件的扁平列表及其生命周期状态——展示加载了哪些能力，刻意不展示树形结构）、`tools`（模型可调用的工具）、`dynamic`（挂载表：id、名称、状态、提供的服务、等待的服务）、`api`（来自生成目录的活跃服务签名及其引用的类型形状）和 `events`（harness 事件及其分发模式和签名）。宽泛的 `api` 和 `events` 报告省略完整 JSDoc 以保持紧凑；精确 `name` 会返回一个服务或事件，以及其原始方法/声明 JSDoc。其他段落不能搭配 name，未知目标会失败，而 API 目标必须处于活跃状态。面向模型的工具描述携带了模型在调用时所需的操作规则；[生成的工具目录](../../../../docs/tool-catalog.md)是其完整呈现。
+
+### 沙箱语义
+
+挂载代码以异步函数体的形式在一个新的 vm realm 中运行。其文档化的接口面将文件、网络、进程和定时器访问引导至 Cordis 服务，使挂载保持可审视和可释放。宿主 realm 的辅助手段仍然使 Node 逃逸成为可能，这与信任姿态一致。`vmTimeoutMs` 仅约束同步执行部分。
+
+沙箱全局变量刻意精简：一个带标签的直写 `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` 直接调用定义。
+
+边界将无歧义的 JSON-Schema 形式规范化为 `ParameterSchemaSpec`，同时保留 `integer`、原始对象开放性和 required 数组。直接使用 DSL 的对象节点必须声明 `additionalProperties`；无效词汇会报错并给出可接受的替代方案。解析错误、TypeScript 错误、缺少 return、Node API 误用和重复工具名等错误信息包含相关源码行或纠正性契约，不叙述实现内部细节。
+
+### 动态分组与挂载生命周期
+
+所有动态挂载都是工具插件下方 `cordis-dynamic` 分组的子节点，因此普通的 fiber 释放即可处理重载和卸载。挂载会等待 settlement；启动失败时在返回错误前释放 fiber。已 settle 但处于 pending 状态的挂载仍然可见，并列出其缺失的注入。`cordis_unmount` 等待挂载 fiber 的释放完成。
+
+### 通过 provide/inject 实现跨挂载组合
+
+挂载之间通过普通的 cordis 服务语义相互关联，以各自的 id 作为生命周期句柄：挂载 A 调用 `ctx.provide('foo', value)`，挂载 B 声明 `inject: ['foo']` 并在 `foo` 存在的瞬间激活；如果 B 先挂载，它保持 pending 状态并列出缺失的服务；卸载 A 使 B 回到 pending（其注册被撤销），之后重新 provide 会通过一个新的沙箱门面重新运行 B 的 `apply`；重复 provide 会明确报错并指出拥有该服务的 fiber。一个 realm 注意事项：由挂载 provide 的服务值是 vm realm 对象——从任何地方调用其方法都能工作，但消费方不得假设它具有宿主原型。
+
+### 生成的 API 目录
+
+`cordis_inspect` 从生成的目录提供 API 和事件数据，而非维护一份重复的表格。生成器复用 Cordis 目录的 AST 扫描，输出服务摘要、签名、原始服务方法与事件 JSDoc、事件模式、引用的类型声明以及继承的上下文接口面。有歧义的类型名被省略，过大的声明被标记为截断。
+
+新鲜度像所有生成产物一样受门禁约束：`pnpm run verify-cordis-api`（在 `doc-sync` 中）在内存中重新生成并在有任何 diff 时失败，因此 JSDoc 或公开签名变更如果不重新生成模型读取的目录就无法合入。运行时 inspect 工具将目录与活跃运行时取交集而非直接转储：宽泛报告把有目录条目的活跃服务渲染为摘要 + 签名，把没有目录条目的活跃服务（挂载提供的）渲染为名称 + 所属 fiber，简要列出有目录条目但无活跃提供方的服务，再附上引用的类型形状。精确名称报告渲染一个活跃服务或事件，并把原始 JSDoc 紧靠在每个签名之前；让该细节按需出现，避免探索性列表承担其 token 成本。
+
+### 配置、渲染与可观测性
+
+该插件暴露一个配置字段，由 schemastery 校验并记录在[配置目录](../../../../docs/config-catalog.md)中：`vmTimeoutMs`（默认 5000），挂载代码同步执行部分的毫秒上限。工具名、`cordis-dynamic` 分组名和 `dyn-` id 前缀是结构性词汇，保持固定。三个工具均按[工具实操手册](../../../../docs/cookbook/adding-a-tool.md)渲染为 `generic` 卡片（`cordis_inspect` 为 `read`，`cordis_mount` 为 `execute` 并将代码作为 `rawInput` 携带，`cordis_unmount` 为 `delete`），不覆盖 `presentResult`。
+
+「模型可见 ⟺ 已记录」成立，且无需新的会话事件类型：挂载或卸载仅通过其自身的 `tool/call` / `tool/result` 对可见（循环会记录它们），而挂载引起的工具集变化由循环在 schema 在步骤间发生变化时发出的完整变更 request header 记录。刻意不设 `cordis/mount` 溯源事件——它只会重复工具调用对已记录的内容。动态挂载是进程生命周期的，不是会话状态：恢复一个持久化的会话会重建对话，但不会重新挂载插件。
+
+## 曾考虑的替代方案
+
+**用结构化的逐能力注册工具替代 `cordis_mount`。** 最具吸引力的替代方案是一个带有显式 `name` / `description` / `parameters` / `code` 字段的 `cordis_register_tool`（以及兄弟工具 `cordis_register_listener`、`cordis_register_service`……），而非单一的「挂载一个插件」原语。否决原因：它唯一的真正优势——对最常见的单一场景免去插件样板代码——不足以抵偿其代价，而单一的 mount 原语能一次性覆盖所有能力。
+
+| 维度 | 结构化逐能力工具 | 单一 `cordis_mount` |
+|---|---|---|
+| Schema 正确性 | `parameters` 仍然是模型编写的 JSON，需要统一 schema 校验，只是提前了一步 | 同样的校验在沙箱边界运行，同样的指导性错误信息 |
+| 代码字段 | `execute` 函数体仍然是 vm 中模型编写的 JS；realm 和服务调用的正确性问题不变 | 一个沙箱、一条规范化路径、一处受保护的注册 |
+| 能力覆盖面 | 仅限工具；监听器、服务、`inject` 关系各需另一个结构化工具——接口面无限增长 | 一套词汇（cordis 插件）覆盖当前和未来的所有效果 |
+| 跨挂载组合 | 在工具注册载荷中无法表达 | 原生 `provide`/`inject`，普通的 cordis 语义 |
+| 可审视性 | 注册的东西无法在插件列表中显示为插件 | 模型挂载的正是 `cordis_inspect` 渲染的 |
+| 模型易用性 | 对最常见的单一场景有优势（无插件样板） | 通过 mount 描述中的规范示例加边界错误信息教会正确调用来缓解 |
+
+因此正确性投入放在能一次性为所有能力带来回报的地方：通过 `cordis_inspect` 呈现的生成 API 目录，以及沙箱边界校验（其错误信息教会正确的调用方式）。结构化注册工具日后仍可作为语法糖添加，由它合成 mount 代码；本设计不排斥这一可能。
+
+**在工具中手工维护服务/事件参考。** inspect 工具的第一版携带了一份手写的服务方法签名表。它被生成的 `api-catalog.ts` 取代，因为手写表在签名变化的瞬间就会与 JSDoc 脱节且没有门禁约束这种漂移，而生成产物的新鲜度由文档使用的同一套 AST 检查。
+
+**新增 `cordis/mount` 会话事件。** 一个持久的溯源事件记录每次挂载（源码、名称）有明确先例（`hook/invoked`、`compact/start`）。v1 中予以否决：挂载和卸载已经作为 `tool/call` / `tool/result` 对可见，工具集变化已经作为完整的变更 request header 被记录，因此专用事件只会重复记录。如果审计用例需要将挂载溯源从工具调用中分离出来，日后仍可添加。
+
+**加固的/能力受限的沙箱。** 对 Node 内置模块设陷阱并向挂载代码提供白名单门面而非原始上下文，可能暗示意图是为安全而沙箱化。这里明确不是：陷阱和门面收窄的是挂载代码所见的*接口面*——将其引导至 cordis 服务、远离易泄漏的 Node 内置模块和框架内部——目的是正确性和封堵未受保护的上下文逃逸，但门面暴露的能力（`ctx.bash`、`ctx.fs`、`ctx.web`）触及真实运行时，因此它不是安全边界。真正的安全边界（独立进程、权限提示）超出了一个开发/显式启用工具集的范围，且会与其核心目的——将活跃运行时交给模型——相冲突。
+
+## 后果
+
+该工具集是刻意的显式启用设计，具有完全特权的 `ctx`，因此部署方采用它的意识程度应与 bash 工具相当。以下几个事实由工具描述直接告知模型：一个 waterfall（瀑布式事件）监听器（如 `tools/pre-execute`）如果不调用 `next()` 就返回，会否决整条链，因此一个挂载的监听器可以瘫痪 agent 自身的工具分发（[waterfall 语义](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)）；挂载代码在当前轮次的工具调用内运行，因此 await 任何只在该轮次结束后才 resolve 的东西会导致死锁；`vmTimeoutMs` 仅约束同步执行；挂载不会在会话恢复后存活。
diff --git a/.agents/notes/implemented/feature/2026-07-10-session-query-service.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-session-query-service.i18n.yaml
new file mode 100644
index 0000000000..f19f20eb9e
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-10-session-query-service.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-10-session-query-service.md: 722f6bf6163278719c3bbb598ed2a2a9d042fb8e
+2026-07-10-session-query-service.zh.md: ae6fcb78e18afe83784560c493ea93b7ee0bd68c
diff --git a/.agents/notes/implemented/feature/2026-07-10-session-query-service.md b/.agents/notes/implemented/feature/2026-07-10-session-query-service.md
index a34d699601..722f6bf616 100644
--- a/.agents/notes/implemented/feature/2026-07-10-session-query-service.md
+++ b/.agents/notes/implemented/feature/2026-07-10-session-query-service.md
@@ -2,15 +2,17 @@
 
 Status: implemented
 
+English | [中文](2026-07-10-session-query-service.zh.md)
+
 ## Problem
 
 Session history exists in two places: current `SessionStore` objects and an optional persistence backend. Consumers that need exact inspection would otherwise duplicate live-versus-persisted precedence, persistence lifecycle handling, raw-event surface classification, relationship tracing, and defensive cloning. Durable state can lag the live log between checkpoints, so persistence alone is not a truthful current source.
 
-Full-text search is related but materially larger. Designing provider registration, extraction, synchronization, invalidation, ranking, and cursor contracts before a real backend exists creates two speculative state machines: one in the interface service and another in the eventual database package.
+Full-text search is related but materially larger. Putting provider coordination, synchronization, invalidation, ranking, and cursor state into the exact-read service would create a second state machine beside the concrete database owner.
 
 ## Decision
 
-`@deepseek-ai/dsh-session-query` owns `ctx.sessionQuery`, a small trusted exact-inspection service over one logical corpus. It exposes `listSessions()`, `listEvents(sessionId)`, bounded `readEvent(request)`, `traceSession(sessionId)`, and `traceEvent(request)`. It does not expose filters, text extractors, search requests, provider registration, or derived-index synchronization. The separate [tracing decision](2026-07-13-session-query-tracing.md) owns lineage and event-relationship semantics.
+`@deepseek-ai/dsh-session-query` owns the single abstract `ctx.sessionQuery` service over one logical corpus. It concretely implements `listSessions()`, provider-independent `filterSessions(filters)`, `listEvents(sessionId)`, `filterEvents(sessionId, filters)`, bounded `readEvent(request)`, `traceSession(sessionId)`, and `traceEvent(request)`, while concrete backends implement its two full-text methods. The [unified service decision](../architecture/2026-07-23-unified-session-query-service.md) owns that topology, the [SQLite search decision](2026-07-10-sqlite-session-query-provider.md) owns search behavior, and the [tracing decision](2026-07-13-session-query-tracing.md) owns lineage and event-relationship semantics.
 
 The service observes the optional `ctx.sessionPersistence` binding dynamically but retains no persisted cache or invalidation listener. Each cross-corpus list asks the active backend for authoritative metadata, then overlays a fresh live-store list. Matching ids become one `SessionRecord`: the live header wins and `live`/`persisted` independently report source availability. Immutable header disagreement is `SESSION_QUERY_SOURCE_CONFLICT`.
 
@@ -31,10 +33,10 @@ The service is context-wide trusted infrastructure, not an authorization layer.
 - **Put logical-corpus resolution directly in every consumer** — rejected because source precedence, conflicts, optional-service lifecycle, cloning, and surface classification are shared correctness rules.
 - **Query only persistence** — rejected because checkpoints can lag the current live log.
 - **Cache persisted metadata and listen for writes/removals** — rejected because exact reads can ask the authoritative sources directly, while cache invalidation adds lifecycle and concurrency state before scale requires it.
-- **Define a provider-neutral search protocol now** — rejected because no provider consumes it. The first SQLite FTS package should own one reconciliation/transaction state machine; a smaller shared seam can be extracted later only when a second implementation proves the boundary.
+- **Put provider registration into the exact-read service** — rejected because the SQLite package owns one reconciliation/transaction lifecycle; a registry would split that state without a second provider to justify it.
 
 ## Consequences
 
-The service has one source-resolution state variable: the currently mounted persistence service. There are no provider queues, fingerprints, extractor registries, observation generations, or derived index updates. Exact reads and event traces remain usable in live-only deployments and deterministic when persistence is present.
+The inherited exact-read implementation has one source-resolution state variable: the currently mounted persistence service. It has no provider queues, fingerprints, extractor registries, observation generations, or derived index updates; a concrete backend owns its full-text state separately. Exact reads, semantic scans, and event traces remain usable in live-only deployments and deterministic when persistence is present.
 
-Cross-corpus listing, lineage tracing, and persisted event operations perform backend I/O on each call. That is deliberate: correctness comes from current authoritative state, and scale-oriented search belongs to the proposed database package. Full-text search is unavailable until that package defines and implements its complete contract.
+Cross-corpus listing, lineage tracing, and persisted event operations perform backend I/O on each call. That is deliberate: correctness comes from current authoritative state, while scale-oriented full-text methods use the concrete backend's SQLite derived index.
diff --git a/.agents/notes/implemented/feature/2026-07-10-session-query-service.zh.md b/.agents/notes/implemented/feature/2026-07-10-session-query-service.zh.md
new file mode 100644
index 0000000000..ae6fcb78e1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-10-session-query-service.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: 精确会话查询服务
+
+Status: implemented
+
+[English](2026-07-10-session-query-service.md) | 中文
+
+## 问题
+
+会话历史存在于两处：当前的 `SessionStore` 对象与可选的持久化后端。需要精确检查的消费方若无统一服务，就不得不各自重复实现活跃/持久化优先级判定、持久化生命周期处理、原始事件的 surface 分类、关系追踪以及防御性克隆。在检查点之间，持久化状态可能落后于活跃日志，因此仅靠持久化并非当前状态的可靠来源。
+
+全文搜索与此相关，但规模大得多。将提供方协调、同步、失效、排序和游标状态放入精确读取服务，会在具体数据库拥有方旁边再创建一个状态机。
+
+## 决策
+
+`@deepseek-ai/dsh-session-query` 拥有面向单一逻辑语料库的唯一抽象 `ctx.sessionQuery` 服务。它具体实现 `listSessions()`、提供方无关的 `filterSessions(filters)`、`listEvents(sessionId)`、`filterEvents(sessionId, filters)`、有界的 `readEvent(request)`、`traceSession(sessionId)` 和 `traceEvent(request)`，而具体后端实现其两个全文搜索方法。[统一服务决策](../architecture/2026-07-23-unified-session-query-service.md)拥有这一拓扑，[SQLite 搜索决策](2026-07-10-sqlite-session-query-provider.md)拥有搜索行为，[追踪决策](2026-07-13-session-query-tracing.md)拥有血缘与事件关系语义。
+
+该服务动态观察可选的 `ctx.sessionPersistence` 绑定，但不保留持久化缓存或失效监听器。每次跨语料库列表操作向活跃后端请求权威元数据，然后叠加一份新鲜的活跃 store 列表。id 匹配的条目合并为一条 `SessionRecord`：活跃 header 优先，`live`/`persisted` 各自独立报告来源可用性。不可变 header 不一致时产生 `SESSION_QUERY_SOURCE_CONFLICT`。
+
+精确目标读取首先检查活跃 store，快照活跃 header 与事件日志。此路径从不查询持久化，因此持久化后端故障不会导致已知的活跃历史不可读。若活跃 store 中无目标，服务列出当前持久化元数据、证明该 id 存在、加载它，并在列表/加载 header 不一致时拒绝。所有返回的 header 与事件都经过一次 structured-clone 边界。
+
+## Surface 语义
+
+`dsh-session` 导出 `foldSurface(events)`，`SurfaceManager` 使用相同的转换函数维护其增量缓存。fold 返回分离的当前事件 seq 以及每次替换实际移除的 seq。`listEvents()` 和 `traceEvent()` 利用该结果为每个原始事件分类，使检查结果不会在位置替换语义上与 model-history 推导产生分歧。
+
+`readEvent()` 返回完整的目标加上按连续 seq 排列的原始相邻事件。`before` 和 `after` 默认为零，各自受 `readWindowMax`（默认 50）约束。结果携带克隆的 `SessionHeader` 而非来源可用性记录，因为判断活跃目标的 persisted 标志会违反「活跃精确读取不依赖持久化健康状态」这一保证。
+
+## 安全边界
+
+该服务是上下文级别的受信任基础设施，而非授权层。未来面向模型的历史工具或人类 UI 将施加显式的调用方/会话范围。该服务不添加面向模型的工具，也不改变 transcript（文本记录）或快照的 surface。
+
+## 曾考虑的替代方案
+
+- **将逻辑语料库解析直接放在每个消费方中**：否决。来源优先级、冲突处理、可选服务生命周期、克隆与 surface 分类是共享的正确性规则。
+- **仅查询持久化**：否决。检查点可能落后于当前活跃日志。
+- **缓存持久化元数据并监听写入/删除**：否决。精确读取可以直接询问权威来源，而缓存失效在规模尚未要求时就引入了生命周期与并发状态。
+- **将提供方注册放入精确读取服务**：否决。SQLite 包拥有一套对账/事务生命周期；若没有第二个提供方证明其必要性，注册表只会拆分该状态。
+
+## 后果
+
+继承的精确读取实现只有一个来源解析状态变量：当前挂载的持久化服务。它没有提供方队列、指纹、提取器注册表、观察代次或派生索引更新；具体后端单独拥有其全文搜索状态。精确读取、语义扫描和事件追踪在纯活跃部署中仍然可用，在持久化存在时具有确定性。
+
+跨语料库列表、血缘追踪和持久化事件操作在每次调用时执行后端 I/O。这是有意为之：正确性来自当前权威状态，而面向规模的全文搜索方法使用具体后端的 SQLite 派生索引。
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
new file mode 100644
index 0000000000..da1ff70e09
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-10-sqlite-session-query-provider.md: be8795b609b52eeb03268c4986b52004eef0dba9
+2026-07-10-sqlite-session-query-provider.zh.md: bb3650da907cf86a853f748fa0ee40d5c2168709
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
new file mode 100644
index 0000000000..be8795b609
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
@@ -0,0 +1,59 @@
+# Agent Note: SQLite FTS5 session search
+
+Status: implemented
+
+English | [中文](2026-07-10-sqlite-session-query-provider.zh.md)
+
+## Problem
+
+The exact-read `ctx.sessionQuery` service deliberately has no derived index. Large persisted histories need full-text search without scanning every event on every query, while current live sessions need an overlay newer than the last durability checkpoint. Search also needs concrete ranking, snippets, filters, pagination, cancellation, and rebuild behavior.
+
+Splitting those concerns across a provider coordinator and a database implementation would create two coupled reconciliation state machines. The first implementation needs to own source observation, extraction, SQLite transactions, generations, and query execution as one lifecycle while still exposing a small provider-neutral call contract.
+
+## Decision
+
+`@deepseek-ai/dsh-session-query` declares one abstract `ctx.sessionQuery` service whose exact reads, filters, and traces are concrete and whose two full-text methods are abstract. `searchSessions(request, exec?)` returns cursor-paginated `SessionSearchHit`s grouped by each session's strongest matching event; `searchEvents(request, exec?)` returns `SessionEventSearchHit`s within one logical session. Both requests require `query`, accept `limit` and an owned branded `SessionSearchCursor`, and support an optional abort signal. Session search accepts `sessionFilters` plus event metadata filters; event search accepts event metadata filters. Results expose bounded plain-text snippets but no provider identifier or numeric relevance score. The [unified service decision](../architecture/2026-07-23-unified-session-query-service.md) owns the single-key topology.
+
+`@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.
+
+## Search semantics
+
+Each semantic event is one FTS document carrying session metadata, event metadata, surface classification, and extracted text. All `current`, `shadowed`, and `log-only` documents participate unless a surface filter narrows them. Metadata filters compile to parameterized SQL before ranking. Session results partition matching documents by session and retain the strongest one.
+
+Ordering is deterministic and comparable across the persistent and TEMP FTS tables: actual FTS5 highlighted-match span count descending, indexed document code-point length ascending, event time descending, session id ascending for the cross-session scope, and seq descending. Snippets use those actual highlight positions, strip the reserved markers, normalize whitespace, and bound by Unicode code points. Opaque cursors bind to the service instance, scope, canonical normalized request, offset, and relevant generation. Any corpus change invalidates cross-session cursors; a within-session cursor changes only when its target source/generation changes, so unrelated sessions do not invalidate it. Reopening creates a new service instance and invalidates old cursors.
+
+Queries are trimmed, whitespace-normalized, and quoted as one literal FTS5 phrase. Embedded quotes are doubled before binding, so MATCH operators such as `OR`, `NEAR`, quotes, parentheses, and `*` remain data rather than executable query syntax. NUL is rejected before SQLite execution. Reserved highlight noncharacters and NUL in documents are normalized before indexing, making inserted presentation markers collision-free. Phrase matching follows tokenizer tokens rather than arbitrary substrings.
+
+## Tokenizer choice
+
+Both persistent and live FTS5 tables use `unicode61`. The implementation experiment found that this tokenizer supports the two-character token `AI` and produces an index about 2.1× smaller than the trigram alternative. The accepted limitation is token/phrase recall: `AI` does not match the larger token `BRAID`, and arbitrary substring search uses the provider-independent text scan instead.
+
+## Extraction and reconciliation
+
+The shared extractor includes message text, reasoning, nested tool-call/result content, tool names and arguments, blocked-prompt reasons, todo status/content, and error or terminal status detail. Structural boundaries, stream chunks, request headers, successful completion markers, and unknown declaration-merged event/content variants produce no document. Surface classification reuses `foldSurface()` so search agrees with model-history derivation.
+
+One serialized operation reads the provider-neutral `SessionPersistence` snapshot listing, compares each source-qualified opaque revision with the revision stored beside the indexed session, loads only new or changed logs, reconciles rows in one transaction, and executes the query. It never calls the backend's mutating `load()` for an id currently owned by `ctx.sessions`; the TEMP overlay records persisted availability, and the durable base refreshes after the live owner detaches. A revision identifies its backing persistence store as well as the backend-local log revision, so reopening against the same store reuses indexed rows while switching to an independent store cannot collide on a session id and local counter. Observation repeats when listing changes during a load; this incorporates a mutating load repair's refreshed revision before commit. Repeated queries and unchanged reopen load no full persisted logs. New, changed, and deleted sessions update on the next stable search. A source or extraction failure cannot mark a row current, and a transaction failure rolls back so a later search retries.
+
+Persisted documents survive restarts. Live sessions use connection-local TEMP tables, shadow the persisted base for the same id, and reveal that base on detach. Closing the database drops live rows. Unmounting persistence hides durable rows without treating absence as authoritative deletion; remounting observes and reconciles the backend again. Conflicting immutable live and durable headers fail rather than combining sources.
+
+The derived schema has its own application id and monotonic schema version. Persistent and TEMP session metadata store the integer `SessionHeader.createdAt` contract in strict `INTEGER` columns. A recognized incompatible version resets only this derived database. A database with a foreign application id or unrecognized user tables is refused before journal-mode mutation, which prevents an accidentally configured canonical session database from being changed. On POSIX filesystems, missing directories and database files are created owner-only so new SQLite sidecars inherit that mode; existing modes are preserved. One service in one process exclusively owns a derived-index path; cross-process writers are unsupported because generations and live TEMP shadow state are connection-owned.
+
+Cancellation rejects queued operations and caller waits around asynchronous source observation without committing an aborted observation. Node's synchronous `DatabaseSync` MATCH call cannot be interrupted once it is executing on the JavaScript thread, so the service checks the signal at serialized boundaries but does not promise mid-statement preemption.
+
+## Alternatives considered
+
+- **Add FTS tables to the canonical persistence database** — rejected because a rebuildable index must not share the authoritative log's schema, reset, or failure boundary.
+- **Add a phase-one provider registry and coordinator** — rejected because one implementation provides no evidence for registration semantics and would split one reconciliation lifecycle across two owners.
+- **Persist live overrides immediately** — rejected because live events are not canonical until the existing checkpoint commits.
+- **Use the FTS5 trigram tokenizer** — rejected because it omits useful queries shorter than three characters and measured about 2.1× the index size of `unicode61`; literal substring filtering remains available through the scan path.
+- **Use FTS5 BM25 independently in each table** — rejected because scores from differently populated persistent and TEMP corpora are not comparable; actual matched spans and document length have one shared scale.
+
+## Consequences
+
+Search has a small provider-neutral API while its only backend owns every derived-index state transition. The separate database adds configuration and a lightweight snapshot read before queries, but index corruption, reset, and tokenizer changes cannot endanger canonical logs. Durable revisions avoid full-log reads and rewrites for unchanged sessions; TEMP live overlays preserve current-session truth without making uncheckpointed events durable.
+
+The chosen tokenizer supports short tokens with a smaller index but does not promise substring recall. Literal phrases make query syntax safe and predictable at the cost of excluding boolean/full MATCH expressions. Cancellation is effective while queued or awaiting sources, but synchronous SQLite execution remains a non-preemptible section.
+
+Unit coverage pins extraction, filters, both search scopes, all default surfaces, metadata-before-ranking, snippets, literal escaping, deterministic ties, complete pagination, scoped cursor invalidation, dynamic persistence mount/unmount, restart reconciliation, live shadow/reveal/reopen, schema safety, rollback retry, and queued/in-flight source-wait cancellation. A keyless real-Loader-path test combines the package with the real SQLite persistence backend.
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
new file mode 100644
index 0000000000..bb3650da90
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
@@ -0,0 +1,59 @@
+# Agent Note: SQLite FTS5 会话搜索
+
+Status: implemented
+
+[English](2026-07-10-sqlite-session-query-provider.md) | 中文
+
+## 问题
+
+精确读取的 `ctx.sessionQuery` 服务有意不维护派生索引。大规模持久化的历史记录需要全文搜索，而不是每次查询都扫描全部事件；当前的活跃会话则需要一个比上一次持久性检查点更新的覆盖层。搜索还需要具体的排序、摘要片段、过滤器、分页、取消以及重建行为。
+
+如果把这些关注点拆分到提供方协调器和数据库实现之间，就会产生两个耦合的对齐状态机。第一个实现既要暴露精简的提供方无关调用契约，也要在同一个生命周期内管理源观察、提取、SQLite 事务、代际与查询执行。
+
+## 决策
+
+`@deepseek-ai/dsh-session-query` 声明一个抽象的 `ctx.sessionQuery` 服务，其精确读取、过滤与追踪均有具体实现，仅有两项全文方法为抽象方法。`searchSessions(request, exec?)` 返回按游标分页的 `SessionSearchHit`，并按每个会话中匹配度最强的事件分组；`searchEvents(request, exec?)` 返回一个逻辑会话内的 `SessionEventSearchHit`。两种请求都必须提供 `query`，可以接受 `limit` 和由服务拥有的品牌化 `SessionSearchCursor`，并支持可选的中止信号。会话搜索接受 `sessionFilters` 与事件元数据过滤器，事件搜索接受事件元数据过滤器。结果会公开有界的纯文本摘要片段，但不公开提供方标识符或数值相关性分数。单一键拓扑由[统一服务决策](../architecture/2026-07-23-unified-session-query-service.md)定义。
+
+`@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 提供方。
+
+## 搜索语义
+
+每个语义事件对应一份 FTS 文档，其中携带会话元数据、事件元数据、surface 分类与提取文本。除非 surface 过滤器缩小范围，否则所有 `current`、`shadowed` 与 `log-only` 文档都会参与搜索。元数据过滤器在排序前编译为参数化 SQL。会话结果按会话划分匹配文档，并保留匹配度最强的文档。
+
+排序在持久化 FTS 表与 TEMP FTS 表之间具有确定性和可比性：先按实际 FTS5 高亮匹配区段数量降序，再按已索引文档的码点长度升序、事件时间降序、跨会话范围内的会话 id 升序，最后按 seq 降序排列。摘要片段使用这些实际高亮位置，移除保留标记、规范化空白，并按 Unicode 码点限制长度。不透明游标会绑定到服务实例、范围、规范化后的标准请求、偏移量与相关代际。语料库发生任何变更都会使跨会话游标失效；会话内游标仅在其目标源或代际发生变化时失效，因此不相关的会话不会使其失效。重新打开服务会创建新的服务实例，并使旧游标失效。
+
+查询会先去除首尾空白并规范化内部空白，再作为一个字面 FTS5 短语整体加引号。嵌入的引号在绑定前写成两个，因此 `OR`、`NEAR`、引号、括号与 `*` 等 MATCH 运算符会作为数据，而不是可执行的查询语法。系统会在 SQLite 执行前拒绝 NUL。文档中的保留高亮非字符与 NUL 会在索引前规范化，因此插入的呈现标记不会与源文本冲突。短语匹配遵循分词器 token，而不是任意子串。
+
+## 分词器选择
+
+持久化 FTS5 表与实时 FTS5 表都使用 `unicode61`。实现实验表明，该分词器支持由两个字符组成的 token `AI`，生成的索引体积约为 trigram 方案的 1/2.1。系统接受的限制是 token/短语召回：`AI` 不会匹配较长的 token `BRAID`，任意子串搜索改用提供方无关的文本扫描。
+
+## 提取与对齐
+
+共享提取器会提取消息文本、推理（reasoning）、嵌套的工具调用/结果内容、工具名称与参数、被阻止提示词的原因、待办事项状态与内容，以及错误或结束状态详情。结构性边界、流式分片、请求头、成功完成标记，以及通过声明合并扩展的未知事件/内容变体都不会产生文档。surface 分类复用 `foldSurface()`，使搜索与模型历史派生保持一致。
+
+一个串行化操作会读取提供方无关的 `SessionPersistence` 快照清单，将每个包含源身份的不透明修订号与同已索引会话一并存储的修订号比较，只加载新增或变更的日志，在一个事务中对齐各行，然后执行查询。它绝不会调用后端会修改状态的 `load()` 来处理当前由 `ctx.sessions` 拥有的 id；TEMP 覆盖层会记录持久化可用性，实时所有者分离后，持久化基础层随之刷新。修订号同时标识其底层持久化存储与后端本地日志修订版本，因此针对同一存储重新打开服务可以复用已索引行，而切换到独立存储时不会因会话 id 与本地计数器相同而发生冲突。如果加载期间清单发生变化，系统会重复观察；因此，会修改状态的加载修复所产生的新修订号会在提交前纳入结果。重复查询与针对未变更存储的重新打开都不会加载完整的持久化日志。新增、变更与删除的会话会在下一次稳定搜索中更新。源或提取失败不能将某一行标记为当前状态，事务失败则会回滚，使后续搜索能够重试。
+
+持久化文档在重启后仍然存在。实时会话使用连接本地的 TEMP 表，遮蔽相同 id 的持久化基础行，并在实时所有者分离时重新显露该基础行。关闭数据库会删除实时行。卸载持久化服务会隐藏持久化行，但不会把缺失视为权威删除；重新挂载后，系统会再次观察并对齐后端。实时会话头与持久化会话头的不可变字段发生冲突时，系统会失败，而不会合并两个来源。
+
+派生 schema 拥有独立的 application id 与单调递增的 schema 版本。持久化与 TEMP 会话元数据均遵循 `SessionHeader.createdAt` 的整数契约，将其存入严格的 `INTEGER` 列。系统识别到不兼容版本时，只会重置该派生数据库。如果数据库具有不属于本应用的 application id 或无法识别的用户表，系统会在修改日志模式前拒绝该数据库，防止意外配置的规范会话数据库遭到修改。在 POSIX 文件系统上，缺失的目录与数据库文件会以仅所有者可访问的权限创建，使新的 SQLite 伴随文件沿用该模式；现有权限模式保持不变。一个进程中的一个服务独占一条派生索引路径；代际与实时 TEMP 遮蔽状态都归连接所有，因此不支持跨进程写入方。
+
+取消会拒绝排队中的操作，并终止调用方对异步源观察的等待；已经中止的观察结果不会提交。Node 的同步 `DatabaseSync` MATCH 调用一旦开始在 JavaScript 线程上执行就无法中断，因此服务会在串行化边界检查信号，但不承诺在语句执行期间抢占。
+
+## 曾考虑的替代方案
+
+- **将 FTS 表添加到规范持久化数据库**：不予采纳，因为可重建索引不应与权威日志共享 schema、重置或故障边界。
+- **添加第一阶段的提供方注册表与协调器**：不予采纳，因为单一实现无法证明注册语义，并且会将一个对齐生命周期拆给两个所有者。
+- **立即持久化实时覆盖层**：不予采纳，因为在现有检查点提交前，实时事件并非规范数据。
+- **使用 FTS5 trigram 分词器**：不予采纳，因为它会遗漏短于三个字符的有用查询，并且测得的索引体积约为 `unicode61` 的 2.1 倍；扫描路径仍可提供字面子串过滤。
+- **在每个表中独立使用 FTS5 BM25**：不予采纳，因为填充内容不同的持久化语料库与 TEMP 语料库所产生的分数不可比较；实际匹配区段与文档长度采用同一套尺度。
+
+## 后果
+
+搜索只公开精简的提供方无关 API，而唯一后端负责派生索引的全部状态转换。独立数据库增加了配置与查询前的轻量快照读取，但索引损坏、重置与分词器变更都不会危及规范日志。持久化修订号使未变更会话无需读取或重写完整日志；TEMP 实时覆盖层保留当前会话事实，同时不会让尚未经过检查点的事件具有持久性。
+
+选定的分词器以较小的索引体积支持短 token，但不承诺子串召回。字面短语使查询语法安全且可预测，代价是不支持布尔表达式或完整 MATCH 表达式。取消在操作排队或等待数据源期间有效，但同步 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
new file mode 100644
index 0000000000..d7dfbedded
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-12-subagent-persona-tool-filter-and-depth.md: c690f4701a54272205eedf719fbfe0863bac566c
+2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: 6e9e9ad44fff4dee6ddb286227485420d100f4ee
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 0f42a547cf..c690f4701a 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-12-subagent-persona-tool-filter-and-depth.zh.md)
+
 ## Problem
 
 A reusable subagent provider answers how to run a child, but different delegation tools need different child behavior. One deployment may want a reviewer persona, a research-only tool set, or a hard recursion bound without creating a new provider for every combination.
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
new file mode 100644
index 0000000000..6e9e9ad44f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
@@ -0,0 +1,96 @@
+# Agent Note: 配置 subagent 的人设、工具可见性与深度
+
+Status: implemented
+
+[English](2026-07-12-subagent-persona-tool-filter-and-depth.md) | 中文
+
+## 问题
+
+一个可复用的 subagent 提供方解决的是「如何运行子 agent（智能体）」的问题，但不同的委派工具需要不同的子 agent 行为。某个部署可能需要评审者人设、仅限研究的工具集，或硬性递归上限，而不必为每种组合创建新的提供方。
+
+这些控制影响子 agent 的第一次模型请求，因此不能在子 agent 可见之后再安装。它们还需要提供方的诚实支持：ACP（Agent Client Protocol）后端不能默默接受一个仅限进程内的工具过滤器，而过滤器在所有插件运行于同一可信进程的情况下也不应被描述为安全边界。
+
+## 决策
+
+subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `maxDepth`。提供方声明对每个控制的支持情况，服务在启动运行之前拒绝不受支持的请求，进程内提供方在子 agent 尚未发布时安装所请求的组合。
+
+这些控制回答不同的问题：
+
+| 控制 | 问题 | 结果 |
+|---|---|---|
+| `persona` | 什么角色指令替换该子 agent 的部署人设？ | 一个子 agent 局部的提示词段落遮蔽 `deployment:persona` |
+| `toolFilter` | 部署全局工具中哪些进入该子 agent 的可见工具视图？ | 一个有作用域的限制在添加子 agent 局部工具之前过滤全局工具 |
+| `maxDepth` | 这棵委派树最深可以长到多少层？ | 子 agent 深度超过绝对上限时，启动请求被拒绝 |
+
+`dsh-tool-subagent` 将这些控制作为插件配置暴露，并复制到它创建的每个请求中。直接调用 `SubagentService` 的调用方可以按请求选择这些控制。提供方的能力描述符仍然是后端能否兑现各字段的真源。
+
+### 人设是有作用域的遮蔽
+
+人设控制改变一个子 agent 的行为，而不改变部署级的提示词组装。在未发布的设置阶段，进程内提供方在子 agent 作用域中注册一个名为 `deployment:persona` 的段落；普通的最具体者优先解析规则仅在该子 agent 的组装中替换全局段落。
+
+其值与部署人设具有相同的严格模板语义。省略时通过全局层继承部署段落；显式空字符串则以空段落遮蔽全局人设。父级和兄弟级的人设永远不会进入子 agent 的扁平作用域。
+
+这使用的是常规的系统提示词注册机制，而非第二条人设通道。因此第一次提示词看到的命名贡献与后续提示词和提示词检查工具看到的一致。
+
+### 工具过滤是一条作用于全局视图的活规则
+
+工具过滤同时控制能力可见性和可执行查找。进程内提供方在发布前于子 agent 作用域中安装 `ToolRegistry.restrict()`，注册表的单一解析器对协议格式（wire format）的工具 schema、查找、执行和 Code Mode SDK 生成施加相同的结果。独立注册的系统提示词段落不在 `ToolRegistry` 内，因此过滤一个工具不会移除该插件的独立指导文本。
+
+解析遵循以下规则：
+
+1. 每条限制对活跃的部署全局工具注册表先应用 `allow` 再应用 `deny`。
+2. 多条限制取交集，因此每条已安装的限制都必须放行一个全局工具。
+3. 子 agent 作用域的工具在全局过滤之后添加，可以遮蔽一个已放行的全局工具。
+4. 保留的 `run_code` 呈现和其他作用域局部的协议贡献不受全局过滤器影响。
+
+当过滤器既未提供 `allow` 也未提供 `deny`，或命名了当前全局可限制集合之外的内容（包括仅作用域局部或保留名称）时，配置会显式失败。`allow: []` 合法，且有意隐藏所有全局工具。这些检查能捕获拼写错误，并防止配置在无法影响所命名条目时看起来仍然有效。
+
+全局注册表保持活跃。仅 deny 的过滤器会放行后来注册的全局名称（除非显式 deny 该名称）；allow 列表会排除后来注册的全局名称（除非显式 allow 该名称）。移除一个全局工具会将其从所有已解析视图中移除。这些语义在保持热注册的同时，使 allow 与 deny 的区别显式化。
+
+### 深度是绝对的树上限
+
+深度限制独立于工具可见性来约束递归委派。顶层 agent 深度为零；进程内子 agent 的深度为其父级已验证深度加一。`maxDepth` 是一个绝对的非负安全整数，当推导出的子 agent 深度大于上限时，启动在子 agent 所有权开始之前即被拒绝。
+
+有效父级深度取持久 `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` 时，数值工具上限会在提供方挂载阶段失败。
+
+部署可以组合深度与过滤，但数值上限不会合成过滤器。委派工具在上限处仍然可见，因为授权可能依赖运行时状态；每次尝试启动都会检查调用方 agent 当前的持久与运行时深度，被拒绝的启动返回错误工具结果，且不发布子 agent。可见性策略固定的部署可以另外在子 agent 中 deny 委派工具。两种选择都不改变提供方的对话历史行为。
+
+### 能力门控保持提供方诚实
+
+能力将请求的功能与提供方实现分离。`SubagentCapabilities` 声明 `persona`、`toolFilter` 和 `depthLimit`；`SubagentService.start()` 在调用提供方之前，对照这些标志检查请求中每个存在的字段。
+
+这使 spawn 和 fork 提供方可以共享进程内实现，而外部提供方只声明自己能强制执行的部分。请求永远不会静默降级：选择不受支持的控制会产生 `UNSUPPORTED_CAPABILITY`，不会有运行或生命周期事件存在。
+
+### 未发布设置使第一次请求正确
+
+所有子 agent 局部的组合在子 agent 变得可观察之前完成。进程内提供方向 agent 创建提供一个设置回调；该回调在子 agent 作用域中安装人设、工具限制和结构化输出贡献。只有设置成功后，创建才发布会话和 agent 并允许驱动器启动。
+
+设置失败会回滚私有子 agent。没有观察者能获取到一个「第一次提示词使用了部署人设或未过滤工具集、后续提示词才使用所请求配置」的子 agent。
+
+## 可见性不是授权
+
+这些控制组合的是同一可信进程内的行为，而非授权行为。`toolFilter` 改变工具注册表解析出的子 agent 视图，但它不创建父到子的授权格，不要求子 agent 仅持有父级子集授权，不沙箱化插件，也不阻止持有另一个 Cordis 上下文的代码直接调用服务。
+
+具体而言，子 agent 局部工具在全局过滤之后添加，可能不在父级视图中。仅 deny 的子 agent 也能看到 deny 列表未命名的后来全局工具。这些是有意的活组合语义，而非不可升权保证。
+
+安全设计需要独立的授权表示、传播规则和执行时强制点。创建时的授权快照、父级子集授权、显式的未来授权 API，以及通用的能力/输出/终止标签均不在本功能范围内。
+
+## 曾考虑的替代方案
+
+**为每种人设或工具集创建一个提供方。** 这会使共享相同传输和生命周期实现的提供方成倍增加，使动态部署配置变得笨拙，且仍需要递归机制。提供方的职责是执行传输；请求承载每个子 agent 的组合。
+
+**复制父级的完整工具视图。** 注册作用域设计上是扁平的，生命周期所有权不意味着可见性继承。复制已解析视图还会冻结动态全局注册，并在未完整定义任一契约的情况下混淆组合与授权。
+
+**在子 agent 创建时快照允许的全局工具。** 冻结的 allow 集合使未来注册统一不可用，但它改变了热注册语义并开启了授权设计。已实现的过滤器保持为活跃的注册表谓词，并直接记录 allow 与 deny 的行为。
+
+**仅隐藏工具 schema。** 仅呈现层的过滤让模型可以通过 Code Mode 或伪造调用执行一个提示词声称不存在的工具。改为由一个解析器同时管控呈现和执行。
+
+**把深度上限编码为自动工具过滤器。** 创建时过滤器会快照一个可能依赖运行时状态的决策，只影响一个已配置工具名，且不保护直接服务调用方或替代委派工具。提供方改为在每次启动时强制绝对上限。
+
+## 后果
+
+贡献者可以配置子 agent 的角色、可见全局工具和递归深度，而无需定义新的提供方。能力检查在所有权开始之前失败，未发布设置使第一次请求一致，单一工具解析器防止呈现/执行漂移。
+
+代价是部署方必须理解活跃的 allow/deny 行为以及可见性与授权的区别。当前深度策略禁止再创建子 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 f58ed600f0..be66b14fbf 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
-2026-07-16-persistent-pty-sessions.md: 76354891f557974b953a1b0b805d94330c9f6e69
-2026-07-16-persistent-pty-sessions.zh.md: 86200d70c6eda815a440c44e8b55457b0424edb6
+2026-07-16-persistent-pty-sessions.md: b33993d36753d3195ec52d3b38dda62746a47bf3
+2026-07-16-persistent-pty-sessions.zh.md: 6ed330d75824a4e6fca9de0d82db61a7c6543322
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 76354891f5..b33993d367 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
@@ -34,14 +34,14 @@ Idle detection is backend behavior, not a second public seam. A remote or contai
 
 There are no plugin-load auto-start sessions. `terminal_open` creates a session only during an agent tool call, when ownership and the owning event-sourced session are known. A future declarative startup feature must compose through unpublished agent setup rather than create shared global terminals.
 
-Agent-scope disposal closes registrations first, then awaits quiescent teardown of every owned PTY. Backend or tool-plugin reload does not orphan sessions: ownership lives in `PtyService` until the agent ends, following the same service-owned-record pattern as [`ctx.tasks`](../../../../packages/tasks/tasks/README.md).
+Agent-scope disposal closes registrations first, then awaits quiescent teardown of every owned PTY. Unpublished backend setup is a tracked lifecycle operation: owner or service disposal aborts its service-owned signal, waits for backend settlement and rollback, and only then returns. Caller cancellation retains its exact `AbortSignal.reason` even when the backend rejects or returns a session whose rollback close fails; that cleanup failure remains tracked for later owner or service disposal instead of replacing the caller reason. A lifecycle-triggered rollback close failure rejects both the spawn and the disposing lifecycle, while `PtyBackendCleanupError` lets a backend preserve its own failed startup cleanup for the disposing lifecycle without replacing a caller cancellation. When caller cancellation settles before disposal, the cleanup failure remains tracked owner activity until later owner or service disposal consumes and reports it, so sandbox-mode policy cannot mistake failed cleanup for quiescence. Backend or tool-plugin reload does not orphan sessions: ownership lives in `PtyService` until the agent ends, following the same service-owned-record pattern as [`ctx.tasks`](../../../../packages/tasks/tasks/README.md). The service reserves the session synchronously for one active send before returning its operation, including before a background task id becomes visible; a second send fails with `SEND_ACTIVE`, so output and cancellation cannot cross operation ownership.
 
 ### Security and process boundary
 
 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*`, `*SECRET*`, `*TOKEN*`, and harness-managed variables unless an explicit trusted mapping supplies 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. `danger-full-access` is the existing explicit unconfined choice rather than a PTY-specific bypass.
+- 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.
 
@@ -58,19 +58,21 @@ The implementation uses only public `node-pty` capabilities: child PID, `data` a
 | `terminal_close` | Close one session and await process-tree quiescence | `{ killed }` |
 | `terminal_list` | List the caller's live sessions | owner-scoped session summaries |
 
-`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.
+The ACP 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`.
 
-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.
+`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.
 
-With `run_in_background: true`, `dsh-tool-pty` registers the in-flight send on `ctx.tasks` and returns immediately with `taskId`. `task_output(wait: true)` waits, reads incremental output, and records the final result; `task_kill` forwards cancellation as `SIGINT` 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.
+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.
 
-`terminal_read` pages backward from the newest retained line. The backend enforces both line and UTF-8 byte caps on retained scrollback and the complete returned value, so one oversized line cannot bypass the bound. `truncated` distinguishes retention loss from an ordinary viewport delta.
+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.
+
+`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.
 
 `terminal_signal` accepts the closed set `SIGINT | SIGTERM | SIGKILL | SIGTSTP | SIGHUP`. The backend resolves the terminal foreground process group at execution time. `SIGKILL` is rejected when that group is the top-level shell, directing the caller to `terminal_close`; a failed group lookup fails the operation instead of signaling a guessed PID.
 
 ### Local readiness detection
 
-The local backend first recognizes a private OSC prompt marker emitted by its controlled bash startup, then runs three bounded fallback tiers. 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. All timings are validated config fields: `pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, and `timeoutMs`.
+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`, 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. 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.
 
@@ -78,7 +80,7 @@ On macOS there is no exact syscall tier. Output silence returns `inferred_idle`
 
 Tier 2 returns `inferred_idle` after `idleSilenceMs` without output. A sleeping or network-blocked command can therefore look ready. Tier 3 returns `timeout` after `timeoutMs` so a foreground tool call cannot hold the agent indefinitely. The result preserves the distinction; callers may wait through `ctx.tasks`, signal the foreground group, or inspect from another session.
 
-`node-pty` data notifications feed one streaming decoder and terminal parser. Parser carry state handles UTF-8 and terminal query sequences split across chunks. The implementation normalizes line-oriented output and detects alternate-screen entry, but it does not promise correct interaction with a full-screen application.
+`node-pty` data notifications feed one terminal parser. Parser carry state handles control sequences and a trailing carriage return split across callbacks, so a divided CRLF produces one newline rather than a pagination-changing blank line. The implementation normalizes line-oriented output, but it does not promise correct interaction with a full-screen application.
 
 ### Model-visible output and durability
 
@@ -88,9 +90,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 that PID and its transitive descendants by parent PID in children-first order, sends `SIGTERM`, closes the PTY, waits for quiescence, then sends `SIGKILL` to verified survivors after configurable `disposeGraceMs` and waits for them to leave the process table. Every captured PID includes process-start identity so reuse cannot redirect escalation.
+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.
 
-Teardown reports root exit and survivor cleanup independently. It does not claim success merely because the shell exited; disposal resolves only after no captured tree member remains or returns a structured cleanup failure naming the survivors. 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 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.
 
 ### Composition and rollout
 
@@ -115,9 +117,12 @@ plugins:
       timeoutMs: 30000
       disposeGraceMs: 3000
   '@deepseek-ai/dsh-tool-pty':
+    config:
+      enableRunInBackground: true
+      maxResultBytes: 262144
 ```
 
-The package ships concise tool guidance explaining persistent state, owner isolation, uncertain idle results, cleanup, and the preference for existing one-shot tools when interaction is unnecessary. It does not add a global system-prompt recommendation or mount PTY in shipped defaults; dedicated ACP and headless snapshot overlays exercise the opt-in composition.
+The package ships concise tool guidance explaining persistent state, owner isolation, uncertain idle results, cleanup, and the preference for existing one-shot tools when interaction is unnecessary. It does not mount PTY in the base shipped examples: PTY is opt-in through the dedicated composition, while ACP and headless snapshot overlays exercise it. Within an enabled `dsh-tool-pty` instance, the six tools and `run_in_background` are enabled by default; deployments may disable only the background argument with config.
 
 ### Deferred work
 
@@ -147,9 +152,9 @@ The package ships concise tool guidance explaining persistent state, owner isola
 
 ## Verification
 
-- Per-file coverage pins owner fencing, concurrent reservations, lifecycle cleanup, readiness tiers, sanitizer carry state, UTF-8 bounds, task integration, schemas, and render intents.
-- Linux process fixtures cover non-leader and non-main-thread stdin waits, 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, signals, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
+- Per-file coverage pins owner fencing, concurrent reservations, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, 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`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition, while ACP and headless snapshots pin the six schemas, bounded results, error rendering, and terminal/generic cards through opt-in overlays.
 - 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.
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 86200d70c6..6ed330d758 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
@@ -34,14 +34,14 @@ idle 检测属于后端行为，不是第二条公共 seam。远程或容器后
 
 实现不提供插件加载期 auto-start 会话。`terminal_open` 只在 agent 工具调用期间创建会话，此时所有权和所属的事件溯源会话都已确定。未来的声明式启动功能必须通过尚未发布的 agent setup 组合，而不能创建全局共享终端。
 
-agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出。后端或工具插件 reload 不会遗留会话：所有权持续存放在 `PtyService` 中，直到 agent 结束，与 [`ctx.tasks`](../../../../packages/tasks/tasks/README.md) 的服务持有记录模式一致。
+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*`、`*SECRET*`、`*TOKEN*` 和 harness 管理的变量，除非显式的可信映射提供这些值。
-- 它要求 `ctx.sandbox` 和共享的 `ctx.sandboxPolicy`。后端在 spawn 时，以部署默认值为底折叠 owner 的有效 session mode，并只包装一次 shell argv；该 mode 与 workspace root 在 PTY 的整个生命周期中充当进程边界。`danger-full-access` 是现有的显式无约束选择，不另设 PTY 私有 bypass。
+- 它要求 `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 时使用。
 
@@ -58,19 +58,21 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 | `terminal_close` | 关闭一个会话并等待进程树静默退出 | `{ killed }` |
 | `terminal_list` | 列出调用方的活会话 | 按 owner 隔离的会话摘要 |
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。
+ACP 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
 
-前台发送返回有界的渲染增量和两个独立事实：`waitReason`（`stdin_read | inferred_idle | timeout | session_exit`）与 `sessionStatus`（`running`，或携带退出码或信号的 `exited`）。`session_exit` 指 PTY 顶层 shell 进程退出，不指由 shell 消费状态的任意前台命令。timeout 从不意味着进程已经退出。
+`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`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
 
-当 `run_in_background: true` 时，`dsh-tool-pty` 在 `ctx.tasks` 上注册进行中的发送，并立即返回 `taskId`。`task_output(wait: true)` 负责等待、读取增量输出并记录最终结果；`task_kill` 将取消转发为 `SIGINT`，只有 PTY 后端拥有的 teardown 路径可以升级信号。若 task 对外接口不存在，后台模式必须在写入输入前失败。设计不新增 PTY 专用的 `sleep` 工具或通用唤醒 seam。
+前台发送返回有界的渲染增量和两个独立事实：`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 内容。渲染器会为后缀预留空间并保持代码点边界，而不会把后端载荷上限当作面向模型结果的最终上限。
 
-`terminal_read` 从最新保留行向后分页。后端同时对保留的 scrollback 和完整返回值执行行数与 UTF-8 字节上限，因此单个超长行无法绕过限制。`truncated` 用于区分保留数据丢失与普通 viewport 增量。
+当 `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_signal` 接受闭合集 `SIGINT | SIGTERM | SIGKILL | SIGTSTP | SIGHUP`。后端在执行时解析终端前台进程组。当目标组是顶层 shell 时拒绝 `SIGKILL`，并指引调用方使用 `terminal_close`；进程组解析失败时操作直接失败，而不是向猜测的 PID 发送信号。
 
 ### 本地就绪检测
 
-本地后端先识别受控 bash 启动时发出的私有 OSC prompt marker，再执行 3 个有界 fallback 层级。marker 在输出到达模型前被移除，使两个平台上的普通 shell 命令都无需固定等待静默阈值。尚未发布的 startup 不会把零输出静默视为就绪；timeout 会拒绝 spawn。所有时间参数都是经校验的配置字段：`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs` 和 `timeoutMs`。
+本地后端先识别受控 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` 和 `timeoutMs`。
 
 在 Linux 上，检查器从 `/proc/<shellPid>/stat` 读取 shell 的终端前台 PGID，枚举该进程组中的每个进程与线程，并检查它们当前的 syscall。Tier 1 只有观察到 stdin 等待才返回正结果：直接 `read(0)`、获准读取且含 fd 0 的 `select`/`pselect6` 或 `poll`/`ppoll` 参数，或者含 fd 0 的 epoll interest list。无法读取的进程内存和未识别的 syscall 都是 miss，绝不作为正向猜测。架构表只包含对应 Linux UAPI 定义的 syscall number；不支持的架构跳过 Tier 1。
 
@@ -78,7 +80,7 @@ macOS 没有精确 syscall 层。任何前台进程组输出静默都会返回 `
 
 Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此 sleep 或网络阻塞的命令可能看似 ready。Tier 3 在 `timeoutMs` 后返回 `timeout`，避免前台工具调用无限占住 agent。结果保留这些区别；调用方可以通过 `ctx.tasks` 等待、向前台组发信号，或从另一个会话排查。
 
-`node-pty` data 通知进入同一个流式 decoder 和终端 parser。parser 的 carry 状态处理跨 chunk 的 UTF-8 与终端查询序列。当前实现只规范化行式输出并检测 alternate-screen 进入，不承诺正确操作全屏应用。
+`node-pty` data 通知进入同一个终端 parser。parser 的 carry state 会处理跨 callback 的控制序列和位于 callback 末尾的回车；因此，即使 CRLF 被拆开，也只会生成一个换行，而不会产生改变分页的空行。实现会规范化行式输出，但不承诺正确操作全屏应用。
 
 ### 模型可见输出与持久性
 
@@ -88,9 +90,9 @@ Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此
 
 ### 进程树 teardown
 
-顶层 `node-pty` 子进程是所有权锚点。关闭时，后端先停止 callback，再按父 PID 以子进程优先顺序捕获该 PID 及其传递子进程、发送 `SIGTERM`、关闭 PTY 并等待静默，然后在可配置的 `disposeGraceMs` 后向已验证的存活者发送 `SIGKILL`，并等待它们离开进程表。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。
+顶层 `node-pty` 子进程是所有权锚点。关闭时，后端先停止 callback，再按父 PID 以子进程优先顺序捕获其传递子进程、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向剩余子孙进程树发送 `SIGKILL`，并在 shell 仍存活时验证每个非僵尸子孙进程都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为静止；shell 关闭时会回收它或将其重新挂接给负责回收的父进程。完成这些步骤后，后端才用 shell 自身的 TERM、宽限等待、KILL 序列停止 shell。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。
 
-teardown 独立报告根进程退出与存活进程清理。它不会只因 shell 退出就声称成功；dispose 只有在已捕获的进程树成员全部消失后才完成，否则返回结构化清理失败并列出存活者。即使某个 close 失败，服务 dispose 仍会清空其后端、预留与 owner detacher 注册表。所有权绝不会扩大到根 PID 所属 POSIX 会话的全部成员。
+teardown 独立报告根进程退出与存活进程清理。它不会只因 shell 退出就声称成功；dispose 只有在已捕获的进程树中不再存在非静止成员后才完成，否则返回清理失败并列出存活者。失败的 close 不会永久缓存：注册表与本地会话各自仅在关闭围栏仍指向该次失败尝试时才将其清除，因此外部存活进程状态改变后，后续的显式 close 或生命周期 close 会重试，且不会干扰较新的并发尝试。即使某个 close 失败，服务 dispose 仍会清空其后端、预留与 owner detacher 注册表。所有权绝不会扩大到根 PID 所属 POSIX 会话的全部成员。
 
 ### 组合与推行
 
@@ -115,9 +117,12 @@ plugins:
       timeoutMs: 30000
       disposeGraceMs: 3000
   '@deepseek-ai/dsh-tool-pty':
+    config:
+      enableRunInBackground: true
+      maxResultBytes: 262144
 ```
 
-包提供简洁的工具指引，说明持久状态、owner 隔离、不确定的 idle 结果、清理，以及无需交互时优先使用现有一次性工具。它不增加全局 system prompt 推荐，也不在已发布的默认配置中挂载 PTY；专用 ACP 与 headless 快照 overlay 覆盖 opt-in 组合。
+包提供简洁的工具指引，说明持久状态、owner 隔离、不确定的 idle 结果、清理，以及无需交互时优先使用现有一次性工具。已发布的基础示例不挂载 PTY：PTY 仅通过专用组合 opt-in，ACP 与 headless 快照 overlay 覆盖该组合。`dsh-tool-pty` 实例一旦启用，6 个工具和 `run_in_background` 就会默认启用；部署可通过配置仅禁用后台参数。
 
 ### 推迟的工作
 
@@ -147,9 +152,9 @@ plugins:
 
 ## 验证
 
-- 每文件覆盖率固定 owner 隔离、并发预留、生命周期清理、就绪层级、sanitizer carry state、UTF-8 上限、task 集成、schema 和 render intent。
-- Linux 进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
-- 真实 `node-pty` 测试在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、信号、忽略 `SIGTERM` 的子进程，以及 dispose 返回后立即静默。
+- 每文件覆盖率固定 owner 隔离、并发预留、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
+- Linux 进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程静止性、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
+- 真实 `node-pty` 测试在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 下的前台 `SIGINT`、忽略 `SIGTERM` 的子进程，以及 dispose 返回后立即静默。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合；ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果、错误渲染和 terminal/generic card。
 - 包契约、架构图、核心数据结构、生成目录和 website API 描述同一个已发布接口。
 - 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
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 e53c591aa5..70ca07b414 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
-2026-07-19-model-facing-goal-tools.md: 7cc3907d708115207e166455ea988120a03d768b
-2026-07-19-model-facing-goal-tools.zh.md: 1a381160354d6a2a24f957f41bc9e375c1ab01ca
+2026-07-19-model-facing-goal-tools.md: 286329390a058c0302520fd2203e5becb8c81395
+2026-07-19-model-facing-goal-tools.zh.md: b0b4fc99ada3597fbab58081f52309e21dd43bac
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 7cc3907d70..286329390a 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
@@ -16,11 +16,11 @@ The surface also needs to preserve the separation between durable state and live
 
 ### Tools and model contract
 
-`get_goal()` returns the current goal or `null`. A non-null result contains the compare-and-set id and revision, objective, durable phase, admitted and maximum goal rounds, any blocker reason, plus the process-local activation observation. `create_goal(objective, max_goal_rounds?)` creates one long-running same-session objective. `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`; replacement fields are valid only for `edit`, while a non-empty `blocked_reason` is required only for `blocked` and persists under the stable `model-reported` code.
+`get_goal()` returns the current goal or `null`. A non-null result contains the compare-and-set id and revision, objective, durable phase, admitted and maximum goal rounds, any blocker reason, plus the process-local activation observation. `create_goal(objective, max_goal_rounds?)` creates one long-running same-session objective. `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`; replacement fields are valid only for `edit`, while a non-empty `blocked_reason` is required only for `blocked` and persists under the stable `model-reported` code. The executor treats exact empty-string optional fields and a zero `max_goal_rounds` as strict-schema fillers: they count as omitted, an edit still requires at least one meaningful replacement, and all non-filler values retain the action restrictions.
 
 The prompt tells the model that it may infer goal intent from a direct human request in any wording or language, but should not convert routine single-turn work into a goal. It must read the current goal before updating and copy the exact id and revision. On a restored or forked active-but-disarmed goal, a semantic human request to continue is grounds for `resume`. Completion is reserved for an achieved objective, and difficulty or uncertainty alone is not a blocker; a block report must name the concrete condition.
 
-All three tools use exclusive execution so a model-ordered batch observes prior mutations and their new revisions. Results are compact JSON. ACP presentation is a pure function of arguments and uses generic read or mutation cards; activation is reported only as live observation and is never written into replay state.
+All three tools use exclusive execution so a model-ordered batch observes prior mutations and their new revisions. Results are compact JSON. ACP presentation is a pure function of arguments and uses generic read or mutation cards; mutation cards select meaningful action values before the goal id, so accepted fillers cannot blank their input. Activation is reported only as live observation and is never written into replay state.
 
 An autonomous goal round that successfully reports completion or blocking contributes the existing terminal `agent/turn-stop` decision for that physical turn, preventing an unnecessary follow-up request. Direct-human mutations do not contribute a terminal stop: the assistant can acknowledge the change, and concurrent human steering remains available to ordinary continuation folding.
 
@@ -38,7 +38,7 @@ Complete and blocked accept either direct-human authority or the exact current g
 
 ## Testing
 
-Unit coverage pins registration and disposal, exclusive scheduling, generated prompt policy, generic presentation, direct-human creation in a non-English turn, exact/stale/non-running agent and driver checks, live-child rejection, resumed-fork root authority, steering, mismatched initiators, read/create/edit/pause/resume behavior, conditional blocker explanations, rearming after a session-start edge, authority-before-conditional-argument failures, exact goal-round completion, autonomous-only terminal stopping, the configured blocking threshold, and immediate human blocking. A keyless replay snapshot mounts the goal domain and tools into the real headless one-shot application, drives `create_goal` and `get_goal` through the shipped loop and persistence stack, pins its stream-json transcript, and inspects the externally persisted goal change. The echo-agent fixture is intentionally not used as an application-UX surrogate.
+Unit coverage pins registration and disposal, exclusive scheduling, generated prompt policy, filler-safe generic presentation, direct-human creation in a non-English turn, exact/stale/non-running agent and driver checks, live-child rejection, resumed-fork root authority, steering, mismatched initiators, read/create/partial-edit/pause/resume behavior including strict-schema fillers, conditional blocker explanations, rearming after a session-start edge, authority-before-conditional-argument failures, exact goal-round completion, autonomous-only terminal stopping, the configured blocking threshold, and immediate human blocking. A keyless replay snapshot mounts the goal domain and tools into the real headless one-shot application, drives a strict-filler `update_goal` probe plus `create_goal` and `get_goal` through the shipped loop and persistence stack, pins its stream-json transcript, and inspects the externally persisted goal change. The echo-agent fixture is intentionally not used as an application-UX surrogate.
 
 ## Alternatives considered
 
@@ -48,6 +48,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 - **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.
+- **Reject every present action-specific field** — rejected because strict-schema providers can serialize zero-value placeholders for every optional field; only meaningful values can express a conflicting action.
 
 ## Consequences
 
@@ -56,6 +57,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 - 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.
+- Strict-schema provider fillers interoperate without allowing meaningful cross-action updates.
 
 ## Known limitations and deferred work
 
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 1a38116035..b0b4fc99ad 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
@@ -16,11 +16,11 @@ Status: implemented
 
 ### 工具与模型契约
 
-`get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大目标回合数、可能存在的阻塞原因，以及进程本地激活态观察。`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` 持久化。
+`get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大目标回合数、可能存在的阻塞原因，以及进程本地激活态观察。`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 占位值：这些值等同于省略；编辑时仍必须提供至少一个有实际意义的替换字段；所有非占位值仍受对应操作的限制。
 
 提示词告诉模型：它可以从任何措辞或语言的直接人类请求中推断目标意图，但不应把常规单轮工作转换为目标。更新前必须读取当前目标，并复制准确的 id 和修订号。对于恢复或派生后处于活跃但未激活状态的目标，人类在语义上要求继续即可成为执行 `resume` 的依据。只有目标已经实现时才能标记完成，困难或不确定性本身不构成阻塞；阻塞报告必须说明具体条件。
 
-三个工具都采用独占执行，使模型排序的批次可以观察此前变更及其新修订号。结果为紧凑 JSON。ACP 展示是参数的纯函数，使用通用读取或变更卡片；激活态仅作为实时观察返回，绝不会写入回放状态。
+三个工具都采用独占执行，使模型排序的批次可以观察此前变更及其新修订号。结果为紧凑 JSON。ACP 展示是参数的纯函数，使用通用读取或变更卡片；变更卡片选择输入时，先取有实际意义的操作值，再取目标 id，因此允许的占位值不会使卡片输入留空。激活态仅作为实时观察返回，绝不会写入回放状态。
 
 自主目标回合成功报告完成或阻塞后，插件会为该物理轮次贡献现有的终止型 `agent/turn-stop` 决策，避免再发起一次不必要的模型请求。直接人类发起的变更不会贡献终止决策：智能体可以确认该变更，并且并发的人类 steering（转向）仍可参与普通的继续执行折叠。
 
@@ -38,7 +38,7 @@ Status: implemented
 
 ## 测试
 
-单元测试固定注册与释放、独占调度、生成的提示词策略、通用展示、非英语轮次中的直接人类创建、精确/陈旧/非运行中智能体与驱动检查、实时子智能体拒绝、恢复后派生根的权限、steering、发起者不匹配、读取/创建/编辑/暂停/恢复行为、条件式阻塞说明、会话启动边沿后的重新激活、权限先于条件参数失败、准确目标回合的完成、仅自主回合触发终止、可配置阻塞阈值，以及人类立即阻塞。无密钥回放快照把目标领域和工具挂载到真实的 headless 单次运行应用中，通过随附循环与持久化栈驱动 `create_goal` 和 `get_goal`，固定 stream-json 转录，并检查外部持久化的目标变更。这里有意不把 echo-agent 测试夹具当作应用 UX 的替代品。
+单元测试固定注册与释放、独占调度、生成的提示词策略、可安全处理占位值的通用展示、非英语轮次中的直接人类创建、精确/陈旧/非运行中智能体与驱动检查、实时子智能体拒绝、恢复后派生根的权限、steering、发起者不匹配、读取/创建/部分字段编辑/暂停/恢复行为（包括严格 schema 占位值）、条件式阻塞说明、会话启动边沿后的重新激活、权限先于条件参数失败、准确目标回合的完成、仅自主回合触发终止、可配置阻塞阈值，以及人类立即阻塞。无密钥回放快照把目标领域和工具挂载到真实的 headless 单次运行应用中，通过随附循环与持久化栈驱动一次携带严格 schema 占位值的 `update_goal` 探测，以及对 `create_goal` 和 `get_goal` 的调用，固定 stream-json 转录，并检查外部持久化的目标变更。这里有意不把 echo-agent 测试夹具当作应用 UX 的替代品。
 
 ## 考虑过的替代方案
 
@@ -48,6 +48,7 @@ Status: implemented
 - **根据持久的根或派生元数据授权**——不予采纳，因为成为独立恢复顶层会话的派生应接受新的人类权限，而当前仍受所有权约束的子智能体则不应接受。
 - **允许自主回合编辑或恢复目标**——不予采纳，因为继续执行权限比重新定义或重启人类目标的权限更窄。
 - **把阻塞阈值当作评估器**——不予采纳，因为事件计数无法证明障碍在语义上未改变或确实不可继续。
+- **拒绝所有已提供的特定操作字段**——不予采纳，因为采用严格 schema 的提供方可能为每个可选字段序列化零值占位符；只有有实际意义的字段值才能表示与指定操作相冲突的另一项操作。
 
 ## 后果
 
@@ -56,6 +57,7 @@ Status: implemented
 - 人类可以通过普通自然语言请求创建和重新激活目标，而恢复后的会话在收到此类输入前保持静止。
 - 目标回合可以完成或报告重复阻塞，但不能自行扩大任务权限。
 - 部署策略选择阻塞下限；同一个解析后的值同时控制执行与提示词指导。
+- 系统可兼容采用严格 schema 的提供方所填入的占位值，同时不会放行有实际意义的跨操作更新。
 
 ## 已知限制与延期工作
 
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
new file mode 100644
index 0000000000..0f1bead590
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-code-mode-typed-tool-returns.md: 29f139a7e965de3a374d195ecc205210e6ae7e93
+2026-07-20-code-mode-typed-tool-returns.zh.md: 431c0b1717c6783771255ce8291c241f8f92c30b
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
new file mode 100644
index 0000000000..29f139a7e9
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
@@ -0,0 +1,112 @@
+# Agent Note: Typed tool returns in Code Mode
+
+Status: implemented
+
+English | [中文](2026-07-20-code-mode-typed-tool-returns.zh.md)
+
+## Problem
+
+Code Mode originally projected each nested tool result back from `ContentBlock[]` into one string. That preserved the human-readable Native surface but erased the canonical result the tool had already produced: programs had to scrape task ids and dynamic mount ids from prose, structured search and workflow results lost their shape, and non-text blocks became placeholders. The generated SDK could describe arguments but could only promise `Promise<string>` regardless of the tool's real output.
+
+The runtime also treated binding values and the final program value as presentation data. Separate log and completion caps could replace an oversized or non-cloneable completion with inspected text even though intermediate values do not enter model context. That made programmatic composition lossy and confused the memory boundary with the prompt boundary.
+
+The [canonical tool-output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) establishes one validated execution-time value and a separate Native renderer. Code Mode should consume that value directly, preserve it across the worker boundary, and bound only the final output the program deliberately returns to the model.
+
+## Decision
+
+Code Mode is a typed projection of the visible tool registry. Each successful binding resolves to the final canonical `JsonValue` after post-execute policy, while a failed binding rejects with a real `ToolCallError`. Intermediate values remain inside the run and cross the worker boundary whole. Only the outer `run_code` logs, completion value, or failure diagnostic enter the configurable output ledger and the model-facing spill pipeline.
+
+This note owns the return and failure contract layered on the original [Code Mode foundation](2026-06-15-code-mode.md). The unified schema vocabulary is owned by the [JSON-value schema DSL note](../architecture/2026-07-20-unified-json-value-schema-dsl.md), and Native rendering and policy projection remain owned by the canonical-output note.
+
+### Generated SDK
+
+At each prompt assembly the registry projects every visible tool's parameter schema and detached canonical output schema into one deterministic declaration:
+
+```ts ignore-check
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+interface ToolArgsMap {
+  // one exact inferred entry per visible tool
+}
+
+interface ToolOutputMap {
+  // one exact inferred entry per visible tool
+}
+
+type ToolName = keyof ToolOutputMap
+
+declare class ToolCallError extends Error {
+  readonly name: 'ToolCallError'
+  readonly toolName: ToolName
+}
+
+declare const tools: {
+  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>
+}
+```
+
+`jsonSchemaToTs()` covers every supported unified-schema node: object, array, string, number, integer, boolean, null, unconstrained JSON, scalar `enum` and `const`, and `oneOf`. Unsupported raw constructs degrade to `unknown` during prompt generation rather than breaking assembly. Tool names retain their exact keys, including names that require quoted access.
+
+### Binding values and failures
+
+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.
+
+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.
+
+### Outer result and output ledger
+
+The runtime accepts an exact lossless JSON completion of any root. Returning `undefined` omits the completion; returning `null` is an explicit result. `run_code` exposes the canonical outer value `{ logs: string[], result?: JsonValue }`. Its Native renderer emits logs first, renders a string result raw, and renders every other JSON root with an iterative pretty printer. Total indentation is capped at ten characters and deeper subtrees remain compact, preserving the established shallow text while keeping traversal stack-safe and formatted size linear in the canonical JSON size.
+
+`WorkerCodeRuntime` replaces the former independent log and value caps with configurable `maxOutputBytes`, defaulting to `67_108_864` bytes. The worker charges captured logs by their exact JSON-string serialization and preflights the detached completion or program exception against the remaining combined budget before posting a terminal message. A giant thrown string or stack therefore crosses the worker port only as the fixed `output-limit` diagnostic. The host repeats the hostile-peer ledger for forged traffic and native pipe writes the worker cannot observe. Fixed `CodeRunResult` field names, braces, the bounded error-kind tag, and later presentation whitespace are deliberately outside this variable-payload ledger. Neither stage materializes an over-limit serialized completion. A result at or below the cap is exact. A completion that cannot survive lossless JSON snapshotting fails as `invalid-output`; a value, diagnostic, or combined outcome over the cap fails as `output-limit` rather than becoming inspected or truncated text.
+
+Logs stream eagerly so a terminated run can retain output already admitted. Native stdout and stderr writes that bypass the worker's patched stream slots use independent pipes, so terminal settlement continues bounded capture until worker termination completes before materializing the result. When the cap is crossed, the runtime returns an explicit bounded failure with the fitting captured prefix. That outer result then traverses the ordinary `run_code` rendering and spill policy, which may save the captured text and expose its configured head/tail preview. The spill layer cannot recover bytes the runtime rejected beyond the hard cap.
+
+Compute time, wall time, worker heap, cancellation, and fresh-worker isolation remain independent limits. The outer ledger never charges intermediate bindings, so snapshotting, flat-wire encoding and decoding, structured-clone cost, and available process or worker memory are their practical bounds.
+
+### Typed handles and lifetime
+
+Background producers return a typed canonical handle such as `{ kind: 'background', taskId }` while retaining their established Native sentence. A pre-aborted background call remains a failure because successful output promises an id and no task was created. After `ctx.tasks.start()` publishes the id, task-owned cancellation governs the work: settlement or later cancellation of the enclosing `run_code` call does not kill it. A later program can pass the returned id to `task_output`, and `task_kill`, owner disposal, or service teardown owns cancellation. Foreground execution remains coupled to the call signal. The task lifetime contract is owned by the [background task runtime note](../architecture/2026-06-20-generic-long-running-tool-runtime.md).
+
+Dynamic Cordis mounting follows the same rule: `cordis_mount` returns `{ id, pluginName, state, provides, waitingFor }`, so a program can read `mounted.id`, inspect active or pending state, and pass that id to `cordis_unmount` without parsing the stable Native sentence.
+
+### Persistence, metadata, and spill
+
+Nested dispatch keeps the existing bounded `tool/code-dispatch.resultSummary` for diagnostics but does not persist canonical values. `tool/result` continues to persist only rendered content, error, and optional metadata. This is deliberately not a session-format change, so `SESSION_FORMAT_VERSION` remains unchanged and replay cannot recreate intermediate program values.
+
+The opaque `exec.parent` token marks nested calls. Presentation metadata and generic or tool-owned spill projections skip those calls because they have no direct result card and their canonical values never enter context. The outer `run_code` call alone produces one card and may spill its final post-policy presentation; `run_code` intentionally declares neither a result presenter nor presentation metadata, so ACP and TUI complete the card through their generic raw-content fallback using durable `tool/result.content`.
+
+## Testing
+
+Compile-time and snapshot tests pin exact `ToolArgsMap`, `ToolOutputMap`, `ToolName`, schema-to-TypeScript coverage, and exotic names. Registry and real-worker tests cover scalar, array, object, and null values; raw string rendering; absent `undefined`; consumer-declared real rejection classes, including `ToolCallError`; invalid arguments and completions, including intrinsic-looking forged prototypes; model-mutated JSON-boundary globals, prototype methods, constructor slots, and inherited descriptor fields; typed binding failures after those mutations; large uncapped intermediate bindings; nested spill suppression; exact and over-limit 64 MiB accounting; combined logs/value/diagnostic accounting; giant thrown stacks; bounded failure spill; hostile forged traffic; and built-package execution.
+
+Keyless real-worker integration tests pin the two handle workflows that prose results could not safely support. A background bash call returns its task id, the outer run settles, and a later run polls that id to completion; separate cases prove pre-abort creates no task, post-publication call abort preserves the task, foreground execution stays signal-coupled, and `task_kill` owns cancellation. A Cordis program reads an active or pending mount's id and `waitingFor` fields directly, unmounts by that id, and confirms removal without parsing rendered text.
+
+## Alternatives considered
+
+**Return Native text plus optional JSON.** Rejected because the program would have two competing success contracts and would still need tool-specific parsing rules when the optional value is absent. Canonical value is the API; Native content is its presentation.
+
+**Expose a success/failure union from every binding.** Rejected because failure has no stable programmatic taxonomy. Rejections preserve ordinary `try`/`catch` control flow and expose only the tool name and human-readable message.
+
+**Cap each intermediate binding.** Rejected because intermediate values are not placed in model context and arbitrary truncation would corrupt programmatic composition. The producer's acquisition contract and process memory remain explicit boundaries.
+
+**Silently inspect or truncate an oversized completion.** Rejected because changing a JSON value into a string is lossy and type-incorrect. The explicit `output-limit` failure lets the model choose a smaller result, while the retained logs and diagnostic can still use normal outer spill.
+
+## Consequences
+
+Code programs can compose tools through stable values instead of reverse-engineering Native prose. Native and Both Mode retain their existing text and editor presentation, while Code Mode receives output-schema types and exact runtime JSON. Tool authors must treat the canonical value as their programmatic API and put display-only formatting in the renderer.
+
+The worker performs bounded-depth flat-wire transport and lossless validation but does not make intermediate values cheap or durable. Outer overflow is an explicit failed run, and error handling remains intentionally human-guided rather than a versioned code union.
+
+## Known Limitations and Deferred Work
+
+- Subagent and workflow caller-defined structured outputs remain object-rooted through consumer-level guards even though tool outputs may use any JSON root.
+- Post-execute has separate value and presentation projections; replacing content is not a confidentiality mechanism, so policy must block or replace the value to hide it from programmatic callers.
+- Intermediate canonical values are execution-local and unavailable to replay because durable events persist only presentation and bounded summaries.
+- Intermediate values have no byte cap and can exhaust process or worker memory through retention, flat-wire copies, or structured-clone cost.
+- The 64 MiB hard cap applies only to the outer variable payloads, excluding fixed result-envelope syntax and presentation whitespace; spill cannot recover bytes rejected beyond that cap.
+- Provider or executor acquisition limits may already have discarded source data before a canonical value reaches Code Mode.
+- Unsupported MCP output schemas fall back to `JsonValue`; richer Native multimedia projection is deferred.
+- There is one result card per outer `run_code`, never per nested call.
+- Code failures expose `ToolCallError` message and tool name only, without a programmatic error-code union.
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
new file mode 100644
index 0000000000..431c0b1717
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
@@ -0,0 +1,112 @@
+# Agent Note：Code Mode 的类型化工具返回值
+
+Status: implemented
+
+[English](2026-07-20-code-mode-typed-tool-returns.md) | 中文
+
+## 问题
+
+Code Mode 过去会把每个嵌套工具的结果从 `ContentBlock[]` 重新投影为一个字符串。这样虽然保留了适合人类阅读的 Native 接口，却丢失了工具已经生成的规范结果：程序只能从自然语言中提取 task id 和动态挂载 id；结构化搜索与工作流结果失去原有形态；非文本块则变为占位符。生成的 SDK 可以描述参数，却无论工具实际输出为何都只能承诺 `Promise<string>`。
+
+运行时还把绑定值和程序最终返回值当作展示数据。日志和完成值分别设置上限，导致过大或无法克隆的完成值可能被替换为检查格式化后的文本，而中间值本来就不会进入模型上下文。这种设计使程序化组合产生信息损失，也混淆了内存边界与提示词边界。
+
+[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)确立了单一、经过校验的执行期值，并将 Native 渲染器与之分离。Code Mode 应直接消费该值，在跨越 worker 边界时完整保留它，并且只限制程序有意返回给模型的最终输出。
+
+## 决策
+
+Code Mode 是可见工具注册表的类型化投影。每个成功的绑定调用都会解析为 post-execute 策略处理后的最终规范 `JsonValue`，失败的绑定调用则以真正的 `ToolCallError` reject。中间值只存在于本次运行中，并完整跨越 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 定义。
+
+### 生成的 SDK
+
+每次组装提示词时，注册表都会把每个可见工具的参数 schema 及其分离的规范输出 schema 投影为一份确定性声明：
+
+```ts ignore-check
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+interface ToolArgsMap {
+  // one exact inferred entry per visible tool
+}
+
+interface ToolOutputMap {
+  // one exact inferred entry per visible tool
+}
+
+type ToolName = keyof ToolOutputMap
+
+declare class ToolCallError extends Error {
+  readonly name: 'ToolCallError'
+  readonly toolName: ToolName
+}
+
+declare const tools: {
+  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>
+}
+```
+
+`jsonSchemaToTs()` 覆盖统一 schema 支持的所有节点：对象、数组、字符串、数字、整数、布尔值、null、无约束 JSON、标量 `enum` 与 `const`，以及 `oneOf`。提示词生成期间，不支持的原始结构会降级为 `unknown`，而不会导致组装失败。工具名会保留精确键名，包括必须使用引号访问的名称。
+
+### 绑定值与失败
+
+分发前，桥接层会把绑定参数快照为无损 JSON，再对分离后的值生成一次快照，供独立的持久摘要事件使用。宿主侧的值分离、执行数据的不可变处理与输出 schema 投影均采用迭代遍历，而不使用嵌套结构化克隆或递归冻结。`undefined`、非有限数、`-0`、稀疏数组、循环引用、函数和非普通对象都会使该调用在工具运行前 reject。成功分发会返回 `ToolExecutionResult.value`；Native `content`、元数据和内部错误信息不会传入程序。
+
+Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其 reject 异常能力。运行时 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 值，同时提供方和执行器的采集上限仍会实际生效。
+
+### 外层结果与输出账本
+
+运行时接受以任意 JSON 类型为根的精确无损完成值。返回 `undefined` 表示省略完成值；返回 `null` 则是显式结果。`run_code` 暴露规范外层值 `{ logs: string[], result?: JsonValue }`。其 Native 渲染器先输出日志；字符串结果保持原文，其他所有 JSON 根值则使用迭代式美化渲染器。总缩进长度上限为 10 个字符，更深的子树保持紧凑格式，既保留既有的浅层文本，又确保遍历不受调用栈深度限制，且格式化输出大小与规范 JSON 大小呈线性关系。
+
+`WorkerCodeRuntime` 以可配置的 `maxOutputBytes` 取代彼此独立的日志与值上限，默认值为 `67_108_864` 字节。worker 会将已捕获日志序列化为 JSON 字符串后的精确字节数计入账本，并在发送终态消息前，根据组合账本的剩余额度预检分离后的完成值或程序异常。因此，即使抛出的字符串或堆栈极大，通过 worker 端口的也只会是固定的 `output-limit` 诊断。宿主侧会针对伪造流量以及 worker 无法观察的原生管道写入，重复执行这套不可信对端计账。固定的 `CodeRunResult` 字段名、花括号、有界的错误类型标签及后续展示空白有意不计入这份可变负载账本。这两个阶段都不会实际生成超出上限的完成值序列化结果。结果不超过上限时会保持精确。完成值无法通过无损 JSON 快照时，以 `invalid-output` 失败；值、诊断或包含日志的组合结果超过上限时，以 `output-limit` 失败，而不会变成检查格式化后或截断的文本。
+
+日志会在产生时立即流出，因此运行被终止时仍可保留已经纳入额度的输出。绕过 worker 中已改写流写入入口的原生 stdout 和 stderr 写入会经由彼此独立的管道传输，因此运行时在终态结算期间仍会继续在上限内捕获输出，直至 worker 完全终止，然后才组装结果。超过上限后，运行时会返回一个显式的有界失败，并携带可容纳的已捕获前缀。该外层结果随后通过普通的 `run_code` 渲染与输出落盘策略；策略可以保存已捕获的文本，并暴露其配置指定的头尾预览。输出落盘层无法恢复运行时在硬上限之外拒绝的字节。
+
+计算时间、墙钟时间、worker 堆内存、取消和每次运行使用全新 worker 的隔离仍是互相独立的限制。外层账本从不计入中间绑定值，因此生成快照、扁平协议格式的编码与解码、结构化克隆开销，以及进程或 worker 的可用内存构成了这些值的实际边界。
+
+### 类型化句柄与生命周期
+
+后台 producer 返回类型化的规范句柄，例如 `{ kind: 'background', taskId }`，同时保留既有的 Native 语句。已预先中止的后台调用仍是失败，因为成功输出承诺返回 id，而此时并未创建任务。`ctx.tasks.start()` 发布 id 后，工作由任务自有的取消机制控制：外围 `run_code` 调用完成，或随后被取消，都不会终止该任务。后续程序可以把返回的 id 传给 `task_output`；取消则由 `task_kill`、owner dispose 或服务 teardown 负责。前台执行仍与本次调用的信号耦合。任务生命周期契约由[后台任务运行时 Agent Note](../architecture/2026-06-20-generic-long-running-tool-runtime.md)定义。
+
+动态 Cordis 挂载遵循同一规则：`cordis_mount` 返回 `{ id, pluginName, state, provides, waitingFor }`，因此程序可以直接读取 `mounted.id`，检查 active 或 pending 状态，并把该 id 传给 `cordis_unmount`，无需解析稳定的 Native 语句。
+
+### 持久化、元数据与输出落盘
+
+嵌套分发会为诊断保留既有的有界 `tool/code-dispatch.resultSummary`，但不会持久化规范值。`tool/result` 继续只持久化渲染后的内容、错误和可选元数据。这并非会话格式变更，因此 `SESSION_FORMAT_VERSION` 保持不变，回放也无法重建程序的中间值。
+
+不透明的 `exec.parent` token 用于标识嵌套调用。由于这些调用没有直接对应的结果卡片，而且其规范值永远不会进入上下文，展示元数据以及通用或工具自有的输出落盘投影都会跳过它们。只有外层 `run_code` 调用会生成一张卡片，并且可能将 post-policy 处理后的最终展示写入落盘文件；`run_code` 有意既不声明结果展示器，也不声明展示元数据，因此 ACP 和 TUI 通过其通用的原始内容回退机制，使用持久化的 `tool/result.content` 补全该卡片。
+
+## 测试
+
+编译期测试与快照测试锁定了精确的 `ToolArgsMap`、`ToolOutputMap`、`ToolName`、schema 到 TypeScript 的覆盖范围以及特殊名称。注册表与真实 worker 测试覆盖标量、数组、对象和 null 值；字符串原文渲染；缺席的 `undefined`；消费方声明并用于 reject 的真实异常类，包括 `ToolCallError`；无效参数与完成值，包括伪装为内建原型的伪造原型；模型代码修改过的 JSON 边界全局对象、原型方法、构造函数槽位，以及继承而来的属性描述符字段；上述修改后的类型化绑定失败；不设上限的大型中间绑定值；嵌套输出落盘抑制；64 MiB 上限内外的精确计量；日志、值与诊断的组合计量；抛出的超大堆栈；有界失败的输出落盘；不可信对端伪造的流量；以及构建后包的执行。
+
+无密钥的真实 worker 集成测试锁定了自然语言结果无法安全支持的两种句柄工作流。后台 bash 调用返回 task id，外层运行结束，之后的运行再根据该 id 轮询直至任务完成；其他用例分别证明，预先中止不会创建任务、发布后的调用取消会保留任务、前台执行仍与信号耦合，并且取消归 `task_kill` 所有。Cordis 程序会直接读取 active 或 pending 挂载的 id 和 `waitingFor` 字段，按该 id 卸载，并在不解析渲染文本的情况下确认挂载已移除。
+
+## 备选方案
+
+**返回 Native 文本并附加可选 JSON：**不予采纳。程序会面对两套相互竞争的成功契约；可选值不存在时，仍需使用工具专属的解析规则。规范值才是 API；Native 内容只是它的展示。
+
+**让每个绑定返回成功／失败联合：**不予采纳。失败没有稳定的程序化分类体系。reject 保留普通的 `try`／`catch` 控制流，并且只暴露工具名与可供人阅读的消息。
+
+**限制每个中间绑定值：**不予采纳。中间值不会进入模型上下文，任意截断会破坏程序化组合。明确的边界仍是生产方的采集契约与进程内存。
+
+**静默检查格式化或截断过大的完成值：**不予采纳。把 JSON 值改成字符串既有损又违反类型。显式的 `output-limit` 失败让模型可以选择返回更小的结果，而保留的日志和诊断仍可使用普通的外层输出落盘机制。
+
+## 影响
+
+Code Mode 程序可以通过稳定值组合工具，无需逆向解析 Native 自然语言。Native 和 Both Mode 保留现有文本与编辑器展示，Code Mode 则获得输出 schema 类型和精确的运行时 JSON。工具作者必须把规范值视为程序化 API，并将仅用于展示的格式化放入渲染器。
+
+worker 会以嵌套深度有界的扁平协议格式传输数据并执行无损校验，但不会降低中间值的开销，也不会使其具备持久性。外层输出溢出会显式导致运行失败，错误处理则有意由人类引导，而不是依赖带版本的错误代码联合。
+
+## 已知限制与延后工作
+
+- 即使工具输出可以采用任意 JSON 根，subagent 和工作流中由调用方定义的结构化输出仍通过消费方级别的门禁保持对象根限制。
+- Post-execute 分别提供值投影与展示投影；替换内容不是保密机制，因此策略若需向程序化调用方隐藏内容，就必须阻止调用或替换值。
+- 中间规范值仅存在于执行期间，无法用于回放，因为持久事件只存储展示和有界摘要。
+- 中间值没有字节上限，可能因值的保留、扁平协议格式副本或结构化克隆开销而耗尽进程或 worker 内存。
+- 64 MiB 硬上限只适用于外层可变负载，不计固定的结果封装语法与展示空白；输出落盘无法恢复超出该上限后被拒绝的字节。
+- 提供方或执行器的采集上限可能在规范值到达 Code Mode 前就已丢弃部分源数据。
+- 不支持的 MCP 输出 schema 会回退为 `JsonValue`；更丰富的 Native 多媒体投影留待后续实现。
+- 每个外层 `run_code` 只有一张结果卡片，嵌套调用不会各自生成卡片。
+- Code Mode 失败只暴露 `ToolCallError` 的消息与工具名，不提供程序可用的错误代码联合。
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 a8c9c28d58..76dd488060 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
-2026-07-20-dsh-cli-personal-config.md: e349374a6bc7fc0137bf14836469aef8bae8d49d
-2026-07-20-dsh-cli-personal-config.zh.md: 88210dc386a245002de927950dab2852e40218ea
+2026-07-20-dsh-cli-personal-config.md: 9525aa811d792a918f03a52c21bc273e92fb8be7
+2026-07-20-dsh-cli-personal-config.zh.md: f21d4b1f22b3a3807b6b4155969282343f6048f5
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 e349374a6b..9525aa811d 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
@@ -12,7 +12,7 @@ A developer's own preferences — which provider and model the TUI uses, persona
 
 Two coupled pieces, aligned with the `apps/` assembly tier proposed by the `dsh web` PR (#443):
 
-**The `dsh` CLI (`apps/cli`, npm name `@deepseek-ai/dsh`).** `apps/*` joins the workspaces as the product-assembly tier over `packages/*` libraries. The bin's dispatch reserves `web` and `-p`/`--prompt` for PR #443 (they exit with a pointer) so the two branches merge as a near-union; everything else runs the default surface: the interactive TUI, booting the shipped `examples/tui-agent/cordis.yml` (or an explicit config argument) with the invoking directory as the workspace. The committed `bin/dsh` launcher resolves the checkout through its own real path and runs the bin **from source** via the repo's tsx (with `--expose-internals` for the config's HMR entry), so `ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh` installs a command that always executes the current working tree. `pnpm run demo:tui` runs the same entry.
+**The `dsh` CLI (`apps/cli`, npm name `@deepseek-ai/dsh`).** `apps/*` joins the workspaces as the product-assembly tier over `packages/*` libraries. The bin's dispatch reserves `web` and `-p`/`--prompt` for PR #443 (they exit with a pointer) so the two branches merge as a near-union; everything else runs the default surface: the interactive TUI, booting the shipped `examples/tui-agent/cordis.yml` (or an explicit config argument) with the invoking directory as the workspace. The committed `bin/dsh` launcher resolves the checkout through its own real path and runs the bin **from source** via the repo's tsx, so `ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh` installs a command that always executes the current working tree. `pnpm run demo:tui` runs the same entry.
 
 **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 surface consumes its two optional files; the demo bins boot their committed trees verbatim:
 
@@ -22,6 +22,8 @@ Two coupled pieces, aligned with the `apps/` assembly tier proposed by the `dsh
 
 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.
 
+Hot-reload interplay: the include re-applies its `patches` on every config re-read (the [config hot-reload resilience Agent Note](../bug-fix/2026-07-20-config-hot-reload-resilience.md)), so a live `cordis.yml` edit keeps the personal overlay applied.
+
 ## Alternatives considered
 
 **A standalone `bin/dsh` wrapper owning the `dsh` name.** Rejected after reading PR #443: that PR establishes `apps/cli` as the `dsh` CLI with subcommand dispatch (`web`, `-p`) and leaves the default slot unclaimed. Two competing `dsh` entrypoints would collide in `$PATH` and in product identity; claiming the default slot inside the same package shape confines the eventual merge conflict to the small dispatch chain.
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 88210dc386..f21d4b1f22 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
@@ -12,7 +12,7 @@ Status: implemented
 
 两个耦合的部分，与 `dsh web` PR（#443）提出的 `apps/` 装配层对齐：
 
-**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 作为 `packages/*` 库之上的产品装配层加入 workspaces。bin 的分发把 `web` 和 `-p`/`--prompt` 保留给 PR #443（它们以指引退出），使两个分支能以接近并集的方式合并；其余一切都运行默认表面：交互式 TUI，加载随仓库提供的 `examples/tui-agent/cordis.yml`（或显式的配置参数），并以调用目录为工作区。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，用仓库的 tsx **从源码**运行该 bin（带 `--expose-internals`，供配置里的 HMR 配置项使用），因此 `ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh` 安装的命令永远执行当前工作树。`pnpm run demo:tui` 运行同一入口。
+**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 作为 `packages/*` 库之上的产品装配层加入 workspaces。bin 的分发把 `web` 和 `-p`/`--prompt` 保留给 PR #443（它们以指引退出），使两个分支能以接近并集的方式合并；其余一切都运行默认表面：交互式 TUI，加载随仓库提供的 `examples/tui-agent/cordis.yml`（或显式的配置参数），并以调用目录为工作区。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，用仓库的 tsx **从源码**运行该 bin，因此 `ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh` 安装的命令永远执行当前工作树。`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 表面消费其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
 
@@ -22,6 +22,8 @@ Status: implemented
 
 PTY 冒烟测试的启动器把 `$DSH_HOME` 隔离到每个测试自己的目录，与它已有的 `DSH_AGENTS_HOME` 隔离方式完全一致，开发者真实的个人 overlay 不可能泄漏进 fixture；只有 dsh CLI 读取个人配置，因此其他测试启动器无需改动。
 
+与热重载的交互：include 在每次配置重读时重新应用其 `patches`（见[配置热重载韧性 Agent Note](../bug-fix/2026-07-20-config-hot-reload-resilience.md)），因此运行中编辑 `cordis.yml` 后个人 overlay 仍保持生效。
+
 ## Alternatives considered
 
 **独立的 `bin/dsh` 包装脚本占有 `dsh` 这个名字。** 读过 PR #443 后否决：该 PR 把 `apps/cli` 确立为带子命令分发（`web`、`-p`）的 `dsh` CLI，并且默认位空缺。两个互相竞争的 `dsh` 入口会在 `$PATH` 和产品身份上冲突；在同一包形态内认领默认位，把最终的合并冲突限制在小小的分发链上。
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 32b0b3a218..929a802080 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
-2026-07-21-log-backed-session-titles.md: cd0d2a4bab9b6504c65e942c0e03bce79488364e
-2026-07-21-log-backed-session-titles.zh.md: b90ac6c59677e6542733210b91de38ef1169c760
+2026-07-21-log-backed-session-titles.md: 183aa6909fecffdaf18c77c2a66fbc38c67c2d2c
+2026-07-21-log-backed-session-titles.zh.md: c6a0c2ce2ad4b2cddec2ada36f655fe55adb143b
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 cd0d2a4bab..183aa6909f 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, the event log is the replay and fork bou
 
 ## 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 with overridable explicit example limits, leaving both model providers opt-in.
+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.
 
 ### Event ownership and folding
 
@@ -32,7 +32,7 @@ The first-message provider schedules once when a fresh session first creates its
 
 `register(provider)` validates one branded stable id, cadence, and generation function, then returns an awaitable effect disposer. A second live registration throws immediately. Provider disposal marks the registration closing, aborts its pending and active work, and waits for every call to settle before removing the registration, so replacement cannot overlap a provider that ignores cancellation. Session disposal aborts its active work. Service teardown prevents queued fallback and provider microtasks from starting, aborts active work, and drains tracked promises before unloading completes. Every session-local generation has a monotonic revision and exact registration identity; acceptance rechecks revision, registration, session liveness, service liveness, and cancellation, so stale output cannot commit.
 
-Model providers require explicit word, CJK-character, input-byte, output-token, and timeout limits. Optional `provider` and `model` overrides are a pair; without them the helper uses the exact route from the logged main request header. Selected messages are framed as JSON under one fixed language-aware instruction. The input limit measures that final user prompt, including wrappers, seq fields, and JSON escaping, before the request is logged or dispatched. Oversized input is rejected rather than truncated because truncation would make the recorded source seqs falsely imply complete use. The fused deadline is checked while consuming each stream chunk and after completion, so a successful result returned after timeout cannot be accepted even when an interceptor or adapter ignores abort.
+Model providers require explicit word, CJK-character, input-byte, output-token, and timeout limits. Optional `provider` and `model` overrides are a pair; without them the helper uses the exact route from the logged main request header. Selected messages are framed as JSON under one fixed language-aware instruction. The dispatched `GenerateOptions` carries `purpose: 'session-title'`; the DeepSeek adapter maps that purpose to thinking-disabled and omits reasoning effort so the bounded output is visible title text, while the main conversation keeps its configured thinking mode. The input limit measures the final user prompt, including wrappers, seq fields, and JSON escaping, before the request is logged or dispatched. Oversized input is rejected rather than truncated because truncation would make the recorded source seqs falsely imply complete use. The fused deadline is checked while consuming each stream chunk and after completion, so a successful result returned after timeout cannot be accepted even when an interceptor or adapter ignores abort.
 
 Automatic provider failures are nonfatal warnings and retain the latest title. Explicit refresh failures reject to the caller. Output must be non-empty text with unique ordered seqs drawn from the fixed request; the service normalizes and byte-limits it before durable acceptance.
 
@@ -40,7 +40,7 @@ Automatic provider failures are nonfatal warnings and retain the latest title. E
 
 A fork inherits seed title events unchanged, like the rest of its source log. The first-message provider does not automatically retitle a fork. The all-messages provider may append a child-owned revision after a later child prompt, using inherited and new eligible messages.
 
-`ctx.sessionQuery.readTitle()` folds one live-preferred or persisted log without loading titles during `listSessions()`. ACP maps the event to `session_info_update` during both live streaming and load replay, using the event timestamp for `updatedAt`. The TUI uses the latest title as its header subtitle and sets the terminal window title to `<session title> — <configured product title>` after terminal-safe rendering. A synthetic title turn remains a completed durability boundary for the metadata write; consumers reporting agent completion use the core `findLastMessageTurnEnd()` fold so a later title, injection, or other plugin-owned turn cannot replace the preceding message-triggered outcome.
+`ctx.sessionQuery.readTitle()` folds one live-preferred or persisted log without loading titles during `listSessions()`. ACP maps the event to `session_info_update` during both live streaming and load replay, using the event timestamp for `updatedAt`. The TUI uses the latest title as its header subtitle and sets the terminal window title to `<session title> — <configured product title>` after terminal-safe rendering. The Web host folds the same log state into a validated mux control frame after each attached-session subscription baseline and immediately after forwarding a live raw title event. The browser retains only newer title event seqs even when the control frame precedes list or session-instance creation; sidebar labels, search, breadcrumbs, and the browser title then react to the projected revision. `session.list` remains metadata-only, so a cold persisted session uses the cwd basename or id until opening or resuming it attaches the log. The browser title uses `<session title> — <existing HTML title>` only for a selected titled session and otherwise preserves the product title. A synthetic title turn remains a completed durability boundary for the metadata write; consumers reporting agent completion use the core `findLastMessageTurnEnd()` fold so a later title, injection, or other plugin-owned turn cannot replace the preceding message-triggered outcome.
 
 ## Alternatives considered
 
@@ -50,11 +50,13 @@ A fork inherits seed title events unchanged, like the rest of its source log. Th
 - **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.
 - **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.
 
 ## Consequences
 
 - Titles survive JSONL and SQLite persistence, replay through ACP, and follow fork inheritance without a separate mutable record.
-- A fallback appears without an auxiliary call; deployments choose whether better titles justify model cost and whether later prompts should retitle a session.
+- Web title delivery stays incremental and log-backed without a title index or persisted-list scan; cold list rows improve after attach.
+- A fallback appears immediately. Each fresh Web session adds one first-message auxiliary call; other compositions choose whether better titles justify model cost and whether later prompts should retitle a session.
 - Auxiliary request records and late accepted titles consume event seqs and may create balanced zero-step turns, so persistence exposes both attempted dispatches and accepted updates even though model history and KV-cache identity do not change.
 - One provider and monotonic per-session revisions make disposal, supersession, and stale-result rejection explicit, at the cost of leaving multi-strategy precedence to a composite provider.
 - Manual rename, deletion, generated-versus-user precedence, search, and list indexing remain outside the capability.
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 b90ac6c596..c6a0c2ce2a 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 主干只挂载回退服务，并为其显式设置可覆盖的示例限制；两种模型提供方均需按需启用。
+[`session-title` 功能包族](../../../../packages/session-title/README.md)负责标题状态和生成策略。`@deepseek-ai/dsh-session-title` 提供 `ctx.sessionTitle`、确定性的首消息回退方案，以及一个至多接受单个可选异步提供方的注册表。`@deepseek-ai/dsh-session-title-llm` 负责通用的辅助模型请求策略；首消息插件和全部用户消息插件分别选择输入调度方式。共享 agent 主干只挂载回退服务。Web host 会挂载该服务和首消息模型提供方，并显式设置可覆盖的限制，因此新建的 Web 会话会立即获得回退标题，随后在不阻塞主响应的情况下获得模型摘要。其他组合需显式选择任一模型提供方。
 
 ### 事件归属与折叠
 
@@ -32,7 +32,7 @@ Status: implemented
 
 `register(provider)` 会验证一个带品牌类型的稳定 id、执行时机和生成函数，然后返回一个可等待完成的 effect 资源释放函数。第二个活跃注册会立即抛出错误。提供方执行资源释放时，会将注册标记为正在关闭，中止其待执行和活跃工作，并等待所有调用结束后才移除注册，因此替代提供方不会与忽略取消的旧提供方重叠运行。会话资源释放会中止其活跃工作。服务卸载时，会阻止排队中的回退和提供方微任务启动，中止活跃工作，并且卸载完成前会等待所有已跟踪的 promise 结算。每项会话本地生成都有单调递增的修订号和对应的注册身份；接受结果时会重新检查修订号、注册、会话活跃状态、服务活跃状态和取消状态，因此陈旧输出无法提交。
 
-模型提供方必须显式配置单词数、CJK 字符数、输入字节数、输出 token 数和超时限制。可选的 `provider` 和 `model` 覆盖项必须成对提供；两者均未提供时，辅助组件会使用主请求已记录请求头中的准确路由。系统在一条固定且能区分语言的指令下，将选中的消息封装为 JSON。输入字节数按最终形成的用户提示词计算，其中包括包装文本、seq 字段和 JSON 转义；系统会在记录请求或发起调用前完成这项检查。过大输入会被拒绝而不是截断，因为截断会让记录的源消息 seq 错误地表示这些消息已被完整使用。系统在消费每个流分片时以及流完成后都会检查融合后的截止时间，因此即使拦截器或适配器忽略中止信号，超时后返回的成功结果也不会被接受。
+模型提供方必须显式配置单词数、CJK 字符数、输入字节数、输出 token 数和超时限制。可选的 `provider` 和 `model` 覆盖项必须成对提供；两者均未提供时，辅助组件会使用主请求已记录请求头中的准确路由。系统在一条固定且能区分语言的指令下，将选中的消息封装为 JSON。发出的 `GenerateOptions` 携带 `purpose: 'session-title'`；DeepSeek 适配器将该用途映射为禁用思考且省略推理强度设置的请求，使受限输出成为可见的标题文本，而主对话仍沿用已配置的思考模式。输入字节数按最终形成的用户提示词计算，其中包括包装文本、seq 字段和 JSON 转义；系统会在记录请求或发起调用前完成这项检查。过大输入会被拒绝而不是截断，因为截断会让记录的源消息 seq 错误地表示这些消息已被完整使用。系统在消费每个流分片时以及流完成后都会检查融合后的截止时间，因此即使拦截器或适配器忽略中止信号，超时后返回的成功结果也不会被接受。
 
 自动提供方故障只会发出非致命警告，并保留最新标题。显式刷新失败则会向调用方返回拒绝。输出必须是非空文本，并包含来自固定请求、唯一且有序的 seq；服务会在持久接受前对其进行规范化并施加字节限制。
 
@@ -40,7 +40,7 @@ Status: implemented
 
 与源日志的其他部分相同，fork 会原样继承作为种子的标题事件。首消息提供方不会自动为 fork 重新生成标题。全部消息提供方可以在子会话出现后续提示词后追加一项归子会话所有的修订，并使用继承的合格消息和新增的合格消息。
 
-`ctx.sessionQuery.readTitle()` 会折叠一份实时优先或已持久化的日志，而不会在 `listSessions()` 期间加载标题。ACP（Agent Client Protocol）会在实时流式输出和加载回放期间把该事件映射到 `session_info_update`，并使用事件时间戳作为 `updatedAt`。TUI 使用最新标题作为其标题栏副标题，并在完成终端安全渲染后，将终端窗口标题设置为 `<session title> — <configured product title>`。合成标题轮次本身仍会完成，并作为元数据写入的持久性边界；报告 agent 完成情况的消费方使用核心的 `findLastMessageTurnEnd()` 折叠逻辑，因此后续的标题轮次、注入轮次或其他归插件所有的轮次无法取代此前由消息触发的结果。
+`ctx.sessionQuery.readTitle()` 会折叠一份实时优先或已持久化的日志，而不会在 `listSessions()` 期间加载标题。ACP（Agent Client Protocol）会在实时流式输出和加载回放期间把该事件映射到 `session_info_update`，并使用事件时间戳作为 `updatedAt`。TUI 使用最新标题作为其标题栏副标题，并在完成终端安全渲染后，将终端窗口标题设置为 `<session title> — <configured product title>`。Web host 会在每个已附加会话的订阅基线之后，以及转发实时原始标题事件后立即，将同一份日志状态折叠为经过校验的 mux 控制帧。即使控制帧先于列表或会话实例创建抵达，浏览器也只保留标题事件 seq 较新的版本；侧边栏标签、搜索、面包屑和浏览器标题会随投影后的修订更新。`session.list` 仍只包含元数据，因此尚未打开的持久化会话会继续以 cwd 基名或 id 作为回退，直至打开或恢复会话时附加其日志。浏览器仅在选中已有标题的会话时将标题设置为 `<session title> — <existing HTML title>`，否则保留产品标题。合成标题轮次本身仍会完成，并作为元数据写入的持久性边界；报告 agent 完成情况的消费方使用核心的 `findLastMessageTurnEnd()` 折叠逻辑，因此后续的标题轮次、注入轮次或其他归插件所有的轮次无法取代此前由消息触发的结果。
 
 ## 考虑过的替代方案
 
@@ -50,11 +50,13 @@ Status: implemented
 - **允许注册多个提供方，并在完成后解析优先级**：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和来源信息变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
 - **静默截断过大的辅助输入**：不予采纳，因为提供方结果会声明准确的源消息来源信息，实际却只接收了部分文本。保留原有标题并发出警告，可以保持归因真实。
 - **立即在 `listSessions()` 中索引标题**：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的 `readTitle()` 建立了读取契约，而没有提前锁定搜索或索引策略。
+- **让 Web host 只使用回退标题**：不予采纳，因为 UI 虽会显示持久标题，却始终无法将第一条提示词的前缀改进为更好的标题。首消息提供方在主响应路径之外运行，并让模型摘要成为 Web 的默认结果。
 
 ## 后果
 
 - 标题可以在 JSONL 和 SQLite 持久化中存续，通过 ACP 回放，并遵循 fork 继承语义，而无需单独的可变记录。
-- 回退标题无需辅助调用即可出现；部署方可以自行决定更优标题是否值得模型成本，以及后续提示词是否需要重新生成会话标题。
+- Web 标题仍以增量方式从日志交付，无需标题索引或扫描持久化列表；冷启动列表项会在会话附加后改用标题。
+- 回退标题会立即出现。每个新建的 Web 会话都会增加一次针对首消息的辅助调用；其他组合可以自行决定更优标题是否值得模型成本，以及后续提示词是否需要重新生成会话标题。
 - 辅助请求记录和延迟接受的标题会占用事件 seq，并可能创建平衡的零步骤轮次，因此持久化会同时呈现尝试发起的调用与已接受的更新，尽管模型历史和 KV 缓存标识保持不变。
 - 单个提供方和每会话单调递增的修订号让释放、取代和陈旧结果拒绝行为明确可见，但多策略优先级必须由复合提供方负责。
 - 手动重命名、删除、生成标题与用户标题的优先级、搜索和列表索引不在此功能范围内。
diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.i18n.yaml
index 321131ac96..05f9ae37b6 100644
--- a/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-21-tui-reload-command.md: de9a5502214a610d88024730b1c0c1044a396c92
-2026-07-21-tui-reload-command.zh.md: 25d1d448459221698ca63377f8f18d05a0fa3d21
+2026-07-21-tui-reload-command.md: 89bf2f7bb482d7f3889136c1a6ac9918ba0c4919
+2026-07-21-tui-reload-command.zh.md: cfea10690af49f2cf484938a3f9f12d954766a71
diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.md b/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.md
index de9a550221..89bf2f7bb4 100644
--- a/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.md
+++ b/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.md
@@ -6,11 +6,11 @@ English | [中文](2026-07-21-tui-reload-command.zh.md)
 
 ## Problem
 
-HMR's file watcher only reacts to in-place `change` events under its configured roots (the config leaf's directory in the shipped demos). Editors that replace files by rename (BSD `sed -i`, `git checkout`) produce no event, and runtimes without the HMR entry (or without `--expose-internals`) have no config reload path at all. During development that means restarting the TUI to apply a config edit the watcher missed. Widening the watch roots to the whole repo was considered and rejected in discussion: dense package sharing makes module-level HMR a remount-most-of-the-tree operation with unpredictable externals boundaries.
+HMR's file watcher only reacts to in-place `change` events under its configured roots (the config leaf's directory in the shipped demos). Editors that replace files by rename (BSD `sed -i`, `git checkout`) produce no event, and runtimes without the HMR entry have no config reload path at all. During development that means restarting the TUI to apply a config edit the watcher missed. Widening the watch roots to the whole repo was considered and rejected in discussion: dense package sharing makes module-level HMR a remount-most-of-the-tree operation with unpredictable externals boundaries.
 
 ## Decision
 
-`dsh-tui` gains an **experimental, dev-only** `/reload` slash command: it walks `ctx.loader.entries()` and calls `refresh()` on every file-backed subtree (`Include`), i.e. the exact code path the HMR watcher's config-change branch drives, invoked manually and watcher-independent. Unchanged files are no-ops (content comparison in `Include.read`).
+`dsh-tui` gains an **experimental, dev-only** `/reload` slash command: it walks `ctx.loader.entries()` and calls `refresh()` on every file-backed subtree (`Include`), i.e. the exact code path the HMR watcher's config-change branch drives, invoked manually and watcher-independent. Unchanged files are no-ops (content comparison in `Include.read`); invalid files warn and keep the running tree (the hot-reload-resilience contract); include `patches` — including the dsh CLI's personal overlay — re-apply on every re-read.
 
 The TUI reaches the Loader **structurally** (`ctx.loader` via a local type, not `inject`): tests and embedders run the TUI without a Loader, where `/reload` degrades to a warning notice instead of failing the mount. Module-source hot reload stays watcher-owned; `/reload` refreshes configs only.
 
@@ -28,8 +28,8 @@ The TUI reaches the Loader **structurally** (`ctx.loader` via a local type, not
 - The command reports tree count and completion as transcript notices; per-file failures surface only in loader logs, which the TUI does not display — acceptable for a dev-only surface, noted in the completion message.
 - A re-entrancy guard serializes reloads: `/reload` while one is in flight is refused with a warning, keeping the loader's unmutexed tree-update pass single-writer; the guard releases on completion or failure.
 - `/reload` runs only while the agent is idle: a reload can dispose and re-mount entries, which under an active turn could tear tools or the adapter out from under in-flight calls. The check is advisory (a send can race in after it) but removes the common footgun.
-- If any `refresh()` rejects, the command reports the failure instead of leaving an unhandled rejection.
+- If `refresh()`'s never-reject contract ever changes, the command reports the failure instead of leaving an unhandled rejection.
 
 ## Testing
 
-`packages/ui/tui/tests/tui.spec.ts` pins: `/reload` refreshes every file-backed subtree and skips plain entries (structural fake Loader), reports completion, refuses re-entry while a gated refresh is in flight and runs again after release, releases the guard on the failure arm, refuses a running agent and runs again at idle, reports a rejecting refresh, and degrades to a warning without a Loader — including mounted as a real plugin fiber, where a throwing service lookup would escape. Verified live in tmux against the real tree: a probe edit reloads successfully.
+`packages/ui/tui/tests/tui.spec.ts` pins: `/reload` refreshes every file-backed subtree and skips plain entries (structural fake Loader), reports completion, refuses re-entry while a gated refresh is in flight and runs again after release, releases the guard on the failure arm, refuses a running agent and runs again at idle, reports a rejecting refresh, and degrades to a warning without a Loader — including mounted as a real plugin fiber, where a throwing service lookup would escape. Verified live in tmux against the real tree: probe edit → reload applies; invalid edit → reload keeps the running tree.
diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.zh.md b/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.zh.md
index 25d1d44845..cfea10690a 100644
--- a/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-tui-reload-command.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## Problem
 
-HMR 的文件监听器只对其配置根目录（示例中即配置叶子所在目录）下的就地 `change` 事件起反应。以重命名方式替换文件的编辑器（BSD `sed -i`、`git checkout`）不产生事件，而没有挂载 HMR 配置项（或没有 `--expose-internals`）的运行时则完全没有配置重载路径。开发时这意味着监听器漏掉一次配置编辑就得重启 TUI。曾考虑把监听根目录扩大到整个仓库，讨论后否决：包之间的密集共享使模块级 HMR 变成「重挂大半棵树」的操作，externals 边界也不可预测。
+HMR 的文件监听器只对其配置根目录（示例中即配置叶子所在目录）下的就地 `change` 事件起反应。以重命名方式替换文件的编辑器（BSD `sed -i`、`git checkout`）不产生事件，而没有挂载 HMR 配置项的运行时则完全没有配置重载路径。开发时这意味着监听器漏掉一次配置编辑就得重启 TUI。曾考虑把监听根目录扩大到整个仓库，讨论后否决：包之间的密集共享使模块级 HMR 变成「重挂大半棵树」的操作，externals 边界也不可预测。
 
 ## Decision
 
-`dsh-tui` 增加一个**实验性、仅供开发**的 `/reload` 斜杠命令：遍历 `ctx.loader.entries()`，对每个文件后端的子树（`Include`）调用 `refresh()`——即 HMR 监听器配置变更分支所走的同一条代码路径，改为手动触发、不依赖监听器。未变化的文件是无操作（`Include.read` 做内容比较）。
+`dsh-tui` 增加一个**实验性、仅供开发**的 `/reload` 斜杠命令：遍历 `ctx.loader.entries()`，对每个文件后端的子树（`Include`）调用 `refresh()`——即 HMR 监听器配置变更分支所走的同一条代码路径，改为手动触发、不依赖监听器。未变化的文件是无操作（`Include.read` 做内容比较）；无效文件记录警告并保留运行中的树（热重载韧性契约）；include 的 `patches`——包括 dsh CLI 的个人 overlay——在每次重读时重新应用。
 
 TUI 以**结构方式**访问 Loader（通过局部类型访问 `ctx.loader`，而非 `inject`）：测试和嵌入方在没有 Loader 的情况下运行 TUI，此时 `/reload` 退化为一条警告通知而不是挂载失败。模块源码热重载仍由监听器负责；`/reload` 只刷新配置。
 
@@ -28,8 +28,8 @@ TUI 以**结构方式**访问 Loader（通过局部类型访问 `ctx.loader`，
 - 命令以 transcript 通知报告树数量与完成；单文件失败只出现在 loader 日志里，TUI 不显示——对仅供开发的表面可以接受，完成消息中已注明。
 - 重入保护串行化重载：前一次进行中时 `/reload` 会被拒绝并提示警告，使 loader 无互斥的树更新过程保持单写者；保护在完成或失败时释放。
 - `/reload` 只在 agent 空闲时运行：重载可能卸载并重新挂载配置项，在活跃轮次下这会把工具或适配器从进行中的调用脚下抽掉。检查是建议性的（检查后仍可能有 send 竞争进来），但消除了常见的坑。
-- 任一 `refresh()` 若 reject，命令会报告失败而不是留下未处理的 rejection。
+- 若 `refresh()` 的永不 reject 契约将来改变，命令会报告失败而不是留下未处理的 rejection。
 
 ## Testing
 
-`packages/ui/tui/tests/tui.spec.ts` 固定：`/reload` 刷新每个文件后端子树并跳过普通配置项（结构化的假 Loader）、报告完成、在门控的刷新进行中拒绝重入并在释放后可再次运行、失败分支同样释放保护、拒绝运行中的 agent 并在空闲后可再次运行、报告 reject 的 refresh、无 Loader 时退化为警告——包括作为真实插件 fiber 挂载的情形，在那里会抛出的服务查找会泄露出去。已在 tmux 中对真实配置树实机验证：探针编辑后 reload 成功生效。
+`packages/ui/tui/tests/tui.spec.ts` 固定：`/reload` 刷新每个文件后端子树并跳过普通配置项（结构化的假 Loader）、报告完成、在门控的刷新进行中拒绝重入并在释放后可再次运行、失败分支同样释放保护、拒绝运行中的 agent 并在空闲后可再次运行、报告 reject 的 refresh、无 Loader 时退化为警告——包括作为真实插件 fiber 挂载的情形，在那里会抛出的服务查找会泄露出去。已在 tmux 中对真实配置树实机验证：探针编辑 → reload 生效；无效编辑 → reload 保留运行中的树。
diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.i18n.yaml
index 210215eb3d..d470b61414 100644
--- a/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-21-tui-resume-command.md: 2282eaa9bff83fdb75bdce315d6b17bf8f9ea303
-2026-07-21-tui-resume-command.zh.md: f9d989a5b4e7eb106ff21c5a4fcfa770a5962343
+2026-07-21-tui-resume-command.md: 86f62e16f5e2ee83e2ed36f0ed675ca2a1422c4b
+2026-07-21-tui-resume-command.zh.md: 06e58f81445aaaf5299282714148194c1d2aacf4
diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.md b/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.md
index 2282eaa9bf..86f62e16f5 100644
--- a/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.md
+++ b/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.md
@@ -1,4 +1,4 @@
-# Agent Note: Resume command hint and `/resume`
+# Agent Note: Product-level TUI session resume
 
 Status: implemented
 
@@ -6,36 +6,34 @@ English | [中文](2026-07-21-tui-resume-command.zh.md)
 
 ## Problem
 
-The TUI can resume a session by launch (`RESUME_SESSION_ID=<id> dsh` feeding `dsh-tui-demo`'s `resumeSessionId`), but nothing told the user the command. On exit the session id survived only in the log and `./.sessions` filenames — the [no-banner Agent Note](2026-07-21-tui-no-banner.md) removed the last place it was shown — so resuming meant hunting for the id and reconstructing the invocation. There was also no in-session way to see which sessions in this workspace are resumable.
+The original `/resume` printed shell commands. It did not let a keyboard user inspect titles or outcomes, distinguish corruption from a missing adapter, or safely transfer the terminal. Leaving the TUI and manually launching a command also hid the required ordering: finish current work, flush it, release the UI and app, then restore the exact persisted identity without silently creating a replacement.
 
 ## Decision
 
-A single optional `resumeCommand` config field on `dsh-tui` gates both surfaces: a shell command template whose every `{session}` is replaced with the live session id (e.g. `dsh --resume {session}`). Absent, neither surface appears.
+`/resume` uses the TUI's existing interactive overlay seam as a full-viewport picker rather than a centered dialog. The flat page keeps the search field, workspace, candidates, and shortcut footer in stable screen regions; only the active row uses the accent role. Its search editor starts immediately after the search glyph and emits pi-tui's cursor marker, so terminal IME composition remains anchored in the field. Escape clears a non-empty query before a second Escape closes the picker. It lists the current workspace by last logged activity and searches log-backed title or id. Each candidate displays current/live/persisted state, last turn outcome, recent provider/model, durable goal phase when present, and the id as secondary text. The current session and sessions already live in this runtime remain visible but disabled.
 
-- **Exit hint.** Process-exiting shutdown prints `To resume this session: <command>` (muted label) via `runtime.terminal.write` after `ui.stop()`, before `runtime.exit`. It prints only once the session is durably persisted: `currentResumeCommand()` scans the session list for the current id and returns `undefined` if it is absent, so a session abandoned before its first flush advertises no command that would fail to load.
-- **`/resume`.** Lists this workspace's persisted sessions newest-first, each with its resume command, marking the current one `(current)`. It warns when `resumeCommand` is unconfigured or no persistence backend is mounted, and notes when nothing is persisted yet. The listing is asynchronous, so the transcript updates a tick after submit.
-- **Listing.** `listWorkspaceSessions()` reads the optional `sessionPersistence` service's `list()`, keeps headers whose `cwd === agent.session.header.cwd`, and sorts by `createdAt` descending. A `list()` rejection is swallowed to `[]` — a persistence failure must never block terminal exit or crash `/resume`.
+`session-query.readSession()` supplies a detached complete log validated by the same core replay boundary used by resume. The TUI folds title and goal state from that log. A candidate load failure is local to that row; selecting a candidate revalidates the log, `cwd`, route, current agent's idle status, and the exclusions for the current session and sessions already live in this runtime, so a stale listing cannot bypass preflight. A missing adapter reports an intact session with an unavailable route. This preflight does not lock the target or exclude another process.
 
-`sessionPersistence` is an optional injected service reached through `ctx.get('sessionPersistence')` (not `inject`), declared as an optional peer dependency. Without a backend the field still parses; the exit hint and `/resume` degrade to nothing and the unconfigured/no-backend warnings respectively. `dsh-tui-demo` forwards `resumeCommand` to `dsh-tui`, and the runnable `examples/tui-agent` leaves set `dsh --resume {session}`. The `dsh` CLI (`apps/cli`) parses that `--resume <id>` flag through `parseResumeArg` in [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md), setting `RESUME_SESSION_ID` before boot so the printed command runs back through the config's existing `resumeSessionId` intake; a mistyped or repeated flag fails loud rather than silently starting fresh.
+After preflight, the TUI flushes the current session, confirms that its agent remains idle, then stops the terminal before calling `TuiRuntime.handoffResume`. The shipped `dsh` host disposes the root app and uses `process.execve` with a normalized `--resume` argument, atomically replacing the process rather than starting a child. The resumed app publishes the same `SessionId`; ordinary replay restores transcript, title, todos, and durable goal state. Goal activation is intentionally disarmed, and the TUI asks for human confirmation or `/goal resume`.
+
+`resumeCommand` remains an exit and no-host fallback. The TUI substitutes `{session}` only for display and never executes arbitrary shell text. The exit hint still appears only after the current session is durable.
 
 ## Alternatives considered
 
-**Hardcode or auto-detect the resume invocation.** Rejected: the launch command is deployment-specific — the env-var name, binary, and flags all vary — so a `DEFAULT_*` constant would be a fixed tunable, not configurability. A template owned by the leaf keeps the choice where the deployment lives, and `{session}` is the only substitution the TUI must know.
+**Have the TUI spawn `resumeCommand`.** Rejected: the template is deployment text, not trusted argv, and the TUI does not own app teardown or process lifetime. The constrained host seam receives only a validated `SessionId`.
 
-**Two config fields, one per surface.** Rejected: both render the identical command, so one field keeps them symmetric and unable to drift; there is no deployment that wants the hint but not the listing.
+**Construct the resumed agent inside the existing TUI.** Rejected: replacing one config-created agent would cross Loader ownership, scoped plugin setup, persistence retirement, and terminal lifecycle in the presentation layer. Root disposal plus process replacement reuses the supported startup path.
 
-**Print the exit hint unconditionally.** Rejected: resuming a session id that never flushed fails to load, so advertising it is a broken instruction. Gating on the id appearing in `list()` costs one scan and only ever suppresses a dead command.
+**Treat a missing adapter as a missing session.** Rejected: storage validity and current route availability are independent facts. The selector keeps the row and names the unavailable provider/model.
 
-**Resume in place from `/resume` (relaunch or reattach).** Rejected: the TUI does not own agent lifecycle or process spawning ([front-door Agent Note](2026-07-17-dedicated-full-screen-tui-front-door.md)). Printing a copyable command respects that boundary and matches the `pi --resume` affordance the request cited.
-
-**Make `sessionPersistence` a required `inject`.** Rejected: the TUI must run without persistence (fixtures, ephemeral runs). An optional service that degrades preserves that, and matches the [`session-query`](../../../../packages/session-query/session-query/package.json) precedent for the same optional peer.
+**Persist goal activation across resume.** Rejected: durable intent is not authorization to continue after a human or process boundary. Goal phase survives; automatic continuation does not.
 
 ## Consequences
 
-- `dsh-tui` gains an optional peer dependency on `@deepseek-ai/dsh-session-persistence` (`peerDependenciesMeta.optional`), matching `session-query`; the package still loads and passes its coverage gate without a backend mounted.
-- The help line and autocomplete gain `/resume`; two existing snapshots re-recorded for the wider help line, and a new `resume-sessions` checkpoint pins the rendered listing.
-- `dsh-tui-demo` and both `examples/tui-agent` leaves carry `resumeCommand`, so a real TUI run now prints its own resume command on exit, and the `dsh` CLI accepts the printed `--resume <id>` flag to run it.
+- Concurrent processes can select or resume the same persisted session because preflight does not serialize them.
+- `/resume` depends on `session-query` for discovery and complete-log reads, but persistence and host handoff remain optional; without a host, the command fallback stays usable.
+- Process replacement intentionally restarts Loader composition. Runtime-only state is rebuilt, while only logged or header-backed session state survives.
 
 ## Testing
 
-`packages/ui/tui/tests/tui.spec.ts` pins the seven behaviors: the exit hint prints only when the current session is persisted, is omitted when it is not and when `list()` rejects; `/resume` lists workspace sessions newest-first with the `(current)` marker and cwd filter, warns when unconfigured and when no backend is mounted, and notes when nothing is persisted. The `resume-sessions` snapshot verifies the full rendered frame. The harness provides a fake `sessionPersistence` through `ctx.provide`. For the `--resume` flag, `packages/ui/app-boot/tests/app-boot.spec.ts` pins `parseResumeArg` (space and inline forms, position independence, and the fail-loud on a valueless, empty, or repeated flag), and `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` boots `apps/cli` with `--resume <missing-id>` and asserts the config resume fails loud — proving the flag reaches the `resumeSessionId` intake.
+TUI tests cover keyboard navigation, title/id search, search-clear/cancel behavior, running-agent refusal, refusal of the current session and sessions already live in this runtime, route absence, corrupt rows, preflight revalidation, fallback commands, and stop-before-handoff ordering. Session-query tests pin detached full-log validation. Agent-loop resume tests pin exact identity and history; title, todo, and goal replay suites pin restored projections and disarmed goal activation. The keyless TUI snapshot owns the full-viewport selector and its IME cursor anchor, and a real PTY smoke covers search plus handoff.
diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.zh.md b/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.zh.md
index f9d989a5b4..06e58f8144 100644
--- a/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-tui-resume-command.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Resume command hint and `/resume`
+# Agent Note: 产品级 TUI 会话恢复
 
 Status: implemented
 
@@ -6,36 +6,34 @@ Status: implemented
 
 ## Problem
 
-TUI 本就能通过启动参数恢复会话（`RESUME_SESSION_ID=<id> dsh` 喂给 `dsh-tui-demo` 的 `resumeSessionId`），但没有任何地方告诉用户这条命令。退出时会话 id 只残留在会话日志和 `./.sessions` 文件名里——[移除启动横幅 Agent Note](2026-07-21-tui-no-banner.md) 移除了它最后一处显示位置——因此恢复意味着先翻出 id 再拼回调用命令。也没有任何会话内的方式查看当前 workspace 里哪些会话可恢复。
+原有 `/resume` 只会打印 shell 命令。使用键盘操作的用户无法查看标题或结果、区分日志损坏与适配器缺失，也无法安全移交终端。退出 TUI 后手动启动命令还掩盖了必要的操作顺序：等待当前工作结束并将其刷写，释放 UI 和应用，再恢复持久化的原有身份，绝不能静默创建替代会话。
 
 ## Decision
 
-`dsh-tui` 上一个可选的 `resumeCommand` 配置字段同时管辖两处出口：一个 shell 命令模板，其中每一处 `{session}` 都会被替换为当前会话 id（例如 `dsh --resume {session}`）。未设置时两处都不出现。
+`/resume` 使用 TUI 现有的交互式浮层接口，但以占满 viewport 的选择页呈现，而不是居中弹窗。这个扁平页面把搜索框、workspace、候选项和快捷键页脚放在稳定的屏幕区域，只有当前行使用强调色。搜索编辑器紧跟搜索图标起始，并输出 pi-tui 的光标标记，因此终端输入法的组合文本会锚定在输入框中。查询非空时，第一次按 Escape 会清空查询，第二次才关闭选择页。页面按日志记录的最后活动时间列出当前 workspace 的会话，并支持按日志内标题或 id 搜索。每个候选项都会显示是否为当前会话、是否活跃、是否已持久化，最近一个轮次的结果，最近使用的提供方／模型，以及可用时的持久化目标阶段；id 作为次要信息显示。当前会话和已在本运行时中处于活跃状态的会话仍会显示，但不可选择。
 
-- **退出提示。** 以退出进程方式关闭时，在 `ui.stop()` 之后、`runtime.exit` 之前，经由 `runtime.terminal.write` 打印 `To resume this session: <command>`（弱化的标签）。仅当会话已持久化时才打印：`currentResumeCommand()` 在会话列表中查找当前 id，若不存在则返回 `undefined`，因此在首次刷盘前就被放弃的会话不会宣传一条注定加载失败的命令。
-- **`/resume`。** 按最新在前列出当前 workspace 里已持久化的会话，每条附带其恢复命令，并给当前会话标注 `(current)`。当 `resumeCommand` 未配置或未挂载持久化后端时给出告警，尚无任何会话被持久化时给出提示。列出是异步的，因此提交后文本记录会在下一个 tick 更新。
-- **列出逻辑。** `listWorkspaceSessions()` 读取可选的 `sessionPersistence` 服务的 `list()`，保留 `cwd === agent.session.header.cwd` 的头部，并按 `createdAt` 降序排序。`list()` 拒绝时吞掉为 `[]`——持久化失败绝不能阻塞终端退出或让 `/resume` 崩溃。
+`session-query.readSession()` 提供一份脱离运行时的完整日志，并通过恢复流程所用的同一核心回放边界完成验证。TUI 从该日志中折叠出标题和目标状态。候选项加载失败时只影响该行；选择候选项后会复查日志、`cwd`、路由、当前 agent 的空闲状态，以及针对当前会话和已在本运行时中处于活跃状态的会话的排除规则，避免陈旧列表绕过预检。适配器缺失时会报告会话完整但路由不可用。该预检不会锁定目标，也不会排除其他进程。
 
-`sessionPersistence` 是一个通过 `ctx.get('sessionPersistence')`（而非 `inject`）获取的可选注入服务，声明为可选的对等依赖（peer dependency）。没有后端时该字段仍能解析；退出提示与 `/resume` 分别退化为不做任何事、以及给出未配置/无后端告警。`dsh-tui-demo` 将 `resumeCommand` 转发给 `dsh-tui`，可运行的 `examples/tui-agent` 叶子配置设为 `dsh --resume {session}`。`dsh` CLI（`apps/cli`）通过 [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) 中的 `parseResumeArg` 解析该 `--resume <id>` 标志，在启动前设置 `RESUME_SESSION_ID`，因此打印出的命令会重新走回配置中既有的 `resumeSessionId` 入口；拼写错误或重复的标志会直接报错退出，而非悄悄开启一个新会话。
+预检通过后，TUI 会刷写当前会话，再次确认其 agent 仍处于空闲状态，然后停止终端并调用 `TuiRuntime.handoffResume`。已交付的 `dsh` 宿主会释放根应用，并使用带有规范化 `--resume` 参数的 `process.execve` 原子替换当前进程，而不是启动子进程。恢复后的应用发布相同的 `SessionId`；常规回放会还原 transcript（文本记录）、标题、待办事项和持久化目标状态。系统会有意解除目标的激活状态，TUI 则要求用户确认继续或执行 `/goal resume`。
+
+`resumeCommand` 保留为退出及无宿主时的回退方案。TUI 仅为显示目的替换 `{session}`，绝不执行任意 shell 文本。只有当前会话已经持久化时，退出提示才会出现。
 
 ## Alternatives considered
 
-**硬编码或自动探测恢复调用命令。** 否决：启动命令与部署强相关——环境变量名、可执行文件、参数都各不相同——因此一个 `DEFAULT_*` 常量只会是固定的可调项，而非可配置项。由叶子拥有的模板把这个选择留在部署所在之处，而 `{session}` 是 TUI 唯一需要知道的替换。
+**让 TUI 创建 `resumeCommand` 进程。** 否决：该模板是部署文本，不是可信的参数列表，且 TUI 不拥有应用拆卸或进程生命周期。受约束的宿主接口只接收经过验证的 `SessionId`。
 
-**两个配置字段，每处出口一个。** 否决：两处渲染的是完全相同的命令，因此单个字段让它们保持对称、不会漂移；不存在只想要提示而不想要列表的部署。
+**在现有 TUI 内构造恢复后的 agent。** 否决：在表现层替换由配置创建的 agent，会跨越 Loader 所有权、作用域插件初始化、持久化资源释放和终端生命周期。释放根应用并替换进程可以复用受支持的启动路径。
 
-**无条件打印退出提示。** 否决：恢复一个从未刷盘的会话 id 会加载失败，宣传它就是一条错误指令。以 id 是否出现在 `list()` 中为条件仅需一次扫描，且只会抑制一条注定失败的命令。
+**把适配器缺失视为会话缺失。** 否决：存储有效性和当前路由可用性是相互独立的事实。选择器会保留该行，并指出不可用的提供方／模型。
 
-**从 `/resume` 就地恢复（重启或重连）。** 否决：TUI 不拥有 agent 生命周期或进程创建（[全屏 TUI 门面 Agent Note](2026-07-17-dedicated-full-screen-tui-front-door.md)）。打印一条可复制的命令尊重这条边界，也契合需求所引用的 `pi --resume` 用法。
-
-**把 `sessionPersistence` 设为必需的 `inject`。** 否决：TUI 必须能在无持久化时运行（fixture（测试前置数据）、临时运行）。一个会优雅退化的可选服务保住了这一点，也与 [`session-query`](../../../../packages/session-query/session-query/package.json) 对同一可选对等依赖的先例一致。
+**恢复会话时延续目标激活状态。** 否决：持久意图并不代表跨越用户或进程边界后仍获授权继续执行。目标阶段会保留，但不会自动续跑。
 
 ## Consequences
 
-- `dsh-tui` 新增对 `@deepseek-ai/dsh-session-persistence` 的可选对等依赖（`peerDependenciesMeta.optional`），与 `session-query` 一致；未挂载后端时该包仍能加载并通过其覆盖率门禁。
-- 帮助行和自动补全新增 `/resume`；两个既有快照因帮助行变宽而重新录制，新增的 `resume-sessions` 检查点固定渲染出的列表。
-- `dsh-tui-demo` 及两个 `examples/tui-agent` 叶子配置都带上 `resumeCommand`，因此真实的 TUI 运行现在退出时会打印自己的恢复命令，且 `dsh` CLI 接受打印出的 `--resume <id>` 标志来运行它。
+- 预检不会串行化不同进程；多个进程可以并发选择或恢复同一个持久化会话。
+- `/resume` 依赖 `session-query` 发现会话并读取完整日志，但持久化和宿主交接仍是可选功能；没有宿主时，命令回退仍可使用。
+- 进程替换会有意重启 Loader 组合。系统会重建仅存在于运行时的状态，而只有日志或会话头部记录的会话状态能够保留。
 
 ## Testing
 
-`packages/ui/tui/tests/tui.spec.ts` 固定这七种行为：退出提示仅在当前会话已持久化时打印，未持久化时以及 `list()` 拒绝时都不打印；`/resume` 按最新在前列出 workspace 会话并带 `(current)` 标注与 cwd 过滤、未配置时告警、无后端时告警、尚无持久化时给出提示。`resume-sessions` 快照验证完整渲染帧。测试脚手架通过 `ctx.provide` 提供一个假的 `sessionPersistence`。对于 `--resume` 标志，`packages/ui/app-boot/tests/app-boot.spec.ts` 固定 `parseResumeArg`（空格形式与内联形式、位置无关性，以及在标志缺值、为空或重复时直接报错退出），`examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 用 `--resume <missing-id>` 启动 `apps/cli` 并断言配置恢复直接报错退出——证明该标志抵达了 `resumeSessionId` 入口。
+TUI 测试覆盖键盘导航、标题／id 搜索、清空搜索后再取消、agent 运行期间拒绝恢复、拒绝恢复当前会话和已在本运行时中处于活跃状态的会话、路由缺失、损坏的候选行、预检复查、回退命令，以及停止终端先于宿主交接的顺序。session-query 测试固定脱离运行时的完整日志验证。agent-loop 恢复测试固定会话身份和历史完全一致；标题、待办事项和目标回放测试套件固定这些投影均可恢复，且目标激活状态已经解除。无密钥 TUI 快照固定全屏选择页和输入法光标锚点，真实 PTY smoke 则覆盖搜索与交接。
diff --git a/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.i18n.yaml
new file mode 100644
index 0000000000..1702c90c43
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-trajectory-step-cell.md: 414c3aac856fb5e60f0e4cf42f8e7b410cdf3413
+2026-07-23-trajectory-step-cell.zh.md: aa76b422f165ebf6918b3781fdfe38797a34ba51
diff --git a/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.md b/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.md
new file mode 100644
index 0000000000..414c3aac85
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.md
@@ -0,0 +1,35 @@
+# Agent Note: Trajectory step cell and turn list chrome
+
+Status: implemented
+
+English | [中文](2026-07-23-trajectory-step-cell.zh.md)
+
+## Problem
+
+The trajectory tab needs a reusable step row and turn-list chrome that can show expanded assistant blocks, own-duration times, Message token columns, and in-flight work. Without folding session event times into conversation nodes and expanding blocks into cells, the UI cannot match the product chrome.
+
+## Decision
+
+[`@deepseek-ai/dsh-client-ui-trajectory`](../../../../packages/client/ui-trajectory/README.md) owns the presentational trajectory list chrome:
+
+- [`TrajectoryCell`](../../../../packages/client/ui-trajectory/src/client/TrajectoryCell.tsx) — 38px step row with kinds User / Message / Tool (no Think, Call, or Result rows). Reasoning blocks are skipped (no block-level clock). Each `tool-call` + paired `tool-result` folds into one Tool row (`name ·` truncated args) whose Time is `result.time − callTime` when both are known. Message rows carry Input/Output/Think token columns from `assistant.usage`. Own-duration Time uses `+Ns` / `+N.1s`, or `—` when absent. Selected state draws a 2px inset `--dsw-alias-brand-primary-new-colorprimary-new-color` ring (`selected` prop) and is not wired to chat selection.
+- [`TrajectoryTurn`](../../../../packages/client/ui-trajectory/src/client/TrajectoryTurn.tsx) / header / group header — sticky Turn bar paints full-bleed `ghost-active-fill`; title/columns and the Message/Step body sit in a centered `max-width: 880px` lane. Cell trailing columns share the Turn header geometry (`320 = 4×71 + 3×12`); cells use pad 20/8.
+- [`deriveTrajectoryLayout`](../../../../packages/client/ui-trajectory/src/client/layout.ts) expands assistant `blocks[]` into cells, pairs tool-calls with `tool-result` by `callId` into Tool, folds `partial` and `runningCalls` (deduped), hangs usage on Message only (including the empty fallback when there is no text block), and builds group descriptions as wall-span + tool histogram (`1.5s bash×6`). `user/message` has no wire turn, so each User row is enclosed in the next assistant/steering turn, else the in-flight `partial` turn, else `lastAssistantTurn + 1` (or `1`). Context nodes emit no cell but still advance the Message duration cursor.
+
+[`ConversationNode`](../../../../packages/client/runtime/src/client/sessions/conversation.ts) carries `time` from `SessionEvent.time`; `ToolResultNode.callTime` and `RunningToolCall.time` come from the paired `tool/call`. Duration rules: User `+0s`; Message = assistant.time − previous surface time (including skipped context); Tool = result.time − callTime when both known; in-flight Tool = `—`. Group header duration is earliest→latest absolute time in the group (wall span; Tool contributes start and start+duration).
+
+## Alternatives considered
+
+**Keep a Think cell for reasoning blocks.** Rejected: a single `assistant/message.time` cannot yield Think own-duration without chunk-level clocks; omit the row rather than show `—`.
+
+**Keep separate Call and Result rows.** Rejected: Result had no own duration to show; one Tool row carries the call→result interval.
+
+**Cumulative elapsed from session/turn start.** Rejected; the Time column is each row's own duration.
+
+**Hang usage on the first expanded row.** Rejected; usage attaches to Message only.
+
+**Show in-flight tool durations via Date.now().** Deferred; in-flight Time stays `—`.
+
+## Consequences
+
+The Trajectory tab can render expanded finalized and in-flight rows with own-duration times once fold emits `time`. Behavior-shaped coverage lives in `packages/client/ui-trajectory/tests/{cell,layout,views}.spec.tsx`. Chat selection deep-links and finer block-level clocks remain deferred.
diff --git a/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.zh.md b/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.zh.md
new file mode 100644
index 0000000000..aa76b422f1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-trajectory-step-cell.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: Trajectory 步骤单元格与轮次列表 chrome
+
+Status: implemented
+
+[English](2026-07-23-trajectory-step-cell.md) | 中文
+
+## Problem
+
+trajectory 标签页需要可复用的步骤行与轮次列表 chrome，以展示展开后的 assistant 块、自身耗时、Message token 列，以及进行中的工作。若不将会话事件时间折叠进会话节点，并将块展开为单元格，UI 就无法对齐产品 chrome。
+
+## Decision
+
+[`@deepseek-ai/dsh-client-ui-trajectory`](../../../../packages/client/ui-trajectory/README.md) 拥有展示型 trajectory 列表 chrome：
+
+- [`TrajectoryCell`](../../../../packages/client/ui-trajectory/src/client/TrajectoryCell.tsx) — 高 38px 的步骤行，类型为 User / Message / Tool（无 Think、Call、Result 行）。reasoning 块跳过（无块级时钟）。每对 `tool-call` + `tool-result` 折成一行 Tool（`name ·` 加截断参数），Time 在两端皆知时为 `result.time − callTime`。Message 行携带来自 `assistant.usage` 的 Input/Output/Think token 列。自身耗时 Time 使用 `+Ns` / `+N.1s`，缺失时为 `—`。选中态绘制 2px 内嵌的 `--dsw-alias-brand-primary-new-colorprimary-new-color` 环（`selected` prop），且未接线到 chat 选中。
+- [`TrajectoryTurn`](../../../../packages/client/ui-trajectory/src/client/TrajectoryTurn.tsx) / header / group header — 粘性 Turn 条背景通栏铺 `ghost-active-fill`；标题／列标与 Message/Step 主体落在居中的 `max-width: 880px` 内容道。单元格右侧列与 Turn 标头共用几何（`320 = 4×71 + 3×12`）；cell pad 20/8。
+- [`deriveTrajectoryLayout`](../../../../packages/client/ui-trajectory/src/client/layout.ts) 将 assistant `blocks[]` 展开为单元格，按 `callId` 将 tool-call 与 tool-result 配对为 Tool，折叠 `partial` 与 `runningCalls`（去重），仅将用量挂在 Message 上（含无 text 块时的空回退行），并以墙钟跨度 + 工具直方图构建分组描述（`1.5s bash×6`）。`user/message` 无线上 turn，故每条 User 行归入下一 assistant/steering 的 turn，否则归入进行中的 `partial` turn，否则为 `lastAssistantTurn + 1`（或 `1`）。context 节点不产出单元格，但仍推进 Message 耗时游标。
+
+[`ConversationNode`](../../../../packages/client/runtime/src/client/sessions/conversation.ts) 携带来自 `SessionEvent.time` 的 `time`；`ToolResultNode.callTime` 与 `RunningToolCall.time` 来自配对的 `tool/call`。耗时规则：User 为 `+0s`；Message = assistant.time − 上一表面时间（含跳过的 context）；Tool = 在两者皆知时 result.time − callTime；进行中 Tool = `—`。分组标头耗时为组内最早→最晚绝对时间（墙钟跨度；Tool 贡献起点与起点+自身耗时）。
+
+## Alternatives considered
+
+**为 reasoning 块保留 Think 单元格。** 否决：单条 `assistant/message.time` 无法给出 Think 自身耗时（除非上 chunk 级时钟）；与其显示 `—`，不如省略该行。
+
+**保留分开的 Call 与 Result 行。** 否决：Result 没有可展示的自身耗时；一行 Tool 承载 call→result 区间。
+
+**自会话／轮次起点累计耗时。** 否决；Time 列是每行自身的耗时。
+
+**将用量挂在展开后的第一行。** 否决；用量仅附着于 Message。
+
+**用 Date.now() 显示进行中工具的耗时。** 延后；进行中的 Time 保持为 `—`。
+
+## Consequences
+
+一旦 fold 发出 `time`，Trajectory 标签页即可渲染带自身耗时的已定稿与进行中展开行。行为导向的覆盖位于 `packages/client/ui-trajectory/tests/{cell,layout,views}.spec.tsx`。chat 选中深链与更细的块级时钟仍延后。
diff --git a/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.i18n.yaml
new file mode 100644
index 0000000000..05b15028e6
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-tui-file-reference-autocomplete.md: 1a136009213c845af28f4ac47a8b31d426ac8cf5
+2026-07-23-tui-file-reference-autocomplete.zh.md: 410f0d49dbd20a2dcf704892a192406020aaa86e
diff --git a/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.md b/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.md
new file mode 100644
index 0000000000..1a13600921
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.md
@@ -0,0 +1,33 @@
+# Agent Note: TUI file-reference autocomplete
+
+Status: implemented
+
+English | [中文](2026-07-23-tui-file-reference-autocomplete.zh.md)
+
+## Problem
+
+The TUI offered structured `@session` references but no dependable way to discover workspace paths while composing a prompt. Requiring users to remember exact paths made file-oriented requests unnecessarily awkward, while eagerly attaching every selected file would spend context before the model knew whether its contents were relevant and would hide the normal `read` observation from the tool transcript.
+
+## Decision
+
+The TUI owns a bounded, cancellable host-workspace path index rooted at the active session's working directory. Typing `@` at a token boundary fuzzy-matches files and directories; queries containing `/` list the named directory directly, accepting a directory continues completion, and paths containing whitespace use the `@"path with spaces"` form. Configuration controls result count, index size, and excluded directory basenames. The default exclusions are `.git` and `node_modules`; traversal does not follow directory symlinks or interpret ignore files.
+
+Selecting a file changes only the editor text. The submitted user message retains the natural `@path` spelling and carries no injected contents, hidden context, or reference object. When the model-facing `read` tool is registered, the TUI contributes a stable system-prompt section that identifies `@` paths as explicit user references, directs the model to call `read` when contents are needed, and forbids claiming inspection before that call. Tool results invalidate the reusable fuzzy index so subsequent interactions observe likely workspace mutations.
+
+Structured session mentions keep their existing snapshot preparation. Unlike files, a referenced session has no general model-facing retrieval tool, so reducing `@session` to a path-like label would make its content unreachable.
+
+## Alternatives considered
+
+**Eagerly inject selected file contents.** This spends tokens before relevance is known, can capture stale content before execution reaches the reference, and bypasses the auditable `read` call/result sequence.
+
+**Require an external file finder.** Depending on `fd`, `rg --files`, or another executable would make baseline completion vary by host installation and complicate cancellation and cross-platform behavior.
+
+**Use the filesystem service's ordinary directory-list operation for discovery.** That seam is optimized for exact model-facing filesystem operations and may represent a remote namespace; recursive fuzzy indexing would multiply provider round trips and couple editor latency to tool policy. Host-side discovery keeps the terminal interaction local, while the documented namespace-alignment limitation remains explicit for non-local deployments.
+
+**Add a new cross-package file-search capability.** The TUI is the only current consumer and the behavior is editor presentation rather than a model capability, so a new interface, implementation, and consumer package set would split the seam prematurely.
+
+## Consequences
+
+Users can discover and insert paths without making selection itself expensive or model-visible beyond the path. The model preserves agency over whether to inspect a file, and any inspection remains reconstructable through the logged tool transcript. The fixed instruction slightly enlarges TUI system prompts when `read` is present, and content-requiring requests take an additional tool round trip.
+
+Completion is deliberately bounded and advisory: very large workspaces may omit paths beyond the configured index cap, ignored files may still appear, and remote or virtual filesystem deployments must align the TUI host working directory with the `read` namespace or supply a different completion surface. Package tests pin token grammar, ranking, bounds, cancellation, invalidation, and path-only submission; terminal snapshots and the real Loader PTY smoke pin the visible menu and keyboard completion.
diff --git a/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.zh.md b/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.zh.md
new file mode 100644
index 0000000000..410f0d49db
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: TUI 文件引用自动补全
+
+Status: implemented
+
+[English](2026-07-23-tui-file-reference-autocomplete.md) | 中文
+
+## 问题
+
+TUI 提供结构化的 `@session` 引用，但用户在编辑提示词时无法可靠地发现工作区路径。要求用户记住准确路径会给面向文件的请求带来不必要的麻烦；如果直接附加每个选中文件，则会在模型判断其内容是否相关之前占用上下文，并在工具 transcript（文本记录）中隐藏常规的 `read` 观察结果。
+
+## 决策
+
+TUI 维护一个有容量上限且可取消的主机工作区路径索引，以活跃会话的工作目录为根。在 token 边界输入 `@` 会对文件和目录进行模糊匹配；查询包含 `/` 时会直接列出指定目录，接受目录后会继续补全，包含空白的路径采用 `@"path with spaces"` 形式。配置项控制结果数量、索引大小以及排除的目录基名。默认排除 `.git` 和 `node_modules`；遍历既不跟随目录符号链接，也不解析忽略文件。
+
+选择文件只会改变编辑器文本。提交的用户消息保留自然的 `@path` 写法，不携带注入的内容、隐藏上下文或引用对象。注册面向模型的 `read` 工具时，TUI 会加入一个稳定的系统提示词段，说明 `@` 路径是用户的显式引用，指示模型在需要内容时调用 `read`，并禁止模型在调用前声称已检查文件。工具结果会使可复用的模糊索引失效，后续交互因而能看到工作区中可能发生的变更。
+
+结构化会话提及保留现有的快照准备方式。与文件不同，被引用的会话没有通用的模型侧检索工具；如果把 `@session` 简化为类似路径的标签，模型将无法获取其内容。
+
+## 备选方案
+
+**直接注入选中文件的内容。** 这种方式会在确定相关性前消耗 token，可能在执行到该引用前捕获到陈旧内容，并绕过可审计的 `read` 调用与结果序列。
+
+**要求使用外部文件查找器。** 依赖 `fd`、`rg --files` 或其他可执行文件，会使基础补全行为随主机安装情况而变化，也会增加取消处理和跨平台支持的复杂度。
+
+**使用文件系统服务的常规目录列表操作进行发现。** 该 seam 针对面向模型的准确文件系统操作进行了优化，并且可能表示远程命名空间；递归模糊索引会增加提供方往返次数，并使编辑器延迟与工具策略耦合。主机侧发现让终端交互保留在本地，同时文档仍明确说明非本地部署中的命名空间对齐限制。
+
+**新增跨包的文件搜索功能。** TUI 是目前唯一的消费方，而且该行为属于编辑器呈现而非模型功能；新增一组接口、实现和消费方包会过早拆分这条 seam。
+
+## 影响
+
+用户可以发现并插入路径，而选择操作本身不会带来高开销，对模型可见的内容也仅限路径。模型仍可自行决定是否检查文件，任何检查都能通过已记录的工具 transcript 重建。存在 `read` 时，固定指令会略微增大 TUI 系统提示词；需要文件内容的请求还会增加一次工具往返。
+
+补全有意采用有界的提示性设计：超大型工作区可能省略超过配置索引上限的路径，被忽略的文件仍可能出现，远程或虚拟文件系统部署必须让 TUI 的主机工作目录与 `read` 命名空间对齐，否则需要提供不同的补全接口。包（package）测试固定 token 语法、排序、边界、取消、失效和仅提交路径的行为；终端快照与真实 Loader PTY 冒烟测试固定可见菜单和键盘补全。
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
new file mode 100644
index 0000000000..1ff9ecac7d
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-web-assistant-markdown.md: ce98a16fa43e2743c18826ee7f2344c38e7c70e7
+2026-07-23-web-assistant-markdown.zh.md: 0d6fd2f9e6b91f76830586ecf4c29774e5d6978a
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
new file mode 100644
index 0000000000..ce98a16fa4
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
@@ -0,0 +1,35 @@
+# Agent Note: Safe assistant Markdown in the Web conversation
+
+Status: implemented
+
+English | [中文](2026-07-23-web-assistant-markdown.zh.md)
+
+## Problem
+
+The Web conversation preserves assistant Markdown source through session events, history replay, and streaming accumulation, but its terminal text primitive renders that source literally. Changing the shared primitive would also format user and steering messages, while parsing in the runtime would mix presentation state into the React-free session projection.
+
+## Decision
+
+`@deepseek-ai/dsh-client-ui-primitives` exports `MarkdownText` as the untrusted assistant-text renderer, and `ui-conversation` selects it only for assistant `text` blocks. Finalized history, the streaming tail, and interrupted partials already share `AssistantMarkdown`, so they receive the same renderer without changing events or snapshots. User and steering messages keep `MessageText` and remain literal.
+
+`MarkdownText` uses `react-markdown` with `remark-gfm` to build React elements from an AST. It covers CommonMark blocks plus GFM tables, task lists, strikethrough, and autolinks without `dangerouslySetInnerHTML`, raw-HTML parsing, or syntax highlighting. The dependency is explicit in `ui-primitives`; because that pure library is seeded by the Web shell, the parser is part of the initial browser bundle.
+
+## Untrusted output policy
+
+Assistant-authored destinations are restricted to absolute HTTP, HTTPS, and mailto URLs. HTTP(S) links open in a new tab with `rel="noopener noreferrer"`; relative destinations and other protocols render as non-navigable text. Markdown images render only their alt text, so model output cannot initiate a remote image request. Raw HTML remains inert source text because no HTML parser enters the pipeline.
+
+The renderer uses existing `--dsw-*` typography and color tokens. Fenced code and GFM tables own horizontal overflow so long content cannot widen the conversation column.
+
+## Alternatives considered
+
+**Promote the existing mdast and micromark development dependencies and maintain a custom React walker.** This avoids a new parser family but makes the product own every node mapping, GFM extension, and security-sensitive rendering branch. The dedicated React renderer keeps that traversal upstream while preserving an AST-to-React path.
+
+**Replace `MessageText` with Markdown rendering.** This formats user prompts and steering as a side effect. Those authored surfaces remain literal until the product chooses that behavior explicitly.
+
+**Parse Markdown into session snapshots.** This would make React nodes or presentation ASTs durable runtime state and reintroduce a final-versus-streaming mode boundary. Parsing stays at the presentation leaf instead.
+
+**Enable raw HTML or remote images with sanitization.** Neither capability has a current product need, while both enlarge the executable or network privacy boundary. They remain disabled rather than adding sanitizer and image-policy dependencies.
+
+## Consequences
+
+Assistant replies render semantic Markdown consistently during streaming and replay, while tool cards, reasoning rows, interactions, user bubbles, and the host protocol remain unchanged. Streaming reparses the current text after each accumulated update; incomplete Markdown can temporarily change structure, but the isolated tail bounds React invalidation and the final event does not switch renderers. The initial Web shell grows by the Markdown parser and GFM runtime, and future extensions such as syntax highlighting or remote media require a separate bundle and security decision.
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
new file mode 100644
index 0000000000..0d6fd2f9e6
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: Web 对话中安全的 assistant Markdown
+
+Status: implemented
+
+[English](2026-07-23-web-assistant-markdown.md) | 中文
+
+## 问题
+
+Web 对话通过会话事件、历史回放与流式累积保留 assistant Markdown 源文本，但其最末端的文本原语会按字面渲染源文本。若修改共享原语，用户消息与 steering（中途引导）消息也会被格式化；若在运行时中解析，则会把呈现状态混入不依赖 React 的会话投影。
+
+## 决策
+
+`@deepseek-ai/dsh-client-ui-primitives` 导出 `MarkdownText`，用作不受信任的 assistant 文本渲染器；`ui-conversation` 仅为 assistant `text` 块选择该渲染器。已完成的历史消息、流式输出尾部与被中断的部分输出已经共用 `AssistantMarkdown`，因此无需更改事件或快照，它们便会采用同一渲染器。用户消息与 steering 消息继续使用 `MessageText`，并保持按字面渲染。
+
+`MarkdownText` 使用 `react-markdown` 与 `remark-gfm`，从 AST 构建 React 元素。它支持 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，但不使用 `dangerouslySetInnerHTML`，不解析原始 HTML，也不进行语法高亮。`ui-primitives` 显式声明该依赖；由于这一纯库由 Web shell 预置，解析器会成为初始浏览器 bundle 的一部分。
+
+## 不受信任输出策略
+
+assistant 生成的目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。HTTP(S) 链接会在新标签页中打开，并带有 `rel="noopener noreferrer"`；相对目标地址与其他协议会渲染为不可导航的文本。Markdown 图片仅渲染替代文本，因此模型输出无法发起远程图片请求。由于管线中未引入 HTML 解析器，原始 HTML 仍是不会生效的源文本。
+
+渲染器使用现有的 `--dsw-*` 排版与颜色 token。围栏代码块与 GFM 表格各自处理横向溢出，因此较长内容无法撑宽对话栏。
+
+## 考虑过的替代方案
+
+**将现有的 mdast 与 micromark 开发依赖提升为正式依赖，并维护自定义 React walker。**此方案避免引入新的解析器体系，但产品需要自行负责每种节点映射、GFM 扩展和安全敏感的渲染分支。专用 React 渲染器将这套遍历交由上游维护，同时保留 AST 到 React 的处理路径。
+
+**将 `MessageText` 替换为 Markdown 渲染。**这会产生格式化用户提示词与 steering 的副作用。在产品明确选择此行为之前，这两类输入内容仍按字面渲染。
+
+**将 Markdown 解析为会话快照。**这会让 React 节点或呈现层 AST 成为持久的运行时状态，并重新引入最终输出与流式输出之间的模式边界。解析仍留在呈现层的叶节点中。
+
+**通过净化启用原始 HTML 或远程图片。**当前产品并不需要这两项功能，但二者都会扩大可执行行为或网络隐私边界。因此它们保持禁用，无需增加净化器与图片策略依赖。
+
+## 后果
+
+assistant 回复在流式输出与回放期间都会一致地渲染为语义化 Markdown，而工具卡片、推理行、交互、用户气泡和宿主协议保持不变。每次累积更新后，流式输出都会重新解析当前文本；未完成的 Markdown 可能暂时改变结构，但独立的尾部会限定 React 失效范围，最终事件也不会切换渲染器。初始 Web shell 的体积会因加入 Markdown 解析器与 GFM 运行时而增大；语法高亮或远程媒体等后续扩展需要另行作出 bundle 与安全决策。
diff --git a/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.i18n.yaml
new file mode 100644
index 0000000000..4b7354a322
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-24-new-session-clears-to-empty-state.md: 1605f44a05d0f59b61fe95cb5b03a0f9f5c3d4ab
+2026-07-24-new-session-clears-to-empty-state.zh.md: 1f78d99babc33d30ee1300bfa6bf048a78e7132e
diff --git a/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.md b/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.md
new file mode 100644
index 0000000000..1605f44a05
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.md
@@ -0,0 +1,23 @@
+# Agent Note: New Session clears onto the empty-state launch
+
+Status: implemented
+
+English | [中文](2026-07-24-new-session-clears-to-empty-state.zh.md)
+
+## Problem
+
+Sidebar "New Session" created and opened a blank session immediately, so the center column showed `ConversationRoot` with an empty transcript and the resident composer. The Figma NEW SESSION screen (`EmptyState` + shared `InputBar` hero) only rendered when `sessions.current` was already undefined, so the launch page was unreachable from the primary creation control.
+
+## Decision
+
+`SessionsService.clear()` wipes the persisted selection and `list.current`. Top-level sidebar creation entries (`onCreate()` with no cwd — New Session and New Workspace) call `clear()` so `AppFrame` renders `conversation.empty`. The empty state's first send still runs `conversation.startSession` (create → open → send) and reuses the same `InputBar` component as the resident composer (`variant="hero"`). Per-project "+" (`onCreate(cwd)`) keeps create-then-open until the empty-state picker can accept a seeded cwd.
+
+## Alternatives considered
+
+**Keep create-then-open for New Session and add a second empty chrome inside ConversationRoot when the transcript is empty.** Rejected: that duplicates the launch InputBar and breaks the empty→content ruling that one InputBar moves position rather than swapping components.
+
+**Route New Session through a dedicated route or slot outside selection.** Rejected for this pass: `conversation.empty` already owns the launch UI; clearing `current` is the existing empty branch.
+
+## Consequences
+
+New Session no longer mints a host session until the first send. Reloading after clear stays on the empty state. Project-scoped "+" still creates immediately. `EmptyState` stacks the Figma hero (Input_Bottom 75:8208) as fish + title, a Menu-backed workspace chip above the card, then shared `InputBar` (`variant="hero"`, max-width 800, r20 card matching the composer — not a taller r24 hero), with a soft ellipse glow (figma 313:14109) centered behind the picker + card and width-locked to the card (`1051/776` asset ratio) so it scales with it. The chip uses the soft interactive hover fill + 12px radius from 75:8208 and opens MenuDropdown (figma 122:9481; `--dsw-specific-menu` + `--dsw-shadow-lv3`): basename rows with folder icons and a trailing check, then a separator and "New Workspace" whose submenu (figma 419:16920) offers "Use a existing folder" and "Create new". Use a existing folder opens the path Dialog (figma 451:18655 copy — "Enter an existing folder path" / Open Folder) over a full-viewport mask (`--dsw-alias-bg-mask-1` + `--dsw-mask-blur`) and sets the chip cwd. Create new opens the same Dialog chrome to name a folder under `host.describe().cwd`; success runs `sessions.createWorkspace` → host `session.create` (mkdir recursive) → `sessions.open`, so a default session lands in the new workspace. `InputBar` paints the bottom chrome (attach / Plan / Read-only / model) with local native `<select>` state only — host plan, access, and model seams remain unwired.
diff --git a/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.zh.md b/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.zh.md
new file mode 100644
index 0000000000..1f78d99bab
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-24-new-session-clears-to-empty-state.zh.md
@@ -0,0 +1,23 @@
+# Agent Note: New Session clears onto the empty-state launch
+
+Status: implemented
+
+[English](2026-07-24-new-session-clears-to-empty-state.md) | 中文
+
+## Problem
+
+侧栏「New Session」会立即创建并打开空白会话，因此中间栏显示带空 transcript（文本记录）与常驻 composer 的 `ConversationRoot`。Figma 的 NEW SESSION 屏（`EmptyState` + 共用的 `InputBar` hero）仅在 `sessions.current` 已为 undefined 时渲染，因而主创建控件无法到达启动页。
+
+## Decision
+
+`SessionsService.clear()` 清除持久化选中项与 `list.current`。顶层侧栏创建入口（无 cwd 的 `onCreate()`——New Session 与 New Workspace）调用 `clear()`，使 `AppFrame` 渲染 `conversation.empty`。空态的首次发送仍走 `conversation.startSession`（create → open → send），并复用与常驻 composer 相同的 `InputBar` 组件（`variant="hero"`）。按项目的「+」（`onCreate(cwd)`）继续 create-then-open，直到空态选择器能接受预填的 cwd。
+
+## Alternatives considered
+
+**为 New Session 保留 create-then-open，并在 transcript 为空时于 ConversationRoot 内再加一套空态 chrome。** 否决：这会重复启动页的 InputBar，并破坏 empty→content 的约定——同一 InputBar 应移动位置，而非互换组件。
+
+**将 New Session 路由到选中状态之外的专用 route 或 slot。** 本轮否决：`conversation.empty` 已拥有启动 UI；清除 `current` 即是既有的空态分支。
+
+## Consequences
+
+New Session 在首次发送前不再创建 host 会话。clear 后重新加载仍停留在空态。项目范围的「+」仍立即创建。`EmptyState` 按 Figma 堆叠英雄区（Input_Bottom 75:8208）：鱼标 + 标题、卡片上方由 Menu 驱动的工作区 chip，再接共用的 `InputBar`（`variant="hero"`，max-width 800，与 composer 一致的 r20 卡片——而非更高的 r24 英雄区），选择器与卡片背后居中铺一层柔光椭圆（figma 313:14109），宽度按卡片锁定为 `1051/776` asset 比例，随卡片缩放。Chip 采用 75:8208 的柔和交互 hover 填充与 12px 圆角，并打开 MenuDropdown（figma 122:9481；`--dsw-specific-menu` + `--dsw-shadow-lv3`）：带文件夹图标与尾随勾选的 basename 行，分隔线后是 "New Workspace"，其子菜单（figma 419:16920）提供 "Use a existing folder" 与 "Create new"。Use a existing folder 打开路径 Dialog（figma 451:18655 copy — "Enter an existing folder path" / Open Folder），置于全视口遮罩（`--dsw-alias-bg-mask-1` + `--dsw-mask-blur`）之上，并设置 chip 的 cwd。Create new 打开同一套 Dialog chrome，在 `host.describe().cwd` 下命名文件夹；成功则走 `sessions.createWorkspace` → host `session.create`（mkdir recursive）→ `sessions.open`，在新 workspace 中默认落下一会话。`InputBar` 绘制底栏 chrome（attach / Plan / Read-only / model），仅用本地原生 `<select>` 状态——host 侧的 plan、access、model 接缝仍未接线。
diff --git a/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.i18n.yaml b/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.i18n.yaml
new file mode 100644
index 0000000000..19b6055f0a
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-doc-sync-enforcement.md: 375059312c312dff7b5ddcb95ea5b82ac8cd4d06
+2026-06-11-doc-sync-enforcement.zh.md: 5c17263bdc2b4908a82237d1fc3b08f1f22a62d9
diff --git a/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.md b/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.md
index 67cdfd6771..375059312c 100644
--- a/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.md
+++ b/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-doc-sync-enforcement.zh.md)
+
 ## Problem
 
 AGENTS.md promises that docs and code stay strictly in sync, but the promise was verified by eyeball. Review caught drift twice — a cookbook example contradicting the type policy, and a README citing the wrong `registerAdapter` call. Out-of-sync docs are worse than no docs, and this codebase is built primarily by agents that follow gates far more reliably than prose (mechanical quality gates). Two classes of doc drift are mechanically checkable: code blocks that no longer compile, and the event-taxonomy table that duplicates the `interface Events` declarations.
diff --git a/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.zh.md b/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.zh.md
new file mode 100644
index 0000000000..5c17263bdc
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: Doc-sync 强制
+
+Status: implemented
+
+[English](2026-06-11-doc-sync-enforcement.md) | 中文
+
+## 问题
+
+AGENTS.md 承诺文档与代码严格同步，但这一承诺此前仅靠人眼核查。评审曾两次发现漂移：一次是实操手册（cookbook）示例与类型策略矛盾，一次是 README 引用了错误的 `registerAdapter` 调用。失去同步的文档比没有文档更糟；而本代码库主要由 agent（智能体）构建，agent 遵守门禁远比遵守行文约定可靠（机械质量门禁）。有两类文档漂移可以被机械检查：不再能编译的代码块，以及与 `interface Events` 声明重复的事件分类体系表。
+
+## 决策
+
+两道门禁，沿用既有的 `scripts/` 风格（tsx ESM，每个脚本一项职责）：
+
+1. **`doc-typecheck`** 从 `README.md`、`docs/**` 和 `packages/*/README.md` 中提取所有 ` ```ts ` 围栏代码块，写入一个继承根 `tsconfig.json` 的临时项目，然后用 `tsc -b` 编译。临时项目复用源码的 `paths` 映射和根 project references，因此文档示例能看到源码，而 vendor 代码仍在其自身的 tsconfig 设置下被检查。刻意作为草图的代码块可通过显式的 ` ```ts ignore-check ` 信息字符串来 opt-out；脚本会报告 opt-out 比例，超过一半即失败，防止该豁免机制悄然成为常态。
+2. **`verify-event-taxonomy`** 从 `packages/*/src` 中的 `interface Events` 块和 `docs/architecture.md` 中的分类体系表分别提取事件名称，断言两个集合完全一致。只校验，不生成：表格保留手写的 Mode/Purpose 列，仅检查名称集合。（落地此门禁时发现了表格遗漏的三个事件：`tools/change`、`llm/adapter-change`、`system-prompt/change`。）**已被取代**：由[生成式 Cordis 目录](2026-06-20-generated-cordis-catalog.md)取代。此门禁及其 `architecture.md` 表格已退役，取而代之的是完全生成的 `docs/cordis-catalog/events.md` + `docs/cordis-catalog/services.md` 及其 `verify-cordis-catalog` 新鲜度门禁。本 Agent Note（agent 决策记录）中的其他门禁（`doc-typecheck` 以及下文修订中的 `verify-md-wrap`）不受影响。
+
+两者都通过 package.json 中共享的 `doc-sync` 脚本运行；贡献者在相关文档变更中调用它，CI 则执行完整检查。[快速本地 Git 钩子](2026-07-22-fast-local-git-hooks.md)决策使这类按变更面选择的工作不进入 commit 和 push 钩子。
+
+**修订（2026-06-17）：** 第三道门禁 **`verify-md-wrap`** 随后被纳入 `doc-sync`。它使用 `mdast-util-from-markdown` + GFM 解析范围内的每个 Markdown 文件（`README.md`、`docs/**`、`packages/*/README.md`，加上 `AGENTS.md` / `packages/AGENTS.md`），如果任何 `paragraph` 节点跨越多个源码行则失败，从而强制执行 docs/AGENTS.md 中「一个段落一个物理行」的写作规则。同样遵循只校验不生成的原则：它报告硬换行但从不重写，因此不会引入格式化噪音。`doc-sync` 现在包含三道门禁。
+
+## 曾考虑的替代方案
+
+- **API-extractor 基准报告**（[已推迟的提案](../../proposed/process/2026-06-11-api-extractor-reports.md)）：有意推迟。对于评审者已能直接看到源码 diff 的内部 monorepo 而言价值有限，且依赖重、配置繁琐。
+- **从源码生成分类体系表**而非仅校验名称：否决，机制比问题本身更重；表格保留了手写的 Mode/Purpose 列，直到[生成式 Cordis 目录](2026-06-20-generated-cordis-catalog.md)完全取代了这项检查。
+
+## 后果
+
+- 可检查类别中的文档漂移会直接使 `doc-sync` 和 CI 失败，而不是等评审人发现。这是「机械门禁优于行文规范」原则的具体应用。
+- 让文档代码片段可编译需要少量 stub import/`declare`；`ignore-check` 比例必须保持低位，否则门禁形同虚设（比例守卫强制执行此约束）。
+- 分类体系检查仅限名称——Mode 或 Purpose 列的错误仍需人工评审。
+- 如果包（package）未来对外发布，API 报告方案仍可重新考虑。
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
new file mode 100644
index 0000000000..6d017a8961
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-quality-gates.md: e1af110387936d644208dc1829fde4a4fdf8a3f9
+2026-06-11-quality-gates.zh.md: a4e57b7a08ecf20babb33b55d8c94414df1b10b1
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 5e1db16e52..e1af110387 100644
--- a/.agents/notes/implemented/process/2026-06-11-quality-gates.md
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-quality-gates.zh.md)
+
 The hook/CI symmetry in this record is superseded by [Fast local Git hooks](2026-07-22-fast-local-git-hooks.md); CI remains the exhaustive enforcement path.
 
 ## Problem
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
new file mode 100644
index 0000000000..a4e57b7a08
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md
@@ -0,0 +1,30 @@
+# Agent Note: 以机械质量门禁取代行文约定
+
+Status: implemented
+
+[English](2026-06-11-quality-gates.md) | 中文
+
+本记录中的钩子/CI 对称设计已由[快速本地 Git 钩子](2026-07-22-fast-local-git-hooks.md)取代；CI 仍是执行完整检查的路径。
+
+## 问题
+
+本代码库主要由 coding agent（智能体）开发。相比行文约定，agent 遵守强制门禁的可靠性远高得多；而当劳动由 agent 承担时，「工作量大」不构成成本论据。早期证据：未通过类型检查的测试被提交（vitest 不做类型检查），仅在评审中才被发现。
+
+## 决策
+
+每条可机械检查的 AGENTS.md 承诺都有一个以非零状态退出的命令。CI 执行完整集合，而 Git 钩子将延迟预算留给可低成本发现的本地缺陷：
+
+- 最严格的 TypeScript 配置（`noUncheckedIndexedAccess`、`exactOptionalPropertyTypes` 等）；示例、测试和脚本通过根目录的 no-emit `tsconfig.json` 在 CI 中进行类型检查，而包（package）/vendor 代码保持在各自 project-reference 边界之后。
+- ESLint strict-type-checked + @stylistic（作为强制执行的统一代码风格），包括文件内重复逻辑检查；vendor 代码排除在外。
+- jscpd 检测包的生产 TypeScript 代码与仓库脚本中的跨文件克隆；窄范围的源码区间例外用于记录有意为之的并行实现。
+- `packages/*/*/src` 下按文件 100% 覆盖率（v8）；不可达的防御性守卫使用 `/* v8 ignore */ ` 并注明理由，而非删除。
+- knip（死代码/依赖）、publint（包的正确性）、workspace 约束（workspace 规则：private、cordis peer+dev、统一版本、ESM），以及对构建出的包声明文件进行 NodeNext 消费方类型检查。
+- lefthook pre-commit 修复已暂存文件的 lint 问题、拒绝已暂存的空白问题并检查 vendor manifest；pre-push 运行增量类型检查。CI 在 Node 22.19/24/26 上运行完整矩阵，并对 Headless、TUI、ACP（Agent Client Protocol）、JSON-RPC、工作流和代码运行时入口路径执行已构建应用的冒烟测试。
+
+## 后果
+
+- 约定不会因 agent 更替而失效；可低成本发现的 commit/push 缺陷在本地失败，其余完整规则违规在 CI 中失败。
+- 门禁本身也是需要维护的代码；配置变更与其他变更一样需要评审。
+- 100% 覆盖率的压力可能催生无断言的测试——变异测试是计划中的对策（见[变异测试提案](../../proposed/testing/2026-06-11-mutation-testing.md)）。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.i18n.yaml b/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.i18n.yaml
new file mode 100644
index 0000000000..4ac1a926c4
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-tsdown-over-dumble.md: e8cdaeb1e3331ffb04de024acff5b0e6ca3e6366
+2026-06-11-tsdown-over-dumble.zh.md: bb5feef585c1748f41d1b204313f1a4d8b357a17
diff --git a/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.md b/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.md
index 0629acabb4..e8cdaeb1e3 100644
--- a/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.md
+++ b/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-tsdown-over-dumble.zh.md)
+
 ## Problem
 
 The initial build used **dumble**, the cordiverse zero-config esbuild wrapper that upstream Cordis itself builds with — maximum alignment with the vendored packages' conventions (it reads each package.json and infers entries/formats from the `exports` field). But dumble is a liability as a load-bearing tool in this repo: v0.2.x, ~530 npm downloads/week, effectively one maintainer, and we were invoking it through a custom orchestration script (`scripts/build.ts`) because it has no workspace mode.
diff --git a/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.zh.md b/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.zh.md
new file mode 100644
index 0000000000..bb5feef585
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.zh.md
@@ -0,0 +1,30 @@
+# Agent Note: 使用 tsdown 替代 dumble 进行 JS 打包
+
+Status: implemented
+
+[English](2026-06-11-tsdown-over-dumble.md) | 中文
+
+## 问题
+
+最初的构建使用 **dumble**，即 cordiverse 的零配置 esbuild 包装层——上游 Cordis 自身也用它构建——与 vendor 包（package）的约定最大程度对齐（它读取每个 package.json 并从 `exports` 字段推断入口/格式）。但 dumble 作为本仓库的承重工具存在隐患：v0.2.x，每周约 530 次 npm 下载，实质上只有一位维护者，而且由于它没有 workspace 模式，我们不得不通过自定义编排脚本（`scripts/build.ts`）来调用它。
+
+目前构建产物只在 `pnpm run build` + publint 中有意义（尚未发布任何包；开发/测试/演示通过 tsx 直接运行未打包的源码），因此切换成本现在最低，一旦包开始发布就只会更高。
+
+## 决策
+
+用 **tsdown**（基于 rolldown，每周约 250 万次下载，VoidZero 支持，活跃发布）替代 dumble：
+
+- 根目录 `tsdown.config.ts`，配置 `workspace: ['vendor/*', 'packages/*/*']`（显式 glob 将打包范围限定在 vendor 的 Cordis 与 TypeScript 包目录树内；`workspace: true` 还会发现示例 manifest 和不需要打包的 workspace 成员）。
+- 共享形状：入口为 `lib/types/index.js`，`outDir: 'lib'`，ESM，`platform: node`，`target: es2024`，`fixedExtension: false`（为 `"type": "module"` 包保留 `.js`），`dts: false`（声明归 tsc -b 所有），`clean: false`（lib/ 还保存 TSC 的 `lib/types` 中间树）。入口最初是 `src/index.ts`；[TSC 优先构建 Agent Note（agent 决策记录）](2026-06-17-ts-build-config.md)随后将 tsdown 改为打包 TSC 输出的 JS，使 TypeScript 转换行为统一由一个编译器提供。
+- vendor/ 中有两个按包覆盖的配置（属于我们自己的修改，与重新生成的 tsconfig 类似；记录在 vendor/README.md 中）：schemastery（通过 `outExtensions` 输出双格式 `.mjs`/`.cjs`）、logger-console（两次单入口 pass，使共享基类被内联到每个入口而非生成哈希命名的分片，与上游发布形态一致）。
+- `scripts/build.ts` 删除；`pnpm run build` = `tsc -b && tsdown`（根 solution 拥有 emit 图）。
+
+## 曾考虑的替代方案
+
+- **直接编写 esbuild 脚本**：最成熟的引擎，零包装层风险，但需要手动维护 tsdown workspace 模式自动提供的按包规格表。
+- **pkgroll**：理念上最接近的直接替代品，但每周仅 78k 下载且基于 Rollup，维护前景严格弱于 tsdown。
+- **保留 dumble**：与上游完美对齐，但巴士因子不可接受。
+
+## 后果
+
+运行时 bundle 输出仍沿用 dumble 时代的公开入口形状（`lib/index.js`，以及包特有的变体，例如 `schemastery` 的 `lib/index.mjs`/`lib/index.cjs` 与 `logger-console` 的 `lib/browser.js`）；根据 [TSC 优先构建 Agent Note](2026-06-17-ts-build-config.md)，声明现位于 `lib/types` 下。External 仍来自各包的 dependencies/peerDependencies。我们放弃了 dumble 的 exports 字段推断：采用非默认形状的新包需要逐包提供 `tsdown.config.ts`，不能只依赖 package.json 字段。未来如果 `tsc -b` 成为瓶颈，tsdown 也可以接管声明打包（isolatedDeclarations）；这需要另写一份 Agent Note。
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
new file mode 100644
index 0000000000..0e0c6693a2
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-vendor-cordis-as-source.md: ae6f5438c5817c61a549d9edb2041d538fbcebe6
+2026-06-11-vendor-cordis-as-source.zh.md: 8d6f0e39d53e1c85eaaa50c4c4bf1d9ef648d953
diff --git a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.md b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.md
index a8895ba5e8..ae6f5438c5 100644
--- a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.md
+++ b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-11-vendor-cordis-as-source.zh.md)
+
 ## Problem
 
 DeepSeek Harness SDK is built on the Cordis framework. Cordis core was at 4.0.0-rc.6 (a release candidate) when this repo started; the harness depends on framework internals (fiber lifecycle, effect disposal, waterfall dispatch) whose exact behavior matters to the agent loop's correctness guarantees.
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
new file mode 100644
index 0000000000..8d6f0e39d5
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md
@@ -0,0 +1,27 @@
+# Agent Note: 将 Cordis 以源码形式收录，而非作为 npm 依赖
+
+Status: implemented
+
+[English](2026-06-11-vendor-cordis-as-source.md) | 中文
+
+## 问题
+
+DeepSeek Harness SDK 构建于 Cordis 框架之上。本仓库启动时，Cordis core 处于 4.0.0-rc.6（一个候选发布版本）；harness 依赖框架内部实现（fiber 生命周期、dispose（资源释放）、waterfall（瀑布式事件）分发），其确切行为直接关系到 agent loop（智能体循环）的正确性保证。
+
+## 决策
+
+将所需的 Cordis 包（core、loader、include、group、timer、hmr、logger-console）与 cordiverse 基础库（cosmokit、schemastery）以源码形式复制到 `vendor/`，扁平化放置，保留其原始 npm 包名以实现透明的 workspace 解析。真正的第三方依赖（js-yaml、chokidar、@standard-schema/spec 等）仍从 npm 获取。
+
+`vendor/README.md` 是 manifest（元数据清单）：记录每个包（package）的上游仓库 + commit SHA，以及一份详尽的本地修改日志。pre-commit 守卫（`scripts/check-vendor-manifest.sh`）会拒绝未在同一次提交中更新 manifest 的 vendor 源码变更。
+
+## 曾考虑的替代方案
+
+- **依赖 npm 包**：否决。core 处于候选发布阶段，harness 依赖框架内部实现（fiber 生命周期、dispose、waterfall 分发），agent loop 的正确性保证取决于这些行为的确切表现；上游 RC 版本升级可能在没有本地修复路径的情况下破坏它们。
+- **递归收录所有传递依赖**：否决。真正的第三方依赖（js-yaml、chokidar、@standard-schema/spec 等）仍从 npm 获取；只有内部实现对我们有影响的框架层才需要自行持有。
+
+## 后果
+
+- harness 完全持有其框架层：可审计、可打补丁、版本锁定。上游 RC 无法影响我们，框架 bug 可以在仓库内直接修复。
+- 上游同步是手动操作（流程记录在 manifest 中）。修改日志使 diff 范围始终可知。
+- 收录的包保留上游代码风格；lint 与严格性门禁将其排除（它们的 tsconfig 在本地放宽了我们较新的编译器选项）。
+- 从第一天起就有一个本地补丁：移除了 hmr 的 locale-YAML 导入（运行时 YAML 导入钩子未被收录）。
diff --git a/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.i18n.yaml b/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.i18n.yaml
new file mode 100644
index 0000000000..6ae4e17a2b
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-16-pnpm-over-yarn.md: 9dee405f509897e2a173399e466d574c518fa9ab
+2026-06-16-pnpm-over-yarn.zh.md: 3a5ff5e9b1fb0511a9191b2e3c35b61f00b705cd
diff --git a/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md b/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md
index 42eb4228b6..9dee405f50 100644
--- a/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md
+++ b/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-16-pnpm-over-yarn.zh.md)
+
 ## Problem
 
 The repo shipped on **Yarn 4** with the `node-modules` linker — a deliberately conservative choice that behaves like npm's flat layout while giving us Yarn's workspaces and `yarn constraints`. It worked. But Yarn 4's Plug'n'Play heritage makes the `node-modules` linker the off-the-beaten-path mode, and the broader JS ecosystem — tooling defaults, CI actions, Corepack examples, contributor familiarity — increasingly centers on pnpm. For a repo that is built primarily by agents and read by occasional human contributors, "the package manager most tools and people expect" has real value: fewer surprises, better-trodden failure paths, more copy-pasteable answers.
diff --git a/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.zh.md b/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.zh.md
new file mode 100644
index 0000000000..3a5ff5e9b1
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.zh.md
@@ -0,0 +1,43 @@
+# Agent Note: 使用 pnpm 替代 Yarn 4 作为包管理器
+
+Status: implemented
+
+[English](2026-06-16-pnpm-over-yarn.md) | 中文
+
+## 问题
+
+本仓库最初使用 **Yarn 4** 搭配 `node-modules` 链接器启动。这是一个刻意保守的选择：行为类似 npm 的扁平布局，同时享有 Yarn 的 workspaces 和 `yarn constraints`。它能正常工作。但 Yarn 4 源自 Plug'n'Play 的血统，使得 `node-modules` 链接器成为非主流模式；而更广泛的 JS 生态——工具默认值、CI action、Corepack 示例、贡献者的熟悉度——正日益以 pnpm 为中心。对于一个主要由 agent（智能体）构建、偶尔有人类贡献者阅读的仓库而言，「大多数工具和人所期望的包管理器」具有实际价值：更少的意外、更成熟的故障路径、更多可直接复用的解答。
+
+切换成本目前处于最低点。本仓库尚无任何包（package）发布（每个包都是 `private: true`）；开发/测试/演示全部通过 tsx **未构建**运行，因此包管理器只需做到：（a）解析并链接 `node_modules`，（b）运行 workspace 脚本，（c）强制执行 workspace 约束。唯一的 Yarn 特有资产是 `yarn.config.cjs`（`@yarnpkg/types` 约束引擎），体量小且可机械地重新表达。这与 [tsdown 决策](2026-06-11-tsdown-over-dumble.md)的逻辑一致：在爆炸半径尚小时，将承重工具换为生态更健康的选项。
+
+## 决策
+
+采用 **pnpm 11.7.0**，通过 `packageManager` 字段固定版本，经 Corepack 安装（与 Yarn 使用的机制相同）：
+
+- **Workspaces** 从 `package.json` 的 `workspaces` 数组 + `.yarnrc.yml` 迁移到 `pnpm-workspace.yaml`（`vendor/*`、`packages/*`——同样的 glob；`examples/*` 保持非 workspace，与先前设置及 tsdown 的显式 glob 一致）。
+- **严格符号链接链接器**（pnpm 默认）取代 Yarn 的提升式 `node-modules` 链接器。我们刻意**不**添加 `node-linker=hoisted` / `shamefully-hoist` 逃生口：pnpm 的非扁平 `node_modules` 会让幻影依赖（引用未声明的传递依赖）大声失败，这对于一个以机械门禁为核心质量保障的仓库（见[机械质量门禁](2026-06-11-quality-gates.md)）是一项*优势*。门禁套件（类型检查、lint、test、build、knip）是证明不存在此类幻影导入的安全网。
+- **构建脚本白名单。** pnpm 10+ 不运行依赖的生命周期脚本，除非将其加入白名单。`pnpm-workspace.yaml` 携带一份显式的 `allowBuilds` 映射（`esbuild`、`lefthook`、`@google/genai`、`protobufjs`）——与本仓库对模型/工具输出已有的供应链加固姿态一致，现在也应用于安装时的代码执行。`peerDependencyRules.allowedVersions.typescript: '>=5 <7'` 消除仓库内 TypeScript 的良性 peer 范围警告。
+- **约束变为包管理器无关。** `yarn.config.cjs`（导入 `@yarnpkg/types`，使用 `Yarn.workspaces()` / `workspace.set()`）被 `scripts/check-workspace-constraints.ts` 取代——一个纯 tsx 脚本，通过 `pnpm run constraints` 运行。它在相同的 `vendor` + `packages` 范围上强制执行完全相同的不变式：每个包 `private: true`；`@deepseek-ai/dsh-*` 包将 `cordis` 同时声明为对等依赖（peer dependency）和 dev 依赖且范围一致、使用根 `package.json` 的版本、设置 `type: module`；vendor 包仅检查 privacy。
+- 所有 CI、lefthook 钩子、`package.json` 脚本和文档中的 `yarn …` 动词变为 `pnpm …` / `pnpm run …`。`yarn.lock` → `pnpm-lock.yaml`（lockfile v9）。`.gitignore` 将 `.yarn/` 换为 `.pnpm-store/`。vendor README（如 `vendor/cordis/README.md`）按 Vendoring Policy 保持其上游 `yarn` 示例不变。
+
+## 曾考虑的替代方案
+
+- **保留 Yarn 4**——零变动，但押注于使用率较低的链接器模式和一个绑定单一包管理器的约束引擎。
+- **npm workspaces**——无处不在，但没有约束方案，monorepo 开发体验也较差。
+- **pnpm 搭配提升式链接器**——迁移更平滑，但放弃了幻影依赖安全性，而这正是迁移的核心正确性理由。
+
+## 后果
+
+约束检查失去了 Yarn 的自动**修复**能力（`workspace.set()` 能原地改写 manifest）；tsx 脚本仅做检查，不通过时以非零退出码和消息退出。这是可接受的：CI 从未运行过 `--fix`，且需要手动编辑的情况很少。贡献者现在为 pnpm 而非 Yarn 运行 `corepack enable`；`pnpm exec lefthook install` 取代 `yarn lefthook install`（`postinstall` 钩子仍会运行 `lefthook install`）。
+
+性能（迁移时在开发 NFS 文件系统上测量；单次运行样本，方差大——仅供方向性参考，非基准测试套件）：
+
+| 场景 | Yarn 4 | pnpm 11 |
+|---|---|---|
+| 冷启动（空缓存/store，无 `node_modules`） | ~14 s | ~16 s |
+| 热重链接（缓存/store 已热，`node_modules` 已删除） | ~12–14 s | ~15–22 s |
+| 冻结，`node_modules` 存在（无操作重验证） | ~2–8 s | ~0.5–7 s |
+
+在快速本地磁盘上，pnpm 的内容寻址 store 通常在冷/热安装中胜出，尤其在多个检出之间的**磁盘占用**方面优势明显（一个全局 store 通过硬链接接入每个 `node_modules`，而 Yarn 每个 worktree 复制约 279 MB——部分开发者经常为本仓库保持约 10 个或更多 worktree）。该去重优势在上述迁移时数据中**未能**体现，因为测试 store 和 `node_modules` 位于不同文件系统，硬链接失效；在单文件系统的开发机或 CI 缓存上则适用。诚实的总结：在我们的 NFS 开发文件系统上，安装速度在噪声范围内不分伯仲；迁移的理由是生态对齐、幻影依赖安全性和跨检出磁盘去重，而非原始安装时间的胜出。
+
+所有质量门禁（constraints、类型检查、lint、doc-sync、达到 100% 的 test:coverage、构建、knip、publint 以及已构建应用的冒烟测试）均在 pnpm 下通过，证明更换 linker 没有引入幽灵依赖故障。
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
new file mode 100644
index 0000000000..80f7838d45
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-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
+2026-06-17-ts-build-config.md: 1275a635242ea887c941db9dc0554fd33acd4102
+2026-06-17-ts-build-config.zh.md: 7691118dd152874e2849f1ace686069c9ea3f61f
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 529400b8d7..1275a63524 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
@@ -2,6 +2,8 @@
 
 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.
 
 ## Problem
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
new file mode 100644
index 0000000000..7691118dd1
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
@@ -0,0 +1,80 @@
+# Agent Note: TSC 优先构建与编译器单一归属
+
+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 优先流水线保持不变。
+
+## 问题
+
+此前的 TypeScript 构建与类型检查配置存在以下问题：
+
+- `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`，使发布产物与类型校验保持一致。
+
+验证过程中发现了若干具体的技术问题和可能的路径：
+
+- `tsdown` 使用 `oxc` 进行 TypeScript 转换，其行为与 `tsc` 不同。
+    - `tsdown` 输出的打包 `.d.ts` 与 Cordis 内部的相对模块增强（module augmentation）结构冲突。
+    - tsc 的输出受 `allowImportingTsExtensions` 影响，因此需要确保生成的 `.js` 文件不会导入 `.ts` 文件，且生成的 `.d.ts` 文件保留 NodeNext/Node16 接受的显式相对说明符。为此，包内相对导入在 TypeScript 源码中使用显式 `.ts` 说明符，由 `rewriteRelativeImportExtensions` 在输出的 JS 中将其重写为 `.js`。
+    - `tsdown` 输出的打包 `.js` 与 `tsc -b` 逐文件输出的 `.js` 行为不同，例如装饰器转换行为。
+- `vendor/*/src`、示例、测试和脚本无法全部以 plain-include 方式纳入一个根目录的严格程序。
+    - 在根目录严格配置下直接对 `vendor/*/src` 做类型检查，会触发大量不属于本项目所有权范围的类型错误。
+    - `packages/*/*` 对 `vendor` 的包依赖解析到 `vendor/*/lib`，以适应不同的 tsconfig 严格度。
+
+
+## 决策
+
+包内相对导入使用显式 `.ts` 说明符。
+
+`pnpm run build` 是两阶段构建：
+
+- 阶段 1：在根 solution 上执行 `tsc -b`，将逐模块的 `.js`、声明文件 `.d.ts`、JS sourcemap `.js.map` 和声明 sourcemap `.d.ts.map` 输出到各包的 `lib/types`。这是权威的 TypeScript 编译结果。发布时保留 `.d.ts` / `.d.ts.map`，忽略 `.js` / `.js.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 源码或输出声明文件。
+
+`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 项目保持重写开启。
+
+命令编排结构如下：
+
+```sh
+pnpm run build:
+tsc -b
+tsdown
+
+pnpm run verify-node-next-types:
+tsx scripts/verify-node-next-types.ts
+
+pnpm run typecheck:
+tsc -b
+```
+
+`pnpm run demo:*` 仍通过 tsx 和根路径直接运行 `src`，无需编译步骤。
+
+## 曾考虑的替代方案
+
+- **继续使用 `tsdown`/oxc 作为 TypeScript 转换器**：oxc 的转换行为与 `tsc` 不同（装饰器转换有差异、打包 JS 与逐文件输出不同），且其打包 `.d.ts` 与 Cordis 内部的相对模块增强结构冲突。
+- **用一个根目录严格程序覆盖包、vendor、示例、测试和脚本**：vendor 源码在根目录严格标志下会触发不属于本项目所有权范围的类型错误；带有逐项目严格度的 project references 才是可行的边界。
+
+## 后果
+
+构建职责更加清晰：
+
+- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `tsx` 和 `vitest`）。
+- `build` 命令驱动根 solution 图。`tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责 `lib/index.*`。
+    - `lib/types/*.d.ts` 和 `.d.ts.map` 是发布用的声明输出。
+    - `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。
+    - `lib/types/*.js` 仅作为打包器输入，禁止用作运行时入口或公开导入目标。
+    - `lib/index.*` 是发布用的运行时输出，由打包器（当前为 `tsdown`）生成。
+- `pnpm run verify-node-next-types` 扫描构建出的声明文件，检查是否存在缺少文件扩展名的相对说明符，然后以 `moduleResolution: "NodeNext"` 对构建出的 `types`/`exports` 接口进行临时外部 ESM 消费方的类型检查，确保声明说明符的回归在发布前被捕获。
+- `typecheck` 命令使用 `tsconfig.json`。示例、测试和脚本由根 no-emit 项目检查，包和 vendor 模块保持与 `build` 相同的输出行为。包和 vendor 源码始终处于 project-reference 边界之后。
+
+Cordis 的 vendor 副本现在与上游多了一处类型结构差异。在上游同步时，该差异必须被重新应用或明确废弃。
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
new file mode 100644
index 0000000000..601a077189
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-18-markdown-cross-link-lint.md: 2e3b0f1fcd03f244756b0030f2da758c516a2bbb
+2026-06-18-markdown-cross-link-lint.zh.md: cfe973ae939eceb50d6381ecf35c80df508907c3
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 e57c75575b..2e3b0f1fcd 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-18-markdown-cross-link-lint.zh.md)
+
 ## Problem
 
 Docs in this repo link to each other by relative path — `[topic](../implemented/2026-…-….md)`, `[the cookbook](adding-a-tool.md)`, `[architecture.md](../../architecture.md)`. Nothing verified those targets exist. A rename or a move silently breaks every inbound link, and the break is invisible until a reader clicks it. [Doc-sync enforcement](2026-06-11-doc-sync-enforcement.md) already mechanized two classes of doc drift (uncompilable code blocks, a stale event-taxonomy table) and [verify-md-wrap](2026-06-11-doc-sync-enforcement.md) a third (hard-wrapped prose) — but a dead cross-link is a fourth, equally mechanical class that was still verified by eyeball.
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
new file mode 100644
index 0000000000..cfe973ae93
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: Markdown 交叉链接有效性检查
+
+Status: implemented
+
+[English](2026-06-18-markdown-cross-link-lint.md) | 中文
+
+## 问题
+
+本仓库的文档通过相对路径互相链接：`[topic](../implemented/2026-…-….md)`、`[the cookbook](adding-a-tool.md)`、`[architecture.md](../../architecture.md)`。此前没有任何机制验证这些目标是否存在。重命名或移动文件会静默破坏所有指向它的链接，且在读者点击之前不可见。[Doc-sync 强制](2026-06-11-doc-sync-enforcement.md)已经将两类文档漂移机械化（无法编译的代码块、陈旧的事件分类表），[verify-md-wrap](2026-06-11-doc-sync-enforcement.md) 覆盖了第三类（硬换行的段落），但死链是第四类同样可机械检查、却仍靠肉眼验证的问题。
+
+引入这道门禁的直接动因是 Agent Note（agent 决策记录）目录树重组：将 `docs/adr/` 与 `.agents/notes/` 统一到同一个 `.agents/notes/` 下，并设置 `proposed/`、`implemented/`、`rejected/` 子目录，需要手工重命名约 40 条文档间链接。只要有一处路径输入错误，就会在没有任何检查拦截的情况下交付断链。
+
+## 决策
+
+新增第四道 `doc-sync` 门禁 `verify-md-links`（`scripts/verify-md-links.ts`），风格与 `verify-md-wrap` 一致（tsx ESM、基于 AST、只验证不生成）：
+
+- 使用 `mdast-util-from-markdown` + GFM 解析每个范围内的 Markdown 文件，遍历所有 `link`、`image` 和 `definition` 节点。
+- 仅当目标是**相对路径**时才检查。跳过带协议的 URL（`https:`、`mailto:` 等）、协议相对路径（`//host`）、根绝对路径（`/path`，在检出目录中没有稳定基准）以及纯页内锚点（`#section`）。剥除 `#fragment`/`?query`，相对于链接所在文件的目录解析路径，并断言目标在磁盘上存在。
+- 只报告、不改写；发现第一条死链即以非零状态退出。
+
+检查范围与其他门禁一致，并额外包含 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` 片段的链接仍会通过（文件可解析；片段被剥除）。
+
+## 曾考虑的替代方案
+
+**锚点级有效性检查**：更重且价值更低；实际造成问题的是文件级死链。这一范围裁剪是有意为之：作者在链接到某个锚点时自行验证 `#fragment`。
+
+## 后果
+
+- 造成交叉链接失效的重命名与移动会直接使 `doc-sync` 和 CI 失败，而不是等读者点击死链才暴露。由此，引入该门禁的 Agent Note 重组具备自校验能力：同一个 PR（Pull Request）在改写 40 条链接的同时，也添加了证明这些链接均未悬空的检查。
+- `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-agent-note-classification.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-agent-note-classification.i18n.yaml
new file mode 100644
index 0000000000..cc0a877084
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-20-agent-note-classification.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-agent-note-classification.md: 094233ed108e35e390cdc66b419179249c2d9173
+2026-06-20-agent-note-classification.zh.md: b424b07e051507a894c8f5961feb5fe24a9da3c6
diff --git a/.agents/notes/implemented/process/2026-06-20-agent-note-classification.md b/.agents/notes/implemented/process/2026-06-20-agent-note-classification.md
index 750a3586e0..094233ed10 100644
--- a/.agents/notes/implemented/process/2026-06-20-agent-note-classification.md
+++ b/.agents/notes/implemented/process/2026-06-20-agent-note-classification.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-agent-note-classification.zh.md)
+
 ## Problem
 
 A lifecycle-only Agent Note tree — `proposed/` / `implemented/` / `rejected/` — does not record what *kind* of decision each file contains. A reader browsing one lifecycle cannot distinguish a new capability from a removal or a tooling-policy change without opening each file.
diff --git a/.agents/notes/implemented/process/2026-06-20-agent-note-classification.zh.md b/.agents/notes/implemented/process/2026-06-20-agent-note-classification.zh.md
new file mode 100644
index 0000000000..b424b07e05
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-20-agent-note-classification.zh.md
@@ -0,0 +1,48 @@
+# Agent Note: 通过路径编码的子目录对 Agent Note 进行分类
+
+Status: implemented
+
+[English](2026-06-20-agent-note-classification.md) | 中文
+
+## 问题
+
+仅按生命周期组织的 Agent Note（agent 决策记录）目录树（`proposed/` / `implemented/` / `rejected/`）无法记录每个文件包含哪一*类*决策。读者浏览某个生命周期时，如果不逐一打开文件，就无法区分新功能、移除项或工具策略变更。
+
+本仓库一贯的倾向是[机械质量门禁优于行文规范](2026-06-11-quality-gates.md)：不被机器检查的约定终将腐烂。因此这里的分类方案必须可强制执行，而非靠自觉的文件头。
+
+## 决策
+
+增加第二个维度，即 Agent Note 的**类别**，并将其编码在路径中：`{lifecycle}/{class}/yyyy-mm-dd-topic.md`。文件夹*就是*标签。文件位置声明其类别；封闭集合限定为「这些文件夹且仅限这些」；既有的 [verify-md-links](2026-06-18-markdown-cross-link-lint.md) 门禁已经保护移动文件所需的路径改写。
+
+### 六个类别的封闭集合
+
+| 类别 | 涵盖范围 |
+|---|---|
+| `feature` | 面向用户或模型的新功能。 |
+| `bug-fix` | 修正缺陷或填补事后复盘暴露的空白。 |
+| `simplification` | 移除代码、行为或对外表面积，不引入新功能。 |
+| `architecture` | 关于**交付源码**的结构性决策——包（package）之间的关系、运行时词汇。 |
+| `process` | **围绕**代码的工具、策略或工作流，而非运行时行为。 |
+| `testing` | 测试基础设施与策略。 |
+
+`architecture` 与 `process` 的分界是：**architecture** 关乎我们交付的源码；**process** 关乎源码周边的工具与工作流。本 Agent Note 本身属于 `process` 决策：它改变仓库的组织方式与门禁，而不是 harness 的运行时行为，因此位于 `implemented/process/` 下。
+
+### 两道门禁
+
+两者都是 `doc-sync`（文档同步门禁）的成员，风格与 `verify-md-wrap` 一致（tsx ESM，只校验不生成，首个违规即以非零退出码退出）：
+
+- **`scripts/verify-agent-note-classification.ts`**：定义封闭的生命周期与类别集合。它断言生命周期文件夹下的每个文件都位于规范集合中的类别文件夹内（生命周期根目录下散落的 `.md` 或未知类别文件夹都会失败），并拒绝集中式 `INDEX.md`。规范集合位于 `scripts/agent-note-tree.ts` 中，[README](../../README.md)则以行文记录每个类别。
+- **`scripts/verify-doc-refs.ts`**：检查引用文档的源码注释。Agent Note 路径不仅出现在 Markdown 中，也出现在 TypeScript 文档注释中（例如以仓库根为起点的 `.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md`）。`verify-md-links` 看不到这些引用，因此目录重组可能静默留下失效引用。该门禁扫描 `packages/**` 与 `examples/**` 下仓库自有的 `.ts` 文件（排除已构建的 `lib/` 与 `vendor/`），查找 `docs/….md` 和 `.agents/notes/….md` token，解析每个以仓库根为起点的路径并断言其存在。它要求使用 `.md` 扩展名，因此不处理无扩展名的行文。
+
+## 曾考虑的替代方案
+
+- **在每个文件中添加 `Classification:` 行文行**（紧邻 `Status:`），由门禁解析。可行，但它将路径已能承载的事实重复到文件中，且行内容可能与所在文件夹不一致。路径编码使标签与其存储合二为一，没有需要保持同步的东西。
+- **设立 `refactor` 类别。** 与 `simplification` 几乎完全重叠；唯一有人试图用来区分的标准是「可观察行为是否改变？」，而 `simplification` 已经编码了这一点（它不改变）。一个类别即可，无需两个。
+- **生成或手工维护的语料索引。** 不予采纳：生命周期/类别目录树才是权威结构；集中式清单会制造合并热点，却没有提供目录树导航或仓库搜索无法实现的发现能力。单独的[索引提案](../../rejected/process/2026-07-04-generate-agent-note-index-tables.md)记录了被放弃的生成形状。
+
+## 后果
+
+- 每份 Agent Note 都位于一个类别文件夹下。读者浏览单个文件夹，即可查看某个生命周期内的全部简化或测试决策。
+- `doc-sync` 链中多了两个快速 tsx 脚本；无新依赖（mdast/GFM 栈已因 `verify-md-wrap`/`verify-md-links` 而存在）。
+- 新增类别必须是显式决策：修改 `scripts/agent-note-tree.ts` 中的 `const` 与 [Classification 章节](../../README.md#classification)，而不是只用 `mkdir` 创建文件夹。门禁会拒绝未知文件夹，因此临时类别无法悄然混入。
+- 源码注释中的文档引用同样受门禁约束：被 `.ts` 注释引用的文档一旦移动或重命名，`doc-sync` 与 CI 中的 `verify-doc-refs` 就会失败，从而堵住 `verify-md-links` 在结构上无法发现的一类漂移。
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
new file mode 100644
index 0000000000..f59c523dce
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-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
+2026-06-20-core-data-structures-catalog.md: d7e9d3d9b14fe723e3396c8167fe714b7613e2b5
+2026-06-20-core-data-structures-catalog.zh.md: 8d2f16a46216cba8df0539be0abd2f1ad840eec3
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 da2b0e8c51..d7e9d3d9b1 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-core-data-structures-catalog.zh.md)
+
 ## Problem
 
 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.
@@ -19,7 +21,7 @@ The scoping line was not picked top-down; it was discovered by testing candidate
 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:
 
 - 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 — the `SchemaSpec`/`InferArgs` DSL — is a sub-page detail (you write a `ToolDefinition`; the type-level machinery that types it you do not). 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 sub-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.
 
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
new file mode 100644
index 0000000000..8d2f16a462
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -0,0 +1,60 @@
+# Agent Note: 核心数据结构目录与 `ts type-equiv` 漂移门禁
+
+Status: implemented
+
+[English](2026-06-20-core-data-structures-catalog.md) | 中文
+
+## 问题
+
+试图理解 harness 的读者可以在 [architecture.md](../../../../docs/architecture.md) 中找到它的*行为*（服务图、会话/轮次/步骤生命周期、事件分类），却找不到一个统一描述其*词汇*的地方，也就是这些行为所传递的数据结构。类型形状只存在于源码中，散落在 `packages/*/src/types.ts` 各处，因此要理解“什么是 `Message`、`SessionEvent`、`StreamChunk`”，就必须直接阅读声明。文字目录会有所帮助，但复述或复制粘贴类型定义的目录会在字段发生变化时立即腐化，而不同步的类型文档比没有文档更糟，因为读者会信任它。
+
+因此，这项工作有两个相互交织的问题：**这样的目录应包含什么**（范围问题——harness 有数十种跨包（package）边界的类型，把它们全部倾倒进来对谁都没有帮助），以及**如何避免粘贴的类型定义发生漂移**（持久性问题）。本 Agent Note（agent 决策记录）记下了这两项决策。与它配套的[生成式 Cordis 事件与服务目录](2026-06-20-generated-cordis-catalog.md)从*接线*维度形成补充：本文对数据结构编目，另一篇则对传递这些结构的事件和服务编目。
+
+## 决策
+
+新增的 `docs/core-data-structures/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` 文档同步门禁，使每个粘贴的类型声明及其 JSDoc 与源码保持同步。
+
+### 何为"核心"——主干与 seam 的分界线
+
+范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算"核心"，那么"核心"就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，"核心"就意味着*中央主干*，bash 词汇归入子页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
+
+确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子页面细节。*** 逐一验证如下：
+
+- 一个数据结构是**核心**的，如果它流经 agent loop 主干——无论加载了哪些插件，循环在每个轮次都会持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄）——**或者**它是插件作者面对某条流水线时编写的唯一标志性类型（`ToolDefinition`）。
+- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，撰写重要性压过了严格的"流经主干"规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是子页面细节。这就是主干与 seam 分界线的精确表述。
+- `ToolSchema` 是核心（它是流经每个步骤的模型请求 `GenerateOptions` 的一个字段），即使它在概念上属于工具流水线——当*流经主干*与*概念归属*冲突时，前者胜出。
+- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇是子页面。
+
+`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到子页面获取各 seam 的细节。子页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
+
+### `ts type-equiv` 机制——既逐字又防漂移
+
+持久性要求很具体：文档展示当前类型声明与原始 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` 断言，是因为目录所保留的是源码名称与文档一致性，而不是可赋值性。
+- 来源信息存放在集中的 `scripts/type-equiv.manifest.json`（`{ doc, symbol, source }` 条目）中，**而非**行文中的指令注释。脚本强制执行 **1:1 对应**：每个 type-equiv 块恰好有一条 manifest 条目，反之亦然；因此一个块永远不会被静默漏检，一条条目也永远不会腐烂。
+- 接入 `doc-sync`，因此相关文档变更会在本地运行它，CI 也会与其他文档检查一起运行它。
+
+### 维护是作者的职责，门禁作为兜底
+
+`verify-type-equiv` 能捕获已记录类型的*粘贴漂移*，但无法告诉你一个全新的核心类型没有被记录。因此 AGENTS.md 和 `dsh-code-review` skill（技能）已更新，要求在变更添加或重塑已记录类型时同步更新目录——门禁处理漂移，人处理新增表面。
+
+## 曾考虑的替代方案
+
+- **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算"核心"，目录对谁都没帮助；分层的主干与 seam 结构胜出。
+- **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或契约注释变化仍会通过。
+- **来源信息作为行文中的指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
+
+## 验证教训
+
+主干与 seam 规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
+
+`verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是清单点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为孤儿。本 Agent Note 将这条失败关闭扫描规则，连同主干与 seam 的分界决策及逐字匹配决策一并记录；生成式 Cordis 目录在[其 Agent Note](2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
+
+## 后果
+
+- 这些词汇现在有一个**无法悄然漂移**的唯一归属：源码中的字段或公共类成员发生变化后，`doc-sync` 和 CI 中的 `verify-type-equiv` 会持续失败，直至粘贴内容刷新。Cordis 服务方法仍由生成式服务目录负责，而不会在此重复。
+- 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
+- `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
+- 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
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
new file mode 100644
index 0000000000..16fb9e2d1e
--- /dev/null
+++ b/.agents/notes/implemented/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
+2026-06-20-generated-cordis-catalog.md: b5957cf06a9316447aae70183de462024bb24be3
+2026-06-20-generated-cordis-catalog.zh.md: 35ed06c4a8e13245a37adaa4d5da7a842e97c0c7
diff --git a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md b/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md
index 4ca9b7e42c..b5957cf06a 100644
--- a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-generated-cordis-catalog.zh.md)
+
 ## Problem
 
 A plugin author needs two reference surfaces that no single document gave them: every cordis **event** they can listen to (with its exact signature and dispatch mode) and every `ctx.<key>` **service** they can call (with its exact interface). The pieces existed but were scattered — a hand-maintained event-taxonomy *table* in `docs/architecture.md` (names + prose Mode/Purpose, name-set-checked by `verify-event-taxonomy`), a Service-map table (8 rows of role prose), and the `interface Events` / `interface Context` declarations themselves. The taxonomy table also could not catch a brand-new *undocumented* event: a name-set verifier only checks the names that are already in the table on both sides.
diff --git a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.zh.md
new file mode 100644
index 0000000000..35ed06c4a8
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.zh.md
@@ -0,0 +1,41 @@
+# Agent Note: 生成式 Cordis 事件与服务目录
+
+Status: implemented
+
+[English](2026-06-20-generated-cordis-catalog.md) | 中文
+
+## 问题
+
+插件作者需要两个参考面，而此前没有任何单一文档能提供：他们可以监听的每一个 Cordis **事件**（含精确签名与分发模式），以及他们可以调用的每一个 `ctx.<key>` **服务**（含精确接口）。相关信息虽然存在，但散落各处：`docs/architecture.md` 中一张手工维护的事件分类*表格*（名称 + 行文描述的 Mode/Purpose，由 `verify-event-taxonomy` 做名称集合校验）、一张服务映射表（8 行角色描述），以及 `interface Events` / `interface Context` 声明本身。分类表格还有一个盲区：它无法捕获全新的*未记录*事件——名称集合校验器只检查两侧已有的名称。
+
+这是对[核心数据结构目录](../../../../docs/core-data-structures/core.md)（[其 Agent Note（agent 决策记录）](2026-06-20-core-data-structures-catalog.md)）在接线维度上的补充：前者对循环传递的*数据结构*编目（经验证的手工粘贴），本文则对传递它们的*事件和服务*编目。
+
+## 决策
+
+从源码生成目录，取代手工维护表格并校验子集的方式。
+
+`scripts/gen-cordis-catalog.ts` 使用 TypeScript 编译器 API，根据声明和源码 JSDoc 分别生成事件与服务参考。事件包含分派模式及其原始成员 JSDoc；服务包含公共签名及各方法的原始 JSDoc。确定性的 `--write` 和 `--check` 模式使两个页面成为生成产物，并由 `doc-sync` 强制检查新鲜度。
+
+纯生成在此处是正确的，因为代码库足够规范，AST 就是全部事实：每个事件/服务名称都是字符串字面量，可以往返映射到静态声明——不存在动态命名的事件，也不存在仅运行时的服务。因此生成的文档不可能出错，且从结构上消除了未记录事件的缺口（生成器枚举源码，而非校验手写子集）。
+
+具体选择：
+
+- **`@mode` 标签，交叉校验。** 每个 harness 事件的 JSDoc 携带一个显式的 `@mode emit|waterfall|parallel|serial` 标签；缺少标签时生成器直接报错。当签名形状具有决定性时——尾部参数为 `next: () => …` 在结构上即为 waterfall（瀑布式事件）——生成器断言标签与之一致，矛盾时直接报错。emit/parallel/serial 的区别在结构上不可见（`session/flush` 返回 `Promise<void> | void` 且无 `next`，有序的 `agent/pre-step` 检查点亦然），因此信任标签。编写规则见 [AGENTS.md](../../../../AGENTS.md)。
+- **分层范围。** harness 层（8 个 `@deepseek-ai/dsh-*` 服务及其事件）从源码完整渲染。继承层（cordis-core 的 `ctx.on/emit/effect/provide/…` + `internal/*` 事件 + loader/hmr/timer）是插件同样可见的固定 vendor 源码；它从生成器中一张人工维护的表格简洁渲染（名称 + 一行描述 + 源码指针），而非遍历 vendor AST。原因是 cordis-core 的 `Context` 混合了真正的 ctx 成员与非服务字段（`root`、`baseUrl`、`logger`），且 vendor 接口面仅在有意的 vendor 同步时才变化。
+- **指向数据结构目录的交叉链接。** 签名中由仓库拥有的每个类型名（`GenerateOptions`、`StreamChunk`、`ToolDefinition`……）都会通过人工维护的映射链接到其主要核心数据结构页面。AST 遍历采用失败关闭策略：每个参数、泛型约束/默认值和返回类型引用都必须已映射、是签名自身的类型参数、是点名的 TypeScript/Cordis 基础类型，或带有点名的例外及其非目录文档归属。违规会连同源码位置汇总报告，并点明相应的归属列表。该映射不会复用 `type-equiv.manifest.json`，因为后者记录 `…Map` 符号，而签名引用派生的联合类型名，并且会在多个页面列出某些符号。
+- **专用围栏。** 签名块使用 ` ```ts cordis-catalog ` 信息字符串，并把原始事件或公共方法 JSDoc 直接放在其声明之前。`doc-typecheck` 会识别并跳过这些裸片段，将其排除在 opt-out 比例之外——与 `type-equiv` 块的处理相同。
+
+本决策**取代** [doc-sync 强制](2026-06-11-doc-sync-enforcement.md)中事件分类的那一半：`verify-event-taxonomy` 及其 `docs/architecture.md` 表格退役（architecture.md 的标题保留，正文改为指向目录；服务映射的角色表格作为人工行文保留）。doc-typecheck、verify-md-wrap、verify-md-links 和 verify-type-equiv 不受影响。
+
+## 曾考虑的替代方案
+
+- **校验而非生成（退役的分类检查所做的事）**：*仅对本参考面*反转了这一策略。此处的数据可以机械地完整获取，因此生成严格强于对手工表格做名称集合校验（完整签名、不会漂移、能捕获未记录事件）。
+- **遍历 vendor AST 以获取继承层**：否决，改用人工维护表格。cordis-core 的 `Context` 混合了真正的 ctx 成员与非服务字段，且固定的 vendor 接口面仅在有意同步时才变化。
+- **复用 `type-equiv.manifest.json` 作为签名交叉链接映射**：否决，改用完整的人工维护常量和失败关闭覆盖。清单记录 `…Map` 符号，而签名引用派生的联合类型名，并且会在多个页面列出某些符号。显式映射让每个渲染目标和每个非目录例外都成为可评审的决策。
+
+## 后果
+
+- 目录不会发生漂移：提交文件未反映的源码变化会使 `doc-sync` 和 CI 中的 `verify-cordis-catalog` 失败。新事件缺少 `@mode` 标签、标签与其签名冲突，或签名类型未分类，都会直接使生成器失败。
+- 事件与服务方法契约只有一个归属——声明处的 JSDoc。目录会在生成的签名块中重复该原始 JSDoc，并使用其描述部分作为条目正文，因此单薄的源码文档只会生成单薄的目录条目。
+- 继承层是手工摘要，因此 vendor 同步若新增或重命名了 cordis-core 事件或 `ctx` 成员，需要同步编辑 `gen-cordis-catalog.ts` 中的人工维护表格。这是不遍历固定 vendor 源码的有意代价；它很少变化，且在生成器中有明确标注。
+- `verify-event-taxonomy.ts` 被删除，`docs/architecture.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 a1d901ad15..3bfc8414e7 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
-2026-07-02-bilingual-docs-and-pairing-gate.md: 3be1d5d8fd9dba20cfca34c79cb01d89fad8097a
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: a8aa8812934e755fe0175c8f3f20d194e4d24b4a
+2026-07-02-bilingual-docs-and-pairing-gate.md: 4bc02878a0ea3f998e411ecc2b064c1626eacf3c
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 90a0c2f07f68b0fb4e26cd1c4b537a30a829b10f
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 3be1d5d8fd..4bc02878a0 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
@@ -13,8 +13,14 @@ This repo's README and docs tree are read by people and agents inside and outsid
 - **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`) 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: required pairs exist, every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical), excluded (generated or bilingual-by-construction) files stay unpaired, and date-named documents on or after the manifest's `requiredSince` cutoff have complete pairs. The `required` list in [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) is a ratchet: each merged translation batch adds its files, so coverage only grows.
+- **The enforcement frontier advances in coherent review batches.** A related set enters `required` only when reviewers can evaluate it as a unit. The core frontier groups [architecture](../../../../docs/architecture.md), the [Cordis primer](../../../../docs/cordis-primer.md), [defensive patterns](../../../../docs/defensive-patterns.md), the [glossary](../../../../docs/glossary.md), and [testing](../../../../docs/testing.md) because their terminology, links, and contributor contracts inform one another; admitting only part would leave the enforced corpus internally inconsistent. 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.
 
+## Verification
+
+The 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.
+
 ## 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.
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 a8aa881293..90a0c2f07f 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
@@ -13,8 +13,14 @@ 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`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
 - **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）不得配对；凡文件名以日期开头且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，也必须有完整配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
+- **执行红线按连贯的评审批次推进。** 一组相关文档只有在评审者能够将其作为整体评估时，才进入 `required`。核心红线将[架构](../../../../docs/architecture.md)、[Cordis 入门](../../../../docs/cordis-primer.md)、[防御性模式](../../../../docs/defensive-patterns.md)、[术语表](../../../../docs/glossary.md)和[测试](../../../../docs/testing.md)归为一组，因为它们的术语、链接和贡献者契约相互关联；只纳入其中一部分会使受门禁约束的文档集合内部不一致。发布到文档站的配对使用 `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。
 
+## 验证
+
+验证契约分别覆盖每个边界。`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)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
+
 ## 曾考虑的替代方案
 
 - **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。
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
new file mode 100644
index 0000000000..65a2b2da28
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-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
+2026-07-02-tool-schema-catalog.md: c8cc69df428f6eee0f66ed976865afe2a0702448
+2026-07-02-tool-schema-catalog.zh.md: f08cb5b5312dd07f91037a4382bf5e416cae552d
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 814331af8b..c8cc69df42 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+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.
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
new file mode 100644
index 0000000000..f08cb5b531
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
@@ -0,0 +1,55 @@
+# Agent Note: 生成式工具 schema 目录（启动并采集）
+
+Status: implemented
+
+[English](2026-07-02-tool-schema-catalog.md) | 中文
+
+## 问题
+
+仓库此前没有一份统一的参考文档来记录实际暴露给模型的工具名称、描述与 JSON Schema。源码声明分散各处且在运行时组合，而既有的 Cordis 目录和数据结构目录覆盖的是接线与词汇，而非工具。
+
+## 决策
+
+目录通过**启动每个工具插件并读取其已注册 schema** 来生成，而不是解析源码。`scripts/gen-tool-catalog.ts` 在全新的 Cordis `Context` 上挂载每个已发布工具包（package）；该上下文还提供 `SystemPrompt`、`ToolRegistry` 以及插件 `apply` 所读取的注入 seam。生成器调用 `ctx.tools.schemas()`——也就是发送给模型的确切 `ToolSchema[]`——随后释放上下文，并为每个包渲染一个 `## <package>` 章节，每个工具附带一个 ` ```json ` `parameters` 块。它与 `gen-cordis-catalog` / `gen-module-graph` 的 CLI 形状一致：默认 `--write` 重新生成；提交副本陈旧时 `--check` 失败；输出具有确定性（按清单排序，工具按名称排序）。`verify-tool-catalog`（即 `--check`）在 `doc-sync` 内运行，因此相关文档变更和 CI 会执行同一项新鲜度检查。
+
+### 为何启动而非解析（核心要点）
+
+Cordis 目录是纯 TypeScript AST 遍历，因为每个事件/服务名都是字符串字面量，可以往返映射到静态声明——AST 即全部事实。**工具 schema 在静态层面不可知**，因此同样的技术会产出一份说谎的文档：
+
+- `tool-todo` 写了 `enum: [...STATUSES]`——对一个运行时 `const` 的展开。AST 看到的是展开表达式，而非 `["pending","in_progress","completed"]`。
+- 每条 description 都通过字符串**拼接**构建（`'…' + '…'`）。AST 看到的是拼接节点，而非模型实际读到的最终文本。
+- `tool-subagent` 的工具名是 `config.toolName ?? 'subagent'`——加载时选定，并非字面量。
+- MCP 插件可以通过 `ctx.tools.register()` 直接注册**原始 JSON Schema**，完全不经过 `defineTool`，因此结构化枚举 `defineTool(` 调用点会遗漏。
+
+唯一准确的真源，是插件加载后注册表实际持有的 schema。启动插件是把[测试策略](../../../../docs/testing.md)中“验证现实，而非自我报告”的准则应用到文档生成器：读取已发布产物，而非重新推导一份。
+
+### 恢复「不会静默遗漏」的保证
+
+启动有一项 AST 遍历不存在的代价：没有源码声明集合可供枚举，新工具包可能被遗忘。一个**完整性守卫**恢复了这项保证——`assertManifestComplete` 对 `packages/` 下所有 `tool-*` 包进行 glob，若有任何一个不在生成器的启动 manifest 中则直接报错。新工具包在注册之前会导致生成器失败，进而导致 `doc-sync` 失败。这与 Cordis 生成器通过枚举源码免费获得的结构性属性相同，只是为基于启动的生成器重新实现了一遍。
+
+### 手动维护的启动 manifest 是不可化约的策略
+
+文件系统负责发现工具包清单，完整性守卫负责拒绝遗漏。`TOOL_PACKAGES` 仍然为每个包持有一份显式的启动配方，因为所需的 seam 实现和配置属于策略，不是能从目录布局或注入名称安全推断的事实。
+
+### 范围
+
+`packages/*/tool-*` 下已发布的产品工具包，每个都使用默认配置启动，包括 `dsh-tool-bash`（`bash`）、`dsh-tool-tasks`（`task_output`、`task_list`、`task_kill`）和 `dsh-tool-subagent`（`subagent`）。仅供示例使用的工具不在范围内。
+
+目录的单位是包，而非每个配置化的工具实例。每个包以默认配置启动一次；加载时的别名（如 `subagent_fork`）会注明，但不枚举所有部署排列。部署清单是一个独立的、无界的接口。
+
+### 使用普通 `json` 围栏
+
+schema 块使用 ` ```json `，而非自定义的 `ts` 系围栏。`doc-typecheck` 只提取 `ts*` 围栏，因此 JSON 块对它不可见——无需 `BlockKind` 接线（不同于 Cordis 目录的 `ts cordis-catalog` 围栏，后者需要加入白名单以避免裸签名片段被编译）。
+
+## 曾考虑的替代方案
+
+- **纯 TypeScript AST 遍历，如 Cordis 目录**：工具 schema 在静态层面不可知（见上文核心要点）：运行时展开、字符串拼接、配置选定的名称，以及原始 `ctx.tools.register()` 注册，都会让 AST 推导出的文档说谎。
+- **从各包的 inject 推断启动配方**：属于[发现包清单提案](../../proposed/process/2026-06-20-discover-package-inventory.md)所警告的「过度聪明」路径；配方保持为手写策略，清单由文件系统发现并由完整性守卫把关。
+- **为 schema 块使用自定义 `ts` 系围栏**：不必要。普通 ` ```json ` 围栏对 `doc-typecheck` 不可见，无需 `BlockKind` 白名单。
+
+## 后果
+
+- 目录不会发生漂移：提交文件未反映的工具 schema 变化会使 `doc-sync` 和 CI 中的 `verify-tool-catalog` 失败。新增的 `tool-*` 包若未加入清单，会直接使完整性守卫失败。
+- 工具描述文本有唯一归属——源码中 `defineTool` 的 `description`——生成的条目质量取决于它，与 Cordis 目录对事件 JSDoc 施加的强制力相同。
+- 生成器导入并执行工作区包（这是仓库中第一个这样做的脚本；其他脚本只读文本）。它通过根 `tsconfig` 的 `paths` 映射在 `tsx` 下运行，使用与演示和测试相同的未构建源码路径，因此不需要构建步骤。
+- 未来某个工具背后新增一个能力 seam，意味着 manifest 中需要新增一条配方条目（声明要挂载哪些 seam）。这正是上文指出的有意为之的手写成本；仅在新增工具包时才需变更。
diff --git a/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.i18n.yaml b/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.i18n.yaml
new file mode 100644
index 0000000000..dbaa77f5ef
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-03-documentation-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
+2026-07-03-documentation-graph-atlas.md: 9a30b13f9db6ceb2715517230e349cbe083850ec
+2026-07-03-documentation-graph-atlas.zh.md: 0734a2c659459f40ee81b9960f259681cb35891c
diff --git a/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md b/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md
index 7969f0e80c..9a30b13f9d 100644
--- a/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md
+++ b/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-03-documentation-graph-atlas.zh.md)
+
 ## Problem
 
 The repo already had several high-trust documentation surfaces, each on a different axis: [module-graph.md](../../../../docs/module-graph.md) is generated from package `peerDependencies`, the generated [Cordis events](../../../../docs/cordis-catalog/events.md) and [services](../../../../docs/cordis-catalog/services.md) catalogs are generated from Cordis `Events` and `Context` declarations, [tool-catalog.md](../../../../docs/tool-catalog.md) is generated by booting shipped tool plugins, and [core-data-structures/](../../../../docs/core-data-structures/core.md) uses `ts type-equiv` blocks to keep pasted type definitions synchronized with source.
diff --git a/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.zh.md b/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.zh.md
new file mode 100644
index 0000000000..0734a2c659
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.zh.md
@@ -0,0 +1,70 @@
+# Agent Note: 面向维护者与 SDK 用户的文档关系图索引
+
+Status: implemented
+
+[English](2026-07-03-documentation-graph-atlas.md) | 中文
+
+## 问题
+
+仓库已经有若干高可信文档表面，各自覆盖不同维度：[module-graph.md](../../../../docs/module-graph.md) 根据包（package）的 `peerDependencies` 生成；生成式 [Cordis 事件](../../../../docs/cordis-catalog/events.md)和[服务](../../../../docs/cordis-catalog/services.md)目录根据 Cordis `Events` 和 `Context` 声明生成；[tool-catalog.md](../../../../docs/tool-catalog.md) 通过启动已发布工具插件生成；[core-data-structures/](../../../../docs/core-data-structures/core.md) 则使用 `ts type-equiv` 块使粘贴的类型定义与源码保持同步。
+
+这些参考文档是准确的，但大多是目录式的。维护者仍需自行综合关系：哪些包构成一个能力 seam、哪个应用组装了具体的主干、哪些事件是持久的而哪些是实时的、钩子或策略插件在哪里可以拦截工作、以及哪个面向模型的工具依赖哪个服务。SDK 用户从另一个角度面临同样的问题：「我想要某种行为，应该安装或加载哪个包？应该扩展哪个事件/服务/工具？」
+
+钩子子系统使事件的生产者/消费方拓扑与拦截点变得更加重要；文件系统 seam 使能力 seam、策略否决、工具呈现与 SDK 组装路径变得更加重要。如果关系图的范围仅限于一个小的 bash/todo/subagent 表面，它们会立即陈旧。
+
+## 决策
+
+新增生成式关系图文档，由聚焦的生成器产出并在 [docs/graph-atlas.md](../../../../docs/graph-atlas.md) 建立索引；作为 `doc-sync` 的一部分，通过 `pnpm run verify-doc-graphs` / 现有目录新鲜度检查进行验证。
+
+该索引是既有目录之上的关系层。它不取代精确的参考文档，而是链接到它们并解释各部分如何组合在一起。
+
+### 维护模式
+
+每个关系图页面声明一种维护模式：
+
+- **Generated（生成）**：所有节点和边均从源码发现；如果已提交的产物陈旧，`--check` 失败。
+- **Hybrid generated（混合生成）**：源码发现清单，一个小型 manifest 对不可约的策略进行分类，完整性守卫在发现的条目未被分类时失败。
+- **Curated（人工策划）**：图表解释设计意图、时序或归属；它由生成器输出以使关系图文档保持为可重新生成的整体，但内容是有意撰写的。
+
+### 首批发布的索引
+
+该索引链接十一种关系表面。包拓扑和工具包所提供的功能位于已经拥有这些事实的现有生成式目录中；其余聚焦图表由 `scripts/gen-doc-graphs.ts` 生成。
+
+| 关系图 | 维护模式 | 真源 |
+|---|---|---|
+| [模块依赖图](../../../../docs/module-graph.md) | 生成式 | `packages/*/*/package.json` 的对等依赖（peer dependency）与包分组路径 |
+| [工具 schema 目录与包映射](../../../../docs/tool-catalog.md) | 生成式 | 启动后采集的工具 schema，以及工具包服务/效应元数据 |
+| [能力 seam 与核心服务](../../../../docs/capability-seams.md) | 混合生成式 | Cordis 服务声明，以及 `gen-doc-graphs.ts` 中的角色清单 |
+| [tui-agent 应用组合](../../../../examples/tui-agent/composition.md) | 混合生成式 | `examples/tui-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
+| [headless-agent 应用组合](../../../../examples/headless-agent/composition.md) | 混合生成式 | `examples/headless-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
+| [cordis-agent 应用组合](../../../../examples/cordis-agent/composition.md) | 混合生成式 | `examples/cordis-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
+| [acp-agent 应用组合](../../../../examples/acp-agent/composition.md) | 混合生成式 | `examples/acp-agent/cordis.yml` 插件列表加人工策划的应用/bundle 展开 |
+| [事件生产者/消费方矩阵](../../../../docs/event-producer-consumer.md) | 混合生成式 | Cordis 事件声明、经 AST 扫描的 `ctx.on/emit/parallel/serial/waterfall` 位置，以及显式动态分派覆盖 |
+| [agent 轮次与步骤生命周期](../../../../docs/agent-lifecycle.md) | 人工维护 | architecture.md 循环生命周期、Cordis 目录链接，以及会话事件语义 |
+| [工具执行管线](../../../../docs/tool-execution-pipeline.md) | 人工维护 | 工具管线语义与 `tools/execute` waterfall（瀑布式事件）|
+| [ACP（Agent Client Protocol）快照回放](../../../../packages/ui/acp/snapshot-replay.md) | 人工策划 | 快照 harness 行为 |
+
+### 为什么由生成器拥有文档
+
+包拓扑留在 `gen-module-graph.ts`，工具-包能力映射留在 `gen-tool-catalog.ts`，因为这些生成器已经拥有权威事实和新鲜度门禁。`gen-doc-graphs.ts` 拥有其余关系页面和索引。代价是人工策划的图表需要在 TypeScript 字符串块中编辑，而非直接编辑 Markdown。对于首版来说这是可接受的，因为面向用户的产物仍然是纯 Markdown/Mermaid；未来如果撰写体验比可重新生成更重要，可以将人工策划的页面拆分出去。
+
+### 完整性守卫
+
+混合生成的页面在其 manifest 陈旧时必须显式报错：
+
+- 模块图读取每个包的 `peerDependencies`，并按 `packages/<group>/<pkg>` 路径对包进行分组。
+- 工具目录通过启动收集已发布的工具，并从同一份 manifest 渲染包/服务/副作用映射（其完整性守卫已在检查该 manifest）。
+- 能力 seam 图导入 Cordis 服务收集器，断言每个发现的 harness `ctx.<key>` 都已在 `SERVICE_ROLES` 中分类，且每个已分类的 key 仍然存在。
+- 事件生产者/消费方矩阵标记为 hybrid，因为 subagent 生命周期事件有意使用 `ctx.events.dispatch` 实现逐监听器隔离；这些动态边是显式覆盖而非无声遗漏。
+- `verify-mermaid` 使用 Mermaid 自身的解析器解析仓库中每个 ` ```mermaid ` 围栏，因此语法错误在本地和 CI 的 `doc-sync` 阶段即被捕获，而非在 GitHub 渲染时才显示为损坏的图表。
+
+## 曾考虑的替代方案
+
+已提交的图表使用 Mermaid，因为 GitHub 在 Markdown 中原生渲染它且不引入新的文档构建依赖；密集的多对多数据（如事件生产者/消费方关系）改用 Markdown 表格。**PlantUML、托管图表服务和生成的 SVG** 曾被考虑，但在 Mermaid 成为瓶颈之前有意不采用。
+
+## 后果
+
+- 维护者获得了拓扑、seam、事件流、生命周期、应用组合与快照行为的可视化入口。
+- SDK 用户获得了从用例到包组合的路径，而非仅有自底向上的包参考。
+- `doc-sync` 现在包含 `verify-doc-graphs` 和 `verify-mermaid`，因此关系图漂移和 Mermaid 语法错误与其他文档新鲜度门禁一起被捕获。
+- 未来的文件系统和钩子工作有了承载新复杂度的具体位置：文件系统应扩展能力文档和工具目录，钩子应扩展事件矩阵和工具执行流水线。
diff --git a/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.i18n.yaml
new file mode 100644
index 0000000000..21465703e1
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-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
+2026-07-04-cordis-jsdoc-completeness-gate.md: c7c39986414437ce4d0d4c64f9e25f47485fdf5c
+2026-07-04-cordis-jsdoc-completeness-gate.zh.md: f1e7ec824ebae119c1cb27ca4dd9f0d8330dde1a
diff --git a/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md b/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md
index 3945382217..c7c3998641 100644
--- a/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md
+++ b/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-cordis-jsdoc-completeness-gate.zh.md)
+
 ## Problem
 
 The generated Cordis catalog enforced event dispatch modes but not complete service and event contracts. Methods could lack descriptions, and parameters or returns could be undocumented on the cross-plugin API surface where IDE guidance matters most.
diff --git a/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.zh.md b/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.zh.md
new file mode 100644
index 0000000000..f1e7ec824e
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.zh.md
@@ -0,0 +1,41 @@
+# Agent Note: 针对 Cordis 对外服务接口的 JSDoc 完整性门禁
+
+Status: implemented
+
+[English](2026-07-04-cordis-jsdoc-completeness-gate.md) | 中文
+
+## 问题
+
+生成的 Cordis 目录此前强制了事件分发模式，但未强制要求完整的服务与事件契约。方法可以缺少描述，参数或返回值可以在跨插件 API 接口上不写文档——而这恰恰是 IDE 引导最重要的地方。
+
+AGENTS.md 中的规则（「每个导出都有解释语义的 JSDoc」）只能靠评审以行文形式检查；本仓库的既定偏好是将不变式编码为机械门禁。「Cordis 服务函数与事件」这一范围有精确的机器定义，只有目录生成器知道：事件是 `declare module 'cordis'` 内 `interface Events` 的成员，服务接口是每个 `interface Context` 键所指向的类的公开方法。ESLint 规则看不到这层映射；生成器在每次运行时计算它。
+
+## 决策
+
+扩展 `scripts/gen-cordis-catalog.ts`——复用同一次遍历和同一套 `@mode` 先例——对它编目的所有内容强制执行 JSDoc 完整性要求。`verify-cordis-catalog` 在 `doc-sync` 内运行，因此相关文档变更和 CI 会执行同一门禁，无需另行接线。
+
+契约如下：
+
+- **事件**需要描述性文字，以及为每个**载荷参数**提供非空的 `@param`。载荷参数是携带事件数据的签名参数；`this` 接收者注解和尾部的 waterfall（瀑布式事件） `next` 免检——`next` 是分发机制，其语义已由 `@mode waterfall` 标签（及其结构交叉检查）拥有，逐事件重述只是样板代码。为免检参数写文档是允许的；只有缺失才被检查。
+- **服务类**需要类级 JSDoc，每个公开方法需要描述性文字、为每个参数提供非空的 `@param`，以及非空的 `@returns`——除非标注的返回类型是 `void`/`Promise<void>`（此时 `@returns` 可选——resolve 时机有时值得记录——但从不强制要求）。
+- **陈旧标签报错**：`@param` 命名了一个不存在的参数即为违规，与 `@mode` 与签名矛盾的检查对称。标签描述必须非空；超出此范围的语义质量由评审负责。
+- **遍历可检查的显式性**：门禁是纯 AST 遍历（不使用类型检查器），因此服务方法必须显式标注返回类型（推断的返回类型无法分类），接口参数必须是简单标识符（解构模式没有名称供 `@param` 匹配）。
+- **违规聚合**为一条错误信息，列出所有违规项——修复时一次看到完整清单。此前快速失败的 `@mode` 检查也移入同一份聚合报告，消息文本不变。
+
+生成器保留同一源码注释的两种视图：`parseJsDoc` 在第一个块标签处结束条目正文，而 `ts cordis-catalog` 签名块包含原始 JSDoc，并完整保留 `@param`、`@returns` 和 `@mode`。因此，读者可以看到完整的源码契约，而块标签文本不会泄漏到周围正文中。
+
+`packages/core/agent/tests/gen-cordis-catalog.spec.ts` 中的负路径测试对合成 fixture（测试前置数据）运行 `collectEvents`/`collectServices`，验证每条守卫都会触发且免检规则成立。撰写规则写在根 [AGENTS.md](../../../../AGENTS.md) 的约定条目中，与 `@mode` 规则并列。
+
+## 曾考虑的替代方案
+
+- **ESLint 规则**：无法看到该范围的机器定义（哪些 `interface Events` 成员、哪些 `ctx.<key>` 类构成 Cordis 对外服务接口）；目录生成器在每次运行时恰好计算这层映射，因此门禁放在那里。
+- **将每个方法展开为单独的正文小节**：否决。目录保留一个服务章节和一个签名块，以维持可扫读性；附着于每个声明的 JSDoc 则在原处保留完整的方法契约。
+- **逃逸标签**：不设。该接口面小且经过策展（采纳时 12 个服务、57 个方法、27 个事件），要点在于检查不可豁免。
+
+## 后果
+
+- 新事件或服务方法不能带着未记录的参数或结果落地：生成器会拒绝重新生成，`verify-cordis-catalog` 也会使 `doc-sync` 和 CI 失败。采纳时发现的约 139 处缺口已在同一变更中补齐，因此门禁以绿色状态落地。
+- 服务接口必须显式标注返回类型并使用标识符参数。两项约束在采纳时均未构成限制（所有方法已有标注；不存在解构的 seam 参数）；但二者现在是承重要求，违反时会被机械检测到。
+- AGENTS.md 中通用的 JSDoc 规则（「一行能说清就用一行」）在此接口上获得了更严格的特例：仅当方法无参数且返回 void 时，一行摘要才足够。
+- 为 `next` 或 `this` 写 `@param` 合法但不检查——这是有意的不对称：门禁强制载荷契约，拒绝要求样板代码。
+- 每个生成的事件或方法片段都带有其原始 JSDoc，而正文摘要不含标签。因此，源码编辑会同时刷新可读索引和签名旁展示的确切契约。
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
new file mode 100644
index 0000000000..d49010e985
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-doc-tiers-and-budgets.md: 9993eda6b0c7f1f8e5908dbd85fcfb4e5c6b3d1d
+2026-07-04-doc-tiers-and-budgets.zh.md: a40e7c2fe56ef86137bb7bb3ee8c818bdeed7eb9
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md
index 68e055f0a2..9993eda6b0 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-doc-tiers-and-budgets.zh.md)
+
 ## Problem
 
 Standing docs accumulated repeated rules, retold incidents, duplicated package maps, and stale Agent Note summaries despite existing writing guidance. Because review alone did not prevent that growth, the repository needed a mechanical budget alongside its documentation taxonomy.
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
new file mode 100644
index 0000000000..a40e7c2fe5
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
@@ -0,0 +1,28 @@
+# Agent Note: 文档分层、预算与上限门禁
+
+Status: implemented
+
+[English](2026-07-04-doc-tiers-and-budgets.md) | 中文
+
+## 问题
+
+尽管已有写作指导，常设文档仍不断累积重复规则、反复讲述的事件、重复的包（package）映射，以及陈旧的 Agent Note（agent 决策记录）摘要。仅靠评审无法阻止这种增长，因此仓库需要在文档分类之外再配一套机械预算。
+
+## 决策
+
+- **每项事实只归属一处的层级分类。**[docs/AGENTS.md](../../../../docs/AGENTS.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 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
+- **上限是只进不退的执行红线。** 上限设定为文档当前字数的至少 105%（留出工作余量，使日常措辞调整能通过，而真正的膨胀仍会触发门禁），并随着文档被精简到目标预算而同步下调、保持该余量（根 `AGENTS.md` ≤ 1,500 词；`architecture.md` ≤ 1,800；子树 `AGENTS.md` ≤ 600；`packages/README.md` ≤ 600）。推进机制与[翻译配对的 `required` 清单](2026-07-02-bilingual-docs-and-pairing-gate.md)相同。门禁变红时，修复方式是按分类体系迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才允许提高上限，manifest（元数据清单）的 diff 本身即为可评审的动作。
+- **精简的工作流 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)认为值得保持的不变式就值得编码。
+- **对所有文档层级全面设限**：否决。一刀切的上限恰好惩罚了那些正当的长文档（如特性矩阵或类型目录，每一行都是事实，例如 `packages/ui/acp/acp-feature-support.md`），并产生逐文件的例外变更，训练贡献者机械地批准提限。
+- **将标准放在 skill 内部**：否决。契约归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 `docs/AGENTS.md` 已经作为子树指令被任何在 `docs/` 下工作的人加载。
+
+## 后果
+
+- 向受预算约束的文档添加内容现在需要置换：将新增内容迁移到其分类体系归属地并留下指针，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。
+- 精简到目标预算的重写以堆叠的后续 PR 落地，每次合并时同步下调 manifest 中的上限；在各自落地之前，文档冻结的上限仅阻止进一步膨胀。
+- 字数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。
diff --git a/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.i18n.yaml
new file mode 100644
index 0000000000..00db07d233
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-04-persistence-log-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
+2026-07-04-persistence-log-catalog.md: 1529f41b485c1bc8ca029c0a9264574fa7a886a0
+2026-07-04-persistence-log-catalog.zh.md: f3f77bb66f8798d953fed16bc79cadadc35c036a
diff --git a/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.md b/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.md
index bde0f08497..1529f41b48 100644
--- a/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.md
+++ b/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-persistence-log-catalog.zh.md)
+
 ## Problem
 
 `SessionEventMap` is the on-disk vocabulary, but its declarations are split across the owning session package and declaration merges. The generated persistence catalog is the single reference for every event, its complete payload declaration and source JSDoc, and the shared `SessionEvent` envelope; hand-maintained tables drift and are removed. These records are not Cordis events—observers receive them through the single `session/event` bus event—so the Cordis catalog cannot cover them. The generator discovers all declarations and the doc-sync freshness gate rejects omissions or stale output.
diff --git a/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.zh.md b/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.zh.md
new file mode 100644
index 0000000000..f3f77bb66f
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 生成式持久化日志事件目录
+
+Status: implemented
+
+[English](2026-07-04-persistence-log-catalog.md) | 中文
+
+## 问题
+
+`SessionEventMap` 是磁盘格式的词汇，但其声明分散在所属的会话包（package）和声明合并中。生成式持久化目录是所有事件、各自完整 payload 声明与源码 JSDoc，以及共享 `SessionEvent` 信封的唯一参考；手工维护的表格会发生漂移，因此被移除。这些记录不是 Cordis 事件——观察者通过唯一的 `session/event` 总线事件接收它们——所以 Cordis 目录无法覆盖。生成器会发现所有声明，文档同步新鲜度门禁会拒绝遗漏或陈旧输出。
+
+## 决策
+
+从源码生成 `docs/persistence-catalog.md`，配合新鲜度门禁，作为第四个参考面：持久化会话日志可以包含的*记录*，与 Cordis 目录（接线）、核心数据结构（词汇）和工具目录（工具）互补。
+
+`gen-persistence-catalog.ts` 使用 TypeScript AST 扫描每个所属及声明合并的 `SessionEventMap`。它从前置 JSDoc 开始渲染每个成员，直至完整的 payload 类型，保留嵌套属性注释且只移除其容器缩进；同时粘贴构成持久化信封的所属 `SessionEventType`、`SurfaceEventType`、`SurfaceOp` 和 `SessionEvent` 声明。派生的 surface 徽章、参考链接和源码位置仍位于声明块之外。文档同步新鲜度检查会拒绝目录尚未重新生成的词汇或信封变更。
+
+具体选择：
+
+- **强制保证 JSDoc 完整性。** 每个成员和渲染出的信封类型都必须带有描述正文，完整的源码 JSDoc 会在目录中保持附着于其声明。`@mode` 标签是硬错误：分派模式属于 Cordis 总线事件，持久化记录没有这种模式。所有违规会汇总为一条错误，列出每个违规项。
+- **surface 徽章由派生得出，而非手工列举。** `SurfaceEventType`（产生 LLM（大语言模型）消息且可能携带 `surfaceOp` 的子集）从拥有方包中的 union 声明解析；如果 union 成员命名了一个未声明的事件，则为硬错误（否则陈旧的 union 成员会静默地不标注任何内容）。其余一律渲染为 **log-only**。
+- **专用围栏。** 声明块使用 ` ```ts persistence-catalog ` 信息字符串，`doc-typecheck` 会识别并跳过这些块，将其排除在 opt-out 比例之外——处理方式与 `ts cordis-catalog` 相同（这些声明引用所属模块中的类型，无法独立编译）。
+- **仓库范围。** 目录枚举本仓库中的包，与兄弟文档的 packages-only 范围一致；下游插件可以合并更多事件类型，它们在设计上不在目录范围内。遍历过程用硬错误保护自身假设：拥有方的顶层 `interface SessionEventMap` 必须是 `@deepseek-ai/dsh-session` 中唯一的导出声明（无关的、局部的或同名重复的接口不能被当作磁盘词汇编入目录）；任何声明不得携带 `extends`（继承的键会加入 `keyof SessionEventMap` 却没有对应的目录行）；每个成员必须是带有显式 payload 类型的属性签名（方法形式的成员会加入 `keyof` 却在静默遍历中被漏过）；跨声明的重复成员也会失败。
+
+本方案取代了手工副本：session.md 的 `hook/*` 表格、精简版 README 的事件表格、hook-protocol README 的 payload 条目列表，以及会话 README 的名称列表现在链接到目录，而不再重述 payload（周围的语义说明文字保留原位）。hook-protocol 合并成员上的两个误加的 `@mode emit` 标签已被移除——新门禁将它们作为类别错误拒绝。
+
+## 曾考虑的替代方案
+
+- **基于启动的生成器（类似工具目录）**：日志词汇完全是静态的，AST 遍历无需启动任何东西即可读取全部真相。
+- **保留手工副本**：手工副本只能检查作者已经写下的名称；目录落地时，会话 README 的合并说明已经漂移。
+
+## 后果
+
+- 目录不会发生漂移：提交文件未反映的词汇或信封变化会使 `doc-sync` 和 CI 中的 `verify-persistence-catalog` 失败，而没有 JSDoc 的新增合并事件会直接使生成器失败——插件不能再添加未记录的磁盘记录类型。
+- 事件正文只有一个归属，即声明处的 JSDoc；目录会保留该 JSDoc 和所有嵌套字段注释，不会将其扁平化或复述。
+- `SurfaceEventType` union 现在对文档具有结构性承载作用：重命名事件而不更新 union（或反过来）会导致生成器失败，而不仅仅是编译器失败。
+- 徽章派生假设 union 始终是一组封闭的字符串字面量且只有一个拥有方；如果重构偏离了这一形状，必须在同一个变更中更新生成器。
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
new file mode 100644
index 0000000000..1cf70223f5
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-05-uniform-agent-note-format.md: 06082251c1b96c90ed470d84224662e00e29791b
+2026-07-05-uniform-agent-note-format.zh.md: df6b0f4dfacf122f452807491680091827f69c25
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
index 1a6aa40477..06082251c1 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-05-uniform-agent-note-format.zh.md)
+
 ## Problem
 
 Agent Note paths encoded lifecycle and class, but file contents still mixed headings, status formats, ADR and proposal templates, and proposal-era sections in implemented records. Authors copied whichever neighbor they found, and lifecycle moves could skip the required rewrite because no gate enforced an in-file contract.
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
new file mode 100644
index 0000000000..df6b0f4dfa
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
@@ -0,0 +1,30 @@
+# Agent Note: Agent Note 的统一受门禁约束的文件内格式
+
+Status: implemented
+
+[English](2026-07-05-uniform-agent-note-format.md) | 中文
+
+## 问题
+
+Agent Note（agent 决策记录）的路径编码了生命周期和类别，但文件内容仍混杂着不同标题、状态格式、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 失败，而不再依赖评审者记忆。
+
+定义该格式的同一变更规范化了整个语料库——遵循预发布立场：不设过渡期，不容忍双格式。唯一受既有条款豁免的是内容，而非格式：替代方案只能记录、不能杜撰，因此若某份格式制定前的 Agent Note 无法从记录中还原替代方案，就会携带确切的 `agent-note-format: alternatives-not-recorded` 注释；门禁只对日期早于本文的文件接受该注释。
+
+## 曾考虑的替代方案
+
+- **完整的刚性模板**（每个生命周期使用固定章节顺序，重构每份 Agent Note 以适配）：否决。大型设计 Agent Note 包含八到十五个定制技术章节（包（package）拓扑、线协议、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` 契约文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个契约文件更易发现和维护。
+
+## 后果
+
+现在每份 Agent Note 都需要稍多一些结构，而强制的 `Alternatives considered` 章节是有意设置的阻力：记录决策却不记录它胜过什么，会招致 Agent Note 本应防止的重新争论。无法还原替代方案的格式制定前 Agent Note 会永久保留既有条款注释——这是记录中诚实的缺口，而不是杜撰的理由。`doc-sync` 增加一道门禁；在生命周期文件夹之间移动 Agent Note 时，现在必须当场完成真正的工作（迁移本就应包含的正文改写），而不是推迟为无人跟踪的清理任务。三十九个债务标记已经消失，由它们一直等待的模板解决。
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
new file mode 100644
index 0000000000..966ac24d13
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-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
+2026-07-06-export-surface-jsdoc-gate.md: 93d8a41fc2ffb235de5c56ffeb5569bc95249392
+2026-07-06-export-surface-jsdoc-gate.zh.md: 64b4bcc620046f2c94a2ce3fbeb67e59ada888d4
diff --git a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
index 734fbeab21..93d8a41fc2 100644
--- a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
+++ b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-export-surface-jsdoc-gate.zh.md)
+
 ## Problem
 
 The [cordis JSDoc completeness gate](2026-07-04-cordis-jsdoc-completeness-gate.md) made undocumented parameters and results impossible on the cordis surface — `interface Events` members and `ctx.<key>` service classes — but that surface is a fraction of what a plugin author imports. The AGENTS.md rule "every export (and non-obvious method) has a JSDoc explaining semantics" stayed prose-checkable only by review everywhere else, and nothing at all asked for `@param`/`@returns` on ordinary exported functions. A survey at adoption found 203 under-documented module-level exports across 34 packages: seam-adjacent helpers (`runBash`, `readForEdit`, `htmlToMarkdown`), format codecs, whole undocumented interfaces and type aliases — exactly the names an IDE consumer hovers.
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
new file mode 100644
index 0000000000..64b4bcc620
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
@@ -0,0 +1,45 @@
+# Agent Note: 导出表面 JSDoc 门禁
+
+Status: implemented
+
+[English](2026-07-06-export-surface-jsdoc-gate.md) | 中文
+
+## 问题
+
+[Cordis JSDoc 完整性门禁](2026-07-04-cordis-jsdoc-completeness-gate.md)使得 Cordis 表面上的参数和返回值不可能缺少文档——`interface Events` 成员和 `ctx.<key>` 服务类——但这只是插件作者所导入内容的一小部分。AGENTS.md 中的规则「每个导出（以及非显而易见的方法）都必须有解释语义的 JSDoc」在其他地方只能靠评审以行文方式检查，而且没有任何机制要求普通导出函数带 `@param`/`@returns`。采纳时的一次调查发现 34 个包（package）中有 203 个文档不完整的模块级导出：seam 相关辅助函数（`runBash`、`readForEdit`、`htmlToMarkdown`）、格式编解码器、完全无文档的接口和类型别名——恰恰是 IDE 消费方悬停查看的那些名称。
+
+## 决策
+
+新增门禁 `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 门禁之下）。
+- 导出命名空间递归检查（在 ambient `declare` 命名空间内，每个成员隐式导出）；命名空间本身仅在不与同名的已文档化声明合并时才需要描述文字（Config-namespace 惯用法只需文档化插件一次）。
+- `declare module`/`declare global` 体和 `export … from` 重导出语句被跳过：augmentation 不是包的导出，重导出的定义在其定义处检查。`export import X = N.member` 别名需要文档化自身——其目标可能是遍历不会访问的非导出命名空间成员——且门禁仅支持纯描述文字的目标类型：可调用、类或命名空间目标携带别名描述文字无法承载的签名/成员契约，门禁会拒绝并要求直接导出该声明。
+- 其余情况按封闭原则失败：`export =` 直接拒绝；基类从未命名的参数即使作为绑定模式仍需 `@param`；dispatch 不识别的导出语句类型本身就是违规——没有任何导出形式能因遗漏而免检。
+
+三类豁免避免门禁要求样板代码，精神与 Cordis 门禁的 `this`/`next` 豁免一致（为已豁免的名称编写文档是允许的；只有缺失才不被检查）：
+
+- **继承成员。** 重写从其基类声明继承文档。新增的公开表面仍需文档：新增参数、将 protected 成员公开重写、或在 void 基类之上返回具体类型。继承查找和推断返回值分类是门禁唯一需要类型检查器的工作；其他检查使用 AST。
+- **插件协议槽位。** 顶层的 `name`/`inject`/`reusable`/`Config` 常量和 `apply` 入口，以及插件类上的同名静态成员，属于框架协议：其形状由 Cordis 固定，模块文档注释加 `interface Config` 承载插件的真实语义。
+- **构造函数**，与 Cordis 门禁一致：插件类由框架构造，类文档承载全部说明。
+
+`collectExportJsdocViolations()` 返回违规列表（CLI（命令行界面）在非空时以 1 退出），因此 `packages/core/agent/tests/verify-export-jsdoc.spec.ts` 中的负路径测试直接断言发现项，通过 fixture（测试前置数据）包驱动每一种拒绝和每一种豁免。
+
+## 曾考虑的替代方案
+
+- **eslint-plugin-jsdoc**（`require-jsdoc`/`require-param`/`require-returns`）：覆盖了机械核心，但无法表达本仓库的契约。继承成员豁免需要跨包的类型解析，协议槽位和命名空间合并惯用法是 Cordis 特有的，而完整性语义（标签前描述文字、过时标签报错、汇总报告）已在 `scripts/jsdoc.ts` 中与 catalog 生成器共享。两套微妙不同的「已文档化」定义，正是本仓库「单一归属」规则所要防止的失败模式。
+- **扩展 `gen-cordis-catalog.ts`**：catalog 生成器渲染一个精选表面并守卫其新鲜度；仓库级遍历没有 catalog 可渲染。共享辅助函数、保持遍历独立，使每个门禁的职责清晰可读。
+- **强制接口/类型别名的成员文档**：推迟。这会使检查表面成倍增长，而这些成员大多是自描述的字段；承载关键成员契约的 seam 服务类已有门禁。如果评审中出现成员文档漂移再重新考虑。
+
+## 后果
+
+- 新导出不能在缺少文档的情况下落地：`verify-export-jsdoc` 会使 `doc-sync` 和 CI 失败。采纳时发现的 203 处缺口已在同一变更中补齐，因此门禁以绿色状态落地。
+- 导出函数必须标注返回类型（采纳时已全面满足，现在成为门禁依赖），并在 `@param` 需要命名参数时使用标识符参数。
+- seam 文档是权威的：实现从其继承链继承文档，值得保留在实现上的行为说明是补充，而非必需。
+- 门禁构建一个 `ts.Program`（约 6 秒）——唯一需要类型解析的文档门禁；在已编译文档片段的 `doc-sync` 内可以接受。
+- 协议槽位名称按约定保留在模块顶层；一个恰好命名为 `apply` 或 `Config` 的非协议导出将不被检查——已接受，记录于此。
diff --git a/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.i18n.yaml
new file mode 100644
index 0000000000..17473bf069
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-generated-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
+2026-07-06-generated-config-catalog.md: f39f5138526d3278e839ee0053d5051bb8bc1c36
+2026-07-06-generated-config-catalog.zh.md: 825046914dad8e1a7d87340a310b252f03cbecb9
diff --git a/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.md b/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.md
index f876191be4..f39f513852 100644
--- a/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.md
+++ b/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-generated-config-catalog.zh.md)
+
 ## Problem
 
 The repository had no source-backed reference for plugin configuration. Package READMEs documented fields inconsistently, did not enumerate which packages are loadable, and did not verify that runtime schemas agree with declared config types.
diff --git a/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.zh.md b/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.zh.md
new file mode 100644
index 0000000000..825046914d
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-generated-config-catalog.zh.md
@@ -0,0 +1,40 @@
+# Agent Note: 生成式插件配置目录
+
+Status: implemented
+
+[English](2026-07-06-generated-config-catalog.md) | 中文
+
+## 问题
+
+仓库此前没有以源码为后盾的插件配置参考。各包（package）的 README 对字段的记录方式不一致，未列举哪些包可被加载，也未校验运行时 schema 与声明的配置类型是否一致。
+
+## 决策
+
+`scripts/gen-config-catalog.ts` 根据各插件声明的 config 类型和 JSDoc 生成 [docs/config-catalog.md](../../../../docs/config-catalog.md)，并包含注入要求、被引用类型的链接和源码位置。包内类型会以传递方式纳入；workspace 类型和外部类型则会链接或点名。确定性的 `--write` 和 `--check` 模式使提交页面成为生成产物。
+
+此处采用纯 AST 生成是正确的，原因与事件/服务目录相同，而与工具目录不同：配置类型是静态声明，仓库中每个 schemastery schema 都是静态的 `z.object`/`z.intersect` 字面量，因此源码即全部真相——配置表面没有任何部分是运行时组合的。
+
+具体选择：
+
+- **配置类型是第二参数的类型。** catalog 记录的是 `apply(ctx, config)` / 服务构造函数 `(ctx, config)` 的声明参数类型——即 Cordis 实际传入的值——而非按命名约定定位的 `Config` 导出。这使得遍历是全量的：无论接口叫 `AcpConfig` 还是 `BasicCompactConfig`，无论类型声明在兄弟文件中，还是插件完全没有验证 schema，都能正常工作。
+- **分类是全量的。** 每个 `packages/<group>/<pkg>` 条目都会被解析（镜像 Loader 的 `unwrapExports`：`exports.default ?? exports`），归入可配置插件、无配置插件、抽象 seam 类或库之一——各自渲染在独立小节中——无法归类的条目直接报错。新包不可能被悄悄遗漏。
+- **逐字段 JSDoc 强制要求。** 粘贴的声明中每个属性（包括嵌套的类型字面量）都需要非空的 JSDoc 描述，否则生成失败。粘贴本身就是文档，因此这与 events catalog 通过 `@mode` 施加的强制函数相同：源码文档过于单薄时门禁报错，而非产出单薄的 catalog。
+- **Schema 键与声明类型做比对。** 生成器通过局部和 workspace 类型解析嵌套的对象与数组路径。确定缺失的路径报错；无法枚举的外部或动态形状则跳过。比对有意设计为单向的，因为声明类型可能包含被排除在 loader 配置之外的运行时专用字段。
+- **专用围栏。** 粘贴的声明使用 ` ```ts config-catalog ` 信息字符串，`doc-typecheck` 会跳过它（引用了导入类型的孤立声明无法独立编译），并将其排除在 opt-out 比例之外——与 `cordis-catalog` 和 `persistence-catalog` 围栏的处理方式相同。
+- **单文件 `docs/config-catalog.md`**，而非一个单文件目录：该页面面向单一受众（`cordis.yml` 的编写者），只有一个维度，不同于 `cordis-catalog/`（其中包含两个并列页面）。
+
+各包 README 中的 `## Config` 小节保留。重叠是有意接受的：README 是经过策划的逐包契约（在部署上下文中描述配置语义，连同限制与扩展点），catalog 则是穷举式的生成枚举。由于 catalog 是生成的，二者不一致时说明 README 有误，修复方式是编辑 README——catalog 不会漂移。
+
+## 曾考虑的替代方案
+
+- **合成式逐字段渲染**：为每个字段生成项目符号列表、表格或带注释的 YAML 片段，从解析的 JSDoc 加 schema 元数据组装。否决，改用逐字粘贴：接口连同其 JSDoc 本身就是以原始形式撰写的契约，合成渲染器会重新格式化它不拥有的行文，增加一个可能歪曲原意的渲染层。
+- **运行时启动 + schema 内省（如工具目录所做的那样）**：否决。此处没有任何内容是运行时组合的，且 schema 本身对配置表面的文档化不足（以行文记录的默认值、运行时专用字段、完全没有 schema 的插件）。启动只会增加脆弱性而不增加真相。
+- **双向 schema/接口等价检查**：否决，改用子集检查。声明类型合理地包含 schema 拒绝从配置接受的成员（运行时专用 seam）。
+- **在同一变更中废除 README `## Config` 小节**：否决。保留可接受的重叠使逐包契约在原处可读，而清理工作需要先把每个 README 的额外事实折入字段 JSDoc——这是可分离的工作，catalog 不依赖它。
+
+## 后果
+
+- 目录不会发生漂移：提交文件未反映的源码变化会使 `doc-sync` 和 CI 中的 `verify-config-catalog` 失败。config 字段未记录、被引用类型名无法解析，或 schema 键未出现在 config 类型中，都会直接使生成器失败。
+- 配置行文现在有了声明处的强制函数：编写新配置字段意味着编写其 JSDoc，而该 JSDoc 将逐字成为 catalog 条目。
+- 生成器对无法静态遍历的形状直接报错——别名化的包内配置导入、非 `object`/`intersect` 组合构建的 schema、未列入的全局类型名。引入此类形状时必须同时教会生成器（否则该形状不能进入仓库），这正是设计意图：catalog 始终是全部真相。
+- `gen-cordis-catalog.ts` 导出其 JSDoc/指针辅助函数与 `LINK_MAP` 供复用，因此两个 catalog 以相同方式交叉链接类型，新增一条 link-map 条目同时服务于两者。
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
new file mode 100644
index 0000000000..2cb7f1009d
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-06-node-engine-floor.md: f1754ea7ca32452a04c6cd8a0599568f602e47dd
+2026-07-06-node-engine-floor.zh.md: 9d376a639378d3a0b9b645aa36c1a5d320d1d147
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 507641a99a..f1754ea7ca 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-node-engine-floor.zh.md)
+
 ## Problem
 
 The Node 22 branch of the root `engines.node` range is a contract for the installed workspace, not only for the runtime APIs the harness source calls directly. It must be no lower than package `engines.node` declarations for dependencies the workspace installs on that branch; otherwise `pnpm install --engine-strict` fails at an advertised LTS version, and non-strict installs run outside a dependency's supported runtime.
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
new file mode 100644
index 0000000000..9d376a6393
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 将 Node LTS 引擎下限提升至 22.19
+
+Status: implemented
+
+[English](2026-07-06-node-engine-floor.md) | 中文
+
+## 问题
+
+根 `engines.node` 范围中的 Node 22 分支是对已安装工作区的契约，而不仅仅是 harness 源码直接调用的运行时 API 的契约。它不得低于工作区在该分支上安装的依赖包（package）所声明的 `engines.node`；否则 `pnpm install --engine-strict` 会在一个已宣传的 LTS 版本上失败，而非严格模式的安装则会在依赖所支持的运行时范围之外运行。
+
+## 决策
+
+将 `engines.node` 设为 `^22.19.0 || >=24.0.0`，并在 keyless CI 兼容性矩阵中测试 `['22.19', 24, 26]`。每条矩阵分支都运行 TypeScript 类型检查加一次 keyless 的源码模式 worker 冒烟测试，因此引擎下限通过完整的源码类型检查和真实的未构建运行时路径两条路径得到验证。真实 API 的 e2e 工作流保持在 Node 24 上，因为它验证的是 API 集成而非运行时下限。
+
+两个 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`。
+
+这些源码特性在 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 分支，而没有任何部署应当使用它。
+
+`@types/node` 继续固定在 22.x 线（`^22.20.0`），以匹配 LTS 支持线：使用 Node 23+/24+/25+ 的 API 会在所有机器和类型检查门禁中导致 `tsc` 失败，而不是编译通过、直到仅下限矩阵分支才能捕获的运行时错误才暴露。目前整个代码树在 Node 22 类型表面上类型检查全部通过，因此这一固定没有任何代价。
+
+## 后果
+
+- 宣传的 LTS 分支不再低于 Pi 适配器依赖的下限。
+- CI 通过 Node 22.19 直接验证 Node 22 LTS 下限，Node 24 分支保持 `node: 24`，Node 26 用于下一个偶数线；每条分支都对源码图执行类型检查，并实际启动未构建的工作流 worker。
+- built-bin 冒烟测试无需版本条件标志：在 22.19 上类型剥离已是默认行为，因此测试保持其文档所述的纯 `node lib/bin.js` 路径。
+- 未来若依赖或源码 API 提高运行时下限，必须在同一变更中同步调整 `engines.node`、兼容性矩阵和本 Agent Note（agent 决策记录）。
+
+## 曾考虑的替代方案
+
+- **保持 `^22.18.0 || >=24.0.0`。** 否决：它宣传的 LTS 版本低于 Pi 适配器依赖的下限。`@earendil-works/pi-ai@0.79.3` 要求 `>=22.19.0`。
+- **降级或固定 `@earendil-works/pi-ai` 以保留 22.18 的宣传范围。** 否决：当前 Pi 适配器依赖是预期工作区的一部分，且 22.19 仍在 Node 22 LTS 线内。
+- **下限 `>=22.13`（`node:sqlite` 边界）加上在 22.13–22.17 的 built-bin 冒烟测试中使用 `--experimental-strip-types`。** 否决：它为一个狭窄范围增加了版本条件测试标志，并将实验性标志依赖包装为正式支持。Pi 适配器依赖已经要求更高的 LTS 下限。
+- **开放式 `>=22.19`。** 否决：它宣传支持 Node 23.0–23.5，而在这些版本上 `node:sqlite`（直到 23.4）或类型剥离（直到 23.6）仍需标志。
+- **包含 Node 23.6+（`^22.19.0 || >=23.6.0`）。** 否决：23.6+ 确实能无标志运行两个源码特性，但 Node 23 已 end-of-life；宣传一条已终止的发布线会增加一个范围项和一条 CI 分支，而没有任何部署应当使用该运行时。
+- **矩阵 `[22, 24, 26]` 而非固定 `22.19`。** 否决：浮动的主版本号条目会随时间上漂，悄然不再验证所声明的 LTS 下限。
+- **保持 `@types/node` 超前于运行时下限（`^25`）。** 否决：类型定义超前于运行时下限会让仅 Node 24/25 才有的 API 编译通过，仅在 22.x 上运行时才失败。将 `@types/node` 固定在 22.x 线上可将此类问题转化为所有环境下的编译错误。
diff --git a/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.i18n.yaml
new file mode 100644
index 0000000000..9aa8a03c52
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-06-parallel-github-ci-gates.md: 5c276f6a75936021369bc5ad9494c9aa6e4e3fc3
+2026-07-06-parallel-github-ci-gates.zh.md: 7d98f842ef1d60a3a5b727f975cb1d93ea6f253c
diff --git a/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.md b/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.md
index fef5852153..5c276f6a75 100644
--- a/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.md
+++ b/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-parallel-github-ci-gates.zh.md)
+
 ## Problem
 
 The keyless GitHub CI gates are mostly orthogonal: typecheck, lint, documentation freshness, coverage, snapshot replay, build, package-publication hygiene, demo smoke, and built-bin smoke fail for different reasons and do not need each other's runtime state. Running them as one ordered command chain makes the workflow wall clock equal the sum of those gates, while splitting every short leaf into its own GitHub job repeats checkout, Node setup, pnpm restore, and install work until orchestration overhead becomes the bottleneck.
diff --git a/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.zh.md b/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.zh.md
new file mode 100644
index 0000000000..7d98f842ef
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.zh.md
@@ -0,0 +1,50 @@
+# Agent Note: 并行 GitHub CI 门禁
+
+Status: implemented
+
+[English](2026-07-06-parallel-github-ci-gates.md) | 中文
+
+## 问题
+
+无密钥 GitHub CI 门禁大多相互正交：类型检查、lint、文档新鲜度、覆盖率、快照重放、构建、包（package）的发布卫生检查、demo 冒烟和已构建二进制冒烟会因不同原因失败，也不需要彼此的运行时状态。将它们作为一条有序命令链运行，会使工作流墙钟时间等于所有门禁耗时之和；而把每个短小叶子拆成独立 GitHub job，又会反复执行 checkout、Node 设置、pnpm 恢复和安装，直到编排开销成为瓶颈。
+
+随着 workspace 增长，原有的宽车道拆分不再满足这一平衡。PR（Pull Request）#404 合并时，Linux 的静态、覆盖率、快照和产物 job 分别耗时 148、195、94 和 230 秒；Windows 的静态和产物 job 分别耗时 251 和 482 秒。每个包都调用一次包管理器打包，主导了两个产物验证器的耗时；覆盖率在仅运行源码的套件前无谓地重建输出；CPU 密集型门禁则在静态与覆盖率车道内争用资源。
+
+产物边界仍然承载关键约束。`publint`、`verify-node-next-types`、已编译不变量加载和已构建二进制冒烟测试都需要生成的 `lib/` 输出。分片不能让这些消费方抢在构建前运行，也不能用源码执行取代它们对已发布产物的信号。
+
+## 决策
+
+下述生产拓扑已经成为历史，并由[基于证据采用更大的托管 runner](2026-07-22-evidence-based-larger-hosted-runners.md) 取代。更大 runner 的决策移除了其分片选择器和工作流 job；本文保留早期拓扑为何被实现的记录。
+
+[CI](../../../../.github/workflows/ci.yml) 将非 Windows job 的一分钟和 Windows job 的三分钟视为观测所得的性能目标，而非取消截止时间。托管 runner 的波动应留下完整计时证据和有用的失败日志，而不是取消本来正确的门禁。[串行跨平台 CI 参考](2026-07-21-serial-cross-platform-ci-reference.md)会在 Linux、macOS 和 Windows 上独立运行完整、未分片的主 Node 聚合，使优化后的车道清单不会成为自身完整性的唯一判据。
+
+在该拓扑中，[scripts/run-gates.ts](../../../../scripts/run-gates.ts) 是通用的有界调度器，GitHub 则为昂贵的门禁族提供显式分片名称。`scripts/static-shards.ts` 将静态门禁划分为基础、文档类型、API 契约、目录、正文、文档投影和文档构建等归属，并拒绝缺失或重复的门禁分配。Linux lint 使用互不重叠的 A-C、D-M、N-S、T-Z 包源码和包测试车道，Windows 则使用完整的包源码与包测试车道；两者都包含从 `.` 开始的仓库补集，使新增顶层目标无法消失在分片之间，并负责唯一一次跨文件重复检查。`scripts/coverage-shards.ts` 把每个 workspace 包恰好分配给一个源码覆盖率车道。目录过滤器保留尾部分隔符，因为 Vitest 位置过滤器按子字符串匹配，否则会纳入具有同名前缀的相邻项。每个覆盖率车道只包含其拥有的源码文件，重复运行穷尽式伴随拓扑测试，并且不先执行构建，因为从删除了所有生成式 `lib/` 的树开始，完整覆盖率套件仍可通过。
+
+快照重放使用两个显式多文件车道，以及大型 ACP（Agent Client Protocol）文件的八个场景分区。`scripts/snapshot-shards.ts` 拥有该清单，其测试会发现快照配置允许的每个文件。每个快照 job 在其 Linux runner 准备 Bubblewrap 的同时安装依赖，随后构建已发布运行时，并且只运行分配给它的重放表面。该套件保留五个子进程的有界并发，因为重放的大部分时间都在等待子进程协议 I/O。fixture（测试前置数据）守卫仍会在每个分区中检查完整 ACP 场景表。
+
+冷启动的独立文档类型检查会重建完整的项目引用图，因此专用文档类型车道只构建一次，再用这些声明检查 Markdown 块。Linux 文档车道使用 VitePress 的 MPA 构建，在观测所得的非 Windows 目标内保留页面渲染与死链接验证；单独的阻塞式 Windows 构建和生产站点车道保留已生成包与已发布站点检查，同时避免把两条关键路径放进同一个 job。
+
+产物使用两个车道：一个元数据车道负责 `publint`、NodeNext 声明和已编译不变量加载，另一个负责已构建二进制冒烟。每个车道都会在其消费方之前自行构建。重复短时构建会消耗 runner 分钟数，但避免了上传/下载依赖，并使每个 job 的关键路径保持有界。
+
+[scripts/publint-all.ts](../../../../scripts/publint-all.ts) 在进程内针对内存发布视图调用 publint 支持的 API；该视图由每份清单声明的文件和 npm 强制元数据文件构成。这样无需生成 103 次包管理器打包命令，也能保留 workspace 文件与已发布文件之间的区别。[scripts/verify-built-package-invariants.mjs](../../../../scripts/verify-built-package-invariants.mjs) 在真实包下暂存这些经过结构验证、由清单声明的 `lib/` 文件，再通过纯 Node 和 Cordis Loader 规范化导入已编译的自引用。若伴随项触及未声明的运行时分片，仍会失败。
+
+兼容性车道会在每条声明支持的 Node 版本线上运行源码 worker 和 Zstandard 运行时冒烟。TypeScript 在专用的主 Node 24 车道中只检查一次源码图；在运行时兼容性 job 中重复同一编译器分析只会增加耗时，不会提供运行时特有信号。
+
+工作流缓存 pnpm store，将每个不可变 ESLint 缓存的键绑定到其所属 lint 分片，为 Windows 测量保留原生 PowerShell，并保留一个聚合的 `all checks passed` 状态用于分支保护。Windows 复用三个穷尽式 lint 分区，并在共享 runner 设置后组合基础/目录/正文门禁与文档类型/API 契约门禁；只有调度方式与 Linux 分区不同。Windows 构建和生产站点验证继续阻塞，而更广泛的 Windows 静态、lint 和产物矩阵仍为观察性检查。
+
+## 曾考虑的替代方案
+
+- **保留宽车道**：最大限度减少工作流 YAML，但会保留观测到的数分钟反馈周期。
+- **让每个叶子门禁分别成为 GitHub job**：最大化扇出，但短小的生成器和正文检查准备 runner 的时间会超过检查仓库的时间。
+- **向产物消费方上传一次构建**：避免重复编译，但上传/下载和依赖调度会延长墙钟时间；干净构建足够短，可以在有界车道内重复。
+- **在两个发布门禁中保留包管理器打包**：把清单选择委托给 pnpm，但会重复启动 200 多个包管理器进程。清单结构门禁加发布视图 fixture 使优化后的清单契约显式化，并会在存在磁盘上有但未发布的依赖时失败。
+- **在覆盖率前保留构建**：提供源码套件已不再消费的生成输出；干净树覆盖率证明表明这只是纯粹的延迟。
+- **在每个 Node 版本上执行类型检查**：重复编译器工作，而兼容性冒烟已经验证实际的 Node 特有加载与压缩行为。
+
+## 后果
+
+上述分片清单和矩阵 job 不属于当前仓库契约。取而代之的更大 runner 决策在单个进程中保留完整主清单，并以串行套件作为独立完整性判据。
+
+优化后的发布验证器依赖由 `verify-package-invariants` 强制执行的清单 `files` 契约。如果发布规则超出该契约，结构门禁和两个暂存视图必须一起变化。
+
+兼容性 job 不再声称 TypeScript 本身已在每个 Node 运行时下执行。它们证明 Node 22、24 和 26 上对运行时敏感的源码加载，而主运行时负责唯一一次源码图类型检查。
diff --git a/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.i18n.yaml
new file mode 100644
index 0000000000..0360eacf60
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-06-parallel-pre-push-gates.md: f2e8f0054e595be20a320ec7095f0fe674eb93c6
+2026-07-06-parallel-pre-push-gates.zh.md: 03b8773e475a9d1c82cea830cae6806a1c016f01
diff --git a/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.md b/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.md
index 87b1c0847b..f2e8f0054e 100644
--- a/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.md
+++ b/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-parallel-pre-push-gates.zh.md)
+
 The local-hook portion of this record is superseded by [Fast local Git hooks](2026-07-22-fast-local-git-hooks.md). The bounded gate scheduler and package-level `publint` parallelism remain in force for CI, `doc-sync`, and explicit local commands.
 
 ## Problem
diff --git a/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.zh.md b/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.zh.md
new file mode 100644
index 0000000000..03b8773e47
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 并行 pre-push 门禁
+
+Status: implemented
+
+[English](2026-07-06-parallel-pre-push-gates.md) | 中文
+
+本记录中的本地 hook 部分已由[快速本地 Git hook](2026-07-22-fast-local-git-hooks.md) 取代。有界门禁调度器和包（package）级 `publint` 并行机制仍用于 CI、`doc-sync` 和显式本地命令。
+
+## 问题
+
+文档同步等聚合 job 隐藏了很长的串行链，其成员只读且相互独立。在工作流 YAML 中重复这些叶子清单，会使未来脚本变更有多个位置可以发生漂移；而串行运行包发布检查，会使一道门禁的耗时与包数量成正比。
+
+## 决策
+
+[scripts/run-gates.ts](../../../../scripts/run-gates.ts) 拥有 CI、`doc-sync` 和选择启用的 `check:all` 命令所使用的有界调度器。它将具名模式展开为叶子门禁，遵守产物依赖，缓冲可归因的输出，并在调用方需要不同 worker 上限时接受 `DSH_GATE_CONCURRENCY`。
+
+[scripts/publint-all.ts](../../../../scripts/publint-all.ts) 从 `packages/<group>/<pkg>` 发现包，并以根据 `availableParallelism()` 确定大小的 worker 池运行 `publint`。`DSH_PUBLINT_CONCURRENCY` 可以针对资源配置不同的本地机器和 CI runner 限制或提高 worker 数量。结果按包缓冲，并按确定性的包顺序打印，因此并行执行不会打乱各包的日志块。
+
+各门禁的包脚本仍是临时本地运行所用的词汇。`hygiene` 继续作为聚合 `&&` 链，而 `doc-sync` 在调度器中拥有其成员列表（[通过门禁调度器运行 doc-sync](2026-07-21-doc-sync-through-gate-scheduler.md)）。
+
+## 曾考虑的替代方案
+
+- **保持聚合 job 串行**：执行更简单，但墙钟时间等于各独立检查之和，并重复启动命令包装器。
+- **每个叶子门禁声明一个 CI job**：暴露最大工作流并行度，但会重复 checkout、设置和安装开销，并在 YAML 中复制调度器清单。
+- **在 shell 脚本内后台运行子命令**：可以并行处理，但会失去各门禁计时、确定性的失败分组和直接的信号处理。
+- **每个包声明一个 `publint` job**：暴露最大包级并行度，但会创建手工维护的包清单，包发生变化时就会漂移。
+- **以无界并发运行 `publint`**：只有通过拿进程数、内存压力、包 tarball 创建和可读日志冒险，才能最大限度缩短小型仓库的耗时。
+
+## 后果
+
+由调度器支持的命令耗时取最慢依赖链，而非各独立门禁之和，并会报告主导耗时的门禁。代价是维护一个具有显式模式清单的定制调度器。
+
+`publint-all.ts` 采用异步执行并缓冲命令输出，而不是实时继承 stdio。换来的是具有稳定输出顺序的包级并行，以及用于资源调节的单一环境变量。
diff --git a/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.i18n.yaml
new file mode 100644
index 0000000000..f24a929889
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-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
+2026-07-10-readme-known-limitations-gate.md: 2ca1168d795692730d17b6ab23dd113e8be277e5
+2026-07-10-readme-known-limitations-gate.zh.md: 4e42492f501cca1a45a90694acea4ca78e920780
diff --git a/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.md b/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.md
index 0d294feb0f..2ca1168d79 100644
--- a/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.md
+++ b/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-10-readme-known-limitations-gate.zh.md)
+
 ## Problem
 
 The [documentation standard](../../../../docs/AGENTS.md) assigns limitations to package READMEs. Without a shared shape, an omitted section cannot distinguish an audited absence from forgotten documentation, and variant headings prevent a repository-wide search.
diff --git a/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.zh.md b/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.zh.md
new file mode 100644
index 0000000000..4e42492f50
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 每个包（package）README 中受门禁保护的 Known Limitations 章节
+
+Status: implemented
+
+[English](2026-07-10-readme-known-limitations-gate.md) | 中文
+
+## 问题
+
+[文档标准](../../../../docs/AGENTS.md)规定限制项归属包 README。没有共享形状时，缺少章节无法区分“经审计确认没有限制”与“忘记编写文档”，不同的标题还会妨碍全仓库搜索。
+
+## 决策
+
+`packages/<group>/<pkg>/package.json` 下的每份包清单都有一个同级 README，其中包含规范的 `## Known Limitations and Deferred Work` 章节。其项目符号记录由该包拥有的持久消费方缺口和不明显的维护者约束；普通清理仍留在源码 TODO 或所属 Agent Note（agent 决策记录）中。[`verify-package-readme-limitations` 门禁](../../../../scripts/verify-package-readme-limitations.ts)从清单推导包集合，拒绝缺失 README，并要求恰好一个规范 h2 且至少包含一个顶层项目符号。“Limitations”“Deferred”“What is NOT here”或“Non-goals”等近似标题都会失败。
+
+如果一个包确实没有需要声明的限制事项，则将其列入 `NO_LIMITATIONS` 并省略该章节。新增限制事项时须移除该条目；重命名或移除条目会失败，因为每个条目都必须对应一个被扫描的包。
+
+门禁检查存在性、形状和允许列表。按照文档与[正文](../../../skills/dsh-prose-standard/SKILL.md)标准进行的评审负责覆盖面和准确性。常设规则位于 [packages/AGENTS.md](../../../../packages/AGENTS.md)。
+
+## 曾考虑的替代方案
+
+- **自由格式标题**：无法统一搜索，仍需近似标题检测。
+- **要求空章节或写 "None."**：样板文字可能在包新增限制事项后仍然残留；白名单使「确无限制」这一状态显式且可评审。
+- **设置字数上限**：合理的限制事项数量因包而异，因此由评审管控这一不设预算的 README 层级。
+
+## 后果
+
+- 新建的包须声明符合条件的限制事项，或显式加入白名单；缺失、漂移或空的章节会在本地和 CI 的 `doc-sync` 中失败。
+- 门禁为 `doc-sync` 新增一个无外部依赖的 TypeScript 脚本。
+- 重命名受强制的标题需要同时修改脚本和所有包 README。
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
new file mode 100644
index 0000000000..ab312d8bcd
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-12-package-model-experience-contract.md: 92a8e5a1a81d00dae085e4af89456896373058e6
+2026-07-12-package-model-experience-contract.zh.md: 54b181738b8276c634f777ad3424191c8652baec
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
index dd986f3661..92a8e5a1a8 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-12-package-model-experience-contract.zh.md)
+
 ## Problem
 
 A package README can explain APIs and runtime mechanics without answering the questions that dominate an agent harness's behavior and cost: what from this package reaches a model request, under which conditions, how long those tokens remain, and whether later requests preserve a reusable KV-cache prefix. The omission is especially hard to audit in a plugin architecture. A consumer may turn a backend result into a tool message, a policy plugin may replace success with an error, compaction may remove old history, and an agent-scoped registration may change one agent's prompt or schemas while leaving every other agent unchanged. Reading only the nominally model-facing packages therefore misses real context effects, while reading source across every dependency is too expensive for routine review.
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
new file mode 100644
index 0000000000..54b181738b
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 包（package）的模型体验契约
+
+Status: implemented
+
+[English](2026-07-12-package-model-experience-contract.md) | 中文
+
+## 问题
+
+包 README 可以解释 API 和运行时机制，却不回答主导 agent harness（智能体框架）行为与成本的问题：该包的哪些内容会进入模型请求、在什么条件下进入、这些 token 会保留多久，以及后续请求是否会保留可复用的 KV cache 前缀。在插件架构中，这种遗漏尤其难以审计。消费方可能把后端结果转为工具消息，策略插件可能以错误取代成功结果，压缩可能移除旧历史，而 agent 范围的注册可能改变某个 agent 的提示词或 schema，却不影响其他 agent。因此，只阅读名义上面向模型的包会遗漏真实的上下文效应，而在每次常规评审中跨所有依赖阅读源码又成本过高。
+
+## 决策
+
+每个具有面向模型或邻近模型契约的 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`——每个字段都以一个正文段落开头。cache 字段区分仅追加增长、稳定重复前缀、替换先前 token，以及独立模型请求；它点明由包拥有、且能在新内容追加前改变请求的每项配置、范围、生命周期、压缩或路由变化。“Does not invalidate”表示该包保留一个已经可复用的前缀，并非承诺提供方一定命中 cache 或保留某段时间。由包拥有的稳定文本按原文精确引用：系统提示词正文和其他长字面量在引入它们的字段下使用带标题的 H5 加 `markdown` 围栏，通常位于 `What the model sees`；短字面量则以内联形式保留，并点名插值占位符。工具 schema 表面链接生成式[工具目录](../../../../docs/tool-catalog.md)中带锚点的章节，并且只陈述组合或配置增量；仅运行时定义解释目录为何省略它们。依赖数据和由提供方拥有的文本采用摘要。agent 范围的可见性须显式说明；当范围可隐藏提示词与 schema 中的一者而不影响另一者时，两种表面保持分离。
+
+没有模型上下文效应的包，或某条路径完全由另一个包渲染的包，使用验证器审计过的短格式：一句以 `None, as ` 或 `Indirectly, through ` 开头的句子，随后是一个 `KV Cache effect` H4 和一个正文段落。纯传输包和无密钥测试支持包若不创建任何进入模型的内容，就使用 none 格式。提供方后端即使会限制或过滤数据也使用 indirect 格式；具名子项拥有全部效应时，接线 bundle 也使用该格式。这些章节定位贡献并声明不会直接使 cache 失效，同时不重复陈述消费方。结构化章节同样只记录由包拥有的输入、变换和增量。
+
+`verify-package-readme-model-experience` 发现包清单，并验证三种分类、规范末尾章节顺序、确切字段标题深度与顺序、非空字段段落、逐字块的 H5 归属、具体字面量证据，以及带锚点的工具目录链接。它在 `doc-sync` 和并行门禁 runner 中运行。评审仍负责覆盖面、链接相关性和事实准确性。
+
+## 曾考虑的替代方案
+
+- **只记录注册提示词或工具的包**：否决。后端、策略插件、适配器、持久化、作用域和压缩都会改变 token 的内容或生命周期，却不拥有面向模型的 schema。
+- **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的契约；集中副本会增加又一个漂移面。
+- **要求给出精确 token 数**：否决。精确数量取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的契约是增长形状：每请求固定、每调用条件性、保留、替换、有上限或零直接影响。
+- **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
+- **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
+- **要求经审计的零效应包或简单间接包使用完整结构化格式**：否决。它会围绕一个事实重复标签。受门禁约束的句子加 cache 字段既保留显式覆盖，又没有多余仪式。
+- **只有约定而无门禁**：否决。仓库级契约必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
+
+## 后果
+
+评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起的前缀变更。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文表面块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺由提供方给出的精确 token 数或 cache 命中；测量仍取决于具体模型、提供方和工作负载，而所记录的增长、可见性和前缀稳定性契约保持稳定。
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 71ea20f6ee..b21353698c 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
-2026-07-20-gui-testing-system.md: fdd5c7f9d33f9a90ea4afe145265be5fe93e0fc2
-2026-07-20-gui-testing-system.zh.md: 0ae08133742711b87e9155ddc6f3104b757c1b55
+2026-07-20-gui-testing-system.md: e42dafcdf37e48475e7d420eaad9600e6c20891c
+2026-07-20-gui-testing-system.zh.md: e4ef6246e59e0ad6c0a3070a38c546f964e347fa
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 fdd5c7f9d3..e42dafcdf3 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
@@ -19,24 +19,24 @@ Cut along the architecture's natural test seams into three tiers, bottom-up:
 | Tier | Under test | Key technique | File location |
 |---|---|---|---|
 | 1 Protocol isomorphism | `AbstractApiClient` + `toFetchHandler` (bidirectional data / rpcId / zod types / SSE streams / batching / timeouts) | **The full chain at the isomorphic point**: `InProcessApiClient(toFetchHandler(脚本化 impl))` skips the network but genuinely runs the wire serialization — zero browser, pure node env | `packages/host/apiproxy/tests/client-handler.spec.ts` |
-| 2 Object-layer orchestration | `Session`/`SessionManager`/`ConnectionController` (state machines and timing: stitching / dedup / paging / optimistic draft clearing / pendingBuffers / reconnect / backoff) | **The "event sequence in → snapshot out" golden path**: programmable fakes + deferreds controlling timing + fake timers controlling backoff | `packages/client/web-runtime/tests/{session,manager,connection,…}.spec.ts` |
-| 3 Browser smoke | Build artifacts × a real browser (the page boots, one conversation round-trips) | Bare playwright library (chromium headless, no @playwright/test framework), minimal pass-through; fixture level + real-host level (self-skips without a key) | `apps/web/tests/smoke-{fixture,real}.e2e.ts` |
+| 2 Object-layer orchestration | `Session`/`SessionManager`/`ConnectionController` (state machines and timing: stitching / dedup / paging / optimistic draft clearing / pendingBuffers / reconnect / backoff) | **The "event sequence in → snapshot out" golden path**: programmable fakes + deferreds controlling timing + fake timers controlling backoff | `packages/client/{runtime,connection}/tests/` |
+| 3 Assembled presentation | Built artifacts × the real client loader and plugin composition | App-owned semantic snapshots boot all eight built client plugins under jsdom for deterministic cross-plugin state changes; bare Playwright smoke separately proves the real browser/carrier boundary, with real-host cases self-skipping without a key | `apps/web/tests/*.snapshot.ts`, `apps/web/tests/smoke-{fixture,real}.e2e.ts` |
 
-Inter-tier discipline: **each tier tests its own layer, upper tiers never re-test lower ones** — smoke only proves the wiring is alive (the fixture level asserts zero `/api` requests and zero pageerror), interaction detail belongs to the verify scripts (see the lane map), wire semantics to tier 1, data semantics to tier 2. Pure-function layers (lineage/partial/notifier/fold-adapter) are tested directly with zero fakes in the same package's tests/ alongside tier 2.
+Inter-tier discipline: **each tier tests its own layer, upper tiers never re-test lower ones** — an app semantic snapshot pins only user-visible projection across the assembled plugin boundary, while Playwright smoke proves browser and carrier liveness; wire semantics belong to tier 1 and data semantics to tier 2. Pure-function layers (lineage/partial/notifier/fold-adapter) are tested directly with zero fakes in the same package's tests/ alongside tier 2.
 
-- **Host side** (apiproxy/runtime/webserver): under the repo-wide `test:coverage` gate, per-file 100%.
-- **Client side**: web-runtime **is already under the per-file 100% gate** (12 defensive unreachable arms carry reasoned `/* v8 ignore */` comments); the `vitest.config.ts` coverage.exclude is down to `packages/client/web-ui/src/**` (temporary — lifted progressively as component specs fill in after the component redo); tests still run, the exclusion only keeps web-ui src out of the thresholds. web-ui takes the **jsdom route (landed)**: jsdom + @testing-library/react entered root devDependencies (dev-only), first spec `web-ui/tests/utils.spec.tsx` (utils pure functions + component RTL render + hook uSES probe); the environment uses the per-file `// @vitest-environment jsdom` pragma, zero impact on the other node-env packages.
-- The exclusion is an **explicitly annotated ruling**, not a silent waiver; the lift path = delete the exclude line + add a justified exclusion or the missing tests.
+- **Host and client source** are under the repo-wide per-file 100% coverage gate except the narrow browser-grade exclusions annotated in `vitest.config.ts`; component suites use per-file jsdom pragmas and Testing Library without changing Node suites.
+- **App-owned semantic snapshots** read built client bundles, execute them through the real loader, and drive only deterministic fixture hooks. They own stable visible state such as sidebar labels, breadcrumbs, and `document.title`, not CSS pixels or lower-layer state-machine details.
 
 ## Lane map
 
 | Scenario | Command | Content | When to run |
 |---|---|---|---|
 | Baseline | `pnpm run test:gui` | Tier 1+2 vitest (`packages/client packages/host`), seconds-fast, no browser, no server | Casually, after touching any GUI source |
+| Semantic snapshot | `DSH_EXAMPLE_MODE=lib pnpm run test:snapshot` | Keyless assembled-application semantics plus the repo's transport-specific expected outputs | After a human-visible GUI change; before delivery |
 | Browser end-to-end | `pnpm run test:web` | Rebuilds the front-end dist first, then runs the tier-3 two-level smoke (fixture level + real-host level self-skip) | After touching the build surface/boot/carriage; before delivery |
-| Gate | `pnpm run test:coverage` | The repo-wide gate (host-side GUI packages included, client side excluded) | The PR window |
+| Gate | `pnpm run test:coverage` | The repo-wide gate (host and client GUI packages included, except annotated browser-grade exclusions) | The PR window |
 
-**Division of labor between the verify scripts and vitest**: verify owns browser black-box regression (sequential steps = a user-operation script, one shared browser session, streaming PASS/FAIL output for the agent to locate the break), vitest owns first-class data-layer semantic assertions (reference stability `toBe`, state-machine timing, wire shapes). The two lanes complement each other, neither absorbs the other — scripts do not migrate to vitest (tearing apart an ordered script is a net loss); promoting one means wrapping a spawn shell hooked into the e2e lane, never rewriting the script body.
+**Division of labor between the browser scripts and vitest**: Playwright owns browser/carrier black-box regression and long sequential user journeys; ordinary vitest owns data-layer semantics such as reference stability, timing, and wire shapes; snapshot vitest owns stable app-level semantic output through the built composition. These lanes complement each other rather than duplicating assertions.
 
 ## Anti-regression discipline
 
@@ -46,7 +46,7 @@ Inter-tier discipline: **each tier tests its own layer, upper tiers never re-tes
 
 ## Consequences
 
-Each lane tests its own tier: touching any GUI source gets seconds-fast `test:gui` feedback, wire/object-layer semantics assert in milliseconds in node env, and the browser carries only wiring-liveness smoke. On the gate surface, the host side is fully under per-file 100%; on the client side web-runtime is under the gate while web-ui waits behind the explicitly annotated exclude. The accepted cost: the inter-tier discipline (upper tiers never re-test lower ones) is upheld by review rather than a machine gate, and web-ui's coverage gap persists until component specs fill in after the component redo.
+Each lane tests its own tier: touching any GUI source gets seconds-fast `test:gui` feedback, wire/object-layer semantics assert in milliseconds in Node, built-composition snapshots pin deterministic user-visible projection, and the browser carries wiring and carrier acceptance. The accepted cost is that inter-tier discipline is upheld by review rather than a machine gate and every new app snapshot must avoid unstable layout or clock output.
 
 ## Alternatives considered
 
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 0ae0813374..e4ef6246e5 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
@@ -19,24 +19,24 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境
 | 层 | 被测物 | 关键手段 | 文件落点 |
 |---|---|---|---|
 | 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/web-runtime/tests/{session,manager,connection,…}.spec.ts` |
-| 3 浏览器 smoke | 构建产物 × 真浏览器（页面起得来、一轮对话跑得通） | playwright 裸库（chromium headless，无 @playwright/test 框架）最简跑通；fixture 级 + 真 host 级（无 key self-skip） | `apps/web/tests/smoke-{fixture,real}.e2e.ts` |
+| 2 对象层编排 | `Session`/`SessionManager`/`ConnectionController`（状态机与时序：缝合/去重/翻页/乐观清稿/pendingBuffers/重连/退避） | **「事件序列进→快照出」黄金路径**：可编程假体 + deferred 控时序 + fake timers 控退避 | `packages/client/{runtime,connection}/tests/` |
+| 3 组装呈现层 | 构建产物 × 真实 client loader 与插件组合 | 归应用所有的语义快照会在 jsdom 下启动全部 8 个已构建的 client 插件，以固定确定性的跨插件状态变化；独立使用 Playwright 裸库的冒烟测试负责验证真实浏览器/承载层边界，真 host 用例在无密钥时自行跳过 | `apps/web/tests/*.snapshot.ts`、`apps/web/tests/smoke-{fixture,real}.e2e.ts` |
 
-层间纪律：**下层各测各的，上层不重测下层**——smoke 只证接线活着（fixture 级断零 `/api` 请求、零 pageerror），交互细节归 verify 脚本（见车道地图），wire 语义归 1 层，数据语义归 2 层。纯函数层（lineage/partial/notifier/fold-adapter）随 2 层同包 tests/ 零假体直测。
+层间纪律：**下层各测各的，上层不重测下层**：应用语义快照只固定组装后插件边界上的用户可见投影，Playwright 冒烟测试负责验证浏览器与承载层是否存活；wire 语义归 1 层，数据语义归 2 层。纯函数层（lineage/partial/notifier/fold-adapter）随 2 层同包 tests/ 零假体直测。
 
-- **host 侧**（apiproxy/runtime/webserver）：进全仓 `test:coverage` 门禁，per-file 100%。
-- **client 侧**：web-runtime **已进 per-file 100% 门禁**（12 处防御性不可达臂带理由 `/* v8 ignore */` 注释）；`vitest.config.ts` coverage.exclude 只剩 `packages/client/web-ui/src/**`（暂时——组件重做后随组件 specs 铺满逐步解除），测试照跑，只是不拉 web-ui src 进阈值。web-ui 走 **jsdom 路线（已落地）**：jsdom + @testing-library/react 入 root devDeps（dev-only），首个 spec `web-ui/tests/utils.spec.tsx`（utils 纯函数 + 组件 RTL render + hook uSES 探针）；环境用 per-file `// @vitest-environment jsdom` pragma，node env 的其他包零影响。
-- 排除是**显式注释的裁决**不是静默豁免；解除路径=删 exclude 行 + 补 justified 排除或补测。
+- **host 与 client 源码**均纳入全仓 per-file 100% 覆盖率门禁，仅排除 `vitest.config.ts` 中带注释的少量浏览器级例外；组件套件通过逐文件 jsdom pragma 和 Testing Library 运行，不会改变 Node 套件。
+- **归应用所有的语义快照**读取已构建的 client bundle，通过真实 loader 执行它们，并且只驱动确定性的 fixture 钩子。它们负责固定侧边栏标签、面包屑和 `document.title` 等稳定可见状态，而不固定 CSS 像素或下层状态机细节。
 
 ## 车道地图
 
 | 场景 | 命令 | 内容 | 何时跑 |
 |---|---|---|---|
 | 基础 | `pnpm run test:gui` | 1+2 层 vitest（`packages/client packages/host`），秒级、无浏览器无 server | 改 GUI 任意源码后随手跑 |
+| 语义快照 | `DSH_EXAMPLE_MODE=lib pnpm run test:snapshot` | 无需密钥的组装应用语义，以及仓库按传输形态划分的预期输出 | 用户可见的 GUI 变更后；交付前 |
 | 浏览器端到端 | `pnpm run test:web` | 先重建前端 dist，再跑 3 层双级 smoke（fixture 级 + 真 host 级 self-skip） | 改构建面/boot/承载后；交付前 |
-| 门禁 | `pnpm run test:coverage` | 全仓 gate（host 侧 GUI 包在内，client 侧 excluded） | PR 窗口 |
+| 门禁 | `pnpm run test:coverage` | 全仓 gate（host 与 client GUI 包均纳入，仅排除带注释的浏览器级例外） | PR 窗口 |
 
-**verify 脚本与 vitest 的分工**：verify 管浏览器黑盒回归（顺序步骤=用户操作剧本，共享一次浏览器会话，PASS/FAIL 流式输出供 agent 定位断点），vitest 管数据层语义一等断言（引用稳定性 `toBe`、状态机时序、wire 形）。两车道互补不收编——脚本不迁 vitest（拆散有序剧本是负收益），转正时包一层 spawn 壳挂 e2e 车道即可，脚本本体不改写。
+**浏览器脚本与 vitest 的分工**：Playwright 负责浏览器/承载层黑盒回归和较长的连续用户操作流程；普通 vitest 负责引用稳定性、时序和 wire 结构等数据层语义；快照 vitest 通过构建后的组合负责稳定的应用层语义输出。这些车道彼此互补，而不重复断言。
 
 ## 防回归纪律
 
@@ -46,7 +46,7 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境
 
 ## Consequences
 
-各车道各测各层：改任意 GUI 源码有秒级 `test:gui` 反馈，wire/对象层语义在 node env 毫秒级断言，浏览器只承担接线存活冒烟。门禁面上 host 侧全量进 per-file 100%；client 侧 web-runtime 已进门，web-ui 暂留显式注释的 exclude 之后。接受的代价：层间纪律（上层不重测下层）靠 review 而非机器门禁维持；web-ui 的覆盖缺口持续到组件重做后组件 specs 铺满为止。
+各车道各测各层：改动任意 GUI 源码后都能获得秒级 `test:gui` 反馈，wire/对象层语义在 Node 环境中进行毫秒级断言，基于构建后组合的快照固定确定性的用户可见投影，浏览器负责接线与承载层验收。接受的代价是层间纪律由评审而非机器门禁维持，而且每个新的应用快照都必须避开不稳定的布局或时钟输出。
 
 ## Alternatives considered
 
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 aa0516648b..1a6a99d648 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
-2026-07-21-serial-cross-platform-ci-reference.md: b795a0aff62c20967d2c85429c0c6115c1b9585d
-2026-07-21-serial-cross-platform-ci-reference.zh.md: 223fd9cf20a1d8228cb0c6b1b2f3f95644becae6
+2026-07-21-serial-cross-platform-ci-reference.md: 3c0ae200d7dbd5b04eae6db2d6628dccc72103bf
+2026-07-21-serial-cross-platform-ci-reference.zh.md: 5c159e12739d68e0baed72aaa08331072e2c3601
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 b795a0aff6..3c0ae200d7 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
@@ -18,6 +18,10 @@ Reviewers also need a direct answer to a simpler question: what happens when the
 
 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 three operating-system 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.
 
+Platform ownership remains explicit inside that complete aggregate. `pty-local` supports Linux and macOS and therefore owns its unit and per-file coverage contract on POSIX rather than loading a backend that rejects `win32`; the Windows run still executes every portable package. Portable fixtures derive native paths through `node:path`, compare canonical identities with the same native realpath implementation as production, and use filenames legal on every host. ACP snapshot runs also pass both JavaScript and native realpath spellings of their generated cwd to the normalizer, which replaces aliases longest-first so Windows short and long paths cannot churn shared fixtures.
+
+The macOS reference runs the ordinary Vitest project in forked processes. Node 24 on macOS arm64 has aborted in its CJS lexer from a worker thread; the process boundary contains that external runtime failure without removing any test from the aggregate, while Linux and Windows retain the lower-overhead thread pool. Repository-owned races are fixed at their observation boundaries: dev bundle polling stages each candidate table, graph, and watch-baseline map before publishing a rescan, and a missing bundle remains dirty until a successful content hash. PTY readiness retains a prompt candidate while polling checks foreground ownership; the ordinary silence bound covers inherited markers from interactive children. The live-link package-manager e2e preserves the workflow-prepared Corepack home and pnpm metadata/store caches while isolating the other managers' mutable caches, so it does not discard reusable package-manager state before the install.
+
 Master reference jobs are diagnostic and do not participate in the pull request's required `all checks passed` result. A pull request runs only its required jobs; a master push runs only the three serial references. 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. Required pull-request jobs use the same portable Linux and Windows 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.
@@ -36,4 +40,6 @@ The workflow contains duplicated setup steps and a master reference run can take
 
 The reference may expose platform failures that the optimized blocking set does not yet claim to support, especially on Windows. Such a failure is evidence about current cross-platform behavior rather than a reason to weaken or silently skip the aggregate.
 
+The explicit `pty-local` ownership boundary means Windows does not claim coverage for a backend it cannot load, and forked macOS unit workers cost more process startup time. In return, every supported surface has an honest platform oracle, a native runtime abort cannot erase the rest of the unit result, and timing-sensitive observers start from state established before callers can mutate it.
+
 Removing strict duration timeouts means a latency regression is observed rather than automatically cancelled. Hosted measurements must therefore accompany performance changes, while the completed logs retain the information needed to optimize the slow lane.
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 223fd9cf20..5c159e1273 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
@@ -18,6 +18,10 @@ Status: implemented
 
 每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的并发数也设为 1。三种操作系统的作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。
 
+该完整聚合流程仍明确划分平台归属。`pty-local` 支持 Linux 与 macOS，因此其单元测试和逐文件覆盖率契约由 POSIX 平台负责，而不会在 Windows 上加载一个明确拒绝 `win32` 的后端；Windows 仍会执行所有可移植包（package）。可移植 fixture（测试前置数据）通过 `node:path` 派生原生路径，使用与生产代码相同的原生 realpath 实现比较规范化后的路径标识，并采用所有宿主机均允许的文件名。ACP（Agent Client Protocol）快照运行还会把生成的 cwd 分别通过 realpath 的 JavaScript 实现与原生实现得到的两种表示一并传给规范化器；规范化器按长度从长到短替换这些别名，避免 Windows 的短路径与长路径表示差异导致共享 fixture 反复变化。
+
+macOS 参考流程使用 fork 进程运行常规 Vitest 项目。macOS arm64 上的 Node 24 曾在工作线程中执行 CJS 词法分析器时异常终止；进程边界能够隔离这一外部运行时故障，且无需从聚合流程中删除任何测试，而 Linux 与 Windows 仍使用开销更低的线程池。仓库自身引入的竞态均在相应的观测边界修复：开发构建产物的轮询逻辑每次发布重新扫描结果前，都会先暂存候选表、候选图和候选监视基线映射；构建产物缺失后会一直保持脏状态，直到成功计算内容哈希。PTY 就绪检测会在轮询检查前台进程组归属期间保留提示符候选项；常规静默时限也适用于交互式子进程继承提示符标记的情况。实时链接场景下的包管理器 e2e 会保留由工作流预先准备的 Corepack 主目录、pnpm 元数据缓存和 store 缓存，同时隔离其他包管理器的可变缓存，因此不会在安装前丢弃可复用的包管理器状态。
+
 master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 `all checks passed` 结果。拉取请求只运行其必需作业；向 master 推送时只运行三个串行参考作业。系统根据已完成托管作业的时间戳评估性能，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。
 
 可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用相同的可移植 Linux 和 Windows 容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
@@ -36,4 +40,6 @@ master 分支的参考作业仅用于诊断，不参与拉取请求所要求的
 
 参考流程可能暴露某些平台上的故障，而优化后的阻塞门禁集合尚未声明支持这些平台，Windows 尤其如此。这类失败反映了当前的跨平台行为，不应成为削弱或静默跳过该聚合流程的理由。
 
+明确的 `pty-local` 归属边界意味着 Windows 不会声称覆盖一个无法加载的后端，而 macOS 采用 fork 的单元测试工作进程会增加进程启动开销。这些代价换来的是：支持范围内的每项功能都有能够如实反映对应平台行为的判据，原生运行时异常终止不会抹掉其余单元测试结果，各项对时序敏感的观测逻辑也都会以调用方有机会修改状态前已建立的状态作为起点。
+
 移除严格的时长超时后，系统会观测到延迟回归，而不是在发生回归时自动取消运行。因此，性能改动必须附带托管环境测量结果，已完成的日志则保留优化最慢通道所需的信息。
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 6dcafc39dd..9d87cb9ad3 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
-2026-07-22-evidence-based-larger-hosted-runners.md: c292a4ea49320d684c35d2b9986549d693efb914
-2026-07-22-evidence-based-larger-hosted-runners.zh.md: 5e59c787a85bd2093f0c3ceaa8290e7cd42528fa
+2026-07-22-evidence-based-larger-hosted-runners.md: aaeab4ed9ae9687598f9f1d4a862120405697672
+2026-07-22-evidence-based-larger-hosted-runners.zh.md: 72b69c85908990a9f35b60f4c0a2ce213f9c8134
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 c292a4ea49..aaeab4ed9a 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
@@ -12,12 +12,16 @@ Larger runners make it possible to pay setup once and parallelize inside the rep
 
 ## Decision
 
-The organization keeps twelve x64 larger-runner pools in the repo-restricted `dsh-larger-ci` group: Ubuntu 24.04 and Windows 2025 at 4, 8, 16, 32, 64, and 96 cores. Public IPs are disabled. Each pool has an autoscaling ceiling of 256; the ceiling does not allocate idle machines or remove the need to bound workflow demand.
+The enterprise keeps repo-restricted x64 larger-runner pools for Ubuntu and Windows. Ordinary pull requests name three 32-core pools directly: Ubuntu 24.04 for exhaustive coverage, Ubuntu latest for the remaining primary Node 24 inventory, and Windows 2025 for blocking Windows contracts. Public IPs are disabled, and workflow concurrency remains bounded because an autoscaling ceiling neither allocates idle machines nor makes repository work scale without limit.
 
-The pools are measurement infrastructure, not a dependency of ordinary pull requests. The [portable required-CI decision](2026-07-23-portable-required-pull-request-ci.md) runs branch-protection jobs on standard GitHub-hosted capacity; `suite=larger-runner-benchmark` compares isolated critical lanes across every provisioned size, and `suite=consolidated-runner-benchmark` compares whole aggregates. Each benchmark reports its observed processor and memory capacity before running repository work.
+The required primary path depends on those enterprise pools. Standard GitHub-hosted jobs retain the Node 22.19, Node 26, and Python SDK compatibility contracts, while the [portable recovery boundary](2026-07-23-portable-required-pull-request-ci.md) and [serial reference](2026-07-21-serial-cross-platform-ci-reference.md) keep complete standard-runner evidence available on `master`. `suite=larger-runner-benchmark` compares isolated critical lanes across provisioned sizes, and `suite=consolidated-runner-benchmark` compares whole aggregates. Each benchmark reports its observed processor and memory capacity before running repository work.
 
 The former gate-level and coarse primary shard jobs are absent from the workflow. Their static, lint, coverage, snapshot, and scenario shard selectors are also absent from the repository, so an unused diagnostic path cannot preserve a second CI architecture.
 
+Linux primary work uses three independent 32-core jobs. Coverage runs alone with its own worker bound, and the static scheduler runs alone so its result has no post-build consumer tail. After static gates finish, that job publishes its emitted `apps/*/lib`, `packages/*/*/lib`, and `vendor/*/lib` tree as a run-scoped artifact. The third job restores that exact tree, then starts lint, Node 24 runtime compatibility, build-backed snapshots, and all artifact consumers without repeating the build. Generated NodeNext consumer directories are excluded from ESLint discovery because the artifact check removes them while these processes overlap. The pnpm store and ESLint cache are restored without putting cache uploads on the pull-request critical path. Performance reports use each job's `startedAt` to `completedAt` interval; runner queue delay is capacity evidence, not repository execution time.
+
+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:
 
 | Complete Linux primary | 4 cores | 8 cores | 16 cores | 32 cores | 64 cores | 96 cores |
@@ -42,7 +46,7 @@ Inner and outer worker limits are separate controls. An [exact-head 32-worker ES
 
 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.
 
-Complete serial Linux, macOS, and Windows references run only when `master` moves. Pull requests use the portable required path, while larger-runner suites run only by manual dispatch.
+Complete serial Linux, macOS, and Windows references run only when `master` moves. Pull requests use the enterprise required path plus standard-hosted compatibility jobs, while other larger-runner sizes run only by manual dispatch.
 
 ## Alternatives considered
 
@@ -54,7 +58,9 @@ Complete serial Linux, macOS, and Windows references run only when `master` move
 
 **Keep build behind typecheck.** This orders independent compiler invocations and turns snapshot replay into a three-stage critical chain. Build output has its own success dependency, so only snapshot and publication consumers wait for it.
 
-**Make larger-runner pools the required default.** This offers lower measured latency when allocation works, but a missing entitlement or delayed organization transfer leaves required jobs queued without repository diagnostics. The portable path accepts longer runtime, and manual suites preserve the performance experiment.
+**Keep static gates and post-build consumers on one runner.** Reusing one workspace avoids a setup wave and artifact transfer, but build-duration variance delays every consumer and leaves their lint and snapshot tails after the static result. A run-scoped built tree preserves one exact build while independent jobs keep both complete paths within the observed target.
+
+**Keep the complete required path on standard GitHub-hosted capacity.** This avoids repository-external runner configuration, but exact-head standard-runner runs remain materially slower and can spend longer queued behind shared capacity. Standard-hosted compatibility and serial references preserve portable evidence without making that slower topology the ordinary primary path.
 
 **Keep required and observational Windows checks in separate jobs.** The split preserves status semantics at the workflow level but pays setup twice. `run-gates` preserves the same required versus non-blocking distinction inside one process.
 
@@ -62,10 +68,10 @@ Complete serial Linux, macOS, and Windows references run only when `master` move
 
 ## Consequences
 
-The benchmark topology pays one setup wave per measured aggregate and retains no shard selectors. It runs paid larger-runner executions only when manually dispatched instead of charging every pull request.
+The required topology pays one setup wave per 32-core lane and retains no shard selectors. Every ordinary pull request consumes paid enterprise Linux and Windows minutes; manual benchmarks add other sizes only when remeasurement is useful.
 
-GitHub rounds each larger-runner execution up to a whole minute, so whole-aggregate measurement exposes both billed time and workflow complexity without making that cost part of branch protection.
+GitHub rounds each larger-runner execution up to a whole minute, so complete-job measurement exposes both billed time and workflow complexity. Splitting Linux repeats setup twice and transfers one built tree, but isolates coverage, static gates, and post-build consumers from each other's critical paths without repeating the build; consolidating Windows avoids repeating its slower setup.
 
 Performance targets are observations, not cancellation deadlines or correctness requirements. Manual all-size and serial suites remain available when image, dependency, scheduler, or pricing changes need remeasurement.
 
-Missing or renamed organization-owned labels leave only manual benchmark jobs queued. All twelve pools remain defined so the benchmark can compare sizes after allocation recovers, while required CI follows the standard-runner fallback.
+Missing or renamed enterprise labels leave required primary jobs queued. Standard-hosted compatibility jobs and `master` references still report useful evidence, but they do not substitute for the required aggregate; runner assignment is therefore an operational dependency that repository CI cannot repair.
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 5e59c787a8..72b69c8590 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,12 +12,16 @@ Status: implemented
 
 ## 决策
 
-组织在仅限本仓库使用的 `dsh-larger-ci` 运行器组中保留 12 个 x64 大型运行器池：Ubuntu 24.04 和 Windows 2025 各设 4、8、16、32、64、96 核规格。公网 IP 已禁用。每个池的自动扩缩容上限为 256；该上限既不会分配闲置机器，也不能免除限制工作流需求的必要性。
+企业保留仅限本仓库使用的 Ubuntu 和 Windows x64 大型运行器池。普通拉取请求直接指定 3 个 32 核运行器池：Ubuntu 24.04 用于完整覆盖率，Ubuntu latest 用于其余主 Node 24 清单，Windows 2025 用于阻塞性 Windows 契约。公网 IP 已禁用；工作流并发仍设有边界，因为自动扩缩容上限既不会分配闲置机器，也不意味着仓库工作可以无限扩展。
 
-这些运行器池是测量基础设施，不是普通拉取请求的依赖。依据[可移植必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，分支保护作业在 GitHub 标准托管容量上运行；`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 架构。
 
+Linux 主流程使用 3 个相互独立的 32 核作业。覆盖率单独运行，并设有自己的工作线程上限；静态调度器也单独运行，因此构建后的消费方不会拖延其结果。静态门禁完成后，该作业将其生成的 `apps/*/lib`、`packages/*/*/lib` 和 `vendor/*/lib` 目录树作为仅供本次运行使用的产物发布。第三个作业恢复完全相同的目录树，再让 lint、Node 24 运行时兼容性、依赖构建产物的快照和所有产物消费方基于构建完成后的工作树启动，而不重复构建。生成的 NodeNext 消费方目录不会纳入 ESLint 的文件发现范围，因为这些进程重叠执行时，产物检查会删除这些目录。pnpm store 和 ESLint 缓存会得到恢复，但缓存上传不会进入拉取请求关键路径。性能报告采用每个作业从 `startedAt` 到 `completedAt` 的区间；运行器排队延迟是容量证据，而非仓库执行时间。
+
+Windows 以一次 32 核环境设置同时承载阻塞性构建、生产网站和观测性的构建产物契约。重复的 lint、覆盖率和快照清单由 Linux 承担，因为在 Windows 上运行这些观测性副本会延长付费关键路径，却不会新增任何阻塞性平台契约。
+
 一次[分支头精确的全规格基准测试](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29908491351)在修正构建尽早启动逻辑前，对每种 Linux 池都运行了完整且未分片的主 Node 聚合流程：
 
 | Linux 完整主流程 | 4 核 | 8 核 | 16 核 | 32 核 | 64 核 | 96 核 |
@@ -42,7 +46,7 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完
 
 进程约束的覆盖率项目恰好包含 5 个套件文件。32 个 fork 曾两次导致 Node 24 的 CJS 词法分析器崩溃，后来一次使用 16 个 fork 的运行又复现了工作进程丢失和无效的覆盖率结果。因此，单次 Vitest 调用会对大范围测试清单使用线程，只为涉及进程全局状态、`process` API 或对时间敏感的进程 I/O 的套件保留 fork。这份有限的 fork 清单包括本地 bash 进程通路套件和 pi-ai 适配器套件，因为聚合争用改变了二者的时序观测结果。这些故障表明，选择工作线程数量时，上限取决于能否得到确定的覆盖率结果，而非标称核心数。
 
-只有在 `master` 移动时，才运行完整的 Linux、macOS 和 Windows 串行参考。拉取请求使用可移植的必需路径，大型运行器套件仅通过手动触发运行。
+只有在 `master` 移动时，才运行完整的 Linux、macOS 和 Windows 串行参考。拉取请求使用企业级运行器必需路径和标准托管兼容性作业，其他大型运行器规格仅通过手动触发运行。
 
 ## 曾考虑的替代方案
 
@@ -54,7 +58,9 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完
 
 **让构建继续等待类型检查。** 此方案会给相互独立的编译器调用排定先后顺序，并把快照回放变成 3 阶段关键链。构建输出本身有独立的成功依赖关系，因此只有快照和发布消费方需要等待它。
 
-**将大型运行器池设为必需的默认选择。** 分配成功时，该方案能缩短实测延迟，但缺少使用资格或组织转移延迟都会使必需作业持续排队，且不会产生仓库诊断信息。可移植路径接受更长的运行时间，手动套件则保留性能实验。
+**将静态门禁和构建后消费方保留在同一台运行器上。** 复用同一个工作区可以省去一轮设置和一次产物传输，但构建耗时的波动会延迟每个消费方，并使消费方的 lint 和快照尾段延续到静态结果之后。仅供本次运行使用的已构建目录树可以保留同一份构建结果，而相互独立的作业能让两条完整路径都保持在实测目标内。
+
+**将完整必需路径保留在 GitHub 标准托管容量上。** 此方案可以避免依赖仓库外部的运行器配置，但标准运行器上的分支头精确运行仍明显更慢，也可能因共享容量而排队更久。标准托管兼容性作业和串行参考流程保留可移植证据，无需让这套较慢的拓扑成为普通主路径。
 
 **将必需的 Windows 检查和观测性 Windows 检查保留在不同作业中。** 这种拆分在工作流层保留状态语义，却需要支付两次设置开销。`run-gates` 在一个进程内保留了相同的必需与非阻塞区别。
 
@@ -62,10 +68,10 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完
 
 ## 后果
 
-基准测试拓扑对每个实测聚合流程只承担 1 轮设置开销，且不保留分片选择器。付费大型运行器仅在手动触发时执行，而不会向每个拉取请求收取这项费用。
+必需拓扑中的每个 32 核通道只承担 1 轮设置开销，且不保留分片选择器。每个普通拉取请求都会消耗付费的企业级 Linux 和 Windows 运行器分钟数；只有在重新测量有价值时，手动基准测试才会加入其他规格。
 
-GitHub 会把每次大型运行器执行向上取整到整分钟计费，因此完整聚合测量能同时呈现计费时长与工作流复杂度，而不会让这项成本进入分支保护路径。
+GitHub 会把每次大型运行器执行向上取整到整分钟计费，因此完整作业测量能同时呈现计费时长与工作流复杂度。拆分 Linux 会重复两轮设置并传输一份已构建目录树，但能使覆盖率、静态门禁与构建后消费方不再相互进入关键路径，且无需重复构建；合并 Windows 则避免重复其耗时更长的设置。
 
 性能目标是观测结果，而非取消截止时间或正确性要求。当映像、依赖、调度器或定价发生变化而需要重新测量时，仍可使用手动全规格和串行套件。
 
-组织自有标签缺失或改名时，只有手动基准作业会排队。全部 12 个池均保持已定义状态，因此分配恢复后，基准测试仍可比较各规格，而必需 CI 则使用标准运行器后备路径。
+企业级运行器标签缺失或改名时，必需主作业会持续排队。标准托管兼容性作业与 `master` 参考流程仍会报告有用证据，但不能替代必需聚合流程；因此，运行器分配是一项仓库 CI 无法修复的运维依赖。
diff --git a/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.i18n.yaml
new file mode 100644
index 0000000000..1aee1563ad
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-browser-demo-gif-recording.md: 096edf453d6b61c4d9046b284ef67a460edf4e88
+2026-07-23-browser-demo-gif-recording.zh.md: f5b8eac1c8dd57a59e9c2293ecc71511078a4896
diff --git a/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.md b/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.md
new file mode 100644
index 0000000000..096edf453d
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.md
@@ -0,0 +1,29 @@
+# Agent Note: Browser demo GIF recording
+
+Status: implemented
+
+English | [中文](2026-07-23-browser-demo-gif-recording.zh.md)
+
+## Problem
+
+Browser demonstrations have been assembled with one-off capture and encoding commands. That makes timing and output size inconsistent, encourages continuous recordings that obscure the useful state changes, and can blur the boundary between a genuine server or API flow and a fixture. Combining local recording with attachment upload or pull-request editing also gives a media task unrelated remote-write authority.
+
+## Decision
+
+The repository provides the [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) skill for local browser-demo artifacts. It uses the available browser-control workflow, establishes whether the requested flow is real, fixture-backed, or otherwise simulated, and captures a small storyboard only after semantically observable UI states. Frames and the output live outside the Git worktree by default.
+
+The bundled `encode_gif.py` helper orders frames lexically, assigns explicit hold durations, uses an `ffmpeg` palette pipeline, and validates source dimensions plus the encoded frame count, dimensions, duration, and byte limit through `ffprobe`. The workflow stops after returning the verified absolute GIF path; uploading the artifact and mutating a pull request, issue, or document remain separate workflows.
+
+## Alternatives considered
+
+**Record continuous video and convert it afterward.** Continuous capture preserves every cursor movement and loading transition but produces larger, noisier artifacts and makes deterministic timing harder. A state storyboard better fits short feature demonstrations where the meaningful evidence is a handful of visible transitions.
+
+**Keep an inline `ffmpeg` recipe in the skill.** Reconstructing quoting, timing manifests, palette filters, overwrite behavior, and post-encode checks in every run is error-prone. A bundled helper keeps those mechanics executable while the skill owns capture judgment.
+
+**Include GitHub attachment and description editing.** Upload and remote mutation require separate authentication, confirmation, and recovery rules. Excluding them keeps invocation of a recording skill local and reversible.
+
+**Use a fixture whenever it is easier to stage.** Fixtures are valid when the requested demonstration is explicitly fixture-backed, but they do not substantiate a real-server or real-API claim. The skill preserves the requested provenance and reports a missing prerequisite instead of silently changing it.
+
+## Consequences
+
+Recordings are small, repeatable local artifacts with explicit provenance and a clean repository boundary. The workflow gives up smooth continuous motion, depends on locally available `ffmpeg` and `ffprobe`, and requires the recorder to identify semantic capture points. The helper is exercised against a four-state browser demonstration and invalid duration input; skill shape and repository links are covered by the skill validator and documentation gates.
diff --git a/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.zh.md b/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.zh.md
new file mode 100644
index 0000000000..f5b8eac1c8
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-23-browser-demo-gif-recording.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 浏览器演示 GIF 录制
+
+Status: implemented
+
+[English](2026-07-23-browser-demo-gif-recording.md) | 中文
+
+## 问题
+
+浏览器演示一直通过一次性的截取与编码命令制作。这会导致播放节奏和输出大小不一致，容易让录制者选择连续录制，反而掩盖有用的状态变化，还可能模糊真实服务器或 API 流程与 fixture（测试前置数据）之间的界限。将本地录制与附件上传或 PR（Pull Request）编辑合并在同一任务中，还会让本应仅处理媒体的任务获得无关的远程写入权限。
+
+## 决策
+
+仓库提供 [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) skill（技能），用于生成本地浏览器演示产物。该 skill 使用当前可用的浏览器控制工作流，先确认请求的流程是真实流程、由 fixture 支撑，还是采用其他模拟方式，再仅在 UI 达到语义上可观察的状态后截取一组精简的分镜帧。帧文件与输出产物默认存放在 Git worktree 之外。
+
+随附的 `encode_gif.py` 辅助脚本按词法顺序排列各帧，为每帧设置明确的停留时长，通过 `ffmpeg` 调色板流水线编码，并借助 `ffprobe` 校验源图像尺寸以及编码结果的帧数、尺寸、时长和字节上限。工作流在返回已验证的 GIF 绝对路径后即结束；上传产物以及修改 PR、issue 或文档仍属于独立的工作流。
+
+## 曾考虑的替代方案
+
+**连续录制视频后再转换。**连续录制能保留每一次光标移动和加载过渡，但会产生体积更大、干扰更多的产物，也更难保持确定的播放时序。状态分镜更适合简短的功能演示，因为有意义的证据只是少数几个可见的状态变化。
+
+**在 skill 中保留内联 `ffmpeg` 配方。**每次运行都重新组装引号转义、时序清单、调色板过滤器、覆盖行为和编码后检查，容易出错。随附的辅助脚本使这些机制保持可执行，skill 则负责判断何时截取画面。
+
+**纳入 GitHub 附件上传与描述编辑。**上传和远程修改需要各自独立的身份认证、确认与恢复规则。将它们排除在外，可以使录制 skill 的调用保持本地且可撤销。
+
+**每当 fixture 更容易布置时就使用它。**当请求明确要求由 fixture 支撑演示时，使用 fixture 是有效的；但它无法为真实服务器或真实 API 的声明提供证据。该 skill 会保持请求指定的演示来源，并在缺少先决条件时报告问题，不会擅自更改来源。
+
+## 后果
+
+录制结果成为体积小、可重复生成的本地产物，明确标注演示来源，并与仓库保持清晰边界。该工作流放弃了流畅的连续动态效果，依赖本机提供的 `ffmpeg` 和 `ffprobe`，并要求录制者识别具有语义意义的截取时点。测试使用四状态浏览器演示与无效时长输入检验辅助脚本；skill 的结构及仓库链接由 skill 校验器和文档门禁覆盖。
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 463777eacf..f8b54b0ec5 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
-2026-07-23-portable-required-pull-request-ci.md: a430d43f7cb3dd4df987d35f3a49d130c397f8e3
-2026-07-23-portable-required-pull-request-ci.zh.md: cbd5d150056f77e52105f56c70a1ead74f052f59
+2026-07-23-portable-required-pull-request-ci.md: 9cf8d97016300c5258c075879176aa6abd64e59e
+2026-07-23-portable-required-pull-request-ci.zh.md: c6839a133d0c3fe7a699362f6168e17d827a5b61
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 a430d43f7c..9cf8d97016 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
@@ -1,4 +1,4 @@
-# Agent Note: Portable required pull-request CI
+# Agent Note: Portable pull-request CI recovery boundary
 
 Status: implemented
 
@@ -8,28 +8,28 @@ English | [中文](2026-07-23-portable-required-pull-request-ci.zh.md)
 
 Required pull-request jobs assigned to organization-owned runner labels remain queued when GitHub cannot allocate those pools. The workflow is valid and standard GitHub-hosted jobs can still pass, but `all checks passed` never starts and an otherwise healthy pull request cannot satisfy branch protection.
 
-Billing health, a runner definition's `Ready` state, and a large autoscaling ceiling do not prove that a named pool can receive a job. Required correctness checks need a portable execution path that does not depend on repository-external runner provisioning.
+Billing health, a runner definition's `Ready` state, and a large autoscaling ceiling do not prove that a named pool can receive a job. Required correctness checks need a known portable recovery path even when the ordinary low-latency path depends on repository-external runner provisioning.
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) runs every required pull-request job on GitHub's standard `ubuntu-latest` or `windows-2025` capacity. The primary Node and Windows jobs keep their complete consolidated inventories, while top-level gates, coverage, ESLint, publint, and snapshot replay use one worker on the smaller hosts. Node versions are selected through `actions/setup-node`, and the Windows job enables Developer Mode before installing the symlinked workspace.
+[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 and Windows jobs on repo-restricted enterprise 32-core pools. 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.
 
-The `node 24 / complete`, Node compatibility, Python SDK, and `windows node 24 / complete` jobs remain dependencies of `all checks passed`; no gate is removed or made observational to recover availability. Branch protection continues to require `e2e` and `all checks passed`.
+The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / complete` remain dependencies of `all checks passed`; branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when an enterprise label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
 
-The two manual larger-runner suites and all twelve organization-owned labels remain available for measurement. They do not participate in ordinary pull requests. The [larger-runner measurements](2026-07-22-evidence-based-larger-hosted-runners.md) remain evidence for future performance work, while the [serial cross-platform reference](2026-07-21-serial-cross-platform-ci-reference.md) remains the independent master-push completeness check.
+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.
 
 ## Alternatives considered
 
-**Wait for organization-runner allocation to recover.** A queue with no assigned runner emits no repository diagnostic and can block every pull request indefinitely, so an external recovery is not a correctness path.
+**Keep every required job on standard capacity.** This removes the enterprise allocation dependency, but complete standard-runner jobs give materially slower feedback and still experience shared-capacity queues. The current split retains portable compatibility and serial evidence while spending enterprise capacity on the primary critical path.
 
-**Use only the smallest organization-owned pools.** Every named pool crosses the same organization allocation boundary; reducing core count does not remove the dependency that caused the queue.
+**Select enterprise size from advertised core count.** Benchmarks show non-monotonic scaling and setup variance, so exact complete-job measurements choose the required pools instead.
 
 **Skip or demote checks while capacity is unavailable.** This would make the status green by dropping evidence rather than by running the repository's required contracts.
 
-**Keep larger-host worker limits on standard runners.** Concurrent full-repository gates and their inner worker pools can oversubscribe the smaller memory and CPU allocation, turning an availability repair into contention failures.
+**Use one worker policy on every host.** Outer gate concurrency and inner tool workers contend differently on Linux, Windows, and standard runners; measured host-specific bounds avoid turning additional cores into slower execution.
 
 ## Consequences
 
-Ordinary pull requests can acquire runners without organization-specific configuration, and a live exact-head run proves the same commands that branch protection consumes. The trade-off is longer elapsed time and more rounded standard-runner minutes than the measured larger-runner topology.
+Ordinary pull requests receive lower active runtime at the cost of depending on enterprise configuration and paid rounded minutes. 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.
 
-Manual larger-runner benchmarks can remain queued without blocking pull requests. Restoring larger runners to the required path needs a separate evidence-based decision after exact-head jobs receive nonzero runner IDs and complete reliably; changing a definition's status alone is insufficient.
+Standard compatibility and serial jobs remain useful when enterprise allocation is degraded, but they do not make a blocked required aggregate green. Recovering availability may require temporarily 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 cbd5d15005..c6839a133d 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
@@ -1,4 +1,4 @@
-# Agent Note: 可移植的拉取请求必需 CI
+# Agent Note: 拉取请求 CI 的可移植恢复边界
 
 Status: implemented
 
@@ -8,28 +8,28 @@ Status: implemented
 
 分配到组织自有运行器标签的拉取请求必需作业，在 GitHub 无法为这些池分配运行器时会持续排队。工作流本身有效，GitHub 标准托管作业仍能通过，但 `all checks passed` 始终无法启动，原本健康的拉取请求因此无法满足分支保护要求。
 
-账单状态正常、运行器定义处于 `Ready` 状态以及较高的自动扩缩容上限，都不能证明指定的运行器池可以接收作业。必需的正确性检查需要一条可移植的执行路径，且该路径不能依赖仓库外部的运行器预配。
+账单状态正常、运行器定义处于 `Ready` 状态以及较高的自动扩缩容上限，都不能证明指定的运行器池可以接收作业。必需的正确性检查需要预先明确一条可移植恢复路径，即使日常低延迟路径依赖仓库外部的运行器预配也不例外。
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 在 GitHub 标准的 `ubuntu-latest` 或 `windows-2025` 容量上运行每项拉取请求必需作业。主 Node 作业和 Windows 作业保留各自完整的合并清单，而顶层门禁、覆盖率、ESLint、publint 和快照回放在这些较小的主机上均使用 1 个工作线程。Node 版本通过 `actions/setup-node` 选择；Windows 作业会在安装采用符号链接的工作区前启用开发人员模式。
+[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业和 Windows 作业。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，`master` 则运行完整的 Linux、macOS 和 Windows 串行参考流程。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
 
-`node 24 / complete`、Node 兼容性、Python SDK 和 `windows node 24 / complete` 作业继续作为 `all checks passed` 的依赖项；为恢复可用性，不会移除任何门禁，也不会将其降为观测性检查。分支保护继续要求 `e2e` 和 `all checks passed`。
+两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / complete` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。企业级运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
 
-两项手动大型运行器套件和全部 12 个组织自有标签继续用于测量，但不参与普通拉取请求。[大型运行器测量结果](2026-07-22-evidence-based-larger-hosted-runners.md)继续作为后续性能工作的证据，[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)则继续作为 master 推送时独立的完整性检查。
+当前主拓扑及其测量结果由[大型运行器决策](2026-07-22-evidence-based-larger-hosted-runners.md)记录。[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)继续作为独立的标准托管完整性检查，手动大型运行器套件则保留规格比较，同时不扩大普通必需矩阵。
 
 ## 曾考虑的替代方案
 
-**等待组织运行器恢复分配。** 未分配运行器的队列不会产生仓库诊断信息，而且可能无限期阻塞每个拉取请求，因此依赖外部恢复不能构成正确性路径。
+**将所有必需作业保留在标准容量上。** 此方案消除了企业级运行器分配依赖，但标准运行器上的完整作业反馈明显更慢，仍会遇到共享容量排队。当前拆分既保留可移植兼容性和串行证据，又将企业级运行器容量用于主关键路径。
 
-**仅使用最小的组织自有运行器池。** 每个指定的运行器池都需要经过相同的组织分配边界；减少核心数不能消除导致作业排队的依赖。
+**根据标称核心数选择企业规格。** 基准测试表明扩展效果不呈单调变化，设置耗时也存在波动，因此必需运行器池改由完整作业的精确测量结果选定。
 
 **在容量不可用时跳过检查或降低其级别。** 这种方式通过丢弃证据而非执行仓库的必需契约来使状态变绿。
 
-**在标准运行器上保留大型主机的工作线程上限。** 完整仓库门禁及其内层工作线程池并发运行时，可能超出较小主机的内存和 CPU 配额，使可用性修复变成资源争用故障。
+**在每台主机上使用同一工作线程策略。** 外层门禁并发与内层工具工作线程在 Linux、Windows 和标准运行器上的争用方式不同；按主机实测的上限可以避免新增核心反而拖慢执行。
 
 ## 后果
 
-普通拉取请求无需组织专有配置即可获得运行器，一次实际的分支头精确运行能够证明分支保护使用的同一组命令。代价是，与实测的大型运行器拓扑相比，总耗时更长，而且按整分钟计费的标准运行器用量更多。
+普通拉取请求获得更短的活动耗时，代价是依赖企业级运行器配置，并消耗按整分钟取整的付费分钟数。一次实际的分支头精确运行能够证明分支保护使用的同一组命令；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
 
-手动大型运行器基准测试可以继续排队，而不会阻塞拉取请求。要将大型运行器恢复为必需路径，需要在分支头精确作业获得非零运行器 ID 并可靠完成后，另行作出基于证据的决策；仅改变运行器定义的状态还不够。
+企业级运行器分配能力下降时，标准兼容性作业和串行作业仍能提供有用证据，但无法让受阻的必需聚合流程变绿。恢复可用性时，可能需要暂时恢复完整的标准托管拓扑；仅改变运行器池定义的状态，不足以证明它可以接收作业。
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
new file mode 100644
index 0000000000..46f5d0e4ea
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-translation-prompt-v4-contract.md: 3e1e51797aa3463c8db24d8657120434e6822789
+2026-07-23-translation-prompt-v4-contract.zh.md: 161d2b6cf3bd3499e3c505a178da40ce577ca797
diff --git a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md
new file mode 100644
index 0000000000..3e1e51797a
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md
@@ -0,0 +1,33 @@
+# Agent Note: Calibrated translation prompt v4 contract
+
+Status: implemented
+
+English | [中文](2026-07-23-translation-prompt-v4-contract.zh.md)
+
+## Problem
+
+Automated counterpart generation needs a stable prompt that reproduces the register and corrections established by human-reviewed translations. Injecting a general-purpose instruction document changes that calibrated model input whenever human or agent guidance changes, while an unframed response cannot carry a draft, its self-review, and the corrected document separately. Plain XML-like section tags also collide with valid Markdown that documents those same tags.
+
+## Decision
+
+The committed [translation prompt](../../../../docs/i18n/translation-prompt.md) is the calibrated pipeline asset. Its renderer injects only the source language, target language, and current [terminology table](../../../../docs/i18n/terminology.md), and rejects unknown, missing, or malformed placeholder syntax before assembling a request. The request assembler retains the source basename outside the model-visible prompt and places each reviewed whole-document pair into one bare-text user/assistant example turn before the real source document. The template may carry model-specific calibration rules, but those rules remain subordinate to the repository's binding pairing, terminology, structure, and emphasis contracts.
+
+The response has three ordered top-level sections: `translation`, `review`, and `final`. The response consumer derives the target basename from the retained source context, preserves optional leading YAML frontmatter, and mechanically inserts or corrects the language switcher after the first H1 in `final`. The parser requires each section exactly once, rejects content outside the envelope, and tolerates one outer `xml` Markdown fence because models sometimes echo the prompt's example fence.
+
+## Response framing
+
+Section delimiter lines are reserved by the wire format. When a Markdown body line consists of a delimiter tag, possibly preceded by backslashes, the serializer and model add one leading backslash; the parser removes exactly one. This count-preserving escape round-trips both a literal delimiter and an already escaped delimiter without changing inline tag mentions.
+
+The executable contract lives in [the renderer, request assembler, parser, and response consumer](../../../../scripts/translation-prompt.ts). Unit tests cover both directions, request order, placeholder validation, target-path validation, strict section order and cardinality, fenced responses, inline tag mentions, delimiter lines inside Markdown bodies, and frontmatter-preserving new-pair switcher correction. A keyless subprocess snapshot pins the assembled prompt and five reviewed example turns together with a frontmatter-bearing recorded response consumed through the target-path correction.
+
+## Alternatives considered
+
+**Inject `translation-rules.md` into every request.** That document governs humans and agents as well as the automated pipeline. Injecting it couples each editorial clarification to model behavior and displaces the manually calibrated prompt constraints; the pipeline instead injects the binding terminology table and verifies its own asset directly.
+
+**Use a strict CDATA XML document.** CDATA provides general XML framing but adds a nested protocol, an additional `]]>` escape, and XML-parser behavior that the three-section contract does not otherwise need. Reserving and escaping six delimiter lines keeps the calibrated response shape while preserving arbitrary Markdown.
+
+**Return only the final translation.** A single body is simpler to parse but discards the explicit correction pass used to catch tone, structure, terminology, and punctuation defects before publication.
+
+## Consequences
+
+Prompt wording is executable behavior and receives code review, a translation-prompt verifier, and a runnable request/response snapshot. The calibrated asset and the general translation rules can evolve for their different audiences, but review must reject contradictions with binding repository contracts. The line escape is visible only when source documentation contains a wrapper tag on its own line, and parser tests pin its lossless behavior.
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
new file mode 100644
index 0000000000..161d2b6cf3
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 经校准的翻译提示词 v4 契约
+
+Status: implemented
+
+[English](2026-07-23-translation-prompt-v4-contract.md) | 中文
+
+## 问题
+
+自动生成对侧文件需要一份稳定的提示词，能够复现经人工评审的译文所确立的语体和修正方式。注入通用说明文档，会让这份经校准的模型输入随着面向人类或 agent（智能体）的指导发生变化，而未经封装的响应无法分别承载草稿、自检内容和修正后的文档。普通的类 XML 分段标签还会与用于说明这些标签的合法 Markdown 内容发生冲突。
+
+## 决策
+
+提交入库的[翻译提示词](../../../../docs/i18n/translation-prompt.md)是经过校准的流水线资源。其渲染器仅注入源语言、目标语言和当前[术语表](../../../../docs/i18n/terminology.md)，并在组装请求前拒绝未知、缺失或语法格式错误的占位符。请求组装器在模型可见的提示词之外保留源文件基本名，并在真正的源文档之前，将每组经评审的整篇文档对编排为一个纯文本 user/assistant 示例轮次。模板可以包含针对特定模型的校准规则，但这些规则必须服从仓库中具约束力的配对、术语、结构与强调格式契约。
+
+响应包含三个有序的顶层分段：`translation`、`review` 和 `final`。响应消费方根据保留的源文件上下文推导目标文件基本名，保留文件开头可选的 YAML frontmatter，并以机械方式在 `final` 中第一个 H1 之后插入或校正语言切换行。解析器要求每个分段恰好出现一次，拒绝封套之外的内容，并允许响应最外层有一层 `xml` Markdown 围栏，因为模型有时会照抄提示词中的示例围栏。
+
+## 响应封装格式
+
+分段定界行由协议格式（wire format）保留。当 Markdown 正文中的某一行仅包含定界标签（前面可以带反斜杠）时，序列化器和模型会在行首再添加一个反斜杠；解析器则只移除一个。这种保留计数的转义方式让字面量定界标签与已转义的定界标签都能无损往返，同时不会改动行内提及的标签。
+
+可执行契约由[渲染器、请求组装器、解析器和响应消费方](../../../../scripts/translation-prompt.ts)实现。单元测试覆盖两个翻译方向、请求顺序、占位符校验、目标路径校验、严格的分段顺序与数量约束、带围栏的响应、行内提及标签、Markdown 正文中的定界行，以及保留 YAML frontmatter 的新配对语言切换行校正。一个无密钥子进程快照锁定组装后的提示词、五个经评审的示例轮次，以及带 YAML frontmatter 的录制响应经目标路径校正后的消费结果。
+
+## 考虑过的替代方案
+
+**在每个请求中注入 `translation-rules.md`。** 该文档既约束人类与 agent，也约束自动翻译流水线。注入它会让编辑规范的每次澄清都与模型行为耦合，并挤占经过人工校准的提示词约束；因此流水线仅注入具约束力的术语表，并直接校验自身资源。
+
+**使用严格的 CDATA XML 文档。** CDATA 提供通用的 XML 封装，但会引入一层嵌套协议、额外的 `]]>` 转义规则，以及三段式契约原本不需要的 XML 解析器行为。预留并转义六种定界行，既能维持经校准的响应形态，也能保留任意 Markdown 内容不变。
+
+**只返回最终译文。** 单一正文更易解析，却会丢弃显式修正步骤；这个步骤用于在发布前发现语气、结构、术语和标点缺陷。
+
+## 影响
+
+提示词措辞属于可执行行为，因此需要经过代码评审、翻译提示词校验器校验及可运行的请求/响应快照验证。经校准的资源与通用翻译规则可以针对各自的受众分别演进，但评审必须拒绝任何与仓库约束性契约冲突的改动。只有当源文档中的封装标签独占一行时，行转义才会显现；解析器测试锁定这一无损行为。
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
new file mode 100644
index 0000000000..bf29a5ddca
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-19-drop-mutable-session-summary.md: 80fe043e365352b17d2a5b3efa1ab8d396d311c4
+2026-06-19-drop-mutable-session-summary.zh.md: e875d96d003367dbe8a671e6057a6b4a6a44ca74
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 f1a9c9aa3c..80fe043e36 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-19-drop-mutable-session-summary.zh.md)
+
 ## Problem
 
 The [session-persistence seam](../architecture/2026-06-14-session-persistence.md) split a session's out-of-log metadata into two types owned by `dsh-session`: an immutable `SessionHeader` (`version`, `id`, `createdAt`, `cwd?`, `parentSession?`) written once at creation, and a mutable `SessionSummary` (`updatedAt`, `title?`, `firstPrompt?`) "updateable without touching the append-only log". Their union was `SessionMeta = SessionHeader & SessionSummary`, and the abstract `SessionPersistence` service carried a seventh method — `update(id, summary)` — for rewriting the summary. Each backend implemented the mutable store its own way: JSONL wrote a separate atomic `.summary.json` **sidecar** beside the log (temp-write + rename, best-effort), SQLite kept `updated_at`/`title`/`first_prompt` **columns** bumped inside the append transaction.
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
new file mode 100644
index 0000000000..e875d96d00
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 移除可变的会话摘要
+
+Status: implemented
+
+[English](2026-06-19-drop-mutable-session-summary.md) | 中文
+
+## 问题
+
+[会话持久化 seam](../architecture/2026-06-14-session-persistence.md)将会话的日志外元数据拆分为 `dsh-session` 拥有的两种类型：一个不可变的 `SessionHeader`（`version`、`id`、`createdAt`、`cwd?`、`parentSession?`），在创建时一次性写入；一个可变的 `SessionSummary`（`updatedAt`、`title?`、`firstPrompt?`），「可在不触碰仅追加日志的情况下更新」。二者的联合类型为 `SessionMeta = SessionHeader & SessionSummary`，抽象的 `SessionPersistence` 服务为此多出第七个方法 `update(id, summary)`，用于重写摘要。各后端各自实现可变存储：JSONL 在日志旁写一个独立的原子 `.summary.json` **伴随文件**（临时写入 + rename，尽力保证）；SQLite 在追加事务内更新 `updated_at`/`title`/`first_prompt` **列**。
+
+摘要是为未来的会话选择器设计的（通过 `updatedAt` 排序近期会话，用 `title`/`firstPrompt` 做预览）。该选择器从未实现。对整个仓库的审计表明，`SessionSummary` 的全部表面积都是**死状态**：
+
+- `SessionPersistence.update()` **零个生产调用方**（所有 `.update(` 匹配都是 `createHash().update()` 或测试代码）。
+- `firstPrompt` 在生产代码中**从未被读取**。
+- `title` *确实*在 ACP（Agent Client Protocol）桥接层被读取过，但读的是工具调用的 **presenter**（`present.title`），从未读取存储的会话元数据。
+- `updatedAt` **没有消费方**：`list()` 唯一的生产调用方读取的是 `meta.cwd`（`SessionHeader` 字段），用于在 `session/load` 时校验工作区；恢复会话读取的是 `createdAt`/`cwd`/`parentSession`——全是 header 字段。
+- 决定性的一点：活跃的 `Session.header` 类型本来就是 `SessionHeader` 而非 `SessionMeta`——摘要从未存在于活跃会话对象上；它只存在于持久化层，除了自身的契约测试外无人写入、无人读取。
+
+## 决策
+
+彻底删除可变的会话摘要。`SessionSummary` 与 `SessionMeta` 这个名称一并移除；后端存储和返回的元数据仅为 `SessionHeader`。`SessionPersistence.update()` 从抽象服务和所有后端中移除。JSONL 去掉整套伴随文件机制（`writeSidecar`/`readSidecar`/`touchSummary`/`removeSidecars`/`sidecarPath` 以及 load/list 的覆盖逻辑）；SQLite 去掉 `updated_at`/`title`/`first_prompt` 列以及每次追加时的 `updated_at` 更新，其 `SCHEMA_VERSION` 从 `1 → 2`。
+
+摘要原本要提供的一切，在消费方真正需要时都**可从仅追加日志中派生**（`firstPrompt` = 第一条 `user/message`；近期度 = 最后一个事件的 `time` 或文件 mtime），或者已经存在于不可变 header 中（`createdAt`、`cwd`）。唯一*不可*派生的是用户*手动编辑*的标题，但它从未实现，纯属 YAGNI；如果未来真有功能需要，它可以作为独立的日志事件或 header 字段回归。
+
+这被记录为一项决策，因为它具有**持久性**（它同时收窄两个后端的公共服务契约和磁盘格式）、**争议性**（summary 是有意为未来设计的结果，而非意外），也具有**意外性**（未来读者在原 Agent Note（agent 决策记录）描述 `SessionMeta` 的位置发现 `SessionHeader`，否则会追问 summary 为何消失）。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
+
+## 无需迁移
+
+这是未发布的软件（见[根 AGENTS.md](../../../../AGENTS.md)「Pre-release stance: foundation over blast radius」一节），因此没有需要保留的磁盘数据库或日志。SQLite 不迁移 v1 数据库：`openDatabase` 守卫现在拒绝任何非当前版本的磁盘 `user_version`（`onDisk !== 0 && onDisk !== SCHEMA_VERSION`），无论更旧*还是*更新，因此陈旧的 v1 数据库会被干净地拒绝，而非在新列集下被半读取。新建数据库写入当前版本号；这是唯一需要正常工作的路径。
+
+## 后果
+
+未来的会话选择器现在必须从日志派生预览/排序信息（或重新引入一个类型化字段），而不能直接读取现成的摘要行。这是正确的代价：为一个尚不存在的功能维护缓存，是每个后端都要付出维护成本、每个契约测试都要付出断言成本的死重。这一原则——**通过的测试固定的是当前行为，不一定是正确行为；行为可能是过去妥协的产物**——现已作为独立约定记录在[根 AGENTS.md](../../../../AGENTS.md) 中，本次变更即为其实例。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..e30531e02d
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-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
+2026-06-20-collapse-trace-only-session-events.md: fce5c48ef6fcb1abc6e2fbb95dc7e83d22956660
+2026-06-20-collapse-trace-only-session-events.zh.md: 5be2d77644c7b4084b892013a2c1e5b97a333d74
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 4e8a092989..fce5c48ef6 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-collapse-trace-only-session-events.zh.md)
+
 ## Problem
 
 The session event vocabulary includes first-class events that are not part of replayable conversation history and have little or no production consumption. `usage` is already present as a model stream chunk before the loop also appends a separate `usage` event. `error` duplicates the `turn/end { kind: 'error', message, code }` reason for loop failures; ACP settlement reads the turn-end reason, ACP rendering ignores the `error` event, and `deriveMessages()` skips it.
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
new file mode 100644
index 0000000000..5be2d77644
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md
@@ -0,0 +1,44 @@
+# Agent Note: 将仅用于追踪的会话事实折叠进承载性事件
+
+Status: implemented
+
+[English](2026-06-20-collapse-trace-only-session-events.md) | 中文
+
+## 问题
+
+会话事件词汇中包含一些一等事件，它们不属于可回放的对话历史，在生产环境中几乎没有消费方。`usage` 已经作为模型流分片存在，之后循环又追加了一个独立的 `usage` 事件。`error` 与 `turn/end { kind: 'error', message, code }` 中的循环失败原因重复；ACP（Agent Client Protocol）结算读取轮次结束原因，ACP 渲染忽略 `error` 事件，`deriveMessages()` 也跳过它。
+
+这些事件让规范的 transcript（文本记录）看起来比实际更像遥测数据。它们增加了事件变体、不变式、测试、快照和持久化用例，但作为独立记录并不承载实际功能。它们携带的事实仍然有用：token 用量应当保留以供计费，错误的步骤编号也不应悄然消失。简化的方式是将这些事实折叠进消费方本已必须理解的邻近事件，而非减少记录的信息量。
+
+## 决策
+
+仅在信息已被保留、无需并行记录的情况下，移除独立的追踪事件：
+
+- 成功步骤的 usage 折叠进匹配的 `assistant/message`（`assistant/message { turn, step, content, usage? }`），使组装好的模型输出与其计费信息一同传递。
+- 失败或中止的步骤如果有 usage 但没有 assistant 内容，则将 usage 放在一个空内容的 `assistant/message` 上（下方实现说明给出了无信息丢失的证明）——不会有已持久化的 usage 分片无处安放。
+- 独立 `error` 事件中的步骤编号折叠进 `turn/end.reason`（当 `kind: 'error'` 时：`{ kind: 'error', step, message, code? }`）——`turn/end` 是 ACP 和恢复机制已经消费的持久轮次结果。
+- `agent/error` 与日志保留用于实时诊断；`turn/end` 之后不再有第二条会话日志错误记录。
+
+用户对话日志包含渲染、恢复、审计和计费所需的全部信息，消费方无需协调重复的追踪行。
+
+## 曾考虑的替代方案
+
+**保留独立行作为遥测**——这些事件让规范 transcript 看起来比实际更像遥测数据，代价是增加了事件变体、不变式、测试、快照和持久化用例，却没有任何消费方使用。如果分析需求真正出现，正确的形态是投影辅助工具或带有独立保留策略的专用遥测存储，而非对话日志中的重复追踪行。
+
+## 验证
+
+`SessionEventMap` 不再包含独立的 `usage` 或 `error`；agent loop（智能体循环）不再追加独立的 usage 事件，持久性失败通过 `turn/end { kind: 'error', step, message, code? }` 记录；ACP 快照和持久化测试断言不存在仅追踪行；已录制的 fixture（测试前置数据）使用新事件形状，会话格式版本固定为 `0`（后端按预发布格式策略拒绝任何非 `0` 的存储日志）；文档说明了 token 用量和操作错误的观测位置。
+
+## 后果
+
+消费方不能再从规范日志中筛选独立的 `usage` 或步骤级 `error` 行，必须从承载它们的 assistant/failure 事件中读取这些事实。只有在实现 PR（Pull Request）证明相同事实仍然存在的前提下，这才是合理的简化；否则独立事件应予保留。
+
+## 实现说明
+
+按提案落地，但有一处范围细化（遵循 AGENTS.md 所述“Agent Note（agent 决策记录）是提案，而非绝对真理”）：
+
+- **空内容 `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-drop-unconsumed-llm-adapter-change-event.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.i18n.yaml
new file mode 100644
index 0000000000..9529343206
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-drop-unconsumed-llm-adapter-change-event.md: a3c7c089d7dfa1a4cd6a891c416bf270dc7eff3d
+2026-06-20-drop-unconsumed-llm-adapter-change-event.zh.md: d9129386dc95bae0716253fdf50236b25ebfdf75
diff --git a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md
index d8d4015b0d..a3c7c089d7 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-drop-unconsumed-llm-adapter-change-event.zh.md)
+
 ## Problem
 
 `LlmService.registerAdapter()` emits `llm/adapter-change` on registration and disposal ([packages/llm/llm/src/index.ts](../../../../packages/llm/llm/src/index.ts)). Grepping `llm/adapter-change` across `packages/*/src` and `examples/*/src` finds only the declaration, emit sites, docs, and tests; no production listener subscribes to it.
diff --git a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.zh.md b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.zh.md
new file mode 100644
index 0000000000..d9129386dc
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 移除未被消费的 `llm/adapter-change` 事件
+
+Status: implemented
+
+[English](2026-06-20-drop-unconsumed-llm-adapter-change-event.md) | 中文
+
+## 问题
+
+`LlmService.registerAdapter()` 在注册和 dispose（资源释放）时发出 `llm/adapter-change` 事件（[packages/llm/llm/src/index.ts](../../../../packages/llm/llm/src/index.ts)）。在 `packages/*/src` 和 `examples/*/src` 中搜索 `llm/adapter-change`，只能找到声明、emit 站点、文档和测试；没有任何生产环境的监听器订阅它。
+
+这与 `tools/change` 和 `system-prompt/change` 不同。如今这两个事件同样没有消费方，但它们有望成为未来实时工具/提示词 UI 的注册表变更信号。LLM（大语言模型）适配器注册更像是启动时的实现细节：适配器不是用户可见的选项面板，真正的模型调用拦截 seam 是 `llm/stream`。保留一个没有监听器的适配器变更事件，只是在更小范围内重复[删除无用 summary](2026-06-19-drop-mutable-session-summary.md) 的模式。
+
+这个事件并非零成本。`registerAdapter()` 在发出 `llm/adapter-change` 之前先 yield 回滚 disposer，这样抛出异常的监听器会回退变更而非泄漏适配器条目；包内还有针对该监听器抛出路径的测试。这种防御性排序保护的是一个只有测试才能触发的失败模式。
+
+## 决策
+
+只移除 `llm/adapter-change`：包括 `dsh-llm` 的 `interface Events` 中的声明、`ctx.emit('llm/adapter-change')` 调用，以及 `LlmService.registerAdapter` JSDoc 中“在注册和释放时发出 `llm/adapter-change`”的句子。`registerAdapter()` 的效应生成器为 HMR（热模块替换）/释放保留变更与回滚 disposer，但移除仅因该事件而存在的监听器抛错回滚顺序。适配器 disposer 测试断言返回的 disposer 会移除适配器，不再订阅事件；监听器抛错回滚测试则随其测试对象一起消失。[docs/architecture.md](../../../../docs/architecture.md) 和 [packages/llm/llm/README.md](../../../../packages/llm/llm/README.md) 中的事件分类也在同一变更中更新。
+
+## 曾考虑的替代方案
+
+### 为什么不移除所有注册表变更事件？
+
+由注册表通告变更的微内核是一种一致的约定。当 UI 能够实时刷新可用工具或提示词章节时，`tools/change` 和 `system-prompt/change` 可能会有用。本 Agent Note（agent 决策记录）在存在合理用户侧消费方的位置保留该约定，只删除当前及可能的未来消费方都不明确的适配器变更事件。
+
+如果将来需要 LLM 适配器浏览器或动态模型选择器用到此信号，届时再连同消费方一起重新引入，并提供比「something changed」更清晰的 payload。
+
+## 验证
+
+`llm/adapter-change` 及其 emit 已消失，重新生成的 Cordis 目录保持新鲜；HMR 安全性仍成立（释放贡献该适配器的 fiber 会移除它）；`tools/change` 和 `system-prompt/change` 仍有文档与测试；ACP（Agent Client Protocol）快照和无密钥 Headless Loader 冒烟则固定了未变的生产路径。
+
+## 后果
+
+- **移除一个已文档化的 emit 事件属于公开接口变更。** 它出现在分类体系表中，读起来像有意设计的 API。但「已声明且已发出」不等于「已被消费」——这与移除可变 summary 时的判断依据相同。分类体系表在同一个变更中更新，因此文档不会漂移。
+- **注册表变更约定变得不均匀。** 这是可接受的，因为 LLM 适配器注册与工具或提示词段落不是同一层面的面向用户概念。不均匀但诚实，胜过统一但无用。
+
+这是一个小裁剪，但它退役了一条守护着并不存在的消费方的正确性不变式。
diff --git a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.i18n.yaml
new file mode 100644
index 0000000000..ad842ae732
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-drop-unconsumed-llm-assembled-surfaces.md: b6b596e822b4bd6fd1bd891c336c622ad675ad45
+2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md: bafc5d3bc630d89c776bbcf53719b29223e1c90d
diff --git a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.md b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.md
index b482a444b5..b6b596e822 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md)
+
 ## Problem
 
 `LlmService` ([packages/llm/llm/src/index.ts](../../../../packages/llm/llm/src/index.ts)) exposes three call surfaces over a model:
diff --git a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md
new file mode 100644
index 0000000000..bafc5d3bc6
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 移除未被消费的 LLM 组装便捷接口
+
+Status: implemented
+
+[English](2026-06-20-drop-unconsumed-llm-assembled-surfaces.md) | 中文
+
+## 问题
+
+`LlmService`（[packages/llm/llm/src/index.ts](../../../../packages/llm/llm/src/index.ts)）在模型之上暴露了三个调用接口：
+
+- `stream()`：原始 `StreamChunk`，通过 `llm/stream` waterfall（瀑布式事件）分发。
+- `streamBlocks()`：一个「便捷视图」，将分片送入 `BlockAssembler` 并按流顺序产出已组装的 `ContentBlock`（[index.ts:137-144](../../../../packages/llm/llm/src/index.ts)）。
+- `generate()`：一个完整组装的 `GenerateResult`，通过第二条 `llm/generate` waterfall 分发（[index.ts:151-157](../../../../packages/llm/llm/src/index.ts)）。
+
+LLM（大语言模型）服务唯一的生产消费方是 agent loop（智能体循环），它只使用 `stream()`：将原始分片送入自己的 `BlockAssembler`，以便在并行组装的同时记录分片，保证回放保真度（[packages/core/agent-loop/src/loop.ts](../../../../packages/core/agent-loop/src/loop.ts)，`ctx.llm.stream(req)` 步骤）。在 `packages/*/src` 和 `examples/*/src` 中 grep `streamBlocks` 与 `ctx.llm.generate`，找不到任何生产调用方。仅有的引用来自服务方法定义、文档和测试；适配器测试用 `generate()` 作为便捷驱动，但它们完全可以通过同一个 assembler 辅助函数手动消费 `stream()`，无需为此保留一个公开的生产 API。
+
+这属于[删除可变会话 summary](2026-06-19-drop-mutable-session-summary.md) 的同类模式：带有受测契约的组装视图 API，由测试而非生产代码消费。它们是为不关心 token 级增量的消费方推测性构建的，但唯一的真实消费方恰恰关心增量，以便持久化高保真重放数据。
+
+`streamBlocks()` 拖带了 `BlockAssembler` 的一块专用逻辑：`flushReady()` 与 `flushRemaining()`（[packages/llm/llm/src/assembler.ts:138-168](../../../../packages/llm/llm/src/assembler.ts)）以及 `flushed` 游标字段，仅为支持按序增量产出而存在。`generate()` 拖带了 `GenerateResult`、`BlockAssembler.result()` 以及 `llm/generate` waterfall——在同一底层流之上的第二个拦截面。agent loop 对 assembler 的使用仅限于 `push()` / `message()` / `usage` / `finish`，不涉及流式 flush 或一次性服务组装。
+
+## 决策
+
+`stream()` 是唯一的公开 LLM 调用接口。移除 `streamBlocks`、`generate`、其事件/结果类型，以及仅被该路径使用的 assembler 辅助方法。适配器测试通过本地辅助函数对公开流进行组装；`BlockAssembler` 仅保留有生产消费方的操作。
+
+## 曾考虑的替代方案
+
+**保留 `generate()` 作为仅供测试的便捷方法**：否决。适配器测试通过共享 assembler 手动消费 `stream()`，走的是与生产完全相同的流式路径；一个唯一调用方只有测试的公开方法，正是 [drop-mutable-summary 先例](2026-06-19-drop-mutable-session-summary.md)所淘汰的死接口形态。未来如果有消费方需要不带增量的组装块，届时再为该消费方引入一个聚焦的辅助方法。
+
+## 验证
+
+`streamBlocks`、`generate`、`llm/generate` 及仅供它们使用的 assembler 辅助函数均已移除，且未产生新的无用导出；两个真实适配器都通过 `stream()` 和共享 assembler 接受测试；循环行为保持一致（ACP（Agent Client Protocol）快照预期输出未变）；README、架构文档和模块文档也不再提及已删除表面。
+
+## 后果
+
+- **从一个核心词汇包中移除了公开方法。** 未来如果有插件需要不带增量的组装块，它需要直接调用 `stream()` 并使用 `BlockAssembler`，或在有真实消费方时重新引入一个聚焦的辅助方法。鉴于预发布阶段「基础优先于预设未来」的立场（[AGENTS.md](../../../../AGENTS.md)），现在正是裁剪仅供测试的公开接口的合适时机。
+- **适配器测试变得更显式。** 它们失去了便捷的 `generate()` 包装层，但这是有益的压力：测试走的是与生产相同的流式路径。
+- **waterfall 使用者失去 `llm/generate`。** 不存在生产监听者。未来的缓存/重试/日志插件应包装 `llm/stream`，它仍然是唯一的提供方调用路径。
+
+改动规模不大，但它从 LLM 包中干净地移除了预设的接口面积，为生产和测试留下唯一一份模型调用契约。
diff --git a/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.i18n.yaml
new file mode 100644
index 0000000000..ed0b63a28d
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-prune-dead-seam-methods.md: 70596d908bb1d7559e876d93bce0e25874ce1ff0
+2026-06-20-prune-dead-seam-methods.zh.md: 1fbc7dbf2f7abb5b17b1df10ef06e490b11335a4
diff --git a/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.md b/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.md
index 782ffe891e..70596d908b 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-prune-dead-seam-methods.zh.md)
+
 > **Implementation note:** Only `SessionPersistence.has()` and `.delete()` were removed. `BashExecutor.get()` and `.list()` remain because removing their one-line lookup surface required substantially more completion-tracking machinery in consumers. Their id branding is covered by the [branded-ids Agent Note](../architecture/2026-06-20-branded-ids.md).
 
 ## Problem
@@ -12,7 +14,7 @@ A capability seam ([interface / implementation / consumer](../architecture/2026-
 
 The abstract service declared its operations beyond create/append: `load`, `list`, `has`, `delete`. Production consumers of `ctx.sessionPersistence` use only two: the agent-loop resume path calls `load()` ([packages/core/agent-loop/src/index.ts:176](../../../../packages/core/agent-loop/src/index.ts)), and the ACP bridge calls `list()` for `session/list` ([packages/ui/acp/src/index.ts:494](../../../../packages/ui/acp/src/index.ts)). Grepping every `sessionPersistence.*` / `persistence.*` use across `packages/*/src` and `examples/` finds no `has(` and no `delete(` on the service. The `.has(`/`.delete(` calls in `packages/ui/acp/src/index.ts` are on the in-memory `SessionStore` and a local `Set` of loading ids, not persistence. The only callers of `has`/`delete` were the contract suites and per-backend specs.
 
-`has()` was not just unused — it was the most intricate branch in the shared coordinator: a tracked-vs-untracked dual-probe (`loadLive(id, cwd)` for a live-tracked session vs `loadStored(id)` for an untracked one) with a multi-line rationale. `delete()` dragged the `deleteStored` backend hook that every backend had to implement. This is the [drop-mutable-session-summary](2026-06-19-drop-mutable-session-summary.md) pattern: a contract test exercised both, but no shipping code asks "is this session persisted?" or removes one.
+`has()` was not just unused: it added a tracked-vs-untracked coordinator probe and a contract branch even though `loadStored(id)` already owns durable existence checks. `delete()` dragged the `deleteStored` backend hook that every backend had to implement. This is the [drop-mutable-session-summary](2026-06-19-drop-mutable-session-summary.md) pattern: a contract test exercised both, but no shipping code asks "is this session persisted?" or removes one.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.zh.md b/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.zh.md
new file mode 100644
index 0000000000..1fbc7dbf2f
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.zh.md
@@ -0,0 +1,43 @@
+# Agent Note: 从持久化 seam 中移除无用方法
+
+Status: implemented
+
+[English](2026-06-20-prune-dead-seam-methods.md) | 中文
+
+> **实现说明：** 仅移除了 `SessionPersistence.has()` 和 `.delete()`。`BashExecutor.get()` 和 `.list()` 仍然保留，因为删除它们的单行查找表面会要求消费方增加显著更多的完成跟踪机制。其 id 品牌化由[品牌化 id Agent Note（agent 决策记录）](../architecture/2026-06-20-branded-ids.md)负责。
+
+## 问题
+
+能力 seam（[接口 / 实现 / 消费方](../architecture/2026-06-13-capability-seams.md)）承载了没有消费方调用的抽象方法。seam 的存在是为了让实现和消费方独立演进——但没有消费方以之编程的方法不是 seam，而是每个实现仍必须实现和测试的推测性表面。
+
+### `SessionPersistence.has()` 与 `.delete()`
+
+该抽象服务在 create/append 之外声明了更多操作：`load`、`list`、`has`、`delete`。`ctx.sessionPersistence` 的生产消费方只用了两个：agent loop（智能体循环）的恢复路径调用 `load()`（[packages/core/agent-loop/src/index.ts:176](../../../../packages/core/agent-loop/src/index.ts)），ACP（Agent Client Protocol）桥接层为 `session/list` 调用 `list()`（[packages/ui/acp/src/index.ts:494](../../../../packages/ui/acp/src/index.ts)）。在 `packages/*/src` 和 `examples/` 中 grep 所有 `sessionPersistence.*` / `persistence.*` 的使用，找不到对该服务的 `has(` 或 `delete(` 调用。`packages/ui/acp/src/index.ts` 中的 `.has(`/`.delete(` 调用作用于内存中的 `SessionStore` 和一个本地的 loading id `Set`，而非持久化。`has`/`delete` 的唯一调用者是契约测试套件和各后端的 spec。
+
+`has()` 不仅未被使用：在 `loadStored(id)` 已负责持久化存在性检查的情况下，它仍增加了协调器的已跟踪/未跟踪探测和一个契约分支。`delete()` 则拖入每个后端都必须实现的 `deleteStored` 后端钩子。这属于[删除可变会话 summary](2026-06-19-drop-mutable-session-summary.md) 的同类模式：契约测试覆盖了两者，但已发布代码从不会询问“这个会话是否已持久化？”或删除某个会话。
+
+## 决策
+
+没有消费方使用的方法被移除——从抽象 seam、实现，以及仅为覆盖它们而存在的契约/spec 测试套件中移除：
+
+- `SessionPersistence.has()` / `.delete()` 已移除：抽象声明、协调器的 `has`/`delete`/`deleteCore`，以及 `PersistenceBackend.deleteStored` 钩子均消失（jsonl 和 sqlite 都只是为了满足该钩子才实现 `deleteStored`，这些实现也一并移除）。后端属于[双后端](../architecture/2026-06-14-session-persistence.md)设计，其他方面不在范围内；删除它们为没有消费方的钩子所做的实现，是删除钩子的一部分，而非重新设计后端。
+- 所有文档和源码注释引用都已更新为保留下来的四方法、仅含 `list()` 的契约——不仅包括字面上的 `has(`/`delete(`/`deleteStored` 拼写，还包括 `{@link has}`/`{@link delete}` JSDoc 链接和“六个公共方法”的计数——涉及 seam 和后端 README、[docs/architecture.md](../../../../docs/architecture.md)、[会话持久化](../architecture/2026-06-14-session-persistence.md)与[写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md) Agent Note，以及协调器/后端 JSDoc。
+
+## 曾考虑的替代方案
+
+### 为什么不以「seam 应当完整」为由保留？
+
+「持久化 seam 理应提供 delete」这种直觉是真实的——但它恰恰是预发布阶段所警惕的投机性完整（[AGENTS.md](../../../../AGENTS.md)：为正确的基础优化，而非为你并不拥有的假想调用者优化）。`delete()` 是一个方法，等消费方真正需要时再加回来即可：一个删除旧会话的会话管理 UI 会需要它——到那时再加，基于该 UI 的真实需求来设计（软删除？级联？确认？），而非现在猜测。
+
+在有活跃消费方的情况下重新添加一个 seam 方法，成本低且设计更优，因为消费方锚定了契约。在无人使用的情况下保留它，意味着每个实现（以及未来的每个后端）都必须实现和测试一个无实际作用的方法。
+
+## 验证
+
+`has`/`delete`/`deleteStored` 已从持久化 seam、实现和契约测试套件中移除，没有新增无用导出；剩余操作（`create`/`append`/`load`/`list`）未受影响，ACP `session/list` 和崩溃恢复行为完全一致；seam README 和 `docs/architecture.md` 仅列出存留的方法。
+
+## 后果
+
+- **`delete()` 是产品最终会需要的操作。** 确实如此，但「最终」正是关键。现在删除、将来基于真实消费方重新添加，严格优于发布一份猜测的契约。两个后端各自减少了一个 `deleteStored` 实现，这是在本次范围之外的包中的有限改动。
+- **低耦合。** 移除局限于持久化 seam + 实现 + 测试；没有跨包消费方引用被移除的方法，因此除文档外没有涟漪效应。
+
+规模不大，但它将 seam 从「实现必须为无人提供什么」恢复为「恰好是消费方使用的东西」。
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
new file mode 100644
index 0000000000..7a5f7fdb48
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-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
+2026-06-20-public-agent-stop-surface.md: 81a21de30bfbc25688069efbffb21647889b1bdb
+2026-06-20-public-agent-stop-surface.zh.md: 1f5a9ea3c1c3dd6f598c258574a81e52e291f3b7
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 824efc804c..81a21de30b 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
@@ -2,6 +2,8 @@
 
 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
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
new file mode 100644
index 0000000000..1f5a9ea3c1
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 保留单一公开停止原语
+
+Status: implemented
+
+[English](2026-06-20-public-agent-stop-surface.md) | 中文
+
+> **实现说明：** 仅移除了 `abort()`。`whenIdle()` 予以保留，因为它是公开的完全停稳信号，能安全处理等待者结算与替换轮次竞态；消费方不应从状态转换中自行重建该行为。
+
+## 问题
+
+公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者则清除已排队和 steering（中途引导）工作，并中止活动轮次。在生产中，ACP（Agent Client Protocol）对 `session/cancel` 使用 `cancel()`，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。
+
+行为差异确实存在，但已发布代码不需要较窄的操作。AgentLoop 改为为整个轮次拥有一个私有取消 holder。`cancel(cause?)` 携带类型化的 `user` 或 `parent` 原因，默认为 `user`，并丢弃待处理输入；释放仍是单独的生命周期中断。完整的归属与传播契约位于[显式轮次取消 Agent Note（agent 决策记录）](../architecture/2026-07-16-explicit-turn-cancellation.md)。
+
+多余的公开接口使得循环不得不承载一个本质上属于内部拆卸的公开动词：`abort()` 必须被文档描述为有别于队列感知的取消，尽管 UI 取消几乎总是需要更广泛的操作。
+
+## 决策
+
+`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用 `cancel()` 放弃当前和已排队工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 契约。
+
+`whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开 seam 等待结算的 agent 测试（`packages/ui/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/ui/acp/src` 本身没有 `whenIdle()` 调用。
+
+公共 `abort()` 已不存在，disposer 仍为异步并等待循环停止。测试通过公共类型化原因和显式 signal seam 验证取消，而不会伸入 holder 内部。
+
+## 曾考虑的替代方案
+
+**同时移除 `whenIdle()`**：最初提案的形态，在对照代码验证前提后被推翻（上方的实现说明记录了完整过程）：它是承重的完全停稳原语，迫使消费方手动观测 `running`→`idle` 转换正是防御性模式所警告的脆弱路径。
+
+## 验证
+
+`Agent` 不再暴露公开的 `abort()`，而 `cancel()`、`whenIdle()` 和 `steer()` 保留；ACP 取消调用 `cancel()`；拆卸通过 handle disposal 等待完全停稳，`whenIdle()` 在完全停稳时为非所有者观测者 resolve；测试套件覆盖取消和 disposal 作为两条受支持的停止路径。
+
+## 后果
+
+未来的插件无法通过公开接口仅中止当前模型/工具步骤而保留队列中的提示词。如果该用例变为现实需求，它应当带着一个具名消费方和更窄的契约回归。目前它是将私有循环机制保持公开的潜在泛化。
+
+## 相关
+
+本 Agent Note 只移除冗余的停止动词。轮次中途 steering 仍是一条有意保留的消息路径；完全停稳观察仍通过 `whenIdle()` 完成。最终公共表面包括 `send()`、`steer()`、`inject()`、`cancel()`、`whenIdle()`、status、options、会话和 identity。
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
new file mode 100644
index 0000000000..9e90a3a343
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-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
+2026-06-20-remove-agent-boundary-mirror-events.md: 8c5bb74f2347fe0269cbb9c6504137de761ab919
+2026-06-20-remove-agent-boundary-mirror-events.zh.md: 1bb166b7f4453b4f0605e2b1b9120bc5a05266b0
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 910eb46e92..8c5bb74f23 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
@@ -2,6 +2,8 @@
 
 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").
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
new file mode 100644
index 0000000000..1bb166b7f4
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md
@@ -0,0 +1,47 @@
+# Agent Note: 停止将持久化边界镜像为 agent 事件
+
+Status: implemented
+
+[English](2026-06-20-remove-agent-boundary-mirror-events.md) | 中文
+
+<!-- 以修订、收窄后的形式落地：
+     移除了四个轮次/步骤边界镜像；此处保留了 `agent/steering` 和
+     `agent/stream-chunk`（它们不是持久边界镜像——参见
+     “范围：移除什么、不移除什么”）。原始提案将 `agent/steering` 与其他项一并
+     移除；把它排除在外，使本 Agent Note 的范围保持在边界上。后来每个保留事件
+     都由各自的决策移除——参见
+     [停止将 token 流镜像为 agent 事件](2026-07-02-remove-stream-chunk-mirror.md)
+     和[移除 `agent/steering` 镜像 emit](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）已经为面向编辑器的 transcript 选择会话日志，因为它是唯一持久、可重放的记录；消费实时镜像需要把它的时序与日志中已经存储的边界进行调和。stdio UI 是唯一仍从镜像事件渲染轮次边界的生产消费方；它已经从 `session/event` 渲染工具调用和结果。
+
+这种重复并非零成本。每次生命周期变更都需要同时更新会话事件、镜像事件、文档、不变式、测试和快照预期。重复的边界事件还使失败排序变得微妙：一个轮次可能在实时 `agent/turn-end` 监听器运行之前就已被持久化关闭，因此边界之后的监听器失败在日志中已没有合法位置可以插入，只能带外上报。
+
+## 决策
+
+将 `session/event` 作为唯一的实时边界/transcript（文本记录）流。需要渲染轮次、工具调用、工具结果、助手消息和持久化边界的消费方统一订阅 `session/event`，从持久化层使用的同一套事件词汇中派生 UI。
+
+四个持久边界镜像——`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（agent 决策记录）](../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/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`。
+
+保留——不是持久边界镜像，因此不在本决策范围内：
+
+- `agent/steering`——不是边界，因此不在本决策范围内（原始提案将其一并移除；在此会造成范围蔓延）。它镜像持久的 `steering/message` 控制记录，而非边界，后来由自己的后续决策移除：[移除 `agent/steering` 镜像 emit](2026-07-04-remove-agent-steering-mirror.md)。
+- `agent/stream-chunk`——实时 token 流。不在本决策范围内（它镜像持久的 `assistant/chunk`，而非边界），后来由自己的后续决策移除：[停止将 token 流镜像为 agent 事件](2026-07-02-remove-stream-chunk-mirror.md)。
+- `agent/created`、`agent/disposed`、`agent/status`、`agent/error`、`agent/queued`——不属于 transcript 数据的生命周期/控制事件。尤其是 `agent/queued`，它是在任何持久事件存在之前触发的 inbox 确认（取消的排队工作可能永远不会进入日志），所以有意只保留为实时事件。
+
+## 曾考虑的替代方案
+
+- **将 `agent/steering` 一并移除**——原始提案的形状；作为范围蔓延被排除：它镜像持久的 `steering/message` 控制记录，而非边界，后来由[自己的决策](2026-07-04-remove-agent-steering-mirror.md)移除（`agent/stream-chunk` 也由[流分片镜像 Agent Note](2026-07-02-remove-stream-chunk-mirror.md)移除）。
+- **为 stdio UI 保留轮次镜像**——[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 的原始立场；在此否决，因为 `dsh-ui-stdio` 是可随时丢弃的测试 REPL，而非承载关键约束的消费方，并且它改为根据 `session/event` 加自己的实时目标对象渲染边界。
+
+## 后果
+
+插件不能再从便捷的 `Agent` 优先事件观察轮次/步骤边界。它需要订阅 `session/event`；如果需要实时对象，则通过 `ctx.agents` 解析共享 id，或保留自己已经拥有的对象。这是可以接受的取舍：边界消费方不应依赖可能与持久日志发生漂移的第二条事件 feed。
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
new file mode 100644
index 0000000000..291dd7d009
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-unify-agent-and-session-id.md: c55152f4f13fe0acb530503e84f465799007cff7
+2026-06-20-unify-agent-and-session-id.zh.md: 1fa2fe1fd64478bfe17c590e45abd0cf8281cbe4
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 a8a2c375b5..c55152f4f1 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-unify-agent-and-session-id.zh.md)
+
 ## Problem
 
 A live agent/session pair needs one identity for registry routing, event sourcing, and persistence. Giving the factory independent `agentId` and `sessionId` inputs would permit pairings no production path can use, while forcing every consumer to choose or translate between two names for the same lifecycle.
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
new file mode 100644
index 0000000000..1fa2fe1fd6
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md
@@ -0,0 +1,40 @@
+# Agent Note: 统一 agent id 与会话 id
+
+Status: implemented
+
+[English](2026-06-20-unify-agent-and-session-id.md) | 中文
+
+## 问题
+
+一个实时 agent（智能体）/会话对需要使用同一 identity 完成注册表路由、事件溯源和持久化。让 factory 接受相互独立的 `agentId` 和 `sessionId` 输入，会允许任何生产路径都无法使用的配对，同时迫使每个消费方为同一生命周期在两个名称之间选择或转换。
+
+ACP（Agent Client Protocol）对两种 identity 使用相同值。Stdio 和钩子也在会话事件流上工作，并且直接需要对应的实时 agent；没有生产路径会把一个实时 agent 对象重新附着到多个会话，或通过多个 agent id 驱动一个会话。
+
+[agent 范围运行时](../architecture/2026-07-12-agent-scope-runtime-design.md)使用同一个 `AgentCreationTransaction` 执行创建和恢复，agent/会话条目共享相同的最终条目冲突规则。第二个 identity 并不代表单独的存活性、回滚或完全停稳；它只会围绕同一事务增加 API 与转换状态。
+
+会话 identity 同样只有一个归属，即 `Session.header.id`；`Session.id` 是派生访问器，而非需要重复验证的独立状态。
+
+## 决策
+
+agent 的注册表 id 等于其会话 id。`CreateAgentOptions` 接受一个 `sessionId`，同时用于两个最终注册表条目；恢复时以 `resumeSessionId` 注册 agent；进程内 subagent 创建使用子会话 id；`Session.id` 则派生自 `header.id`。远程 ACP 运行没有本地 agent/会话对：它保留一个由父项铸造的生命周期 id，而子服务器线协议内的会话 id 仅用于 ACP 调用。现有创建事务、最终条目冲突检查和精确条目分离语义保持不变；唯一职责是在本地 id 之间转换的 map 与字段已经消失。
+
+配置驱动路径保留 `agents[].id` 作为稳定配置标签，而非实时路由 identity。普通的全新启动会铸造组合 id `${label}-session-${randomUUID()}`，使持久重启不会冲突。耦合应用可以预先铸造并传入精确的 `sessionId`：首次使用时创建它，而当持久化服务已经存在时，AgentLoop 重新挂载会在同一 identity 下恢复已物化历史。`resumeSessionId` 则要求已有的持久化 identity。两个精确 id 输入互斥。Stdio 使用“恢复或创建”形式，使配置创建的 agent 和 UI 在循环重载之间共享一个不透明 identity，而不是根据前缀猜测。日志可以使用稳定标签，而所有实时与持久查找都使用同一个 `SessionId`。
+
+`agent/created` 和 `agent/disposed` 保留。它们是成对的发布生命周期事件，而非 identity 别名；以后若发现没有消费方并要移除，必须先重新搜索，再提出独立提案。
+
+## 曾考虑的替代方案
+
+**保持路由与日志 identity 分离。** 稳定的配置标签加全新的持久对话确实有用，但不需要两个实时 identity：标签可以继续作为配置/显示元数据，而每次运行的组合 `SessionId` 负责路由和持久化。保留两个 id 会让转换 map 持续存在，允许不可能的配对，却不会增加生命周期功能。
+
+## 验证
+
+- Agent 创建/恢复和 subagent 创建只携带一个 identity，`Session` 也只在一个位置存储它。
+- 创建事务继续覆盖最终条目冲突、精确条目分离、回滚和完全停稳，无需 identity 特有的生命周期状态。
+- 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 全部通过。
+
+## 后果
+
+这排除了潜在的多会话 actor 和会话交接设计，并使由客户端选择、已持久化的会话 identity 成为注册表 identity。如果独立路由 identity 成为真实需求，就需要显式的生命周期设计，而不是由调用方提供一对不受约束的值。
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
new file mode 100644
index 0000000000..6e428fa348
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-26-fsspec-style-fs-seam.md: d496f273e2635624e0ab8e70e06c8729563c5466
+2026-06-26-fsspec-style-fs-seam.zh.md: 18e4be5177f593253dc100a864b6c741904a90b2
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 3753fb803a..d496f273e2 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-26-fsspec-style-fs-seam.zh.md)
+
 ## Problem
 
 The filesystem capability from [filesystem-capability-seam](../architecture/2026-06-17-filesystem-capability-seam.md) currently makes one abstract `FileSystem` service own two different jobs:
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
new file mode 100644
index 0000000000..18e4be5177
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
@@ -0,0 +1,130 @@
+# Agent Note: 拆分文件系统 seam——提供方文本变更操作与 `dsh-fs-policy` 插件
+
+Status: implemented
+
+[English](2026-06-26-fsspec-style-fs-seam.md) | 中文
+
+## 问题
+
+[文件系统能力 seam](../architecture/2026-06-17-filesystem-capability-seam.md)中的文件系统能力目前让一个抽象 `FileSystem` 服务同时负责两项不同工作：
+
+1. **提供方操作**——解析目标、stat/版本元数据、文本读取/流式读取、原子写入，以及受保护的字面编辑。
+2. **面向 agent（智能体）的策略**——行窗口、字面编辑语义，以及读后写/编辑的观测状态。
+
+这导致每个未来的后端都要重新实现面向模型的读取语义和观测策略。`readPage` 返回带行号的行和视图元数据；基础服务按 owner 存储文件状态，并区分 `full` 与 `partial` 读取。这些是有用的策略，但它们不是文件系统提供方的原语。字面文本变更则不同：版本守卫、字面匹配、歧义检测与原子重写必须留在提供方的变更边界内，但当前的 `applyEdit` 命名及其周围的 seam 将这一提供方操作绑定到了旧的读后编辑策略形状上。
+
+这还造成了一个真实的用户体验死胡同：窗口化读取记录 `view: partial`，而 partial 视图无法授权 `edit`。一个模型读取了大文件的第 100-150 行，如果想编辑第 120 行，就必须先获取一次 `full` 读取，而对于超过读取上限的文件这可能做不到。字面编辑实际上只需要新鲜度：被匹配的字节仍然来自模型所读取的那个版本即可。
+
+旧 Agent Note（agent 决策记录）已经推迟了独立的 `@deepseek-ai/dsh-fs-policy` 包。本 Agent Note 构建该层，使 `ctx.fs` 保持接近 fsspec 风格的存储原语（`info`/`cat`/`open`），但不把它变成完整的 fsspec。
+
+## 决策
+
+将栈拆为四层：
+
+```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      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`。本文描述已经落地的事件门禁形状；提供方的版本守卫可选（省略即无条件裸提供方）。
+
+## 提供方契约
+
+`@deepseek-ai/dsh-fs` 收缩为提供方文本 IO 加受保护的文本变更：
+
+```ts ignore-check
+abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
+abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
+abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
+abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
+abstract writeText(target: FsTarget, content: string, expected: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
+abstract editText(target: FsTarget, edit: FsEditRequest, expected: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
+
+interface FsInfo {
+  version: FsVersion
+  type: 'file' | 'directory' | 'other'
+  size?: number
+}
+
+type FsWriteIntent =
+  | { kind: 'createIfAbsent' }
+  | { kind: 'replaceIfVersion'; version: FsVersion }
+```
+
+`stat` 返回元数据而非内容。`version` 是新鲜度令牌；`type` 让执行器在读取前拒绝目录/特殊文件；`size` 让 `read` 工具无需通过失败探测即可选择 `readText` 还是 `streamText`。`undefined` 表示目标不存在。
+
+`readText` 读取整个常规文本文件。`streamText` 以相同的文本语义流式读取大文件。两个提供方原语负责常规文件检查、UTF-8 解码、二进制/NUL 拒绝以及 `FS_NOT_TEXT`；策略层从不处理原始字节，也不重新实现跨分片解码。`readText` 是小文件/直接全文件原语，而面向模型的大文件读取使用 `streamText`。
+
+`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，而无需策略层拉取整个文件。
+
+这是一个*文本存储* seam，刻意比字节级 fsspec（`cat`/`open` 返回原始字节）高半个层次。UTF-8 解码、二进制/NUL 拒绝、受保护的全文件写入和受保护的字面文本编辑都在提供方内完成，因此策略层从不接触原始字节、不重新实现跨分片解码、也不将陈旧检查与变更临界区分离。面向模型的概念仍然不下沉到提供方：行窗口、带行号的行、渲染的页脚、观测状态存储都不会泄漏下去。
+
+从 `dsh-fs` 删除：`readPage`、`FsExpectation`、`FsView`、`FsStateSource`、`FsReadRequest`、`FsTextLine`、行/窗口常量、`formatReadBody` 和 observed-state `WeakMap`。`applyEdit` 由更窄的提供方原语 `editText` 取代，其契约是带版本守卫的字面文本变更，而非策略层读取授权。`FS_PARTIAL_OBSERVATION` code 也从 `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) 将其细化为本文所述插件，使工具永远不会在方法层与策略耦合。）
+
+观测状态以 `WeakMap<owner, Map<targetKey, FsVersion>>` 的形式存放于此。当且仅当 owner 读取、写入或编辑过该目标时，条目才存在（每次成功都会发出 `fs/observed`），因此条目的存在*本身就是*先前观测的记录——没有单独的 `hasRead` 标志。owner 从不透明的事件 actor（`{ agent?: { session? } }`）结构化派生，该形状定义在 `dsh-fs-policy` 中而非 `dsh-fs` 中。
+
+该插件决定三个 `fs/*` 事件：
+
+- `fs/write-intent`——无先前观测 ⇒ `{ kind: 'createIfAbsent' }`（只有新文件可以盲创建）；有先前观测 ⇒ `{ kind: 'replaceIfVersion', version: vObserved }`（已有文件仅在自观测以来未变时才替换）。单槽决策；不调用 `next()`。
+- `fs/edit-intent`——要求 owner 有先前观测（否则 `FS_NOT_OBSERVED`）；返回 `{ version: vObserved }` 作为 CAS 基础。它不实现字面替换——它授权并提供版本，提供方的变更临界区负责应用守卫，因此基于同一观测版本的并发编辑仍然是一赢一陈旧。
+- `fs/observed`——在成功的读取/写入/编辑后，为该 owner+target 记录 `{ version }`。同步、仅副作用的 `WeakMap.set`。
+
+该插件不做任何文件系统 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/*` 事件。
+
+每个变更操作先分发其 intent waterfall（瀑布式事件），带有 `undefined` 裸提供方默认值，然后调用 `ctx.fs`，再发出 `fs/observed`。例如 `write` 执行 `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` → `ctx.fs.writeText(target, content, intent)` → `ctx.emit('fs/observed', …)`。`read` 先 stat 一次，然后读取/流式读取，构建窗口，最后发出 `fs/observed`。将 `exec` 作为 actor 传递，让 `dsh-fs-policy` 无需工具深入策略即可派生 owner。
+
+由于策略通过带有 `undefined` 默认值的事件贡献，`dsh-tool-fs` 不与 `dsh-fs-policy` 产生方法耦合：在插件缺席时，每个 intent waterfall 都落到 `undefined`（无条件裸提供方写入/编辑），`fs/observed` 没有监听器。加载插件后即可叠加读后写/编辑策略。
+
+## 并发边界
+
+进程内更新是安全的：本地后端保持既有的按目标变更锁，因此版本检查-然后-rename 是串行化的，失败的更新会看到 `FS_STALE_VERSION`。
+
+进程内创建由同一个按目标变更锁保护：两个调用者以 `createIfAbsent` 竞争时串行化，一个创建成功，另一个看到目标已存在并收到 `FS_NOT_OBSERVED`。跨进程创建仅为尽力而为；本地的 stat-then-rename 守卫无法在所有未来后端上提供可移植的排他创建保证。
+
+跨进程写入是尽力而为的新鲜度加原子替换：`mtime:size` 通常能捕获编辑器保存，但同一 tick 相同大小的写入可能遗漏；原子的 temp+rename 防止文件撕裂但不能防止所有丢失更新。
+
+## 取代
+
+本 Agent Note 推翻[文件系统能力 seam](../architecture/2026-06-17-filesystem-capability-seam.md)中的两项决策，并收窄第三项：
+
+- 读后写/编辑策略从 `ctx.fs` 移出，进入 `dsh-fs-policy` 插件（通过 `fs/*` 事件门控）。
+- 文本读取不再返回后端编号的行记录或 `full`/`partial` 视图；授权基于版本新鲜度，因此窗口化读取在文件未变时即可授权编辑。
+- 字面编辑不再位于旧的 `applyEdit` API 之后（该 API 混合了后端变更与 seam 拥有的观测策略）。它作为 `editText` 保留为提供方原语，因为版本守卫 + 字面匹配 + 原子重写必须留在提供方的变更临界区内。
+
+保留的内容：接口/实现/消费方纪律、消费方不导入后端规则、后端定义的 target/version/display 元数据、原子本地写入，以及共享的 `FsError` 分类体系。
+
+## 验证
+
+`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（资源释放）覆盖率。
+
+## 后续扩展
+
+后来，[为文件系统 seam 添加直接目录列表](../architecture/2026-07-03-filesystem-directory-listing-seam.md)进一步扩展了该 seam。该后续工作单独跟踪，使本 Agent Note 的验收标准继续描述最初落地的 fsspec 风格改造。
+
+## 曾考虑的替代方案
+
+- **字节级 fsspec（`cat`/`open` 返回原始字节）**：否决。该 seam 刻意定位为文本存储，比字节级高半个层次，这样 UTF-8 解码、二进制/NUL 拒绝和受保护的文本变更只在提供方实现一次，策略层从不接触原始字节，也不将陈旧检查与变更临界区分离。
+- **具体的 `ctx.fileContext` 方法服务**——本 Agent Note 最初的策略形状；[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 将其重做为门禁插件，使工具永远不会在方法层与策略耦合。
+- **在提供方保留 `readPage` 和 `full`/`partial` 视图授权**：「取代」一节所逆转的重构前形态。视图完整性不是编辑安全所需的，版本新鲜度才是；而视图规则使超过读取上限的大文件无法编辑。
+
+## 后果
+
+- 新增第四个 fs 包和一个新的插件层。这是有意为之：它是此前推迟的策略层，而非第二个抽象后端 seam。
+- 直接使用 `ctx.fs` 会绕过策略：直接 `ctx.fs.readText` 不发出 `fs/observed`，因此在默认策略下，后续 `edit` 会以 `FS_NOT_OBSERVED` 拒绝，直到通过 `read` 工具读取该文件。这一失败是显式且有文档记录的。
+- 大文件行窗口化从后端移至 `dsh-tool-fs` 中的 `read` 工具；文本解码和二进制拒绝留在 `ctx.fs.streamText` 中，因此这只是窗口化逻辑的迁移，而非第二套文本 IO 实现。
+- 将 `editText` 保留在提供方 seam 上意味着每个后端都必须实现字面替换契约。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该契约应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
+- 新鲜度允许在窗口化读取后进行全文件 `write`。这比旧的视图检查更弱，但避免了大文件无法编辑的问题；提示词引导仍然不鼓励盲目的全文件替换。
diff --git a/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.i18n.yaml
new file mode 100644
index 0000000000..b6b4adcc16
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-02-remove-stream-chunk-mirror.md: 5dd816940a4b2c2b63980e01f1bd4e0aac53a3e2
+2026-07-02-remove-stream-chunk-mirror.zh.md: ca65a3c2ad46d14835416c14d0087ef542de03bb
diff --git a/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.md b/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.md
index c79202b95a..5dd816940a 100644
--- a/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.md
+++ b/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-02-remove-stream-chunk-mirror.zh.md)
+
 ## Problem
 
 The loop records every model token delta as a durable `assistant/chunk` session event AND emitted a parallel live `agent/stream-chunk` Cordis event carrying the identical data. In `packages/core/agent-loop/src/loop.ts` the two sat one line apart:
diff --git a/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.zh.md b/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.zh.md
new file mode 100644
index 0000000000..ca65a3c2ad
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.zh.md
@@ -0,0 +1,47 @@
+# Agent Note: 停止将 token 流镜像为 agent 事件
+
+Status: implemented
+
+[English](2026-07-02-remove-stream-chunk-mirror.md) | 中文
+
+## 问题
+
+agent loop（智能体循环）将模型的每个 token delta 同时记录为持久的 `assistant/chunk` 会话事件，并发射一个携带相同数据的并行实时 `agent/stream-chunk` Cordis 事件。在 `packages/core/agent-loop/src/loop.ts` 中，二者仅相隔一行：
+
+```ts ignore-check
+const chunkEvent = session.append('assistant/chunk', { turn, step, chunk })
+chunkSeqs.push(chunkEvent.seq)
+ctx.emit('agent/stream-chunk', agent, turn, step, chunk)   // ← the mirror
+```
+
+- 持久事件：`assistant/chunk: { turn, step, chunk }`。
+- 实时发射：`agent/stream-chunk(agent, turn, step, chunk)`——相同的 `StreamChunk`，相同的 `turn`/`step`。
+
+实时发射相比会话事件唯一多出的东西是实时的 `Agent` 句柄，而唯一的消费方直接丢弃了它（其处理函数签名为 `(_agent, _turn, _step, chunk)`）。
+
+这与[移除边界镜像](2026-06-20-remove-agent-boundary-mirror-events.md)为轮次/步骤边界消除的重复相同：消费方面对同一持久事实的两个真源，每次变更都必须同时触及两者。该 Agent Note（agent 决策记录）没有把分片流一并纳入，而是推迟处理（“`assistant/chunk` 持久化仍承载关键约束，所以以后可以将分片流作为镜像评估，但那是一项独立决策”）。本 Agent Note 就是那项独立决策。
+
+推迟所依赖的前提已经明确：分片持久化是权威的，且将保留。停止持久化分片、仅保留瞬态实时流事件的提案已被[否决](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)——高保真回放、部分失败的流以及快照回放都依赖持久化的 `assistant/chunk` 序列。因此 `session/event` 上的 `assistant/chunk` 是持久的、承重的 token 流，而 `agent/stream-chunk` 是它的纯冗余镜像。
+
+## 决策
+
+从 agent 事件分类体系中移除 `agent/stream-chunk`。token 流通过 `session/event` 以 `assistant/chunk` 的形式读取——持久化与回放已经使用的正是同一个序列。`session/event` 是唯一的实时 transcript（文本记录）流（assistant 分片、轮次/步骤边界、工具活动、todo）。
+
+**消费方。** 唯一重要的生产消费方——ACP（Agent Client Protocol）桥接（`dsh-acp`，面向编辑器的真实流式输出接口）——已经从 `session/event` 渲染 `assistant/chunk`，从未使用 `agent/stream-chunk`，因此不受影响。stdio UI（`dsh-ui-stdio`，一个一次性的测试 REPL）是唯一的实时消费方；它在边界迁移时已经有了 `session/event` 监听器，因此其分片渲染被折叠进该监听器作为 `assistant/chunk` 分支。合并为一个监听器还消除了一个潜在隐患：`inReasoning` dim-SGR 标志此前在两个独立监听器（`agent/stream-chunk` 和 `session/event`）之间共享，分片与边界在该标志上竞争时没有确定的顺序；单一监听器按追加顺序处理，使交错变为确定性的。
+
+## 范围
+
+移除：`agent/stream-chunk`。
+
+未触及：
+- `assistant/chunk`（持久会话事件）——权威 token 流，原样保留。本 Agent Note 移除的是实时镜像，而非持久化（移除持久化的提案已单独遭到拒绝——见上文）。
+- `agent/steering`——本决策未触及（它是控制信号，不是 token 流）。其持久孪生事件是 `steering/message`，镜像发射由其自身的后续 Agent Note 移除：[移除 `agent/steering` 镜像发射](2026-07-04-remove-agent-steering-mirror.md)。
+- `agent/status`、`agent/error`、`agent/created`/`agent/disposed`、`agent/queued`、`agent/session-start`——生命周期/控制事件，不是 transcript 数据，也没有持久副本。
+
+## 曾考虑的替代方案
+
+**移除持久化、仅保留瞬态实时流**——反向裁剪，已被[单独否决](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)：高保真回放、部分失败的流以及快照回放都依赖持久化的 `assistant/chunk` 序列。在此前提确定后，实时发射才是配对中冗余的那一半。
+
+## 后果
+
+插件不能再从 `Agent` 优先事件观察 token 增量。它需要订阅 `session/event`、过滤 `assistant/chunk`，并在需要时通过 `ctx.agents.get(session.id)` 直接查找对应的实时 handle。没有生产消费方需要在分片时刻取得实时 `Agent`；这与移除边界镜像所作的取舍相同，均可接受。
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
new file mode 100644
index 0000000000..464ffc54d4
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-drop-image-content-block.md: 566803ab5b9f213b7dc87fcf779ed7a963d988fd
+2026-07-04-drop-image-content-block.zh.md: 667ddbc1b7bce2a276fe7528f46d3e43916bad83
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 df63f2a78f..566803ab5b 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-drop-image-content-block.zh.md)
+
 ## Problem
 
 `ImageBlock` (`packages/llm/llm/src/types.ts`) had no production producer, and every consumer on every path DROPPED it: the deepseek adapter's serializer skipped image blocks (a documented MVP limitation), the pi-ai converter skipped them as unrepresentable, the ACP codec neither advertises image prompt capability nor forwarded image blocks outbound and REJECTS image prompt content inbound, and the compaction estimator charged a flat token constant and rendered `[image]`. An `ImageBlock` constructed then would silently vanish from the wire — the vocabulary advertised a capability no path honored, which is the silent-data-loss shape AGENTS.md's defensive patterns warn against. The only constructors anywhere were tests pinning the skip/drop/estimate branches.
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
new file mode 100644
index 0000000000..667ddbc1b7
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 移除 `image` 内容块，直到有路径能真正处理它
+
+Status: implemented
+
+[English](2026-07-04-drop-image-content-block.md) | 中文
+
+## 问题
+
+`ImageBlock`（`packages/llm/llm/src/types.ts`）没有任何生产环境的生产者，而每条路径上的每个消费方都将其丢弃：deepseek 适配器的序列化器跳过 image 块（这是文档中注明的 MVP 限制）；pi-ai 转换器因无法表示而跳过；ACP（Agent Client Protocol）编解码器既不宣告图像提示词能力、也不向外转发 image 块，并且会拒绝入站的图像提示词内容；压缩（compaction）估算器对其收取一个固定 token 常量并渲染为 `[image]`。此时构造的 `ImageBlock` 会在协议格式（wire format）上静默消失——词汇宣告了一种没有任何路径兑现的能力，这正是 AGENTS.md 防御性模式所警告的静默数据丢失形态。唯一的构造调用出现在测试中，用于覆盖 skip/drop/estimate 分支。
+
+## 决策
+
+移除 `ImageBlock`、其 map 条目，以及适配器、ACP 渲染和压缩中的 image 专用分支。在同一个变更中更新所属的词汇文档与生成的引用。未知扩展块仍然覆盖默认分支，ACP 继续独立于 harness 词汇拒绝入站的图像提示词内容。
+
+## 曾考虑的替代方案
+
+### 为什么不保留？
+
+当适配器、ACP 和压缩全部支持 image 时，`ContentBlockMap` 可以重新引入。保留一个唯一实现就是拒绝的核心类型，等于宣告一个不可用的对外服务接口；移除后，生产者会立即得到编译期错误。
+
+评审中记录的回退方案（假如评审决定保留该槽位）：保留 `ImageBlock`，但将所有静默跳过替换为显式拒绝，并在词汇文档中记录该策略——静默丢弃是唯一没有辩护者的状态。评审最终决定移除；此回退方案作为文档化的替代方案保留，以备该槽位在完整功能就绪之前回归。
+
+## 验证
+
+除 Agent Note（agent 决策记录）之外，没有任何地方构造 harness `ImageBlock`。ACP 独立的入站图像拒绝路径仍有测试；适配器、codec 和压缩的默认分支则使用插件定义的块类型覆盖。
+
+## 后果
+
+日后重新添加核心词汇类型需要同时改动多个包（package）——但这种协调变更本就是真正的多模态功能所需的形态（适配器映射、ACP 能力宣告、压缩定价），而当前并不存在需要保留的实现。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.i18n.yaml
new file mode 100644
index 0000000000..4d018139c5
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-drop-inert-request-knobs.md: 06fa6c1c539f9ff0cfabf76bc41c53800bd46c8c
+2026-07-04-drop-inert-request-knobs.zh.md: 42aadde2b279a453fac9444060b8ac34bf9e3c8b
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.md b/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.md
index dadab43f76..06fa6c1c53 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-drop-inert-request-knobs.zh.md)
+
 ## Problem
 
 Two request-contract knobs rode the whole request pipeline, yet neither could do anything:
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.zh.md b/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.zh.md
new file mode 100644
index 0000000000..42aadde2b2
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 移除 `GenerateOptions.prefill` 与 `ToolSchema.strict`——无端到端可用路径的请求旋钮
+
+Status: implemented
+
+[English](2026-07-04-drop-inert-request-knobs.md) | 中文
+
+## 问题
+
+两个请求契约旋钮贯穿了整条请求流水线，却都无法产生任何效果：
+
+- **`prefill`**（`packages/llm/llm/src/types.ts`）没有生产级的 setter：agent loop（智能体循环）组装的是 `model`/`system`/`tools`/`messages` 加 `sessionId`/`signal`，上下文压缩（context compaction）后端只追加 `maxTokens`；而且两个适配器都拒绝它：`packages/llm/llm-deepseek/src/serialize.ts` 和 `packages/llm/llm-pi-ai/src/adapter.ts` 各自在 `prefill` 非 undefined 时抛出 `LlmError('UNSUPPORTED')`。该字段的全部可观测行为就是两个 throw，各由一条适配器测试固定。DeepSeek 的 chat-prefix completion 是一个 Beta 功能，运行在两个适配器都未指向的 base URL 上。
+- **`strict`**（`ToolSchema`，同一文件）穿过了 `DefineToolOptions`/`defineTool`（`packages/core/tools/src/schema.ts`）、注册表的 `schemas()` 允许列表（`packages/core/tools/src/index.ts`）、deepseek 协议格式（wire format）映射（`packages/llm/llm-deepseek/src/serialize.ts`，其 wire-type 注释记录了 strict 模式需要适配器未使用的 `/beta` base URL）、`packages/llm/llm-pi-ai/src/adapter.ts` 中的逐工具 payload 修补逻辑，以及 tool-catalog 渲染器（`scripts/gen-tool-catalog.ts`）中的条件 `Strict:` 行。没有任何已发布的工具设置过它——在所有 `tool-*` 包的 src 和 `examples/` 中执行 `rg` 搜索，`strict:` 的生产者为零；唯一的 setter 出现在 dsh-tools 单元测试中。
+
+两个旋钮在适配器间是对称的，因此移除操作将它们从两个孪生适配器中一并剥离——[孪生适配器设计](../architecture/2026-06-13-twin-llm-adapters.md)不受影响。
+
+## 决策
+
+- 从 `GenerateOptions` 中移除 `prefill`，同时移除两个适配器的 UNSUPPORTED 守卫、固定抛错行为的测试、[core.md](../../../../docs/core-data-structures/core.md) 中的粘贴行，以及记录该拒绝行为的适配器 README 表格行。实操手册中的 UNSUPPORTED 指导（[adding-an-llm-adapter.md](../../../../docs/cookbook/adding-an-llm-adapter.md)）改为通用表述规则——提供方无法遵守的 `GenerateOptions` 字段应抛出 `LlmError(..., 'UNSUPPORTED')`——而不再以 prefill 为例。[内容块词汇 Agent Note（agent 决策记录）](../architecture/2026-06-11-content-block-vocabulary.md)的后果按照 [implemented/AGENTS.md](../AGENTS.md)，将 prefill 记录为由生产者门控，而不是已有归属。
+- 从 `ToolSchema`、`DefineToolOptions`、`defineTool`、`schemas()` 允许列表、deepseek 序列化分支及其 wire-type 字段，以及工具目录渲染器的 `Strict:` 行中移除 `strict`。pi-ai 的 payload 修补逻辑简化为对 pi-ai 自身逐工具 strict 默认值的无条件清除（pi-ai 在每个序列化的工具上打 `strict: false`；手写的孪生适配器不发送此字段，因此清除逻辑为保持协议格式对等而保留，由其序列化器测试固定）。setter 测试和 core.md 粘贴行已移除；`GenerateOptions` 与 `ToolSchema` 在 `scripts/type-equiv.manifest.json` 中保留各自的行，因为两个类型只是少了一个字段，本身仍然存在。
+
+本 Agent Note 刻意不触及 `temperature`、`stop` 或 `maxTokens`：两个适配器都会端到端遵守它们，而且它们自然是 `agent/request` 上修改请求的钩子插件首批目标。
+
+## 曾考虑的替代方案
+
+### 为什么不保留？
+
+「显式的 UNSUPPORTED throw 是诚实的契约行为」——但一个在两个孪生适配器中唯一的实现就是拒绝的旋钮，什么也没承诺；删除它反而升级了失败模式：意外的 setter 变成编译错误而非运行时 throw。「Strict schema 遵循是官方文档记载的提供方功能，且管道完整」——但一个旋钮在有已发布的工具设置它并且有端点兑现它之前，不构成产品表面；今天两者都不成立。它们各自随首个真实 producer 回归：`prefill` 随实现了 chat-prefix completion 的适配器（以及对不支持该功能的适配器的明确策略）一起回来；`strict` 随需要它的工具和 beta 端点方案一起回来。
+
+## 验证
+
+`rg prefill` 只返回 Agent Note 记录（本文及[内容块词汇 Agent Note](../architecture/2026-06-11-content-block-vocabulary.md)中由生产者门控的后果）；限定在工具 schema 范围内的 `rg strict` 只返回本 Agent Note、保留下来的 pi-ai 清理逻辑，以及 `strictEqual` 等无关正文。两个适配器的契约测试都能在没有守卫的情况下通过，pi-ai 修正仍会清理库的 strict 默认值——其 serializer 测试固定了线协议一致性。
+
+## 后果
+
+已发布的钩子桥接不设置任何请求字段，而请求变更插件（`agent/request` waterfall（瀑布式事件）监听器）使用的是 `temperature`/`stop`（保留且可用），而非适配器拒绝的字段。如果 chat-prefix completion 或 strict 模式成为产品功能，重新添加将随适配器/端点工作一起落地，届时契约能说明实际发生了什么，而不是「所有人都 throw」。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.i18n.yaml
new file mode 100644
index 0000000000..2845b37a05
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-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
+2026-07-04-drop-unconsumed-web-observation-surface.md: 5b1cb1307c63ef7c298200ee1655119026b9ebf5
+2026-07-04-drop-unconsumed-web-observation-surface.zh.md: c4351c7e66d00f47e1bf9ed117c5f7b043045808
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md b/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md
index 80faa2ac07..5b1cb1307c 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-drop-unconsumed-web-observation-surface.zh.md)
+
 ## Problem
 
 `WebService` exposes an observation surface no production code observes:
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.zh.md b/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.zh.md
new file mode 100644
index 0000000000..c4351c7e66
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.zh.md
@@ -0,0 +1,34 @@
+# Agent Note: 移除未被消费的 web 观测接口——`providers-change` 事件与 status 方法
+
+Status: implemented
+
+[English](2026-07-04-drop-unconsumed-web-observation-surface.md) | 中文
+
+## 问题
+
+`WebService` 暴露了一组没有任何生产代码观测的观测接口：
+
+- **`web/providers-change`**（`packages/web/web/src/index.ts`）在每次提供方注册和 dispose（资源释放）时声明并发出，且每个注册 effect 的回滚 yield 被刻意排在 emit 之前，唯一目的是让抛出异常的 change listener 能回退注册。在该包自身的两个单元测试之外没有任何 listener（其中一个测试的存在仅仅是为了固定那个回滚顺序）。
+- **`searchStatus()` / `fetchStatus()` 与 `WebCapabilityStatus` 联合类型**（同一包）没有生产调用方：`dsh-tool-web` 直接通过 `ctx.web.search()`/`fetch()` 执行，并把不可用性呈现为 seam 在执行时抛出的结构化 `WebError` code（`packages/web/tool-web/src/search.ts`、`packages/web/tool-web/src/fetch.ts`）；唯一的 status 调用方是 web 包自己的测试。`packages/web/tool-web/README.md` 和 [architecture.md](../../../../docs/architecture.md) 中的正文声称工具“只读取聚合的 `searchStatus()`/`fetchStatus()`”——这种漂移之所以存续，只是因为没有机制对照调用位置检查正文。
+
+seam 自身的设计使这两个接口天然没有消费方：工具注册跟随产品 ENABLEMENT 而非提供方可用性（`packages/web/tool-web/src/index.ts`），提供方选择在执行时解析且从不缓存——因此没有需要失效的缓存、没有需要重算的注册集合、也没有调用方需要一个有别于「执行并路由结构化错误」的可用性探测。HMR（热模块替换）清理由 effect disposer 自身承载。
+
+这与[删除无人消费的 `llm/adapter-change` 事件](2026-06-20-drop-unconsumed-llm-adapter-change-event.md)相呼应；后者从 `LlmService` 移除了相同的通知形状、相同的 emit 前回滚机制和相同的监听器抛错测试。该 Agent Note（agent 决策记录）的保留/删除标准是：为可能面向用户的工具列表消费方保留 `tools/change`，删除启动时后端注册表信号。按这一标准，web 提供方注册表明确属于删除一侧；status 方法则是把同一判断应用于拉取表面，而非推送表面。
+
+## 决策
+
+移除注册表变更事件、聚合 status 方法与类型，以及它们的专属测试。提供方私有的 status 保留用于执行时选择。面向调用方的覆盖率现在断言成功执行或结构化的选择错误，web 文档描述该按需调用契约。
+
+## 曾考虑的替代方案
+
+### 为什么不保留？
+
+web seam Agent Note 刻意规定了两者——事件作为最小 HMR 可见性信号，status 方法作为工具的聚合诊断——未来也可以设想提供方状态面板。但同一 Agent Note 的其他选择让它们失去了生存条件：调用时派生选择和基于启用状态的注册，使任何消费方都不可能需要其中任一项；已发布工具展示了真实模式（执行并路由结构化错误）；发生漂移的 README 句子则表明承诺中的消费方从未出现。按照 AGENTS.md 所述“Agent Note 是提案，而非绝对真理”，代码后来证明提案中的这些部分超出了需要；未来的观察者应根据真实消费方的形状，重新引入它实际消费的最小信号或查询。
+
+## 验证
+
+除 Agent Note 历史外，不再存在 `providers-change`、`searchStatus`、`fetchStatus` 或 `WebCapabilityStatus` 拼写；目录保持新鲜（`verify-cordis-catalog` 为绿色）；注册/释放 HMR 安全性测试通过执行行为证明清理；tool-web README 和架构段落也描述了工具实际拥有的执行时错误路由契约。
+
+## 后果
+
+未来若有提供方选择器 UI 或诊断面板需要变更通知或 status 查询，它将重新添加自身所消费的最小接口；相同的判断及其反转条件已记录在 LLM（大语言模型）先例中。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.i18n.yaml
new file mode 100644
index 0000000000..3e67070db5
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-fold-stdio-ui-helper.md: 01165df19942e8e0adf84ede3a371f53ad12e464
+2026-07-04-fold-stdio-ui-helper.zh.md: 37b316283e96d7640e1e7af5fdbb05ab487aa6fa
diff --git a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md
index b05dd22357..01165df199 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-fold-stdio-ui-helper.zh.md)
+
 The later [redundant-agent removal](2026-07-20-remove-stdio-and-echo-agents.md) supersedes this package-placement decision and removes the folded package, app, and line-oriented surface entirely.
 
 ## Problem
diff --git a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.zh.md b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.zh.md
new file mode 100644
index 0000000000..37b316283e
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.zh.md
@@ -0,0 +1,30 @@
+# Agent Note: 将 stdio UI 辅助模块折入 stdio 应用
+
+Status: implemented
+
+[English](2026-07-04-fold-stdio-ui-helper.md) | 中文
+
+后来的[冗余 agent（智能体）移除](2026-07-20-remove-stdio-and-echo-agents.md)取代了这项包放置决策，并完整移除合并后的包、应用和面向行的表面。
+
+## 问题
+
+readline UI 曾是一个完整的包（`packages/support/` 下的 `@deepseek-ai/dsh-ui-stdio`），其唯一的运行时导入方是应用包 `@deepseek-ai/dsh-stdio-demo`。示例通过加载应用来使用 readline UI，从不自行组合该辅助模块；仓库中所有其他引用都是因为包边界存在而存在的机械性或描述性表面：manifest（元数据清单）与 tsconfig 条目、生成的 module-graph 行、依赖图与 README 行，以及命名该包的文档注释。ui 组 README 记录了 support 放置的理由（"主要为示例和覆盖率门禁而存在，`ui/` 保留给作为产品交付的界面"），这留下了一个持续的张力：一个已交付的产品应用依赖一个被明确标注为非产品表面的 support 包。
+
+这条边界换来的是：包元数据、workspace 与 tsconfig 引用、module-graph 行、README 条目，以及 publint 表面——服务于一个并不可独立替换的辅助模块：stdio 应用的前门集群始终包含 readline UI，且没有其他消费方能有意义地使用它。
+
+## 决策
+
+当时，该辅助函数移入 `@deepseek-ai/dsh-stdio`，成为终端通道插件。`createStdioChat`、其 `StdioRuntime` 测试 seam 和单元测试随之一同迁移，使 EOF 处理、渲染、释放以及管道/TTY 行为继续受逐文件覆盖率门禁约束，而不会劫持进程全局量。该模块保留应用挂载所消费的具名 `name`/`inject`/`Config`/`apply` 导出形状；当时的 Echo 和 REPL Loader 冒烟证明组合树，插件形状套件则固定显式 `unwrapExports` 行为。上方取代本文的移除记录负责当前包和示例状态。
+
+早期的支持辅助包已移除：其清单、tsconfig 引用、模块图行和 README 行均已消失，其余文档改为描述包内模块。
+
+## 曾考虑的替代方案
+
+### 为什么不将其提升到 `ui/` 而是折入？
+
+提升可以解决 support 与 product 之间的错位，同时保留边界——只有在 readline UI 是一个可独立替换的集成或有第二个组合方时才是正确选择，而消费方普查表明两者皆非。结构化的 ACP（Agent Client Protocol）桥接保留为独立包，因为它是具有自身契约和快照层级的产品协议表面；readline 辅助模块只是一个应用前门的脚手架。在发布前重新拆分成本很低：如果将来有第二个产品应用需要 readline UI，届时再拆出来，由那个消费方来塑造包契约。
+
+## 后果
+
+- stdio 应用完整拥有自己的前门；叶子 `cordis.yml` 仍然只加载一个应用包，演示的形态没有变化。
+- 未来如果有独立的终端 UI 需要将该辅助模块作为包使用，届时由那个第二消费方驱动重新引入，而非仓库为假设性的复用保留一条边界。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.i18n.yaml
new file mode 100644
index 0000000000..c343b6ff92
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-prune-producerless-vocabulary-variants.md: 34492e6906cd2d795f880310b1bcd120e3953fcf
+2026-07-04-prune-producerless-vocabulary-variants.zh.md: a68a8b04fedefed8a2ab92f08baf5e8b3ea90222
diff --git a/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.md b/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.md
index aa61e859d2..34492e6906 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-prune-producerless-vocabulary-variants.zh.md)
+
 ## Problem
 
 The merge-extensible vocabulary maps are designed to grow by declaration merging, and the codebase already states the admission policy on `TurnEndReasonMap` (`packages/core/session/src/types.ts`): a variant like `refusal` is "deliberately omitted until" an adapter or loop first emits it. Three declared vocabulary items violated that policy — each had no producer and no consumer, and two had not even a test:
diff --git a/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.zh.md b/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.zh.md
new file mode 100644
index 0000000000..a68a8b04fe
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 裁剪无生产者的词汇变体（块缓存提示、`agent` 消息来源、`continuation` 轮次触发器）
+
+Status: implemented
+
+[English](2026-07-04-prune-producerless-vocabulary-variants.md) | 中文
+
+## 问题
+
+可合并扩展的词汇映射表设计上通过声明合并来增长，代码库已在 `TurnEndReasonMap`（`packages/core/session/src/types.ts`）上明确了准入策略：像 `refusal` 这样的变体「在适配器或循环首次发出它之前，有意不纳入」。三个已声明的词汇项违反了该策略——每个都既无生产者也无消费方，其中两个甚至没有测试：
+
+- **`TextBlock`/`ToolResultBlock` 上的 `CacheHint` 及其 `cache?: CacheHint` 块字段**（`packages/llm/llm/src/types.ts`；图像块曾有第三个此类字段，已随图像块一同移除——参见[删除图像 Agent Note（agent 决策记录）](2026-07-04-drop-image-content-block.md)）。任何地方都没有构造带 `cache:` 的块——src、测试和文档粘贴均为空——两个适配器也都不读取 `.cache`：DeepSeek 的提示词缓存是自动的，因此适配器会从响应中映射出 `prompt_cache_hit_tokens`，却从不向请求中发送 hint。这是没有任何提供方能够遵守的 Anthropic 风格 `cache_control` 表面。
+- **`MessageSourceMap.agent`**（`{ kind: 'agent'; agentId: string }`，同一文件）。零个构造点，包括测试在内。它预期的生产者在实现时并未使用它：subagent 后端将父级的提示词发送给子级时不带 `source`，因此记录为 `{ kind: 'user' }`，通用信封渲染器在插值 `source.kind` 时也从未对其做路由。
+- **`TurnTriggerMap.continuation`**（`packages/core/session/src/types.ts`）。agent loop（智能体循环）在结构上不可能发出它——continuation 发生在一个轮次*内部*作为后续步骤，而非作为新轮次——循环只构造 `message` 和 `injection` 触发器。唯一的写入者是一个手工构建的测试 fixture（测试前置数据），它只需要一个任意的非消息触发器（`packages/support/llm-replay/tests/llm-replay.spec.ts`），`injection` 触发器同样满足需求；唯一的生产环境触发器读取方 ACP（Agent Client Protocol）桥接层只过滤 `kind === 'message'`。
+
+## 决策
+
+`CacheHint`、其 `cache?` 块字段、`agent` 消息来源变体和 `continuation` 轮次触发器变体均已删除：已发布词汇不再携带它们。llm-replay fixture 使用 `injection` 触发器（任何非 `message` 触发器都能满足其用途）。[core.md](../../../../docs/core-data-structures/core.md) 和 [session.md](../../../../docs/core-data-structures/session.md) 中的 type-equiv 粘贴与裁剪后的 map 匹配——两个符号仍保留在 `scripts/type-equiv.manifest.json` 中的行，因为每个 map 都只是少了一个成员而继续存在——并且[内容块词汇 Agent Note](../architecture/2026-06-11-content-block-vocabulary.md)的后果按照 [implemented/AGENTS.md](../AGENTS.md)，将 cache hint 记录为由生产者门控，而不是已有归属。
+
+每个变体在获得真正的生产者之日回归，这正是映射表设计的增长方式：缓存功能连同传输它的适配器一起重新添加 `cache`；subagent 归属连同打标的后端和路由它的消费方一起重新添加 `agent`；真正启动新轮次的自动续行功能连同发出它的插件一起重新添加 `continuation`。
+
+## 曾考虑的替代方案
+
+### 为什么不保留它们？
+
+[内容块词汇 Agent Note](../architecture/2026-06-11-content-block-vocabulary.md)曾把“cache hint……有了归属”列为设计后果，预留槽位也确实能表明意图。但空槽位是每个实现和消费方都必须考虑的契约表面（我的适配器是否必须遵守 `cache`？我的 renderer 是否必须路由 `agent` 来源？），而相邻 map 自身的 JSDoc 已经拒绝“无 emitter 先预留”——`refusal` 和 `max_turn_requests` 被点名为*首次有内容发出它们时*再添加的变体，而不是提前声明。让已经声明但无用的变体遵守同一标准，才能使词汇真正有意义：只要它位于 map 中，就必须有内容生产它。
+
+## 验证
+
+对 `CacheHint`、`agent` 消息来源拼写和 `continuation` 触发器拼写运行 `rg`，只会返回 Agent Note 记录（本文，以及[删除图像 Agent Note](2026-07-04-drop-image-content-block.md)对图像块自身 `cache` 字段的说明）；llm-replay fixture 使用 `injection` 触发器断言相同的重放行为；核心数据结构粘贴和 type-equiv 清单保持同步。
+
+## 后果
+
+操作行为没有变化——原本就没有内容能够构造这些值。镜像事件移除（[边界镜像 Agent Note](2026-06-20-remove-agent-boundary-mirror-events.md)、[流分片 Agent Note](2026-07-02-remove-stream-chunk-mirror.md)）只触及瞬态 `agent/*` 事件，从不触及持久词汇，因此不存在冲突。其他位置已经遵守准入策略：`rejected`、`prompt/blocked` 和 `hook/invoked`/`hook/result` 都有实时生产者——本 Agent Note 将同一门槛扩展到缺少生产者的三个变体。图像块自身的 `cache?` 字段归属[删除图像 Agent Note](2026-07-04-drop-image-content-block.md)，后者将其与该块一同移除；本 Agent Note 覆盖剩余块类型上的两个字段。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.i18n.yaml
new file mode 100644
index 0000000000..e7aabd9dc2
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-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
+2026-07-04-prune-write-only-fs-surface.md: 6cfd5d9ab8a2fc6322814d384fba735c06681976
+2026-07-04-prune-write-only-fs-surface.zh.md: cb7494b5e958c8ed86ffa3ba8ffbe82748d1db03
diff --git a/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.md b/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.md
index 97652ef50c..6cfd5d9ab8 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-prune-write-only-fs-surface.zh.md)
+
 ## Problem
 
 The [fs seam split](2026-06-26-fsspec-style-fs-seam.md) moved read routing and policy out of the backend into `dsh-tool-fs` and `dsh-fs-policy`. Four pieces of surface kept the pre-split shape — populated on every call, read by nobody:
diff --git a/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.zh.md b/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.zh.md
new file mode 100644
index 0000000000..cb7494b5e9
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: 从 fs seam 中移除只写字段与一个无效的路由旋钮
+
+Status: implemented
+
+[English](2026-07-04-prune-write-only-fs-surface.md) | 中文
+
+## 问题
+
+[fs seam 拆分](2026-06-26-fsspec-style-fs-seam.md)将读取路由与策略从后端移至 `dsh-tool-fs` 和 `dsh-fs-policy`。有四处接口保留了拆分前的形态——每次调用都填充，却无人读取：
+
+1. **`dsh-fs-local` 中的 `STREAM_MIN_SIZE` + `FsIoInternals.streamMinSize`**——*在本次变更之前已被「禁止硬编码可调参数」审计移除，该审计将路由阈值改为 `dsh-tool-fs` 的 `readStreamMinSize` 配置；此处记录是为了完整呈现整次清理。* 原始位置（`packages/fs/fs-local/src/fsio.ts`，从 `packages/fs/fs-local/src/index.ts` 重导出）：包括 fs-local 自身源码和测试在内，全仓库零读取者。后端没有读取路由——`readWholeText`/`streamWholeText` 是调用方自行选择的两个独立原语——真正的路由常量位于消费方（`packages/fs/tool-fs/src/read.ts`，与 `info.size` 比较）。同一个 10 MiB 事实的两份镜像；后端那份是死代码，且该旋钮的 JSDoc 声称提供一个实际不存在的「read routing」覆盖。
+2. **`FsTarget.inputPath`**（`packages/fs/fs/src/types.ts`）：每个后端和每个测试 mock 都必须为这个「仅供诊断」的字段编造一个值，而生产环境零读取者——策略插件和所有错误消息使用的是 `targetKey`/`displayPath`。`listDir` 的生产者暴露了语义上的摇摆：目录子项得到的是裸条目名，这不是任何人的「input」。
+3. **`FsEditOutcome.replacements` + `.replaceAll`**（`packages/fs/fs/src/types.ts`）：`replacements` 生产环境零读取者（单匹配策略本身保留——它由后端内部 `FS_AMBIGUOUS_EDIT`/`FS_EDIT_NOT_FOUND` 抛出来强制执行，错误消息保留了内部计数）；`replaceAll` 仅被 `packages/fs/tool-fs/src/edit.ts` 中的 `formatEditOutput` 读取——作为工具本身已持有的 `replace_all` 参数的回声。精简后，`FsEditOutcome` 变为 `{ version, before, after }`，与 `FsWriteOutcome` 中真正由后端发现的字段对齐。
+4. **`FileReadOutcome.limit` + `.version`**（`packages/fs/tool-fs/src/read-render.ts`）：由读取工具填充，但 `formatReadOutput` 只渲染 `offset`/`lines`/`totalLines`/`truncatedByBytes`，且 `fs/observed` 事件发射直接使用 `info.version` 而非 outcome 的副本。
+
+## 决策
+
+删除 fs-local 常量、其再导出和 `streamMinSize` 配置项（其余 `FsIoInternals` 配置项确实由原子写入测试使用）；从 `FsTarget` 删除 `inputPath`；将 `FsEditOutcome` 收窄为 `{ version, before, after }`，并把解析参数中的 `replaceAll` 传给 `formatEditOutput`；从 `FileReadOutcome` 删除 `limit`/`version`。[filesystem.md](../../../../docs/core-data-structures/filesystem.md) 中的粘贴、`packages/fs/fs/README.md`，以及不得不虚构已删除字段的测试 fake 都随类型一同收窄。
+
+## 曾考虑的替代方案
+
+### 为什么不保留？
+
+未来的权限/隔离层可能需要解析前的路径来生成错误文本——但它需要的是*请求*，每个调用点仍然持有请求。「替换了 N 处」可能成为面向模型的文本——这是一个需要时再设计的行为变更，且后端内部的计数为其错误消息而保留。读取页脚可能展示 `limit`——但页脚展示的一切已经可以从 `lines`/`totalLines` 推导。与此同时，每个现有和未来的后端（远程、原生）都必须编造无人消费的协议字段，每个测试 mock 都必须满足它们。
+
+## 验证
+
+已删除表面不复存在——`dsh-fs-local` 中的 `STREAM_MIN_SIZE`/`streamMinSize`、`FsTarget.inputPath`、`FsEditOutcome.replacements`/`.replaceAll`，以及 `FileReadOutcome.limit`/`.version`——而请求侧 `replaceAll`（`FsEditRequest`）和其他 outcome 类型上的版本字段保持不变；测试 fake 随类型一同收窄。`formatEditOutput` 在两个 `replace_all` 分支中生成的文本都没有变化，因此没有快照预期输出发生改动。
+
+## 后果
+
+后端不增加新义务，反而卸下了四个无人消费的字段。fs 发现功能（glob/grep 工具）涉及相同的 `dsh-fs` 类型文件——这是文本层面而非设计层面的重叠，可以机械地合并解决。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.i18n.yaml
new file mode 100644
index 0000000000..8b6bb07da2
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-remove-agent-steering-mirror.md: 9f7cd5abe968ff216cbd7012163ea1c04dc00599
+2026-07-04-remove-agent-steering-mirror.zh.md: 63f575347d989f288b3129e0a53e5690b85bb4e8
diff --git a/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.md b/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.md
index ebfc774792..9f7cd5abe9 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-remove-agent-steering-mirror.zh.md)
+
 ## Problem
 
 `agent/steering` was the last remaining transient mirror of a durable session event. The loop's steering drain appends the durable `steering/message { turn, content, source }` and, on the very next line, emitted `agent/steering(agent, turn, content, source)` — the identical fact as a fire-and-forget event (`packages/core/agent-loop/src/loop.ts`, `drainSteering`). It had zero production listeners: the only subscriber anywhere was a loop regression test asserting the emit carried `source` — the same fact the durable event already records one line above.
diff --git a/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.zh.md b/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.zh.md
new file mode 100644
index 0000000000..63f575347d
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 移除 `agent/steering` 镜像 emit
+
+Status: implemented
+
+[English](2026-07-04-remove-agent-steering-mirror.md) | 中文
+
+## 问题
+
+`agent/steering` 是最后一个仍存在的、对持久会话事件的瞬态镜像。agent loop（智能体循环）的 steering（中途引导）drain 逻辑先追加持久事件 `steering/message { turn, content, source }`，紧接着下一行就 emit `agent/steering(agent, turn, content, source)`——同一个事实以 fire-and-forget 事件的形式重复发出（`packages/core/agent-loop/src/loop.ts`，`drainSteering`）。它在生产环境中没有任何监听者：唯一的订阅方是一个 agent loop 回归测试，断言 emit 携带了 `source`——而这同一个事实已经由上一行的持久事件记录。
+
+`agent/steering` 以相同的 payload 重复了紧接其前的持久事件 `steering/message`。`agent/queued` 仍保留为纯瞬态信号，因为它在持久化之前触发，覆盖了可能在进入日志前被取消的工作。
+
+Steering 承载真实生产流量——钩子 bridge 的轮次延续决策通过 `inbox.steer()` 注入其理由，最终成为由钩子矩阵预期输出固定的持久 `steering/message` 事件——而这些消费方无一例外都观察持久事件。没有任何内容观察镜像。
+
+## 决策
+
+`agent/steering` 已从 agent 事件分类中移除：包括 `packages/core/agent/src/types.ts` 中的声明（以及其中实时事件 JSDoc 列表对它的提及）、`drainSteering` 中的 emit（当时已无用的 `ctx` 参数也随之移除）、`packages/core/agent/README.md` 中的表格行，以及循环伪代码块（`packages/core/agent-loop/src/loop.ts` 模块文档和 [architecture.md](../../../../docs/architecture.md)）中的 emit 行；Cordis 目录重新生成后不再包含它。唯一的回归测试改为在持久 `steering/message` 事件上固定来源保留行为——所固定的事实存在于日志上。
+
+三份已实现 Agent Note（agent 决策记录）曾说明保留该事件；按照 [implemented/AGENTS.md](../AGENTS.md)，每份记录都已修改并指向本文作为移除记录：包括[边界 Agent Note](2026-06-20-remove-agent-boundary-mirror-events.md) 的保留列表条目、[流分片 Agent Note](2026-07-02-remove-stream-chunk-mirror.md) 的范围条款，以及[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 的瞬态 emit 枚举。
+
+## 曾考虑的替代方案
+
+### 为什么不保留？
+
+“它是控制信号，不是边界”——但该分类的实际区分是镜像/仅实时，而非控制/边界，并且该事件确实是镜像。希望在入队时收到通知的消费方可以使用 `agent/queued`（及其 steering 标记）；希望在排空时收到通知的消费方，本质上是在要求获知 `steering/message` 被追加的时刻，而 `session/event` 会交付相同 payload 并附带持久性。遭拒绝的[退役轮次中途 steering Agent Note](../../rejected/simplification/2026-06-20-retire-mid-turn-steering.md)所捍卫的是 steering *功能*——`steer()`、持久事件、强制延续——本次移除不会触及其中任何一项。
+
+## 验证
+
+`agent/steering` 拼写只存在于 Agent Note 正文中（本 Agent Note、上方三份已修改 Agent Note，以及已冻结的[遭拒绝 steering 功能 Agent Note](../../rejected/simplification/2026-06-20-retire-mid-turn-steering.md)，其正文记录了它所否决的提案）；目录已重新生成；重新定向的测试在 `steering/message` 上固定来源保留行为。
+
+## 后果
+
+生产环境中没有需要迁移的监听者，两种瞬态通知需求各有归宿：入队时由 `agent/queued`（带 `steering` flag）承载，drain 时由 `session/event` 在持久事件 `steering/message` 落地时承载。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.i18n.yaml
new file mode 100644
index 0000000000..32517c2c50
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-share-app-bin-boot-glue.md: 7a763eba8a229ec5017387edb54657a5c367105b
+2026-07-04-share-app-bin-boot-glue.zh.md: d65a6613f7b05cdea0f99529808c992aff4256e9
diff --git a/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.md b/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.md
index f054f168a2..7a763eba8a 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-share-app-bin-boot-glue.zh.md)
+
 ## Problem
 
 The stdio and ACP bins duplicated environment loading, fail-loud handling, entry validation, and boot logic, including subtle Loader failure behavior. Their copies had already drifted and lived in self-executing files excluded from unit coverage, making their helper exports unusable.
diff --git a/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.zh.md b/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.zh.md
new file mode 100644
index 0000000000..d65a6613f7
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.zh.md
@@ -0,0 +1,27 @@
+# Agent Note: 共享应用 bin 的启动胶水代码，而非维护两份副本
+
+Status: implemented
+
+[English](2026-07-04-share-app-bin-boot-glue.md) | 中文
+
+## 问题
+
+stdio 和 ACP（Agent Client Protocol）两个 bin 各自重复了环境加载、fail-loud 处理、入口校验与启动逻辑，包括微妙的 Loader 失败行为。两份副本已经发生漂移，且位于自执行文件中、被排除在单元测试覆盖率之外，导致其导出的辅助函数无法被复用。
+
+## 决策
+
+辅助函数只存在一处：[`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot)（`packages/ui/app-boot`，归入 `ui` 分组，因为 bin 是已发布产物，其运行时依赖本身也必须是已发布的包，而非 `support/`）。包含：`resolveConfigPath`（快照感知，两个 bin 共用的唯一路径解析器）、`loadEnv`、`installFailLoud`、`assertEntriesLoaded` 与 `boot`，每个函数都通过 bin 的诊断前缀参数化，并在其副作用 seam（warn sink、process slice）处支持注入，使单元测试套件能覆盖每个分支——包括 `boot()` 在进程内驱动真实 Loader、使用相对路径 specifier 配置的场景，既覆盖已稳定树的正常路径，也覆盖无 fiber 入口的拒绝路径。该包启用逐文件 100% 覆盖率门禁；Loader 失败的相关知识只有一个归属地。
+
+每个 `bin.ts` 都是在共享辅助函数之上加应用特有生命周期的精简自执行组合（ACP bin：重放模式环境变量跳过和 stdin EOF 释放；stdio bin：没有额外逻辑）。这些 bin 仍排除在覆盖率之外且不导出任何内容；已发布产物守卫保持不变——按照“真实入口路径即已发布产物”的防御模式，已构建 bin 冒烟仍在具有 node_modules 形状的临时目录中用纯 node 运行每个 bin（现在也会符号链接 `ui/app-boot`），并继续断言缺失配置时以非零状态退出。[提取示例应用包 Agent Note（agent 决策记录）](../architecture/2026-06-20-extract-example-app-packages.md)中的 bin 归属事实已据此修改。
+
+## 曾考虑的替代方案
+
+### 为何不保留重复？
+
+这些 bin 当时被定位为归属相互独立的已发布产物，而新包会带来固定开销（清单、README、tsconfig 引用、publint 表面），与去重的行数相当。但创建 bin 的 Agent Note 从未权衡应用间共享——它把三份示例 `start.ts` 副本合并进 bin 后便止步于此；漂移是已经观察到的事实；覆盖率缺口的理由也独立于去重理由：这是仓库中唯一免受逐文件 100% 门禁约束的非平凡运行时逻辑。记录的后备方案（只将纯逻辑提取到各应用模块）会结束豁免，但会继续让相关知识拥有两个归属。
+
+## 后果
+
+- 启动胶水代码的变更（新增守卫、修复路径解析）只需落地一次，两个已发布 bin 自动继承；bin 之间不会再次漂移。
+- `dsh-app-boot` 保持轻量依赖（cordis + loader/include 对）——它是启动机制，不是应用表面积。
+- bin 自身的文件几乎是平凡的组合；所有含分支的逻辑都在覆盖率门禁之下。
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
new file mode 100644
index 0000000000..b2c35d276c
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-tighten-hook-protocol-contract.md: a1972ee8ef486982268ba8886b2413f3557061b4
+2026-07-04-tighten-hook-protocol-contract.zh.md: 4917a8f551672f51b0ebc27b1267c7e8e8eb2178
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 82830b1366..a1972ee8ef 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-tighten-hook-protocol-contract.zh.md)
+
 ## Problem
 
 Four pieces of the `dsh-hook-protocol`/bridge contract missed the discipline the [subagent-observe-enrich Agent Note](../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:
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
new file mode 100644
index 0000000000..4917a8f551
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: 收紧 hook-protocol 契约——dialect、废弃字段、双重默认值与 lib 拥有的 `hook/result` 语义
+
+Status: implemented
+
+[English](2026-07-04-tighten-hook-protocol-contract.md) | 中文
+
+## 问题
+
+`dsh-hook-protocol`/bridge 契约中有四部分没有遵守 [subagent observe/enrich Agent Note（agent 决策记录）](../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` 得到的是无声的空操作，且无任何警告。
+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 漂移（不同的上限、不同的回退），共享持久化事件的语义就会悄然分叉。
+
+## 决策
+
+`HookDialect` 是封闭的 bridge 集合：`'claude' | 'codex'`；`HookOutput` 移除了不受支持的 `suppressOutput`。`hook/result.durationMs` 保留为持久化的审计计时，仅在快照中做归一化。参考默认值各只存在一处：`DEFAULT_HOOK_TIMEOUT_MS` 与 `DEFAULT_STDERR_SUMMARY_MAX_CHARS`。`HookResultRecord` 与 `appendHookResult` 为两个 bridge 统一拥有 stderr 摘要化和 decision 推导逻辑。`BLOCKING_EXIT_CODE` 为 codec 内部常量。
+
+## 曾考虑的替代方案
+
+### 为什么不保留它们？
+
+不受支持的词汇可以在真正有消费方时回归。`durationMs` 保留，因为持久化的审计计时独立于当前是否有读取方而有价值。Bridge 特有的 payload 构造留在各自 bridge 中，而共享持久化事件的归一化属于协议库。
+
+## 验证
+
+`HookDialect` 仅包含 Claude 和 Codex，`suppressOutput` 在源码、已解析字段文档和归一化逻辑中均不存在。`durationMs` 保留在事件和 fixture（测试前置数据）中，回放时做清洗。`600_000` 和 `500` 两个默认值各只在协议库中出现一次；每个钩子的超时覆盖仍然生效；两个 bridge 的测试套件均验证了由库拥有的 stderr 截断和 decision 规则。
+
+## 后果
+
+`dialect`、`suppressOutput`、可调参数和语义变更在线协议和预期输出中均不可见。代价是 `dsh-hook-protocol` 和两个 bridge 中的改动——在预发布立场下成本很低，也比让一项持久事件语义的两个副本各自老化更便宜。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.i18n.yaml
new file mode 100644
index 0000000000..0aa39a18ff
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-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
+2026-07-04-trim-acp-bridge-unreachable-surface.md: ce0c623930192d02c8347c3956c497ee13048904
+2026-07-04-trim-acp-bridge-unreachable-surface.zh.md: e89b0e7c9c7c8438fb71adacf1b525a0b94bf04b
diff --git a/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md b/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md
index 7d1065d250..ce0c623930 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-trim-acp-bridge-unreachable-surface.zh.md)
+
 ## Problem
 
 Two pieces of `dsh-acp` surface were unreachable from any shipped configuration:
diff --git a/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.zh.md b/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.zh.md
new file mode 100644
index 0000000000..e89b0e7c9c
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.zh.md
@@ -0,0 +1,26 @@
+# Agent Note: 裁剪不可达的 ACP 桥接层表面——品牌配置项与 kind 嗅探回退
+
+Status: implemented
+
+[English](2026-07-04-trim-acp-bridge-unreachable-surface.md) | 中文
+
+## 问题
+
+`dsh-acp` 有两处对外表面在任何已交付的配置中都不可达：
+
+1. **`AcpConfig.agentName` / `agentVersion`**（`packages/ui/acp/src/index.ts`）。已发布应用包只向 bridge 传递 `{ model }`（`packages/examples/acp-demo/src/index.ts`），因此没有任何叶子 `cordis.yml`——唯一的生产配置表面——能够设置这些配置项；只有直接挂载 bridge 才能设置它们，而这种做法只存在于一个单元测试中。每份快照预期输出——包括钩子矩阵场景——都固定 schema 默认值（`deepseek-harness-acp` / `0.0.1`）。这对配置项还带有一个尚未解决的 `TODO(double-default)`：字面量存在两次（schema `.default(...)` 加 `??` 后备值），TODO 要求为它们选择一个归属。
+2. **`toolKindFor` 名称启发式**（同一文件）在通用回退路径中对 `bash*`/`read*`/`write`/`edit*` 工具名做了特殊处理。自[render-intent 联合类型](../architecture/2026-07-02-tool-render-intent-union.md)以来，这些分支匹配到的每个第一方工具都自带 `presentCall` 并携带其 kind，而没有 presenter 的生产工具（`subagent`、`subagent_fork`）本来就落入 `other`。这些分支只有在工具拒绝自行呈现调用时才在生产中可达：`presentCall` 抛出异常（容错回退），或模型参数未通过工具 schema 导致 `defineTool` 的 `presentCall` 包装层返回 `undefined`（例如 `bash` 调用缺少必需的 `description`）。而桥接层自身的模块文档明确声明了该启发式所违反的设计规则："桥接层绝不对工具名做特殊处理"。
+
+## 决策
+
+在初始化时硬编码现有的握手标识 `{ name: 'deepseek-harness-acp', version: '0.0.1' }`，移除不可达的配置字段与重复默认值。在两个 presenter 回退处，将 `toolKindFor` 替换为中性的 `'other'`。正常的第一方呈现不受影响；格式错误或失败的呈现现在会渲染一个诚实的通用卡片，而非从工具名推断 kind。初始化测试和快照固定握手标识；只有 `hook-codex-posttool-block` 中格式错误的调用改变了回退卡片的 kind。
+
+## 曾考虑的替代方案
+
+### 为什么不保留？
+
+品牌配置可以在 app 包将其暴露给部署环境时再回来。从未知工具名推断呈现方式违反了 render-intent 契约；中性回退卡片还能为格式错误的调用和损坏的 presenter 保留原始输入。
+
+## 后果
+
+除上述回退渲染的取舍外没有其他影响——退化路径下，中性卡片比推断出的第一方卡片更易于诊断。
diff --git a/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.i18n.yaml
new file mode 100644
index 0000000000..6c3e5859e7
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-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
+2026-07-12-drop-unconsumed-skill-provider-events.md: b0ed7585882328b6abdcf57974200053d9c26048
+2026-07-12-drop-unconsumed-skill-provider-events.zh.md: fd380b2c0421abfc3032b88b550b4a3e8b88bf38
diff --git a/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.md b/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.md
index a719e20f1e..b0ed758588 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.md
+++ b/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-12-drop-unconsumed-skill-provider-events.zh.md)
+
 ## Problem
 
 Two skill-registry notifications are produced but have no production listener. The generated producer/consumer matrix and exact event-name searches find only declarations, emit sites, tests, generated catalogs, and prose for `skill/provider-added` and `skill/provider-removed`.
diff --git a/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.zh.md b/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.zh.md
new file mode 100644
index 0000000000..fd380b2c04
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 移除无消费方的 skill 提供方事件
+
+Status: implemented
+
+[English](2026-07-12-drop-unconsumed-skill-provider-events.md) | 中文
+
+## 问题
+
+skill（技能）注册表产出两个通知事件，但没有生产环境的监听方。生成的生产者/消费方矩阵以及对事件名的精确搜索表明，`skill/provider-added` 与 `skill/provider-removed` 仅出现在声明、emit 站点、测试、生成的 catalog 和行文中。
+
+skill 发现按需读取当前的提供方映射表，提供方注册时同步清除已完成的 catalog，而 await 后的版本检查阻止了陈旧的发现结果进入缓存。没有兄弟插件通过这些事件等待 skill 提供方——与之形成对比的是活跃的 `subagent/provider-added` 消费方，它容忍兄弟并发加载。
+
+`tools/change` 与 `system-prompt/change` 明确不在本提案范围内。既有的简化决策将它们保留为面向实时工具和提示词 UI 的有意观测点，且自引用的已挂载插件已在使用 `tools/change`。本提案同样不改动 `subagent/provider-added`/`removed`，因为 `tool-subagent` 有生产环境的生命周期消费方。
+
+## 决策
+
+skill 注册表不再声明和 emit 提供方成员变更事件。提供方的注册与 dispose（资源释放）仍为 effect 所有的直接状态变更，同步使已完成的 catalog 失效；查找与发现按需读取当前提供方映射表。测试通过提供方查找和收集到的输出来观察清理行为，而非依赖生命周期通知。
+
+生成式事件目录、API 目录和生产者/消费方矩阵均不再包含已删除通知。skill system Agent Note（agent 决策记录）和包文档改为通过其由 effect 直接拥有的状态与 cache 失效契约描述注册。
+
+## 曾考虑的替代方案
+
+**为未来插件保留 skill 提供方通知。** 第三方插件可能想观察提供方的可用性，但直接提供方注册与按需查找才是扩展契约；当前没有消费方需要推送信号。如果将来出现兄弟加载竞态，可以像 subagent 注册表那样，引入一个带有该消费方实际所需的身份与就绪语义的通知。
+
+## 后果
+
+生成的事件矩阵中不再有 `skill/provider-added` 或 `skill/provider-removed` 的行。skill 发现、直接运行时注册、提供方 effect 回滚/dispose、缓存失效与注册表查找清理保持不变；监听方触发的回滚随事件一起消失。`tools/change`、`system-prompt/change` 以及已被消费的 subagent 提供方生命周期事件不受影响。
+
+预发布消费方失去 skill 提供方观测点，但仍保留两种贡献 skill 的方式：直接运行时注册与提供方注册。未来若有消费方需要实时的提供方可用性信息，必须新增一个带有其实际所需的身份与就绪语义的专用通知。
diff --git a/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.i18n.yaml
new file mode 100644
index 0000000000..1f8a055362
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-12-prune-unused-web-seam-fields.md: c50bf44161579a44b09113fc501f3d67fb5d6855
+2026-07-12-prune-unused-web-seam-fields.zh.md: 401bdd0c812175cffc572e722141d2829a3fc2d5
diff --git a/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.md b/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.md
index 68ced83876..c50bf44161 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.md
+++ b/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-12-prune-unused-web-seam-fields.zh.md)
+
 ## Problem
 
 The web capability carries request/result/status values that every shipped implementation populates but no production consumer reads. `WebSearchResult.providerId` and `query` and `WebFetchResult.providerId` are result echoes; `tool-web` formats only content/sources/truncation or final URL/status/body/truncation, and no other runtime reads them. Search providers return `WebProviderStatus.reason`, but resolution checks only `available` and intentionally emits a generic unavailable diagnostic.
diff --git a/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.zh.md b/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.zh.md
new file mode 100644
index 0000000000..401bdd0c81
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.zh.md
@@ -0,0 +1,27 @@
+# Agent Note: 裁剪 web seam 中未使用的字段
+
+Status: implemented
+
+[English](2026-07-12-prune-unused-web-seam-fields.md) | 中文
+
+## 问题
+
+web 能力携带的 request/result/status 值，虽然每个已交付的实现都会填充，但没有任何生产环境的消费方读取它们。`WebSearchResult.providerId`、`query` 与 `WebFetchResult.providerId` 是结果回显；`tool-web` 只格式化 content/sources/truncation 或最终 URL/status/body/truncation，没有其他运行时读取这些字段。搜索提供方返回 `WebProviderStatus.reason`，但可用性检查只看 `available`，并有意输出一条通用的不可用诊断信息。
+
+`WebFetchRequest.timeoutMs` 同样从未被生产调用方设置。`tool-web` 只提供 URL，使用工具定义的 timeout 加 `exec.signal` 作为调用方截止时间，并依赖本地提供方的配置默认值作为兜底。这个未使用的逐请求覆盖迫使 `web-fetch-local` 暴露 `maxTimeoutMs`、对两个 timeout 来源做 clamp，并为没有任何产品路径能选中的优先级规则编写文档和测试。`WebExecContext` 则是另一个单字段包装层：每个调用方分配 `{ signal }`，每个提供方立即解包 `exec?.signal`；不存在第二个执行控制字段。
+
+## 决策
+
+web seam 移除搜索/抓取结果中的 `providerId` 回显和搜索的 `query` 回显；调用方本身已持有请求和提供方选择信息。提供方以返回布尔值的方法暴露可用性。抓取请求不再有逐请求 timeout 或 `maxTimeoutMs` clamp；本地提供方保留其可配置的默认 timeout，工具保留自身的截止时间。提供方方法直接接收一个可选的 `AbortSignal`，而非单字段的 `WebExecContext` 包装层。
+
+所有 web 实现与面向模型的工具使用更精简的契约。接口/实现/消费方的包（package）拆分、提供方选择、来源引用、最终 URL/状态数据、截断报告与安全限制保持不变。
+
+## 曾考虑的替代方案
+
+**保留自描述结果、逐请求截止时间与可扩展的执行上下文对象。** 结果回显可以帮助通用遥测，请求级 timeout 可以帮助受信的程序化调用方，包装层则为未来的控制字段留出空间。但目前不存在这样的消费方或第二个字段；在每个提供方中携带重复的身份标识、第二套截止时间策略以及包装/解包管道，使当前契约更难实现和解释。如果遥测或逐调用预算控制到来，届时应当定义哪个截止时间优先、在哪里观测提供方身份，以及多个控制字段是否足以证明需要一个上下文对象。
+
+## 后果
+
+保留下来的每个 web request/result 字段，要么被生产代码消费，要么是执行提供方请求所必需的。工具可见的搜索/抓取输出、提供方回退、中止行为、可配置的 timeout 兜底、截断与引用仍然被覆盖，无需请求级 timeout 优先级分支或执行上下文包装层。
+
+预发布阶段的程序化调用方失去了结果来源回显和逐请求的抓取截止时间。提供方仍具备部署级可配置 timeout 并尊重取消信号，因此这次精简移除的是可配置性，而非安全边界。
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
new file mode 100644
index 0000000000..64bea6aec8
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-12-simplify-session-log-representation.md: a40f4013a97a9c940012dbb37d59beb2faf8fb22
+2026-07-12-simplify-session-log-representation.zh.md: a4ecd8c7340affda71d95505ab44910539e36bb9
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 97a89e5be7..a40f4013a9 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-12-simplify-session-log-representation.zh.md)
+
 ## Problem
 
 The session log maintains two representations that cost more machinery than their consumers require: a pseudo-linked surface and custom request-header deltas.
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
new file mode 100644
index 0000000000..a4ecd8c734
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 简化会话日志表示
+
+Status: implemented
+
+[English](2026-07-12-simplify-session-log-representation.md) | 中文
+
+## 问题
+
+会话日志维护着两种表示，其机制复杂度超出了消费方的实际需求：一个伪链表 surface 和自定义的请求头增量。
+
+`SurfaceManager` 同时在数组、seq map 和可变 `prev`/`next` 链接中存储相同顺序。生产代码从不读取任一链接：compact 的工具配对 balance 根据按 surface 顺序缓存的每个切点 balance 作答。替换已经使用 `indexOf`，因此链接并未使其主导操作成为常数时间。使用线性替换查找的 seq 数组具有相同的渐近替换成本，却只有一种表示需要验证。
+
+请求头子系统实现了一套自定义的系统/工具增量编解码器和传输决策层，尽管其契约声明增量只是编码优化，而非可重建性要求。在每个 agent loop（智能体循环）实例边界保留初始/恢复的完整快照，然后在该实例的组装头发生变化时写入一条规范的完整 `request/header`，即可保留回放能力，同时删除 `SystemDelta`、`ToolsDelta`、往返回退逻辑以及持久化的 `request/header-delta` 变体。编解码器专属的词汇随编解码器一起消失，并非因为其各分支本身无效。
+
+实现保留追加与替换 `sourceEventSeqs`、崩溃修复 provenance，以及所有 `SessionStartSource` 变体，因为这些字段承担审计/拦截职责，当前没有读取方并不能推翻这一点。
+
+## 决策
+
+`SurfaceManager.nodes` 是由事件序号组成的 `readonly number[]`；公共 `SurfaceNode` 形状、node 链接和 seq-to-node map 均已移除。内部替换 generation 信号保留。session-query 使用的完整 `foldSurface()` 读取会返回相同的数字数组表示和替换元数据，而无需让增量 manager 保留历史。工具配对 balance 和压缩使用事件序号与 surface 位置；由 compact 拥有的每切点 balance cache 不依赖 node 链接。
+
+请求头只使用规范的完整快照。初始与恢复锚点即使没有变化也仍是完整快照；实例内变化会追加另一个完整 `request/header`，reason 为 `change`。delta 事件、codec 类型、diff/apply 辅助函数，以及仅供 codec 使用的 `fallback` reason 均已移除。请求重建选择最新快照。
+
+`SESSION_FORMAT_VERSION` 仍固定为 `0`，因此 seed、追加和持久化加载验证会显式拒绝旧 v0 `request/header-delta` 事件，以及携带已删除 `fallback` reason 的完整快照。不存在兼容性 fold 或迁移。JSONL 与 SQLite 测试固定了这一响亮失败边界；ACP（Agent Client Protocol）快照 harness 则把合法的会话中途变更表示为完整固定请求头和完整可读提示词。
+
+## 曾考虑的替代方案
+
+**保留链表节点和紧凑增量以备未来扩展。** 链接可能有助于未来的游标 API，增量在大型工具 schema 仅有少量变化时可以缩减日志。但没有已发布的游标使用这些链接，而完整快照以磁盘空间换取了显著更简单的正确性。如果头部体积确实成为问题，可以基于真实 trace 设计压缩方案或经过度量的规范增量方案。
+
+## 验证
+
+单元覆盖率固定有序 surface 的追加/替换行为、工具配对、压缩、完整请求头 fold/记录、请求重建和开发不变量。Seed 验证以及 JSONL、SQLite 加载测试会在重放前拒绝旧事件。无密钥 ACP 套件以新形状覆盖记录、刷新、重放、变化请求头固定，以及沙箱模式切换 fixture（测试前置数据）。
+
+## 后果
+
+完整请求头会增加日志体积，线性替换查找在极大 surface 上也可能较慢。由于先前实现调用 `indexOf`，替换原本就是线性的；benchmark 推迟到真实 trace 表明更简单的数组成为瓶颈时再进行。格式版本仍为 `0`，因此显式拒绝旧事件是预发布格式边界的永久组成部分。作为交换，surface 顺序和请求头状态现在各自只有一种表示，删除了链接维护、map、codec 分支、往返 fallback 和感知 delta 的快照规范化。
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 bf64296c60..c6b8ad0680 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
-2026-07-22-plan-specific-collaboration-state.md: 8a7caf9b1150cb6d3ea2c8ed52e42751f30c773c
-2026-07-22-plan-specific-collaboration-state.zh.md: c4d2528cc06a74ce8c152199bc2503daff315dbf
+2026-07-22-plan-specific-collaboration-state.md: 2fc163213ca0ee1de5633e4d7db14a814b2f7bb2
+2026-07-22-plan-specific-collaboration-state.zh.md: 811f657bf31c96dde88e400fc25fe2fe6df1f157
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 8a7caf9b11..2fc163213c 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
@@ -14,7 +14,7 @@ The word “mode” also spans unrelated domains. Sandbox mode is an enforcing p
 
 Plan mode owns a plan-specific product package: `@deepseek-ai/dsh-plan-mode` at `packages/plan/plan-mode/`. The durable fact is `plan/mode: { active: boolean }`, folded by `foldPlanMode(events)` with `false` as the empty-log value. `ctx.planMode.get(agent)` returns `{ active, pending? }`, and `set(agent, active)` records the boundary-applied selection. The existing prompt-submit, continuation, retry, append-failure, and disposal fences remain unchanged in meaning.
 
-Configuration is exactly `{ section: string }`. The package registers the fixed `plan:policy` section, `/plan [message]`, and `exit_plan_mode` itself. Bare `/plan` selects the state; a non-empty argument selects it first and then sends the trimmed text through `agent.steer()`, making the text an ordinary logged user message in the affected step. The exit tool remains registered while plan mode is inactive so the request tool catalog stays stable.
+Configuration is exactly `{ section: string }`. The package registers the fixed `plan:policy` section, `/plan [message]`, the exact `/plan off` direct-exit form, and `exit_plan_mode` itself. Bare `/plan` selects active; another non-empty argument selects it first and then sends the trimmed text through `agent.steer()`, making the text an ordinary logged user message in the affected step. `/plan off` selects inactive without model input and can cancel an entry that is still pending at the boundary. The exit tool remains registered while plan mode is inactive so the request tool catalog stays stable.
 
 ACP keeps its protocol-level `default` and `plan` ids. The bridge maps those two ids to the boolean service, advertises only that fixed pair, rejects every other id at the adapter boundary, and maps committed `plan/mode` events back to `current_mode_update`. The protocol remains generic without forcing genericity into the product domain.
 
@@ -38,9 +38,9 @@ Sandbox mode and approval policy remain separate enforcement axes. Plan mode nei
 ## Verification
 
 - Package tests retain boundary ordering, retry, append-failure, HMR disposal, prompt assembly, stable native and Code Mode schemas, review outcomes, and invariant coverage through the boolean service.
-- Command tests cover bare `/plan`, `/plan <message>`, absence of `/mode` and `/review`, and effect-scoped removal.
+- Command tests cover bare `/plan`, `/plan <message>`, active `/plan off`, pending-entry cancellation, inactive idempotence, absence of `/mode` and `/review`, and effect-scoped removal.
 - ACP tests cover fixed advertisement, both ids, unknown-id rejection, optimistic updates, committed exits, and load replay.
-- The keyless TUI scenario enters through `/plan <message>` and proves `plan/mode` precedes the first request header and that the message is logged under plan guidance.
+- The keyless TUI scenarios enter through `/plan <message>`, leave through `/plan off`, and prove that each committed `plan/mode` precedes the request header it changes, the entry message is logged under plan guidance, and the post-exit request omits that guidance.
 
 ## Consequences
 
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 c4d2528cc0..811f657bf3 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
@@ -14,7 +14,7 @@ Status: implemented
 
 Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/` 的 `@deepseek-ai/dsh-plan-mode`。持久化事实为 `plan/mode: { active: boolean }`，由 `foldPlanMode(events)` 折叠，空日志值为 `false`。`ctx.planMode.get(agent)` 返回 `{ active, pending? }`，`set(agent, active)` 则记录在边界生效的选择。现有的提示词提交、continuation、重试、追加失败和 dispose（资源释放）栅栏在语义上保持不变。
 
-配置严格为 `{ section: string }`。该包自行注册固定的 `plan:policy` 段、`/plan [message]` 和 `exit_plan_mode`。不带参数的 `/plan` 选择该状态；非空参数则先选择该状态，再通过 `agent.steer()` 发送去除首尾空白后的文本，使该文本在受影响的步骤中成为一条记录到日志的普通用户消息。即使 plan mode 未激活，退出工具仍保持注册，以确保请求工具目录稳定。
+配置严格为 `{ section: string }`。该包自行注册固定的 `plan:policy` 段、`/plan [message]`、精确匹配的 `/plan off` 主动退出形式，以及 `exit_plan_mode`。不带参数的 `/plan` 选择激活；其他非空参数则先选择激活，再通过 `agent.steer()` 发送去除首尾空白后的文本，使该文本在受影响的步骤中成为一条记录到日志的普通用户消息。`/plan off` 选择未激活，不产生模型输入，并可取消仍待在边界生效的进入选择。即使 plan mode 未激活，退出工具仍保持注册，以确保请求工具目录稳定。
 
 ACP 保留协议层的 `default` 和 `plan` id。桥接层把这两个 id 映射到布尔服务，只公布这组固定选项，在适配器边界拒绝其他所有 id，并把已提交的 `plan/mode` 事件映射回 `current_mode_update`。协议仍保持通用性，但不会迫使产品领域也采用通用抽象。
 
@@ -38,9 +38,9 @@ ACP 保留协议层的 `default` 和 `plan` id。桥接层把这两个 id 映射
 ## 验证
 
 - 包测试通过布尔服务继续覆盖边界顺序、重试、追加失败、HMR（热模块替换）资源释放、提示词组装、稳定的原生 schema 与 Code Mode schema、评审结果和不变式。
-- 命令测试覆盖不带参数的 `/plan`、`/plan <message>`、不存在 `/mode` 和 `/review`，以及随 effect 作用域移除。
+- 命令测试覆盖不带参数的 `/plan`、`/plan <message>`、激活状态下的 `/plan off`、取消待生效的进入选择、未激活状态下的幂等性、不存在 `/mode` 和 `/review`，以及随 effect 作用域移除。
 - ACP 测试覆盖固定模式列表公布、两个 id、未知 id 拒绝、乐观更新、已提交退出和加载回放。
-- 无密钥 TUI 场景通过 `/plan <message>` 进入，证明 `plan/mode` 先于首个请求头，且消息在 plan 引导下记录到日志。
+- 无密钥 TUI 场景通过 `/plan <message>` 进入、通过 `/plan off` 退出，并证明每个已提交的 `plan/mode` 都先于其所改变的请求头，进入消息在 plan 引导下记录到日志，且退出后的请求不含该引导。
 
 ## 后果
 
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
new file mode 100644
index 0000000000..e3e24181d8
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-collapse-persistence-flush-state.md: a9b0f6847712f47d46adb6b01c57563033738964
+2026-07-23-collapse-persistence-flush-state.zh.md: acb9f798d86b4ec41d975d9de23f36080d3d7848
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
new file mode 100644
index 0000000000..a9b0f68477
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
@@ -0,0 +1,47 @@
+# Agent Note: Collapse live persistence into one flush controller
+
+Status: implemented
+
+English | [中文](2026-07-23-collapse-persistence-flush-state.zh.md)
+
+## 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.
+
+`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.
+
+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.
+
+Crash repair is cold-only. For a live identity, `load(id)` snapshots the authoritative in-memory events before awaiting their flush, then returns them with `SessionState.meta`, the header actually used for durable writes; it rejects an open turn without reading or repairing storage. A cold load reserves its identity synchronously inside the per-id chain before awaiting stored-prefix reads or repair writes; the `session/created` publication boundary rejects and rolls back a same-id live session until the reservation clears. HMR adoption remains separate through `loadStored` plus the coordinator's cwd check and truncates torn storage without closing the authoritative live turn.
+
+The live-controller map is also the retirement registry. Successful retirement drains and removes its controller; failed retirement leaves it in the map. Backend teardown stops event admission, flushes every controller still present, awaits remaining per-id operations, and closes the backend. No separate retirement set is needed to rediscover unfinished work.
+
+## 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.
+
+**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.
+
+**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`.
+- 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.
+- An AgentLoop regression races `resume()` against a live open turn and proves the original agent can still durably complete it without an injected `interrupted` boundary.
+- A controlled backend blocks `loadStored`, attempts same-id session publication while repair owns the reservation, and proves rollback leaves no ghost controller before a balanced resume succeeds.
+- The ownerless-claim contract gives the live `Session` a different `createdAt`, then proves live and later cold loads both return the original stored header.
+
+## 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.
+
+`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
new file mode 100644
index 0000000000..acb9f798d8
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
@@ -0,0 +1,47 @@
+# Agent Note: 将实时持久化归并到单个刷新控制器
+
+Status: implemented
+
+[English](2026-07-23-collapse-persistence-flush-state.md) | 中文
+
+## 问题
+
+持久化协调器使用彼此独立的缓冲区、初始化容器和退役容器，以及按 id 划分的操作链，表示一个活跃会话的写入生命周期。这些结构反映的是同一个事实：该 `Session` 是否仍有初始化操作或事件必须完成，之后才能释放其状态。仅由检查点触发的排空还会让每个事件都停留在易失状态，直至另一个插件请求 `session/flush`，尽管后端可以在不阻塞同步生产方的情况下开始持久化工作。
+
+## 决策
+
+每个活跃的 `Session` 都有一个控制器，其中包含 `pending`、`init` 和可选的当前 `flush` promise。`session/event` 监听器将冻结的事件复制到 `pending`，并立即调度 `ensureFlush()`。活跃写入期间的调用复用同一个 promise。排空操作会对待处理事件中一个稳定的前缀生成快照，并且只在 `appendBatch` 提交后移除该前缀；写入期间接纳的事件保留在该前缀之后，并调度一个后续批次。
+
+`session/flush` 是观测屏障。它等待初始化完成，并反复等待或启动控制器的刷新，直至当前 promise 和待处理事件均不存在。即时写入失败会被记录，但不会拒绝同步事件生产方；完整批次会保留下来，由下一次显式刷新、退役尝试或后端资源销毁重试。若该次重试仍失败，显式刷新和资源销毁仍会向调用方暴露失败。
+
+初始化只进入现有的按 id 操作链一次，并在占有该轮执行权时调用未串行化的核心操作。该操作链与活跃控制器保持分离，因为公共 `create`、`append`、`load` 调用即使没有 `Session` 对象仍可能发生竞态，依然需要按标识串行执行。
+
+崩溃修复仅适用于冷态标识。对于活跃标识，`load(id)` 会在等待刷新完成前，先对内存中的权威事件生成快照，再将这些事件与 `SessionState.meta`（即持久化写入实际使用的标头）一同返回；若轮次仍打开，则在不读取或修复存储的情况下拒绝该次加载。冷态加载会先在按 id 操作链内同步占用对应标识，再等待读取已存储前缀或执行修复写入；在这项占用解除前，`session/created` 发布边界会拒绝同 id 活跃会话的发布并将其回滚。HMR 接管仍由 `loadStored` 与协调器的 cwd 检查独立处理，会截断撕裂的存储，但不会闭合权威的活跃轮次。
+
+活跃控制器映射同时也是退役注册表。退役成功时，系统排空并移除其控制器；退役失败时，控制器保留在映射中。后端资源销毁会停止接纳事件，刷新所有仍存在的控制器，等待其余按 id 操作完成，然后关闭后端。无需另设退役集合来重新发现未完成的工作。
+
+## 备选方案
+
+**保留仅由检查点触发的延后写入。** 这种方式可以形成更大的批次，但会让持久性依赖另行挂载的检查点策略，并使检查点之间因崩溃而丢失数据的窗口达到最大。即时调度仍会合并同步突发事件，以及活跃写入期间到达的事件。
+
+**在整个协调器范围内使用一个刷新 promise。** 这种挂接方式适用于单个文件，但全局 promise 会串行化互不相关的会话。每个活跃会话各有一个控制器，既能让不同会话的后端操作独立推进，又由按 id 操作链保护同一标识的操作。
+
+**永久锁存首次即时写入错误。** 这会让后续每次刷新都得到确定的结果，却会阻止现有的资源销毁重试从暂时性存储故障中恢复。保留批次但不锁存错误，可以同时保留可观测性和重试能力。
+
+**拒绝对所有活跃会话的加载。** 这样做很安全，但会让持久化消费方和测试无法再使用既有的闭合活跃会话快照。先生成快照再刷新，为调用提供了稳定的线性化点：刷新成功即可证明正是该快照已持久化，而活跃路径绝不调用崩溃修复。
+
+## 验证
+
+- 一个针对协调器的测试会阻塞第一次追加，在该次写入期间接纳另一个事件，并在不调用 `session/flush` 的情况下观测到自动执行的第二个持久批次。
+- 共享协调器契约仍覆盖内存、JSONL 和 SQLite 后端上的活跃会话接管、冲突、崩溃修复，以及会话和后端的资源释放。
+- 失败和资源销毁测试会让写入失败的批次保持待处理，在关闭前重试这些批次，并证明尚在执行的控制器会延迟后端关闭。
+- 共享后端契约会持久化一个仍打开的活跃轮次，证明 `load` 会拒绝且不会写入合成闭合事件，随后完成该轮次并让其所有者退役，最后重新加载完全相同的已完成轮次。
+- AgentLoop 回归测试让 `resume()` 与一个仍打开的活跃轮次发生竞态，并证明原有的 agent（智能体）仍能完成该轮次并将其持久化，其间不会注入 `interrupted` 边界。
+- 一个受控后端会阻塞 `loadStored`，在修复操作持有标识占用期间尝试发布同 id 会话，并证明回滚不会留下残留控制器，之后可以成功恢复一个闭合会话。
+- 无所有者声明契约会为活跃 `Session` 设置不同的 `createdAt`，并证明活跃加载和之后的冷态加载均返回最初存储的标头。
+
+## 后果
+
+协调器有三个长生命周期容器：持久化的标识状态、活跃会话控制器和按 id 操作链。即时写入缩短了通常情况下因崩溃而丢失数据的窗口，并移除了彼此独立的缓冲区、初始化注册表和退役注册表。与仅由检查点触发的排空相比，这种方式可能产生更多后端批次；同一轮事件循环内的突发事件和一次写入期间接纳的事件仍会合并。
+
+`session/flush` 不再决定普通持久化何时开始。它仍是循环和检查点策略使用的顺序与错误观测边界，因此检查点成功仍表示在其完成前接纳的每个事件都已持久化。
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
new file mode 100644
index 0000000000..e118ff7330
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-property-based-testing.md: a1bd4147a26a3d562899310e238096939fc2d01a
+2026-06-11-property-based-testing.zh.md: 0e1934a24fcf22442420a664c9824bb74c0fe7f7
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 06350753cd..a1bd4147a2 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
@@ -2,6 +2,8 @@
 
 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.
 
 ## Problem
@@ -14,7 +16,7 @@ Adopt `fast-check` (a root devDependency) with one `tests/properties.spec.ts` pe
 
 - **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.
-- **dsh-tools:** arbitrary `SchemaSpec`. Invariants: JSON Schema `required` equals the `required:true` keys at every level; conversion total; **and the composition with [runtime arg validation](../architecture/2026-06-11-runtime-arg-validation.md)** — generated args satisfying a spec pass `validateArgs`, and targeted corruptions (dropped required key, non-object top level) are rejected. This closes the validator/`InferArgs` drift risk.
+- **dsh-tools:** arbitrary `ParameterSchemaSpec`. Invariants: JSON Schema `required` equals the `required:true` keys at every level; conversion is total for valid declarations; **and the composition with [runtime arg validation](../architecture/2026-06-11-runtime-arg-validation.md)** — generated args satisfying a spec pass `validateArgs`, and targeted corruptions (dropped required key, non-object top level) are rejected. Focused cases cover every value root, exact-one overlap/no-match, explicit openness, raw defaults, and lossy JSON. This closes the compiler/validator/`InferArgs` drift risk.
 - **dsh-agent-loop:** arbitrary send schedules against a never-exhausting adapter, driven through the `agent/status` settle signal (no wall-clock sleeps). Invariants: no message lost; turn numbers strictly increase; status transitions stay on the legal machine.
 
 ## Consequences
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
new file mode 100644
index 0000000000..0e1934a24f
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 对协议形态代码进行基于属性的测试
+
+Status: implemented
+
+[English](2026-06-11-property-based-testing.md) | 中文
+
+> 将原始提案与同一主题的决策记录合并为一篇。首次运行即发现了 BlockAssembler 重复 `block-end` 的真实 bug。
+
+## 问题
+
+基于示例的测试只能固定我们想到的用例。harness 的核心是协议形态的代码：分片流、事件日志、schema 转换、收件箱调度。这些场景的输入空间是组合式的，有趣的 bug 藏在没人写过示例的交错序列中。佐证：一个块组装的排序 bug 曾在 happy path 100% 行覆盖率下存活。逐文件 100% 覆盖率证明每一行都跑过了，但不能证明每种交错都是正确的。
+
+## 决策
+
+引入 `fast-check`（作为根 devDependency），在每个协议形态的包（package）中编写一个 `tests/properties.spec.ts`。生成器调优为*逼真但对抗性*的输入（而非均匀噪声），`numRuns` 控制在本地套件总耗时远低于约 10 秒。失败时打印可复现的 seed。（原始提案还草拟了一个夜间 CI job，以 100 倍迭代运行；该部分未交付。属性测试套件仅在常规的 `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 严格单调递增；非消息事件不影响推导出的历史；推导出的内容与日志解耦。
+- **dsh-tools：** 任意 `ParameterSchemaSpec`。不变式：JSON Schema 的 `required` 等于每一层 `required:true` 的键集；转换对合法声明而言是全函数；**并且与[运行时参数校验](../architecture/2026-06-11-runtime-arg-validation.md)组合验证**——满足 spec 的生成参数通过 `validateArgs`，而定向破坏（删除必填键、顶层非对象）被拒绝。聚焦用例覆盖每种根值类型、恰好一项匹配中的分支重叠与无匹配、显式开放性、原始默认值以及有损 JSON。这封堵了编译器、validator 与 `InferArgs` 之间的漂移风险。
+- **dsh-agent-loop：** 任意发送调度，对接一个永不耗尽的适配器，通过 `agent/status` settle 信号驱动（无挂钟 sleep）。不变式：无消息丢失；轮次编号严格递增；状态转换保持在合法状态机上。
+
+## 后果
+
+- 生成器质量是价值杠杆——生成器偏向小索引池和短字符串，使碰撞与交错频繁发生。
+- **它已经带来回报：** BlockAssembler 流发现了一个真实 bug——同一索引处重复的 `block-end` 会改写已经完成的块。现已修复（首次关闭优先，与现有迟到项规则一致），并加入专用回归测试。
+- 属性测试因超时而 flake 是一个发现，不应通过重试消除。循环属性测试在设计上是确定性的（通过 `agent/status` settle），因此挂起即为真实缺陷。
+- 属性测试是对示例测试的补充而非替代；示例测试固定特定分支，服务于 100% 覆盖率门禁。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..15551560ba
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-19-acp-snapshot-tests.md: 43900632c4e5e3904c2d0e3b75f2a3fe3b3a50cc
+2026-06-19-acp-snapshot-tests.zh.md: a4613b19001afe87c1f6bdb61196fabbfa947a4c
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 ebc48ba183..43900632c4 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-19-acp-snapshot-tests.zh.md)
+
 ## Problem
 
 Unit tests do not exercise the complete ACP subprocess transcript, while real-API tests are nondeterministic and key-gated. Editor-facing `session/update` output can therefore regress despite green unit coverage, as the [default-export postmortem](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) demonstrated.
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
new file mode 100644
index 0000000000..a4613b1900
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
@@ -0,0 +1,84 @@
+# Agent Note: ACP 快照测试——一次录制 / 确定性回放
+
+Status: implemented
+
+[English](2026-06-19-acp-snapshot-tests.md) | 中文
+
+## 问题
+
+单元测试不会覆盖完整的 ACP（Agent Client Protocol）子进程 transcript（文本记录），而真实 API 测试不具确定性且受密钥门控。因此，即使单元覆盖率为绿色，面向编辑器的 `session/update` 输出仍可能回归，[默认导出事后分析](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)已经证明了这一点。
+
+全 transcript 测试的阻塞因素在于模型：agent（智能体）的输出由非确定性的 LLM（大语言模型）驱动，而每次运行都命中真实 API 的密钥门控测试既不确定也无法在 CI 中运行。我们需要真实运行的保真度与 fixture（测试前置数据）的确定性兼得。
+
+本 Agent Note（agent 决策记录）记下了新增第三层测试——**快照测试**——的决策，以及让它具备确定性、在 CI 中无需密钥、且维护成本低廉的设计选择。
+
+## 决策
+
+快照测试会启动真实 ACP 示例，通过确定性脚本驱动其 stdio 协议，并将规范化输出与已提交的预期输出比较。从真实 API 一次记录的会话日志为后续所有模型流提供数据。fixture 就是产品普通的持久化 JSONL。
+
+### fixture 即持久化的会话 JSONL
+
+每个场景的 `session.jsonl` 都从真实运行中采集。`assistant/chunk` 事件复现模型流；工具、消息和边界事件捕获 harness 行为。因此，一份普通会话产物同时充当重放来源和行为预期输出。
+
+当场景固定另一种物理存储布局时，其 fixture 会从真实的未打包对应项机械派生。场景测试要求包含每一种预期存储行类型，并在解码后逐事件精确相等；随后，普通重放与日志比较才会证明组合后的进程能够消费并复现该布局。
+
+### 回放从日志推导模型脚本
+
+`llm-replay` 短路了提供方无关的 `llm/stream` waterfall（瀑布式事件）。`deriveReplayScript()` 按 `(turn, step)` 对已录制的分片分组，每次模型调用服务一组。agent loop（智能体循环）每个步骤发起一次流调用，因此分组精确对应，错误结束分片也无需特殊处理。
+
+### 内存中的回放条目遵守完整的 LLM 契约
+
+`deriveReplayScript` 产出一组 `ReplayEntry`，即回放监听器按位置服务的内存单元：
+
+```
+{ kind: 'chunks', chunks: StreamChunk[] }
+| { kind: 'throw', chunks: StreamChunk[], message: string, code: string }
+| { kind: 'hang' }
+```
+
+日志推导出分片条目。流开始前的抛出和挂起没有可重建的分片表示，因此这些场景提供 `replay.override.json`。throw 条目可以包含前缀分片以模拟流中途失败。显式覆盖避免了从有损的轮次结束原因推断适配器行为。
+
+### 位置式回放，单个在途流
+
+回放是位置式的，因此每个场景只允许一个在途模型流。并发会话快照需要按请求键索引的条目。调用顺序变更需要重新录制，fixture 缺失或耗尽时立即报错。
+
+### 录制采集日志；无密钥回放需要无提供方的配置
+
+记录模式使用真实 `llm-deepseek` 适配器和配置为 `persistenceCompression: 'none'` 的 JSONL 持久化后端运行场景，再把生成的 `.jsonl` 复制到场景目录。显式 raw 模式让已提交重放 fixture 保持逐行可读，而普通部署使用后端的压缩默认值。逐事件追加具有持久性，但 harness 会在采集前优雅关闭子进程（关闭 stdin → `await ctx.dispose()`），以确保最终事件已刷出。`llm-replay` 本身不执行记录——它只负责重放。
+
+重放使用 `cordis.snapshot.yml` overlay，以 `llm-replay` 替换真实适配器，同时保留实时组合。记录使用普通配置和由 harness 提供的持久化根目录。重放模式跳过 `.env` 加载，因此意外存在的 API 密钥不会触发实时调用。参见[单一来源配置 Agent Note](2026-07-04-single-source-acp-replay-config.md)。
+
+### 两个表面：归一化后比对
+
+快照运行断言**两个**归一化后的表面，因为 harness 的外部表面是不同的：
+
+1. **stdout transcript**——编辑器看到的、经过 framing 的 `session/update` JSON-RPC。用于捕获 ACP bridge 中事件→更新转换（`streamSessionEventUpdate`）的回归。与已提交的 `stdout.expected.jsonl` 比较。
+2. **重新持久化的会话 JSONL**，经过规范化后与 `session.jsonl` 比较。同一 fixture 同时作为重放来源和预期日志。提示词文本会被清理；按照[请求头固定 Agent Note](2026-07-06-pin-request-header-content-in-one-scenario.md)所述，每种请求头类别由一个场景固定可读提示词与工具内容。Override 场景仅从其 sidecar 派生模型行为。
+
+两个表面互补：stdout 覆盖 bridge 投影，JSONL 覆盖投影所省略的 loop、工具和 boundary 结构。
+
+规范化会替换会话、cwd、协议 id、时间戳、路径和进程易变值，同时保留确定性序号。场景把真实 bash 使用限制在稳定命令上。stdout 预期输出仍是线协议形状的 JSONL，每个原始行都必须可解析为 JSON。Vitest 只更新 stdout 预期输出；规范化会话相等性检查从不覆盖重放 fixture。
+
+### 隔离：当前靠归一化，后续可加沙箱
+
+工具确定性来自生成的 cwd、清理后的环境、全新的非登录 shell、受限命令和规范化。cwd 默认为平台临时目录；当临时目录是始终可写的策略根，而行为需要独立项目位置时，场景可以改为提供其父目录。并发重放运行各自拥有独立 cwd、持久化目录和由定长场景键区分的 spill 根目录，因此一个场景的拆除无法删除另一个场景仍在进行的完整输出恢复，同时真实路径预览预算保持稳定。该层不声称提供 OS 级隔离。如果需要更强层级，沙箱执行器可以通过现有[能力 seam](../architecture/2026-06-13-capability-seams.md)替换本地后端。
+
+### 回放插件是独立的包
+
+`@deepseek-ai/dsh-llm-replay` 是一个支撑包（package），而非示例本地的胶水代码。它通过用从 JSONL 重建的流短路 `llm/stream` 来替换真实适配器，其包级放置使回放逻辑处于正常覆盖率门禁之下。
+
+### 两个子命令，回放在默认门禁中
+
+`pnpm run test:snapshot` 无需密钥即可重放已提交 fixture；`test:snapshot:record` 使用真实 API，并重写采集的会话日志与 stdout 预期输出。缺少 fixture 时会响亮失败。每个场景都包含 `input.json`、`stdout.expected.jsonl` 和 `session.jsonl`；不调用模型的情况使用仅有请求头的日志。只有标记为 `overridden` 的场景才需要 `replay.override.json`，因为它一旦存在就会取代派生重放。Fixture 守卫会拒绝缺失、不匹配和孤立文件。两个命令都接受场景过滤器。
+
+## 曾考虑的替代方案
+
+- **手工编写包含模型分片的 `llm.json`**——早期草案；复用真实会话日志，使 fixture 成为系统的真实产物而非手工构建的 mock，并让它同时充当行为预期输出。
+- **字节级 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。
+
+## 后果
+
+新测试层为每个场景增加经过评审的输入、会话、stdout、可选 override 和可选 workspace fixture。记录与重放都会把 workspace seed 复制到生成的 cwd。作为回报，该层通过真实 Loader 和工具组合提供确定性的无密钥 transcript 覆盖。子进程、输入、workspace、规范化和重放 harness 也可以支持 ACP 之外的示例。
+
+本 Agent Note 与[拟议的确定性 Agent Note](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md)相关，但不取代它：该提案的“通用重放 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
new file mode 100644
index 0000000000..0ca80ac88b
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-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
+2026-06-19-real-api-e2e-ci.md: a9289980ada8ab6390b5daa488f07ec258db1bd5
+2026-06-19-real-api-e2e-ci.zh.md: dcb5759d26e7680d392a4855665b2eb88551ba79
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 05da5152ff..a9289980ad 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-19-real-api-e2e-ci.zh.md)
+
 ## Problem
 
 The harness leans hard on real-API tests by policy: [docs/testing.md](../../../../docs/testing.md) argues that a no-key suite proves the plumbing but not the product, and the [ACP inject postmortem](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) is the standing proof — 178 keyless tests stayed green while a real editor session crashed instantly. The real-API e2e suite (`pnpm run test:e2e`, the `*.e2e.ts` files) exists precisely to close that gap: it drives the agent against the live DeepSeek API — real model calls, real bash tools, multi-turn, resume, ACP-over-stdio.
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
new file mode 100644
index 0000000000..dcb5759d26
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
@@ -0,0 +1,102 @@
+# Agent Note: 在 CI 中对外部 DeepSeek API 运行真实 API e2e 测试
+
+Status: implemented
+
+[English](2026-06-19-real-api-e2e-ci.md) | 中文
+
+## 问题
+
+根据策略，harness 高度依赖真实 API 测试：[docs/testing.md](../../../../docs/testing.md) 指出，无密钥套件证明的是管线，而非产品；[ACP（Agent Client Protocol）inject 事后分析](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)则是常设证据——178 项无密钥测试保持绿色时，真实编辑器会话却立即崩溃。真实 API e2e 套件（`pnpm run test:e2e`，即 `*.e2e.ts` 文件）的存在正是为了弥合这一缺口：它针对实时 DeepSeek API 驱动 agent（智能体）——真实模型调用、真实 bash 工具、多轮次、恢复、ACP-over-stdio。
+
+默认门禁（[.github/workflows/ci.yml](../../../../.github/workflows/ci.yml)）刻意无密钥：不携带 secret，可供 fork 运行。`test:e2e` 在无密钥时自动跳过（`describe.skipIf(!process.env.DEEPSEEK_API_KEY)`），因此将其加入该工作流只会报绿而不会真正执行真实套件。要让真实 API 覆盖率成为合并信号，需要一个独立的、携带 secret 的工作流。
+
+本 Agent Note（agent 决策记录）记下了新增**第二条消费 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 中的一个 job
+
+ci.yml 的价值在于它无密钥、可 fork、始终为绿：任何贡献者（包括外部 fork）都能获得完整的无密钥信号，secret 不在爆炸半径内。在其中添加消费 secret 的 job 会将这个始终为绿的门禁耦合到凭证可用性和不同的触发策略上。将携带 secret 的工作放在独立文件中，隔离了 secret、触发和并发策略，并为 fork 保留了 ci.yml 的特性。不同的生命周期→不同的文件。
+
+### 约束不是成本，而是可靠性
+
+内部推理成本不是限制因素，因此工作流针对覆盖面和信号优化。它会在多种触发条件和每个受信任 PR（Pull Request）上运行所有匹配的 `*.e2e.ts` 文件，以落实 [docs/testing.md](../../../../docs/testing.md) 的有密钥策略。
+
+### 触发条件：仅限可信事件
+
+`workflow_dispatch` + `push` 到 `main`/`master` + 每夜 `schedule`（`17 0 * * *`，即北京时间 08:17）+ `pull_request`。push 提供合并后信号；schedule 捕捉外部 API 漂移；dispatch 是手动逃生通道；可信 pull request 获得合并前门禁。该合并前信号有意接受 § 安全性中描述的更大密钥暴露面。
+
+### 不可信 PR 的门禁
+
+GitHub 对两类 PR 扣留 repo secret：来自 **fork** 的 PR，以及 **Dependabot** PR（同仓库分支，`head.repo.fork == false`，但 secret 仍被扣留）。一个 job 级 `if:` 对两者都跳过整个 job：
+
+```
+github.event_name != 'pull_request'
+  || !(github.event.pull_request.head.repo.fork || github.event.pull_request.user.login == 'dependabot[bot]')
+```
+
+Dependabot 子句基于 PR **作者**（`pull_request.user.login`）而非 `github.actor`（运行触发者）：维护者重新打开或重跑 Dependabot PR 时，`github.actor` 会变成人类，但该 PR 仍然无密钥；基于作者的判断在这种情况下依然正确。被 **job 级** `if:` 跳过的 job 报告为*成功*检查（不同于工作流/触发级跳过会保持 pending），因此如果需要将此工作流标记为 required status check 也是安全的——fork/Dependabot PR 的跳过但绿色的检查不会阻塞合并。
+
+该门禁是一个*干净跳过的便利措施*，而非 secret 的安全边界（见 § 安全性——边界是 GitHub 自身在 `pull_request` 下对 fork 的 secret 扣留机制）。没有该门禁，fork 仍然无法读取密钥；只是会遇到令人困惑的 preflight 硬失败并浪费计算资源。
+
+### Preflight：大声失败，绝不虚假为绿
+
+由于 job 仅在 secret 应当存在的可信事件上运行，preflight 是一个无条件的存在性检查：密钥为空→`exit 1` 并附带 `::error::` 注解指明需要配置的 secret 名称。这是让自跳过套件可以安全地作为门禁的关键。没有它，被删除/重命名/错误配置的 secret 会让 `test:e2e` 跳过所有真实套件并报告全绿——整个安全网的静默退化。该守卫将「secret 缺失」从不可见的虚假通过转化为可见的失败。（其正确性已在实际中验证：secret 存在之前的运行恰好在此步骤失败。）
+
+### Secret 映射与卫生
+
+repo secret 命名为 `DEEPSEEK_API_KEY_EXTERNAL`；映射到适配器和测试读取的 `DEEPSEEK_API_KEY` 环境变量（`process.env.DEEPSEEK_API_KEY`）。独立的 secret 名称记录了意图（这是*外部*公开 API 密钥，不是内部端点密钥），并允许内部端点密钥日后无冲突地共存。以下卫生选择均为防御性设计：
+
+- **步骤级 secret。** `DEEPSEEK_API_KEY` 仅在 preflight 和 e2e 步骤的 `env:` 中设置，从不在 job 级设置——因此 checkout/setup-node/install 永远看不到它。依赖中被入侵的安装时生命周期脚本无法读取不在其环境中的 secret。
+- **`permissions: contents: read`。** job 仅读取仓库以运行测试；不需要写权限（无 PR 评论、无 status 写入），因此 `GITHUB_TOKEN` 降至最小权限。
+- **`DEEPSEEK_BASE_URL` 固定**为 e2e 步骤上的 `https://api.deepseek.com`。适配器在未设置时会默认使用此值（[packages/llm/llm-deepseek/src/index.ts](../../../../packages/llm/llm-deepseek/src/index.ts) `PUBLIC_BASE_URL`），但显式固定具有自文档性和密封性——仓库根目录的 `.env`（`vitest.e2e.config.ts` 存在时会加载）无法静默地将运行重定向到其他端点。
+- **不回显 secret。** preflight 仅打印 `DEEPSEEK_API_KEY present.`——不打印值或长度。
+
+### 范围与运行时形态
+
+job 仅在 Node 24 上运行 `test:e2e`；无密钥门禁和版本兼容性属于主 CI 工作流。测试通过 workspace paths 映射以未构建形式运行，使用有界的可配置 worker 池、逐测试重试和 job 超时。被取代的 PR 运行会被取消，而 push 和 schedule 运行完整执行以提供合并后信号。
+
+DeepSeek 原生 `web_search` 探测已注册但会跳过。实时 Anthropic 兼容端点可能返回成功响应却没有结构化来源块，因此对来源存在性的正向断言不是可靠的合并信号；单元覆盖率仍会固定响应解析，但 CI 不会证明实时来源块的线协议形状。
+
+## 安全性
+
+仓库的首个 CI secret 需要一份记录在案的威胁模型，因为同仓库 PR、fork PR 和 Dependabot PR 的访问权限各不相同，且仓库公开后会发生变化。
+
+### 当前谁能触及 secret（私有仓库）
+
+- **无写权限（fork PR）：不能。** 两个独立事实阻止了它。第一，工作流使用 `pull_request` 而**非** `pull_request_target`——GitHub 不会将 repo secret 传递给 fork PR 的 `pull_request` 运行，因此 `secrets.DEEPSEEK_API_KEY_EXTERNAL` 在 fork runner 上解析为空。第二，`if:` 门禁完全跳过 fork PR。secret 扣留是真正的边界；门禁是纵深防御和用户体验。
+- **有写（push）权限：能。** 同仓库分支 PR 会收到 secret，因此有写权限的作者可以修改测试代码（或安装生命周期脚本，或其分支上的工作流 YAML）来窃取密钥。这**是 GitHub Actions 的固有特性，并非本文引入的**：任何对任何仓库有 push 权限的人都可以通过编写工作流来窃取该仓库的任何 Actions secret。写权限⇒secret 访问权，始终如此。缓解措施在于谁被授予写权限以及分支保护，而非本文件。
+
+因此「任何能开 PR 的人都能窃取它」是错误的：只有写权限集合内的人能，而这些人本来就能窃取仓库持有的任何 secret。
+
+### `pull_request` 触发器增加的残余暴露面
+
+由于启用了 PR 运行，密钥会在合并前被交给**写权限作者 PR 分支上的代码**。这比 `push` + `schedule` + `workflow_dispatch` 的暴露面更大，为在可信写权限集合内获得合并前信号而接受。如果这一权衡发生变化，可移除 `pull_request` 触发器，同时保留合并后、每夜和按需覆盖。
+
+### 仓库公开后的变化
+
+**通过本工作流**，secret 对公众仍然受保护：`pull_request` 在公开仓库上行为一致——fork PR（现在任何人都能开）仍然收不到 secret，且在公开仓库上 GitHub 额外要求维护者批准 fork PR 运行，即使批准后运行也不会获得 secret（批准运行不等于交出密钥）。写权限集合不因可见性改变而改变，因此内部人员的现实也不变。
+
+变差的是*周边*模型，以下是翻转可见性之前需要处理的事项：
+
+- **日志变为全球可读。** 今天泄露给组织成员的粗心 secret 回显，公开后会泄露给整个互联网并在数分钟内被爬取。secret 处理纪律（不回显值/长度——已做到）的重要性大幅提升。
+- **`pull_request_target` 陷阱变为灾难性的。** 如果有人为了「修复」PR 运行而将触发器切换为 `pull_request_target`，工作流将在 base-repo 上下文中运行不可信的 fork 代码并**携带** secret——完整的密钥泄露向量。在私有仓库中这勉强无害，在公开仓库中则是灾难。e2e.yml 中触发器上的 `SECURITY —` 注释禁止此更改并指向本文。
+- **翻转时轮换密钥。** 密钥曾存在于私有仓库的 CI 中；将公开视为「假定已暴露」，在那一刻轮换 `DEEPSEEK_API_KEY_EXTERNAL`。
+- **将 secret 置于控制之下。** 确认 Settings → Actions → *"Send secrets to workflows from fork pull requests"* 保持**关闭**（这是唯一真正会打破 fork 边界的设置），并考虑将密钥移入带有 required reviewers 的 GitHub **Environment**，使即使已合并的代码也只在受控条件下使用它，且轮换有单一归属。
+
+以上均不需要修改工作流即可公开；它们是运维步骤加上已添加的 `pull_request_target` 守卫注释。
+
+## 曾考虑的替代方案
+
+- **在 ci.yml 中添加消费 secret 的 job**：否决。会将无密钥、可 fork、始终为绿的门禁耦合到凭证可用性和不同的触发/并发策略上；不同的生命周期，不同的文件。
+- **省略 `pull_request` 触发器**（更小的密钥暴露面）：为获得合并前信号而否决；安全性章节承载了已接受的暴露分析。
+
+## 后果
+
+新增一个 CI 工作流和仓库的首个需要维护的 secret。真实 API 套件现在作为合并门禁（可信 PR 上的合并前门禁、主分支上的合并后门禁）并每夜运行，因此 agent 与外部 API 交互中的真实故障会在 CI 中浮现，而非仅在开发者的本地运行中出现——代价是每个可信 PR 和合并都会产生真实的（但内部免费的）API 调用。preflight 使 secret 配置错误变为自我通告而非静默禁用安全网。
+
+该设计带有已记录的约束表面：`pull_request` 触发器在密钥暴露方面的取舍（删除它可加强防护）、`if:` 门禁对基于作者的 Dependabot 检查的依赖，以及对 `pull_request_target` 的严格禁止。上方公开仓库检查清单是操作配套——未来维护者在更改触发器集合或切换仓库可见性之前，应重新阅读本 Agent Note，而不是从头推导 fork/secret 模型。
+
+schedule 触发器在仓库不活跃 60 天后会自动禁用（GitHub 行为）；push/PR/dispatch 是后备，活跃的 monorepo 不会触及此限制。假设 runner 对 `https://api.deepseek.com` 有出站连通性——GitHub 托管的 `ubuntu-latest` 具备此条件；受出站限制的自托管 runner 需要在依赖每夜运行之前确认连通性。
diff --git a/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.i18n.yaml b/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.i18n.yaml
new file mode 100644
index 0000000000..9ea114c43e
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-remove-redundant-snapshot-log-expected-output.md: c2452f971d3cb76dceb766072dbc0a5c81465e78
+2026-06-20-remove-redundant-snapshot-log-expected-output.zh.md: e6175181589eabae064c34044f353efae537961b
diff --git a/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.md b/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.md
index b17ecad098..c2452f971d 100644
--- a/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.md
+++ b/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-20-remove-redundant-snapshot-log-expected-output.zh.md)
+
 ## Problem
 
 Model-driving ACP snapshot scenarios ship both `session.jsonl` and `session.expected.jsonl`. For normal recorded scenarios, `session.jsonl` is the replay fixture harvested from a real run, and the replay test normalizes the newly persisted log and compares it to `session.expected.jsonl`. In the current fixtures, the two normalized logs are identical for ordinary recorded scenarios.
diff --git a/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.zh.md b/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.zh.md
new file mode 100644
index 0000000000..e617518158
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 使用 `session.jsonl` 作为唯一的快照会话日志产物
+
+Status: implemented
+
+[English](2026-06-20-remove-redundant-snapshot-log-expected-output.md) | 中文
+
+## 问题
+
+驱动模型的 ACP（Agent Client Protocol）快照场景同时包含 `session.jsonl` 和 `session.expected.jsonl`。对于普通记录场景，`session.jsonl` 是从真实运行采集的重放 fixture（测试前置数据）；重放测试会规范化新持久化的日志，并将其与 `session.expected.jsonl` 比较。在当前 fixture 中，普通记录场景的两份规范化日志完全相同。
+
+手工编写的 override 场景（`error-finish`、`cancel`）目前使用 `replay.override.json` 驱动模型行为，并把 `session.jsonl` 保留为最小 dummy fixture，而 `session.expected.jsonl` 存放预期的持久化日志。override 文件是由 `ReplayEntry` 对象组成的 JSON 数组：`{ "kind": "chunks", "chunks": StreamChunk[] }`、`{ "kind": "throw", "chunks": StreamChunk[], "message": string, "code": string }` 或 `{ "kind": "hang" }`。这种拆分同样没有必要：override sidecar 存在时，`llm-replay` 会替换派生脚本，不需要从 `session.jsonl` 取得模型分片，因此 `session.jsonl` 仍可作为场景的预期会话日志产物。
+
+## 决策
+
+彻底移除 `session.expected.jsonl` 概念。每个场景最多只有一个已提交会话日志产物，即 `session.jsonl`：
+
+- 对于录制场景，`session.jsonl` 仍是原始采集的日志。回放仍从中派生模型分片，快照测试将回放运行归一化后的持久化日志与归一化后的 `session.jsonl` 进行比较。
+- 对于手工编写的覆盖场景，`replay.override.json` 驱动模型行为，`session.jsonl` 存放预期产出的会话日志。当覆盖文件存在时，回放适配器不从 fixture 获取模型分片，因此同一个文件既可作为预期日志，又不影响回放行为。
+- 对于无模型场景，`session.jsonl` 可保留为引导 `llm-replay` 所需的最小 fixture；除非场景创建了持久化会话，否则无需进行会话日志比较。
+
+Stdout 预期输出保持不变；它们是面向编辑器的投影，与会话 fixture 并不重复。
+
+## 曾考虑的替代方案
+
+**对两侧基于共享的（回放运行）上下文做归一化**：否决。`normalizeSessionLog` 通过精确字符串匹配擦除 cwd，因此 fixture 中录制的 cwd 不会被擦除，每次比较都会失败。两侧各自基于自身 header 派生的上下文做归一化——下方的实现说明描述了具体机制。
+
+## 验证
+
+快照 harness、fixture、孤立项守卫和文档中都不再出现 `session.expected.jsonl`；对于每个模型场景，快照测试都从 `session.jsonl` 派生预期会话日志；手工编写 sidecar 的场景把预期生成日志提交为 `session.jsonl`，并以 `replay.override.json` 覆盖模型行为；孤立 fixture 守卫知道每种场景类型所需的文件。[ACP 快照测试 Agent Note（agent 决策记录）](2026-06-19-acp-snapshot-tests.md)描述了精简后的 fixture 集合。
+
+## 后果
+
+评审者失去了一个能在视觉上区分预期持久化日志与重放 fixture 的产物名。stdout 预期输出仍然保护编辑器 transcript（文本记录），而将重放输出与 `session.jsonl` 比较，无需复制文件即可保留循环/持久化回归检查。
+
+## 实现说明
+
+两侧各自基于自身 header 值做归一化，因为录制与回放具有不同的 id、路径和时间戳。`fixtureContext()` 从 fixture 的 header 派生上下文，使已归一化的 fixture 具有幂等性。会话日志使用普通相等比较而非文件快照更新，因此比较过程不会改写 fixture。
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
new file mode 100644
index 0000000000..822fc921b4
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-22-fork-child-replay-seed-boundary.md: d3cbbb1dae1d64a10973bd5895ccc47d877eba28
+2026-06-22-fork-child-replay-seed-boundary.zh.md: a944538b9dcb74eb15142593089c7905efc3f565
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 93280ed62e..d3cbbb1dae 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-22-fork-child-replay-seed-boundary.zh.md)
+
 ## Problem
 
 The [per-session snapshot replay Agent Note](2026-06-22-subagent-snapshot-replay.md) made the snapshot tier express a nested-agent shape: a parent plus one recorded log per in-process subagent, each replayed as its own script keyed by calling session. It noted (§ Scope, final bullet) that a fork snapshot was "a trivial future addition, not a gap in the keying." That was wrong about a fork child specifically — not the keying, but the *script derivation*.
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
new file mode 100644
index 0000000000..a944538b9d
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
@@ -0,0 +1,49 @@
+# Agent Note: 持久化 seed 边界以确保 fork 子会话回放正确路由
+
+Status: implemented
+
+[English](2026-06-22-fork-child-replay-seed-boundary.md) | 中文
+
+## 问题
+
+[逐会话快照重放 Agent Note（agent 决策记录）](2026-06-22-subagent-snapshot-replay.md)使快照层能够表达嵌套 agent 形状：一个父项加上每个进程内 subagent 的一份记录日志，每份日志都按调用会话作为键，以独立脚本重放。它曾指出（§ 范围，最后一个项目符号），fork 快照“只是未来很容易添加的一项，并非键控缺口”。这一判断对 fork 子项而言是错误的——问题不在键控，而在*脚本派生*。
+
+subagent 脚本由 [`deriveReplayScript`](../../../../packages/support/llm-replay) 从已录制的会话日志推导：它按 `(turn, step)` 对日志中的 `assistant/chunk` 事件分组，每次 `stream()` 调用对应一条回放条目。对 **spawn** 子会话而言这是正确的，因为其日志只包含自身的模型调用。
+
+**fork** 子会话不同。fork 后端用*父日志的一段平衡的已完成轮次前缀*（[`dsh-subagent-inprocess`](../../../../packages/subagent/subagent-inprocess)）来播种子会话，而该 seed 会成为子会话持久化的 `log`（`Session` 构造函数将 seed 复制进 `this.log`）。因此 fork 子会话的 `.jsonl` 以**父会话**的事件开头——包括父会话的 `assistant/chunk` 事件——之后才是子会话自身的轮次。
+
+从 fork 子会话的完整日志推导脚本，会把**父会话**的已录制响应当作**子会话**的模型调用来回放：实际运行的 fork 子会话第一次调用 `stream()` 时，会收到父会话的第一段分片序列而非自身的。目前已录制的场景全部是 spawn，所以这从未触发——但 fork 快照会静默地错误路由，恰好属于快照层存在的意义所要捕获的那类 bug。
+
+## 决策
+
+记录会话**继承**前缀的结束位置，将其持久化，并让回放 harness 仅从子会话**自身**的事件推导脚本。
+
+### 1. 会话头部的 `seedLength`
+
+`SessionHeader` 新增可选字段 `seedLength: number`——表示有多少前导事件是通过 seed 继承而来、而非本会话产生的。fork 后端在创建子会话时设置它（= 播种前缀的长度）；全新的 spawn 子会话不设置（等同于 0）。它通过 `CreateSessionOptions.meta`（及 `CreateAgentOptions.meta`）传递，在 `SessionStore.prepare` 中设置。
+
+`seedLength` 是**显式**的，绝不从 `seed.length` 推断。恢复/加载时用会话的完整已存储日志作为 seed，此时 `seed.length` 是全长而非原始边界——恢复路径改为从加载的 header 中取回持久化的 `seedLength`。（形状与 `createdAt` 相同：恢复时显式保留，而非重新默认为当前时间。）
+
+### 2. 两个持久化后端均完整往返
+
+- **JSONL**：header 行上的 `seedLength` 字段（`toHeaderLine`/`fromHeaderLine`）。
+- **SQLite**：`sessions` 表上的 `seed_length` 列。
+
+包含 `seed_length`、`source_event_seqs` 和 `surface_op` 的 SQLite 布局为 schema version 4。更早的 version 3 布局存在歧义，因此在预发布策略下，所有非当前 `user_version` 均直接拒绝，不做迁移。
+
+### 3. 回放从边界之后推导子会话脚本
+
+`dsh-llm-replay` 的 `parseSessionHeader` 现在也读取 `seedLength`（缺失则为 0），`loadSessionScripts` 从 `parseSessionLog(text).slice(seedLength)` 推导子会话条目——即边界及之后的事件，也就是子会话自身的模型调用。对 spawn 子会话而言 `seedLength` 为 0，此操作是空操作，spawn 场景逐字节不变。
+
+这关闭了路由正确性的缺口，两个已录制的 fork 场景对其进行端到端验证——见[记录 fork 与混合 spawn+fork 快照场景](2026-06-22-fork-snapshot-scenarios.md)。
+
+## 曾考虑的替代方案
+
+- **在 `llm-replay` 中启发式推导边界**（播种前缀是连续的父事件，止于子会话第一条 `user/message` 之前的最后一个 `turn/end`）。否决：在测试 harness 中用脆弱的启发式重新推导一个生产者已经知道的事实。在源头（fork 后端）持久化边界，是「在包（package）seam 处显式优于隐式」这条规则跨越持久化边界的应用——子会话 fixture（测试前置数据）的读取者永远不需要重建继承在哪里结束。
+- **固定格式版本而不递增**（事件日志使用的 `SESSION_FORMAT_VERSION = 0`「不稳定」姿态）。对 SQLite *表*布局否决：`SCHEMA_VERSION` 是单调递增并拒绝旧版的旋钮（一组小的、值得区分的修订），与事件词汇表的 `version` 不同。新增列正是它所版本化的那种破坏性表变更，因此需要递增。
+
+## 后果
+
+- core 与两个后端新增一个持久化 header 字段；核心数据结构目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。
+- 既有的 schema v2 SQLite 数据库在打开时被拒绝（预发布阶段无用户数据）。
+- spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 契约）。
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.i18n.yaml
new file mode 100644
index 0000000000..2e87edf31e
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-22-fork-snapshot-scenarios.md: 46c688a4095a1d8af32b3b99887929f71a1526ce
+2026-06-22-fork-snapshot-scenarios.zh.md: 8823611ec02f269e5a21a8065c9ed3cc3911f749
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.md b/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.md
index 272e62ba77..46c688a409 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-22-fork-snapshot-scenarios.zh.md)
+
 ## Problem
 
 The [seed-boundary Agent Note](2026-06-22-fork-child-replay-seed-boundary.md) made fork-child replay route correctly: `dsh-llm-replay` derives a child's script from the events at or after its persisted `seedLength` boundary, so a fork child's inherited parent prefix is not replayed as the child's own model calls. But it shipped with **no recorded fork scenario** — the slice was exercised only by `llm-replay`'s unit tests (a synthetic child fixture) and a persistence round-trip test. The full-transcript snapshot tier, the one net that boots the real `acp-agent` and replays an end-to-end nested transcript, had only spawn children (`subagent-spawn`, `subagent-multi`). A fork-routing regression that left the unit tests green would still have escaped the tier built to catch transcript regressions.
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.zh.md
new file mode 100644
index 0000000000..8823611ec0
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 记录 fork 与混合 spawn+fork 快照场景
+
+Status: implemented
+
+[English](2026-06-22-fork-snapshot-scenarios.md) | 中文
+
+## 问题
+
+[seed 边界 Agent Note（agent 决策记录）](2026-06-22-fork-child-replay-seed-boundary.md)让 fork 子项重放能够正确路由：`dsh-llm-replay` 根据持久化 `seedLength` 边界处及其后的事件派生子项脚本，因此 fork 子项继承的父前缀不会作为子项自身的模型调用重放。但落地时**没有记录式 fork 场景**——slice 只由 `llm-replay` 单元测试（合成子项 fixture（测试前置数据））和持久化往返测试覆盖。完整 transcript（文本记录）快照层——会启动真实 `acp-agent` 并重放端到端嵌套 transcript 的那张网——只有 spawn 子项（`subagent-spawn`、`subagent-multi`）。如果 fork 路由回归没有让单元测试变红，它仍会逃过专为捕获 transcript 回归而构建的这一层。
+
+表达 fork 场景所需的快照基础设施已经就位：两个进程内后端都在 `cordis.yml` / `cordis.snapshot.yml` 中以两个面向模型的工具接入（`subagent` → spawn、`subagent_fork` → fork），harness 会收集每个子会话的日志，回放按 `seedLength` 为键转发各子会话的 fixture。缺少的是一个*已记录的场景*来驱动 fork 子会话走完这条路径。
+
+## 决策
+
+针对真实 API 记录两个场景，均在默认门禁中以无密钥方式回放：
+
+- **`subagent-fork`**：父会话完成一个轮次以建立一个事实，然后通过 `subagent_fork` 委派一个子任务。fork 子会话继承对话（其日志携带非零 `seedLength`），因此可以从父会话的上下文中作答。这是聚焦的回归守卫：子会话 fixture 的 `seedLength` 就是回放切片所依赖的边界，来自真实 fork 的记录而非手工合成。
+- **`subagent-mixed`**——父项完成一个轮次，随后在同一 transcript 中通过 `subagent` 委托一次（全新 spawn 子项，`seedLength` 为 0），再通过 `subagent_fork` 委托一次（fork 子项，`seedLength` 非零）。这是 seed 边界与逐会话重放 Agent Note 都点名作为未来新增项的 spawn+fork 混合场景：一份 transcript 覆盖两种传输方式和 slice 的两个分支（`seedLength` 为 0 = 无操作，`seedLength > 0` = 裁剪继承前缀），两个子项按 `createdAt` 排列为先 spawn、后 fork。
+
+### 为什么需要一个已完成的第一轮次
+
+fork 后端使用父项的**已配平完整轮次前缀**为子项提供 seed。父项若在第一个轮次就执行 fork，没有已完成轮次可供继承，因此 seed 为空（≡ 全新 spawn，`seedLength` 为 0）——这不会覆盖 slice。因此，两个场景都使用双提示词输入：第一个提示词完成一个轮次（建立稍后要求子项回忆的 codeword），第二个提示词委托 fork。子项 transcript 中回忆出的 codeword 只是模型行为的附带结果；承载关键约束的产物是子项 fixture 中记录、由重放 slice 消费的 `seedLength`。
+
+## 后果
+
+- fork 路由切片现在由全 transcript 层守卫，而不仅仅是单元测试。移除 `slice(seedLength)`（回放整个子会话日志）会让**两个**新场景变红——fork 子会话收到的是父会话记录的分片而非自己的——证明守卫确实生效（场景落地时已验证红→绿）。
+- `subagent-mixed` 是第一个在同一个 transcript 中驱动两种*不同* subagent 后端的快照场景，同时覆盖了跨 spawn 和 fork 子会话的逐会话回放键控。
+- 进程外（ACP（Agent Client Protocol））subagent 回放形态不同（每个子会话是独立进程、有自己的回放），仍以 `TODO(acp-subagent-replay)` 跟踪——本文场景仅限进程内。
+- 重新录制（`pnpm run test:snapshot:record`）会从真实 API 重新生成全部四个 fork/spawn fixture；两个新场景在无密钥时自动跳过，与所有已录制场景一致。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..379054599b
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-22-subagent-snapshot-replay.md: 4aad8b6ddd3e4f8b8ad5565e10b263953d81ea31
+2026-06-22-subagent-snapshot-replay.zh.md: 96890bc98a64357d9785b8081c8ba123bb3c716e
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 d21a081f9b..4aad8b6ddd 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
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-06-22-subagent-snapshot-replay.zh.md)
+
 ## Problem
 
 The snapshot tier (`pnpm run test:snapshot`) boots the real `acp-agent` subprocess, replays a recorded session through [`dsh-llm-replay`](../../../../packages/support/llm-replay), and diffs the normalized stdout transcript + re-persisted session log against committed expected outputs. It is the only tier that exercises the full editor-facing transcript end to end.
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
new file mode 100644
index 0000000000..96890bc98a
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
@@ -0,0 +1,58 @@
+# Agent Note: 嵌套 agent 的逐会话快照回放
+
+Status: implemented
+
+[English](2026-06-22-subagent-snapshot-replay.md) | 中文
+
+## 问题
+
+快照层（`pnpm run test:snapshot`）会启动真实 `acp-agent` 子进程，通过 [`dsh-llm-replay`](../../../../packages/support/llm-replay) 重放已记录会话，并将规范化 stdout transcript（文本记录）+ 重新持久化的会话日志与已提交预期输出进行 diff。它是唯一端到端覆盖完整面向编辑器 transcript 的测试层。
+
+该层最初为每个进程只有一个会话而构建，这一假设硬编码在两处：
+
+- **`dsh-llm-replay` 没有做任何键控。** 它用一个全局游标，将第 N 次 `llm/stream` 调用对应到单一录制序列的第 N 条。当父 agent（智能体）和一个进程内 subagent 在同一个上下文上同时流式输出时，调用交错，单一游标会把子 agent 的脚本发给父 agent（反之亦然）。
+- **harness 只收集一份日志。** `findSessionLog` 遍历 sessions 根目录，返回找到的第一个 `.jsonl`。subagent 作为第二个 `Session` 运行，在同一个 cwd bucket 下有自己的日志，因此子 agent 的 transcript 被静默丢弃。
+
+这就是 [subagent seam Agent Note（agent 决策记录）](../feature/2026-06-21-subagent-capability-seam.md)中通过 `TODO(subagent-snapshots)` 推迟的工作：进程内后端（PR2）落地时已有单元 + e2e 覆盖，但在这套基础设施落地前，完整 transcript 快照层无法表达嵌套 agent 形状。本 Agent Note 就是该堆叠式后续工作。
+
+## 决策
+
+回放按**调用方会话**键控，harness 收集**所有**会话日志。
+
+### 1. 调用方会话 id 附着在模型请求上
+
+`GenerateOptions` 新增可选字段 `sessionId`，在请求组装时从 `agent.session.id` 赋值。适配器忽略它；`llm/stream` 监听器用它按发起会话路由。其类型为 `Branded<'SessionId'>`（来自 `dsh-brand`）而非 `dsh-session` 的 `SessionId`，因为后者所在包（package）导入了 `dsh-llm` 的 `Message`，反向导入会形成循环。两个类型等价，因此会话 id 赋值无需类型转换。将 brand 移到一个专用 ids 包属于独立工作，因为它会影响所有 id 导入。
+
+### 2. 回放按首次调用顺序将活跃会话绑定到录制脚本
+
+嵌套场景录制多份日志：父会话（`session.jsonl`）加每个 subagent 子会话各一份（`session.1.jsonl`……）。`dsh-llm-replay` 全部加载，为每个录制会话派生一份脚本，并按 header 中的 `createdAt` 排序（父会话先于子会话创建）。
+
+活跃会话 id 每次运行都是全新随机值，永远不等于录制时的 id，因此活跃会话无法通过 id 相等绑定到脚本。取而代之的是**首次调用顺序**绑定：第一个发起任何模型调用的活跃会话认领第一份有序脚本（即父会话：`createdAt` 最早，且必然最先流式输出，因为它必须先运行一个轮次才能委派），下一个新活跃会话认领下一份脚本，依此类推。此后每个会话独立推进自己的游标。
+
+这种方式按谁在调用键控，而非按全局调用顺序。因此即使 subagent 将来并发或在后台运行（全局游标会导致交错），它仍然正确。不携带 `sessionId` 的调用（直接在单元测试中调用 `stream()`）被视为一个匿名会话、绑定到主脚本，因此单会话路径与旧行为逐字节一致。活跃会话数多于录制脚本数时会快速失败报错（出现了未录制的 subagent），绝不会静默错误路由。
+
+子 fixture（测试前置数据）按 `createdAt` 排序，在兄弟会话严格顺序执行时与调用顺序一致。id 平局打破仅使退化碰撞具有确定性。并发或后台子会话必须引入显式的首次调用序号，而非依赖时间戳。
+
+## 曾考虑的替代方案
+
+曾考虑但否决的方案是：**将父子日志按调用顺序合并**为一份全局脚本（仅在进程内 subagent 执行严格嵌套——父 agent 阻塞等待子 agent——时才正确）。对当前的同步裁剪而言更简单，但将「父阻塞于子」这一不变式固化了进去；未来若引入后台/并发 subagent 就会失效。逐会话键控则不会。
+
+### 3. harness 收集所有日志，主会话优先
+
+`harvestSessionLogs` 收集 sessions 根目录下每个 cwd bucket 中的所有 `.jsonl`（JSONL 后端将父会话与同 cwd 的子会话放在同一个 bucket），解析各自的 header，并按主会话优先排序：顶层会话（无 `parentSession`）在前，各子会话按 `createdAt` 升序排列。`RunResult.sessionLogs` 是复数结果；spec 在录制时将每份日志写回对应 fixture（`session.jsonl` + `session.<n>.jsonl`），在回放时将每份收集到的日志与其 fixture 做 diff。归一化器已支持复数会话 id 并会折叠任何游离 UUID，因此无需修改归一化器。
+
+### 4. 场景
+
+新增两个嵌套场景，均对真实 API 录制：
+
+- **`subagent-spawn`**：父 agent 通过 `subagent` 工具将一个子任务委派给一个新 spawn 的子 agent（2 个会话）。
+- **`subagent-multi`**：父 agent 委派两个子任务，各自交给自己的 spawn 子 agent（3 个会话），以三份并行脚本和同一父 agent 下两个子会话的 `createdAt` 排序来压测逐会话键控。
+
+两者均在默认门禁中以 keyless 方式回放。
+
+## 后果
+
+- `TODO(subagent-snapshots)` 延期项已解决：嵌套 agent 的 transcript 现在是快照层的一等形态。
+- `GenerateOptions.sessionId` 是一个小而诚实的 core-seam 新增，在回放之外同样有用（遥测、请求路由）。
+- `subagent` 工具绑定到单一提供方，因此 `subagent-multi` 中的两个子 agent 都是 spawn（全新创建）。键控按会话路由而非按后端路由，因此对 fork 同样正确。但脚本*派生*逻辑此前不正确：fork 子会话的日志以种子化的父前缀（父会话的 `assistant/chunk` 事件）开头，如果从完整日志派生脚本，就会把父 agent 的响应当作子 agent 的来回放。这一正确性缺口通过持久化种子边界来弥合——见[持久化种子边界，使 fork 子项重放能够正确路由](2026-06-22-fork-child-replay-seed-boundary.md)——录制的 fork 与混合 spawn+fork 场景现在通过一份 transcript 同时验证两种传输方式（见[记录 fork 与混合 spawn+fork 快照场景](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-04-hook-snapshot-matrix.i18n.yaml b/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.i18n.yaml
new file mode 100644
index 0000000000..743d7ecbf0
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-hook-snapshot-matrix.md: ceb91a70e1f9582cf2a7cb4cec0ba8aaf5699b8e
+2026-07-04-hook-snapshot-matrix.zh.md: 250995dd1aae566aa5b9d40a14ed281b14fbfe0b
diff --git a/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.md b/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.md
index 7c2c33460c..ceb91a70e1 100644
--- a/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.md
+++ b/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-hook-snapshot-matrix.zh.md)
+
 ## Problem
 
 The hook bridges — [`dsh-hooks-claude`](../../../../packages/hooks/hooks-claude) (7 Claude Code hook points) and [`dsh-hooks-codex`](../../../../packages/hooks/hooks-codex) (5 Codex points) — map external hook commands onto the harness interception seams. They carry deep unit and coverage-spec coverage (every decision arm, every payload dialect, driven against a mocked seam) plus one key-gated e2e (`hooks.e2e.ts`, a live `PreToolUse` block). But the full-transcript snapshot tier — the one net that boots the real `acp-agent` subprocess, replays a recorded session keyless, and diffs the normalized ACP stdout + re-persisted log against committed expected outputs — covered exactly ONE hook: a Claude `UserPromptSubmit` block (`hook-cc-promptsubmit-block`).
diff --git a/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.zh.md b/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.zh.md
new file mode 100644
index 0000000000..250995dd1a
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.zh.md
@@ -0,0 +1,52 @@
+# Agent Note: 钩子快照矩阵——覆盖两种 bridge 的端到端预期输出测试
+
+Status: implemented
+
+[English](2026-07-04-hook-snapshot-matrix.md) | 中文
+
+## 问题
+
+钩子 bridge——[`dsh-hooks-claude`](../../../../packages/hooks/hooks-claude)（7 个 Claude Code 钩子点）和 [`dsh-hooks-codex`](../../../../packages/hooks/hooks-codex)（5 个 Codex 点）——把外部钩子命令映射到 harness 拦截 seam。它们有深入的单元与覆盖率规格覆盖（每个决策分支、每种 payload dialect，针对 mock seam 驱动），外加一个受密钥门控的 e2e（`hooks.e2e.ts`，实时 `PreToolUse` 阻止）。但完整 transcript（文本记录）快照层——会启动真实 `acp-agent` 子进程、无需密钥重放已记录会话，并将规范化 ACP（Agent Client Protocol）stdout + 重新持久化日志与已提交预期输出进行 diff 的那张网——只覆盖了一个钩子：Claude `UserPromptSubmit` 阻止（`hook-cc-promptsubmit-block`）。
+
+这正是 mock 单元测试在结构上无法替代的层级：它验证的是真实 bridge 将真实钩子进程的结果翻译到真实 seam 决策，再到真实 agent loop（智能体循环）的反应，渲染结果与编辑器看到的完全一致。一个 bridge 翻译或 loop 结构的回归，即使让所有单元测试保持绿色，也会在除那一个钩子点之外的所有点上逃逸；而对于 Codex bridge，ACP 示例甚至没有加载它，因此没有任何 Codex 钩子能端到端触发。
+
+## 决策
+
+实现由两个耦合部分组成：
+
+### 1. ACP 示例同时加载两种钩子 bridge
+
+`examples/acp-agent/cordis.yml` 和 `cordis.snapshot.yml` 现在同时加载 `dsh-hooks-codex` 与 `dsh-hooks-claude`，各自指向自己的配置文件（Claude 用 `./hooks.json`，Codex 用 `./codex-hooks.json`——两种方言无法共用一个文件）。这是一个真正的产品接口变更，而非仅用于测试的接线：交付的 ACP 服务器（以及 `demo:acp` 入口）现在同时携带两种 bridge。
+
+这是安全的，因为配置文件不存在时 bridge 是**静默无操作**的：`apply()` 捕获读取失败、通过 `ctx.logger` 记录日志、不注册任何东西——零监听器、零会话事件。`acp-agent` 应用不附带 stdout logger，因此警告不会到达 ACP JSON-RPC 通道。只需要 Claude 钩子的场景（或真实项目）只提供 `hooks.json`；Codex bridge 找不到 `codex-hooks.json` 便自动消失。这已通过实验验证：在两种 bridge 同时加载的情况下，所有既有快照（均不附带 `codex-hooks.json`）逐字节一致。
+
+同时加载是让快照层能够在产品交付的同一个真实应用上验证每种方言的最低要求。录制（启动 `cordis.yml`）天然加载两者，回放以同样方式继承：`cordis.snapshot.yml` 是 `cordis.yml` 的 include-overlay，只替换 llm 入口（见[单一来源 acp-agent 回放配置](2026-07-04-single-source-acp-replay-config.md)），因此添加到运行时树的 bridge 无需第二次编辑即出现在回放树中。
+
+### 2. 每个钩子点 × 其主要结果各一个快照场景，覆盖两种方言
+
+`examples/acp-agent/tests/snapshots/` 下共 13 个场景，命名为 `hook-<dialect>-<point>-<outcome>`：
+
+- **手工编写、无模型轮次**（无密钥、无 sidecar——派生的回放脚本为空；比对的是携带 `hook/*` 事件的 `rejected` 轮次）：`hook-cc-promptsubmit-block`、`hook-codex-promptsubmit-block`。
+- **对真实 API 录制、录制期间钩子活跃**（模型对决策的反应是捕获的 transcript 的一部分，此后无密钥回放）：`hook-{cc,codex}-promptsubmit-context`（allow + additionalContext 折叠）、`hook-cc-pretool-deny` / `hook-codex-pretool-block`（deny → `isError` 工具结果）、`hook-cc-pretool-ask`（ask → 降级为 deny 并附带 approval-required 原因）、`hook-{cc,codex}-posttool-block`（阻止并附带反馈）、`hook-{cc,codex}-posttool-context`（accept + additionalContext）、`hook-{cc,codex}-stop-continue`（阻塞性 Stop 钩子通过 steering（中途引导）强制多走一步）。
+
+每个钩子命令只输出固定字面量字符串（无时间戳/pid/`$RANDOM`/cwd 回显）；快照规范化器擦除 `hook/result` 携带的唯一不稳定字段（`durationMs`）。`Stop` 场景通过标记文件（`.stop_fired`）自限，使 force-continue 不会循环——`stop_hook_active` 循环守卫仍是 bridge 的一个 `TODO`，因此无条件的 Stop 钩子会在每一步都 force-continue。
+
+`PostToolUse` 阻止场景会在其证明的机制处自行限制。Claude 钩子在首次拒绝后持久化一个 workspace 标记，因此允许一次恢复调用；Codex 提示词发起一次调用并报告注入结果。每份预期输出固定一次遭阻止调用，不会重复阻止/重试循环。
+
+### 三个钩子点被有意排除在快照之外
+
+在构建矩阵过程中发现，记录于此是因为这些遗漏是决策而非疏忽：
+
+- **`SessionStart` 和 `SubagentStart`** 通过脱离且尽力而为的 `void runPoint(...).then(agent.inject())` 注入上下文，没有轮次绑定。由此产生的 `context/message` 会与它应先于的工作（首次模型请求 / 子项的第一个轮次）竞速，并落在不确定的日志位置。记录的预期输出甚至无法在自己的重放中复现——对两者执行 10 次重放稳定性检查，结果均为 10/10 次失败。它们继续留在 bridge 的单元覆盖率中，那里会直接驱动 seam 而不存在时序竞速。（如果注入未来改为绑定轮次且具备确定性——`TODO(session-start-gating)` 所指方向——它们就能接受快照测试。）
+- **`SubagentStop`** 只观察：其 `subagent/end` handler 不传递轮次（因此没有 `hook/*` 日志事件），也不执行注入。它不会向 transcript 写入任何内容，因此预期输出会与无钩子运行逐字节相同，永远无法证明失败——一道咬不住问题的守卫。它继续由单元覆盖率负责（`bridge.spec.ts` 已断言仅观察调用）。
+
+因此，该矩阵覆盖了所有具有确定性、可观测 transcript 足迹的钩子点，涵盖两种方言。
+
+## 后果
+
+- 现在，两种 dialect 中每个具有可观察 transcript 的 bridge seam 映射，都在真实应用的完整 transcript 层受到守护——包括此前完全没有端到端覆盖的 Codex bridge。记录的预期输出捕获模型对遭拒绝/遭阻止/强制继续轮次的真实反应，而手工编写的 transcript 只能猜测这种反应。
+- `UserPromptSubmit` 阻止场景无需密钥即可编写（没有模型轮次）；其余场景从已记录 fixture（测试前置数据）无需密钥重放。`pnpm run test:snapshot:record` 从实时 API 重新生成记录式 fixture，并像所有记录场景一样在缺少密钥时自行跳过。
+- 证明会变红的准则仍成立：篡改钩子配置输出（例如改变拒绝理由）会让相应场景在重放时变红——钩子进程在重放期间真实运行（只有模型被重放），因此预期输出守护的是实际钩子→seam→循环路径，而非其 mock。
+- `acp-agent` 演示现在加载了一个通常会无操作的 Codex bridge（典型项目中没有 `codex-hooks.json`），这正是预期的柔性失败行为，而非代价。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.i18n.yaml b/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.i18n.yaml
new file mode 100644
index 0000000000..719884e56c
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-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
+2026-07-04-single-source-acp-replay-config.md: f270d70feca184217503c472c1cb7c536187a249
+2026-07-04-single-source-acp-replay-config.zh.md: 86eb2d3e15c4939d1de3a78150cd0536d46e10f6
diff --git a/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.md b/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.md
index 3de645deeb..f270d70fec 100644
--- a/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.md
+++ b/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-04-single-source-acp-replay-config.zh.md)
+
 ## Problem
 
 `examples/acp-agent` shipped two hand-maintained configs: `cordis.yml` (the live tree) and a `cordis.snapshot.yml` that mirrored it entry-for-entry with only the llm backend swapped — stripped of comments, the entire difference was the eight-line `llm-deepseek` stanza versus the two-line `llm-replay` stanza. Every app-shape change had to be made twice, and nothing gated the symmetry: if the copies drifted, the snapshot tier would silently exercise a different app than the one that ships — the ["green units, broken product" class of gap](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) the snapshot tier exists to close, reintroduced one level up, with reviewer vigilance as the only defense.
diff --git a/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.zh.md b/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.zh.md
new file mode 100644
index 0000000000..86eb2d3e15
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.zh.md
@@ -0,0 +1,27 @@
+# Agent Note: 将 acp-agent 回放配置改为单一来源
+
+Status: implemented
+
+[English](2026-07-04-single-source-acp-replay-config.md) | 中文
+
+## 问题
+
+`examples/acp-agent` 发布了两份手工维护的配置：`cordis.yml`（实时树）和逐条镜像它、只替换 llm 后端的 `cordis.snapshot.yml`——去除注释后，两者的全部差异就是八行 `llm-deepseek` stanza 与两行 `llm-replay` stanza。每次应用形状变化都必须修改两遍，也没有任何机制约束对称性：如果副本发生漂移，快照层会悄然覆盖与已发布应用不同的应用——快照层本就是为了弥合[“单元测试绿色，产品损坏”这类缺口](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)，如今同类缺口在上一层重新出现，只能依靠评审者警惕。
+
+## 决策
+
+`cordis.snapshot.yml` include 正式配置，通过 id 和 name 禁用指定的 DeepSeek 适配器，并插入回放适配器。其余所有条目因此来自正式运行树。回放时选择 overlay；录制仍然启动 `cordis.yml`，加载守卫允许被有意禁用的条目。
+
+overlay 有意依赖一项 vendored 插件事实：include 加载文件时会应用 `patches`，而其 `refresh()`/`internal/update` 路径会重新读取但不重新打补丁——这恰好足以满足一次性重放启动（重放应用不加载 `hmr`，运行中也没有内容重写配置）。快照套件就是证明：所有场景都能在 overlay 上原样通过，包括逐字节相同的预期输出。
+
+## 曾考虑的替代方案
+
+### 为何不采用这些替代方案？
+
+保留完整的双副本并加一道对称性校验门禁是记录在案的退路——它能消除静默漂移这一类问题，但仍保留一份 125 行的近乎复制品，其全部内容只是一个条目的差异，且随应用每增加一个插件而增长。在 bin 侧做替换（解析配置、替换条目、删除文件）则会把 YAML 手术放进发布产物，并把回放差异藏到视线之外；overlay 让差异保持声明式、可读，且紧邻基础配置——这正是双副本支持者真正看重的教学价值。
+
+## 后果
+
+- 向 `cordis.yml` 添加插件即自动进入回放树，无需第二次编辑；漂移这一类问题从结构上消失，而非靠门禁拦截。
+- overlay 依赖条目携带稳定的 `id:`。禁用补丁上的 `name` 断言防止误定位（id 被复用时补丁跳过而非禁用错误的插件）。如果 id 被重命名，补丁退化为跳过，其警告需要一个回放应用有意不具备的 logger——可观测结果是一条无效的无密钥 `llm-deepseek` 条目与 `llm-replay` 并存，回放输出仍然正确（`llm-replay` 拥有流的短路权）；这属于配置腐烂，留给评审发现，不会产生错误的快照。顶层插入一个 id 与既有条目冲突的新条目时，loader 的 id map 以后者为准；当前配置无冲突，新增补丁行才是引入冲突的场所。
+- 如果未来回放树需要第二处差异（另一个后端被替换），只需多加一行补丁，而非再 fork 一份文件。
diff --git a/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.i18n.yaml b/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.i18n.yaml
new file mode 100644
index 0000000000..2b7c1cc937
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-06-pin-request-header-content-in-one-scenario.md: bca6d9eb943e758d68efaf3a76ec367179cd15fd
+2026-07-06-pin-request-header-content-in-one-scenario.zh.md: e01c84c63583e2fe14b0b4fe0381a18b209d2346
diff --git a/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md b/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md
index 1dcfc2e085..bca6d9eb94 100644
--- a/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md
+++ b/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-06-pin-request-header-content-in-one-scenario.zh.md)
+
 ## Problem
 
 An ACP snapshot suite needs to prove the exact composed system prompt and tool-schema list sent in each `request/header`, but duplicating that content inside every `session.jsonl` makes a prompt or schema edit rewrite dozens of giant one-line JSON records. Keeping one raw header avoids the duplication but still makes prompt review poor: prose is JSON-escaped onto one line and mixed with thousands of characters of tool schemas.
diff --git a/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.zh.md b/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.zh.md
new file mode 100644
index 0000000000..e01c84c635
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 在单个快照场景中固定请求头内容
+
+Status: implemented
+
+[English](2026-07-06-pin-request-header-content-in-one-scenario.md) | 中文
+
+## 问题
+
+一个 ACP（Agent Client Protocol）快照测试套件需要证明每个 `request/header` 中实际发送的组合系统提示词与工具 schema 列表，但如果在每个 `session.jsonl` 中重复这些内容，一次提示词或 schema 编辑就会改写数十条巨大的单行 JSON 记录。保留一份原始 header 可以避免重复，但提示词的评审体验仍然很差：行文被 JSON 转义到一行中，与数千字符的工具 schema 混在一起。
+
+## 决策
+
+每种请求头组合类别恰好有一个场景标记为 `pinsHeader`。其目录按评审格式拆分固定内容：`system-prompt.expected.md` 以普通 Markdown 包含规范化的完整提示词序列；`tool-schemas.expected.json` 以结构化 JSON 包含对应的完整 schema 序列；`session.jsonl` 保留 config、reason 和所有模型可见前缀，同时将 `header.system` 与 `header.tools` 存为 `"{{system}}"` / `"{{tools}}"`。其他每份 JSONL 都使用相同的提示词与工具 token，并同样将会话前缀内容 token 化。固定机制位于 [`dsh-acp-snapshot`](../../../../packages/support/acp-snapshot/README.md)，其套件 factory 强制每种类别恰好有一个固定场景。
+
+纯 `scrubSystemPrompts` 和 `scrubToolSchemas` 规范化器会分别将每个已存储完整请求头 token 化。`scrubRequestHeaders` 还会为非固定场景把会话前缀内容 token 化，同时保留请求头数量、字段存在性、config、reason 和前缀消息数量。记录与刷新写回会在写入 JSONL 前应用适当清理，并根据规范化的实时完整请求头序列重新生成两个 sidecar，因此两条路径都无法把大段提示词/schema 重新引入 JSONL，也不会留下陈旧的评审产物。
+
+守卫使这种拆分能够自我强制。在磁盘上，每个 `session*.jsonl` 都是提示词和 schema 清理器的固定点；只有非固定 fixture（测试前置数据）必须是完整请求头清理的固定点；两个 sidecar 恰好位于固定 fixture 旁，并采用规范、以换行符结尾的格式；每种类别都有一个固定场景。在实时运行中，由父项、spawn 子项、fork 子项、初始请求、恢复或实例内变化产生的每个 `request/header`，都必须在易变值规范化后与重建的类别序列匹配。请求头若没有字符串提示词、没有数组值工具列表，或超过固定场景声明的变更请求头数量，就会响亮失败。
+
+一个固定场景覆盖整个套件，因为每个会话（parent、spawn 子会话、fork 子会话）组合出的工具列表完全相同、提示词除 cwd 外完全相同，而一致性守卫会在这一前提不再成立时立即使套件失败。如果 header 组合将来在设计上变为会话相关的（例如受限的 subagent 工具集），那么分歧的形态将获得自己的固定场景。
+
+## 曾考虑的替代方案
+
+- **每次变更重新录制或手动编辑所有 fixture**：保留了精确的 header，但行为差异被重复的提示词和 schema 内容淹没。
+- **仅在比较时 scrub，fixture 保持原始内容**：比较能通过，但已提交的 fixture 保留着陈旧的重复内容，下次录制时会整体重写。存储 token 诚实地表明每个 JSONL 没有固定什么。
+- **全部 scrub，不做任何固定**：丢失了组合 header 实际发送内容（提示词组装、已注册工具顺序、完整 schema）的唯一端到端记录。生成的工具目录只孤立地记录每个工具；只有真实 fixture 才能固定组合后的完整集合。
+- **将完整固定内容全部保留在 JSONL 中**：消除了套件范围的重复，但提示词和 schema 变更仍然是一行转义文本。Markdown 和结构化 JSON 为每种内容提供其自然的评审格式，同时不削弱重建 header 的断言。
+- **收窄会话日志本身（记录内容 digest，把请求头存到其他位置）**——违反可重建性契约：产品日志必须逐 bit 复现每个请求（[可重建请求 Agent Note（agent 决策记录）](../architecture/2026-07-05-reconstructable-requests.md)）。请求头体积是测试产物问题，应在测试规范化中解决；实时日志保持不变。
+
+## 验证
+
+该套件针对拆分后的固定内容回放每个场景。单元覆盖率会覆盖独立与完整清理器、两种完整请求头 sidecar 格式、记录/刷新重新生成、规范化提示词/schema 提取、固定点强制、必需文件对称性、重建请求头一致性，以及变更请求头数量拒绝。
+
+## 后果
+
+系统提示词变更在每个受影响的组合类别中产生一个面向行的 Markdown diff；工具描述变更在每个类别中产生一个结构化 JSON diff；普通行为 fixture 不受影响。会话 fixture 对省略的内容显示 token，运行时一致性守卫使每个拆分固定场景对其类别内的所有会话具有权威性。每个固定场景携带两个生成的、换行规范化的 sidecar 文件。
diff --git a/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.i18n.yaml b/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.i18n.yaml
new file mode 100644
index 0000000000..5c5bad0b1a
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-08-shared-acp-snapshot-package.md: 3e5a2b12114d535490a17361128862f6d1c09a73
+2026-07-08-shared-acp-snapshot-package.zh.md: 072ef692702cb769c428f8b6aa3863a3b77d3d59
diff --git a/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.md b/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.md
index 8d6032d1cc..3e5a2b1211 100644
--- a/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.md
+++ b/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+English | [中文](2026-07-08-shared-acp-snapshot-package.zh.md)
+
 ## Problem
 
 The ACP snapshot tier ([snapshot Agent Note](2026-06-19-acp-snapshot-tests.md)) was built from three modules living inside one example's test directory: `snapshot-harness.ts` (boot the real bin subprocess, drive it over ACP JSON-RPC, harvest the persisted logs), `snapshot-normalize.ts` (the pure expected-output normalizers), and the ~150-line scenario body plus fixture guards in `acp.snapshot.ts` (record/replay modes, the stdout expected-output and log comparisons, the pinned-header uniformity guard, the orphan/required-file/single-pin meta-tests).
diff --git a/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.zh.md b/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.zh.md
new file mode 100644
index 0000000000..072ef69270
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.zh.md
@@ -0,0 +1,40 @@
+# Agent Note: 将 ACP 快照套件提取为支持包
+
+Status: implemented
+
+[English](2026-07-08-shared-acp-snapshot-package.md) | 中文
+
+## 问题
+
+ACP（Agent Client Protocol）快照层（[快照 Agent Note（agent 决策记录）](2026-06-19-acp-snapshot-tests.md)）由位于一个示例测试目录内的三个模块构建：`snapshot-harness.ts`（启动真实 bin 子进程，通过 ACP JSON-RPC 驱动它，采集持久化日志）、`snapshot-normalize.ts`（纯预期输出规范化器），以及 `acp.snapshot.ts` 中约 150 行的场景主体与 fixture（测试前置数据）守卫（记录/回放模式、stdout 预期输出与日志比较、固定请求头一致性守卫、孤立项/必需文件/单一固定项元测试）。
+
+第二个希望获得快照覆盖的 ACP 示例——直接消费方是沙箱/approval 组合——只能复制这些模块，恰好分叉了绝不能漂移的逻辑：记录写回、请求头清理、子会话采集顺序。spawn/client 胶水也在 `acp.e2e.ts`、`hooks.e2e.ts` 和 harness 中重复三份。文件位置决定了测试严格度：逐文件 100% 覆盖率门禁只测量 `packages/*/*/src`，因此这些机制完全未被测量——正是同一种缺口，曾推动 `dsh-llm-replay` 从 `examples/` 移入 [packages/support](../../../../packages/support/README.md)。此外，harness 的 ACP client 硬编码 `requestPermission → cancelled`，因此 approval 往返——沙箱组合的主打行为——完全无法在快照层表达。
+
+## 决策
+
+这些机制位于 [`packages/support/acp-snapshot`](../../../../packages/support/acp-snapshot/README.md)（`@deepseek-ai/dsh-acp-snapshot`）；示例的 `*.snapshot.ts` 只包含场景表、agent 路径和一次工厂调用，依赖自己的 `snapshots/` fixture 与 `cordis.snapshot.yml` overlay（[单源回放配置](2026-07-04-single-source-acp-replay-config.md)）。读取 `DSH_SNAPSHOT` 留在边缘层——库接收的是已解析的 `mode`。
+
+**`src/launcher.ts`**——`launchAcpTestAgent` 拥有通用的未构建进程边界：绝对 tsx loader 解析、`TSX_TSCONFIG_PATH`、隔离的 harness home、stdio 接线、原始字节 stdout tee、stderr 与更新捕获、失败关闭的权限后备、更新 waiter，以及优雅或信号式关闭。快照场景和普通 e2e 套件提供相同的 `AgentUnderTest`（`binScript`、`configPath`、`tsconfigPath`）；扮演用户的测试只提供其权限 handler。ACP 与钩子 e2e 套件以及沙箱/approval e2e 套件都使用该 launcher，而不再重新构建 SDK client 边界。
+
+**`src/harness.ts`**——`runScenario` 和输入脚本/结果类型在 launcher 之上叠加确定性步骤、临时 workspace、快照环境和持久化日志采集。其 `session/request_permission` handler 消费可选的 `InputScript.permissionAnswers` FIFO 队列，每个条目按选项**类型**进行选择（id 是 agent 生成的随机值，已提交脚本无法预知；类型是 ACP 稳定词汇，会在回答时映射到已提供的 `optionId`）；队列不存在或耗尽时回答 `cancelled`，若请求从未提供某种类型则拒绝该次运行——agent 自身收到的回答是 `cancelled`，因此场景 bug 会使 harness 失败，而不会被吸收为 agent 侧拒绝。由此，approval 套件可以根据 `input.json` 确定性地驱动允许/拒绝往返。
+
+**`src/normalize.ts`** 是纯规范化器，按策略不含钩子：当未来某个事件携带新的易变字段（例如审批耗时），共享规范化器在同一个变更中学会它，保持「规范化」的含义只有一个归属，而非各套件各自扩展清洗逻辑。
+
+**`src/suite.ts`**——包含 `Scenario` 类型和 `defineAcpSnapshotSuite(options)`，注册各场景比较、记录/刷新 fixture 写回、带实时一致性守卫的请求头固定项，以及 fixture 守卫块（没有孤立场景目录、必需文件存在、每种类别恰好一个固定项、每份 JSONL 都是 `scrubSystemPrompts` 固定点、非固定 fixture 同时也是 `scrubRequestHeaders` 固定点）。刷新会先展开打包的计时信封，再对齐现有易变事件时间，因此在打包与未打包布局之间切换不会移动后续记录；全新的分片片段数组仍为权威，因为其边界属于回放行为。场景目录中的 `session.jsonl` 加连续的 `session.<n>.jsonl` 同级文件构成有序主项/子项清单，因此场景表可以声明策略而不重复子项数量。固定请求头契约（[固定请求头 Agent Note](2026-07-06-pin-request-header-content-in-one-scenario.md)）按套件生效：每种请求头类别恰好标记一个 `pinsHeader` 场景，其 `system-prompt.expected.md` 和 JSONL 工具列表把组合请求头拆成可评审产物；一致性守卫会将两者与该类别的每个实时请求头比较。固定场景可以声明任何合法的变更请求头数量，其 Markdown 产物记录每个完整的已变提示词。纯辅助函数（`sessionFixtureNames`、`fixtureContext`、`normalizedHeaders`、`normalizedSystemPrompts`、`formatSystemPromptSnapshot`、`headerChangeCount`）从模块导出，以便直接进行单元覆盖。
+
+## 曾考虑的替代方案
+
+- **把模块复制到每个示例中**——这正是本 Agent Note 要防止的分叉：记录/守卫逻辑恰好是必须在各套件间保持逐字节相同的代码，而示例位于覆盖率门禁之外，所以每份副本也都无法测量。
+- **在 `examples/` 下建共享模块目录**：代码仍在覆盖率门禁之外，且需要跨示例边界的相对导入，违反包名导入约定；`examples/` 的叶子节点按设计应保持轻薄。
+- **`dsh-acp-demo` 的 `/testing` 子路径导出**：将测试基础设施耦合到产品包的对外服务接口与依赖集中；`packages/support/` 的存在正是为了真实但兼容性承诺较低的开发/测试包，`dsh-llm-replay` 是先例，本包与之配套。
+- **导出原始测试体函数而非套件工厂**：每个示例将重新拥有 `describe`/`it` 骨架（每套件约 80 行注册样板），却无灵活性收益；工厂使消费方只需一张场景表加一次调用，而导出的纯辅助函数在工厂设计内保留了可单元测试性。
+- **使用可注入 ACP `Client` factory 代替声明式 `permissionAnswers`**——灵活性最大，但会把 SDK client 构造泄漏给每个消费方，并恰好在正在统一的层重新引入逐示例漂移；声明式队列让 `input.json` 保持为唯一脚本表面，并与预期输出规范化兼容。
+- **泛化到 ACP 之外（传输无关的快照 harness）**：不存在第二种传输方式；harness 端到端都是 ACP 形态（SDK 客户端、JSON-RPC 帧、`session/update` 等待器），推测性的抽象将是一个超前于任何消费方的 seam 拆分。
+
+## 测试
+
+提取一致性得到机械证明：迁移后，`pnpm run test:snapshot` 的结果与基准提交匹配，`examples/acp-agent/tests/snapshots/` 下没有任何字节变化。包的 `src/` 在门禁单元运行中保持逐文件 100% 语句/分支/函数/行覆盖，并通过脚本化 fake ACP bin（`tests/fixtures/fake-acp-agent.ts`，每个场景由 fixture 旁的 `behavior.json` 编排行为）经过真实 launcher 驱动：`harness.spec.ts` 直接覆盖 launcher 默认值、捕获、更新等待、关闭以及环境/配置变体，随后覆盖每种场景步骤操作、两个 expect-error 分支、权限队列（选择、后备、不可能点击）、workspace seed，以及采集顺序/噪音/后备分支；`suite.spec.ts` 在收集时真实运行 factory——一个针对已提交合成 fixture 的回放套件和一个针对临时副本的记录套件（写回从不触及已提交树；`ACP_SNAPSHOT_SPEC_BOOTSTRAP=1` 会重新引导它）——并包含纯辅助函数的直接用例。fake bin 会把 `session/new` cwd 而非 `process.cwd()` 代入脚本化日志，与真实 bin 请求头携带的内容一致（darwin 会将 `/var/folders/…` realpath 为 `/private/var/folders/…`）。
+
+## 后果
+
+新示例通过场景表加 fixture 即可获得完整快照层，普通 ACP e2e 则通过一次 launcher 调用获得同一条经过测试的进程/client 边界。代价是：`suite.ts` 导入 vitest，因此包入口只能在 vitest 运行中导入——其他包都没有这种形状，其 README 已说明；每个套件还要固定自己的约 8 KB 请求头 fixture（真正不同的组合理应拥有自己的固定项；相同组合则会被该套件的一致性守卫捕获）。
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
new file mode 100644
index 0000000000..e36caa3f12
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-16-typed-event-schemas.md: 97a7d0c3787eb5556696e25a6c8b1bb75642aba9
+2026-06-16-typed-event-schemas.zh.md: c19f67c6ff058d42293ff2b6346630fe91c54dec
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 500be241c6..97a7d0c378 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
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-06-16-typed-event-schemas.zh.md)
+
 ## Problem
 
 The harness models its core vocabulary — content blocks, message sources, finish reasons, turn triggers, turn-end reasons, and session events — as **merge-extensible maps**: a TypeScript `interface` (e.g. `SessionEventMap`, `ContentBlockMap`) that plugins augment via declaration merging, with the public union derived as `Map[keyof Map]`. This is the repo's universal extension pattern, documented in [docs/architecture.md](../../../../docs/architecture.md) ("The same merge-extensible-map pattern is used for `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`") and relied on by the `defineTool` `InferArgs` DSL and the `assertNever` exhaustiveness convention.
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
new file mode 100644
index 0000000000..c19f67c6ff
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
@@ -0,0 +1,77 @@
+# Agent Note: 事件词汇的运行时 schema（Zod 与 merge-extensible-map 模式之辩）
+
+Status: proposed
+
+[English](2026-06-16-typed-event-schemas.md) | 中文
+
+## 问题
+
+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)暴露了两个后果：
+
+1. **持久化将 `event.data` 视为不透明 JSON。** JSONL/SQLite 后端对每个事件逐字 `JSON.stringify`/`JSON.parse`；唯一的运行时守卫是 `isJsonValue`（往返可序列化性检查：拒绝 BigInt、函数、循环引用、非有限数等），而非结构校验。一个损坏但仍为合法 JSON 的事件数据（字段类型错误、字段缺失）会静默往返，只有在后续消费方的 `switch` 中才可能被捕获。
+2. **插件新增变体没有运行时契约。** 一个通过声明合并添加新 `SessionEventMap` 键的插件，在自身代码中获得了编译期类型，但没有任何机制校验它产出的值是否符合它所声明的形状——无论是在生产者处、持久化边界处还是重新加载时。
+
+由此引出问题：事件词汇是否应迁移到 **Zod** 或其他运行时 schema 库，使持久化和插件边界拥有运行时 schema 而非被擦除的类型。
+
+本 Agent Note（agent 决策记录）界定该问题的范围，不提出具体实现。
+
+## 为什么这不是一个持久化层的改动
+
+很容易把「用 Zod 做序列化」理解为对 `dsh-session-persistence-jsonl/src/format.ts` 的局部修改。但它不是，原因在于一个结构性事实：**插件无法对 Zod schema 进行声明合并。** 声明合并是 TypeScript 编译期机制；Zod schema 是运行时值。要用 Zod 校验事件，就需要一个**运行时注册表**，每个产出事件的包（package）向其贡献自己的 schema（如 `ctx.sessionEvents.register('compaction/marker', z.object({…}))`），每个消费方从中读取。这个注册表——而非持久化后端——将成为词汇的真源，取代 merge-extensible 接口。
+
+因此，真正的提案是：**用运行时 schema 注册表替换编译期的 merge-extensible-map 模式，范围覆盖整个仓库。** 这是一次核心词汇的重新设计。
+
+## 影响范围（已度量）
+
+将事件/词汇表面迁移到运行时 schema，至少涉及：
+
+- **六个 merge-extensible map**（约 370 行核心类型）：`ContentBlockMap`、`MessageSourceMap`、`FinishReasonMap`（位于 `dsh-llm`）；`TurnTriggerMap`、`TurnEndReasonMap`、`SessionEventMap`（位于 `dsh-session`）。
+- **约 10 处 `declare module` 扩展点**，分布在 `dsh-agent`、`dsh-agent-loop`、`dsh-bash`、`dsh-llm`、`dsh-session`、`dsh-session-persistence`、`dsh-system-prompt`、`dsh-tools` 各包中——每处都将从声明合并改为运行时 `register()` 调用。
+- **事件生产者**——agent loop（智能体循环）中 16 处 `session.append(...)` 调用——形状不变，但现在在边界处被校验。
+- **约 7 个 switch 消费方**，对这些联合类型进行分支：`deriveMessages` 与包自有的不变式 companion（`dsh-session`）、`BlockAssembler`（`dsh-llm`）、两个 LLM（大语言模型）适配器（`dsh-llm-deepseek`、`dsh-llm-pi-ai`）以及工具 schema 层（`dsh-tools`）。`assertNever` 对封闭联合类型的穷举 vs 对可扩展联合类型的 fall-through 约定（一条已记录的 lint 规则）需要重新考量——运行时变体在静态层面不可穷举。
+- **`defineTool` 的 `InferArgs` DSL**（`dsh-tools`），它从编译期 schema 规范派生出零类型转换的 `execute` 参数类型——这是当前方案的标杆用例。
+- **文档**：architecture.md（该模式被描述为基础性的）、[开发模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md)，以及所有引用该模式的 Agent Note。
+
+这是一次仓库级别的词汇重新设计，而非持久化的实现细节。
+
+## 曾考虑的替代方案
+
+### A. 维持现状——merge-extensible 类型 + 持久化边界处 `isJsonValue`
+保留编译期模式。持久化继续使用不透明 JSON + 可序列化性守卫。插件通过声明合并扩展；事件*形状*的正确性由生产者负责，并由 TypeScript 在编译期保证。启用包自有的不变式 companion 后，它们会检查选定的跨记录关系，但不提供通用运行时形状 schema。
+
+- **优点**：零变动；插件扩展只需一行 `interface` 增补，享有完整类型推断，无需运行时注册仪式；无新运行时依赖；`defineTool` DSL 与 `assertNever` 穷举继续工作。
+- **缺点**：持久化边界和插件 seam 处无运行时结构校验；格式错误但仍为合法 JSON 的数据被延迟捕获。
+
+### B. 仅对头部/封闭形状做校验（schemastery），事件仍为不透明
+仅对那些已有手写类型守卫的真正封闭形状加以收紧——例如 JSONL 的 `HeaderLine` 守卫（`isHeaderLine`）——使用 **schemastery**（仓库现有的 schema 库，已用于每个插件的 `static Config`）。merge-extensible 事件联合类型保持不变。
+
+- **优点**：改动小，契合现有约定（schemastery，而非新库）；用声明式 schema 替换封闭形状上的手写守卫；无核心重新设计。
+- **缺点**：不解决事件数据校验问题；仅固定的元数据记录得到改善。
+
+### C. 为整个词汇建立运行时 schema 注册表（Zod 或 schemastery）
+用运行时注册表替换 merge-extensible map，生产者向其贡献 schema，持久化/消费路径据此校验。
+
+- **优点**：持久化边界和插件 seam 处获得真正的运行时校验；单一真源；可支撑通用工具（自动生成文档、模糊测试、协议格式检查）。
+- **缺点**：上述全部影响范围；**Zod 目前不是直接依赖**（仅作为 `@earendil-works/pi-ai` 的传递依赖），仓库选定的 schema 库是 **schemastery**——广泛引入 Zod 本身就是一个依赖决策；声明合并的易用性（一行插件扩展、完整推断）被运行时注册 + 手动类型接线取代；`assertNever` 穷举保证弱化（运行时变体在静态层面不可穷举）。
+
+## 提案
+
+推迟。如果需要在持久化边界做运行时校验，**方案 B**（对封闭的头部和元数据形状使用 schemastery）是现有约定下的适度步骤。**方案 C** 是一个架构决策，需要自己的实现 Agent Note，其中包括 Zod 与 schemastery 之间的选择。
+
+## 验收标准
+
+- 方案 C 只能通过自己的实现 Agent Note 推进，绝不能作为持久化的附带改动。
+- 如果采纳方案 B，封闭的头部/元数据形状（JSONL 的 `isHeaderLine` 守卫及同类）改用 schemastery 校验，替代手写守卫，merge-extensible map 保持不动。
+
+## 风险
+
+- 推迟意味着事件 `data` 在持久化边界处仍无结构校验：格式错误但仍为合法 JSON 的数据被延迟捕获，由消费方的 `switch` 兜底——这是现状的代价，有意接受。
+- 如果方案 C 最终被采纳，易用性的损失是真实的：一行声明合并变为运行时注册加手动类型接线，`assertNever` 的静态穷举保证弱化。
+
+## 待解问题
+
+- 如果采用注册表，库选 **schemastery**（已在仓库中，已作为配置 schema 库）还是 **Zod**（生态更丰富，目前仅为传递依赖）？同时维护两个 schema 库本身就是一种成本。
+- 能否采用混合方案：保留编译期推断（使 `defineTool` 和插件开发体验不受影响），同时为每个变体添加*可选*的运行时 schema，仅在持久化/协议边界校验，而非每次进程内 append 都校验？
+- `ctx.invariants` 服务启用后是否已覆盖了足够多的运行时形状缺口，使得边界校验仅在面对真正不可信输入（重新加载外部修改过的日志）时才有必要？
diff --git a/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
new file mode 100644
index 0000000000..233cc3901c
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-24-separate-context-injection-from-turn-execution.md: 652c3d410ab625d91a828f854bce302adcb0c9e0
+2026-07-24-separate-context-injection-from-turn-execution.zh.md: 1064e7a869ab9ea46c0145eb010119894a03aacf
diff --git a/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.md b/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
new file mode 100644
index 0000000000..652c3d410a
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
@@ -0,0 +1,75 @@
+# Agent Note: Separate context injection from turn execution
+
+Status: proposed
+
+English | [中文](2026-07-24-separate-context-injection-from-turn-execution.zh.md)
+
+## Problem
+
+The agent API currently represents supplementary model-facing input in three overlapping ways: callers attach `HookContext[]` through `SendOptions.contexts`, interception and tool hooks return `additionalContexts`, and plugins call `agent.inject()`. These paths eventually write context into the same model history, but they carry different placement, metadata, admission, queue, and turn-lifecycle rules.
+
+Atomic attachment to an inbox message forces the loop to preserve context through prompt admission, steering conversion, cancellation, and terminal discard. `prompt-prefix` placement then combines context and the direct prompt into one event, requiring a model-hidden envelope so transcript consumers can recover what the user actually wrote. The result makes outbox entries, session projection, and UI replay responsible for a distinction that belongs to the producer.
+
+Idle `inject()` exposes a second mismatch. Injection does not request model execution, yet the current implementation opens and closes a zero-step `injection` turn solely to satisfy the turn-enclosure invariant and obtain a durability checkpoint. A turn therefore sometimes means “run the agent loop” and sometimes means “persist context without running it.”
+
+`HookContext` also names its producer rather than its role. The value may come from a native plugin, a hook bridge, prompt admission, or tool post-processing. Its stable meaning is simply additional model-facing context with provenance.
+
+## Proposal
+
+Make `inject()` the only caller-facing operation for adding supplementary model-facing input, and define a turn exclusively as one execution of the model loop.
+
+Remove `SendOptions.contexts`. A caller that owns context delivers it with `inject()` and independently submits the direct message with `send()` or `steer()`. Rename `HookContext` to `AdditionalContext`; retain only `content` and `source`, and remove placement and model-hidden metadata from this shared shape.
+
+Prompt and tool extension points may still return `additionalContexts`. These values are outputs of the extension point, not attachments captured from a caller's inbox item. Prompt admission runs before `run()` opens a turn. An allowed prompt enters the outbox together with its returned additional contexts; a blocked prompt writes neither and opens no turn. Tool-produced additional contexts enter the same outbox after the corresponding tool results.
+
+Every additional context becomes an independent `user/message` whose `source` records provenance. Remove `context/message`, prompt-prefix placement, the stable request delimiter, and the prompt envelope. Transcript and UI consumers distinguish direct user messages from injected context by `source`, not by recovering a hidden direct-prompt field from combined model content.
+
+## Injection lifecycle
+
+When a turn is open, `inject()` stages the context in the loop outbox. The loop drains the outbox at a safe step boundary, preserving tool protocol adjacency: a context accepted during an assistant tool-call batch appears only after that batch's complete ordered results. Taking the outbox as a whole makes steering and injected context accepted for one boundary visible to the same following request.
+
+When no turn is open, `inject()` appends its `user/message` immediately and starts a session flush. It does not increment turn numbering, emit `turn/start` or `turn/end`, change agent status, or run the model. The synchronous API still returns before the asynchronous flush settles; `whenIdle()` and agent disposal include outstanding idle-injection flushes in their quiescence boundary.
+
+A failed idle flush has no legitimate turn or step coordinates. It is reported through logging or a persistence-owned error surface, not by inventing an `agent/error` payload for a nonexistent turn. The in-memory event remains accepted and a later flush may retry persistence.
+
+The session invariant therefore permits `user/message` between turns while continuing to require turn enclosure for execution events, steering, assistant output, tools, and package-added events by default. Persistence, recovery, resume, fork, and compaction code must treat a valid out-of-turn `user/message` as committed session history rather than an interrupted or discardable turn tail.
+
+## Extension and caller semantics
+
+`PromptDecision.content` continues to replace only the direct prompt. `PromptDecision.additionalContexts` and tool-result `additionalContexts` retain FIFO order and individual provenance, but no longer select placement. A waterfall listener that delegates with `next()` must preserve downstream prompt content and additional contexts unless it intentionally returns replacements.
+
+Caller-driven injection and hook-produced additional context deliberately have different admission ownership. A hook's additional contexts materialize only after that hook allows the prompt or tool result. A caller that invokes `inject(context)` and then `send(prompt)` has already committed context independently; if prompt admission later blocks the prompt, the injected context remains in history. Callers requiring all-or-nothing domain behavior must perform their own preparation before either operation or expose a domain-specific admission seam.
+
+Cross-session references follow the ordinary composition: the host prepares the snapshot, injects it with session-reference provenance, then sends or steers the readable direct prompt. The target log contains two simple messages, so later source mutation cannot change replay and transcript consumers do not need a prompt envelope. This supersedes the attachment mechanism in the [cross-session reference decision](../../implemented/feature/2026-07-21-cross-session-references.md) while retaining its snapshot and trust-boundary rules.
+
+This proposal preserves the caller-owned framing decision from [unwrapped injected content](../../implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md), the one-item turn rule from [one send, one turn](../../implemented/simplification/2026-07-17-one-send-one-turn.md), and narrows the [turn-enclosure decision](../../implemented/architecture/2026-06-15-turn-enclosure-invariant.md) so turns enclose execution rather than every session event.
+
+## Alternatives considered
+
+**Keep `SendOptions.contexts` as an atomic attachment.** This preserves all-or-nothing delivery when prompt admission blocks, but it keeps context inside inbox lifecycle state and requires every queue transition and observation event to carry it. The generic agent API should not encode a domain transaction that most callers can express as context injection followed by message delivery.
+
+**Keep a distinct `context/message` session event.** A separate event makes the out-of-turn exception narrower, but user-role model input would again have two event types with identical projection. `user/message.source` already carries the distinction needed by policy, transcript, and replay consumers.
+
+**Keep one-shot turns for idle injection.** This retains universal turn enclosure and a convenient flush boundary, but it makes turn counts and turn observers report work that never ran the model. Durability is an independent session concern and can be awaited without fabricating execution.
+
+**Keep `prompt-prefix` as an optional placement.** Prefix baking can make the context and request appear in one provider message, but it introduces a second representation of the direct prompt and spreads placement handling across admission, steering, logging, replay, and UI code. Producers that require textual framing may include it in their own context content.
+
+**Let hooks call `inject()` directly instead of returning additional contexts.** Direct injection would erase the extension point's admission ownership: a listener could append context before a downstream listener blocks the operation. Returning `additionalContexts` keeps the waterfall result authoritative while sharing the same post-admission outbox path.
+
+## Acceptance criteria
+
+- `SendOptions` and steering inbox records contain no attached contexts; `agent/queued` reports only the retained message and steering facts.
+- `AdditionalContext` replaces `HookContext` across prompt interception, tool execution, hook bridges, guards, and context producers, with only `content` and `source`.
+- Prompt-prefix placement, prompt envelopes, and `context/message` are absent from public types, durable events, projection, and UI replay.
+- Idle `inject()` appends and flushes one sourced `user/message` without a turn or model call; `whenIdle()` and disposal await the flush.
+- Active-turn injection and hook-produced contexts drain at safe boundaries after complete tool-result batches and before the request that consumes them.
+- Blocked prompt admission opens no turn and appends neither the prompt nor hook-produced additional contexts; independently injected caller context remains.
+- Unit, persistence/resume, invariant, ACP/TUI replay, and keyless assembled-application snapshots cover the new event order and durability semantics.
+
+## Risks
+
+- Allowing one surface event outside turns weakens a simple invariant and may expose hidden assumptions in persistence scanning, crash repair, forking, compaction, and session queries.
+- Consecutive user-role messages replace one baked prompt message; provider adapters and cache behavior must accept and preserve that ordering.
+- `inject()` followed by a blocked `send()` leaves context without its intended direct prompt unless the caller accepts the independent-commit contract.
+- A synchronous injection API cannot return flush failure. Logging alone is less structured than `agent/error`, while adding a new persistence event solely for this case may create another unnecessary seam.
+- Removing attachment, placement, metadata, envelopes, and a durable event type is a broad pre-release migration that must update every producer and consumer atomically.
diff --git a/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md b/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
new file mode 100644
index 0000000000..1064e7a869
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
@@ -0,0 +1,75 @@
+# Agent Note: 将上下文注入与轮次执行分离
+
+Status: proposed
+
+[English](2026-07-24-separate-context-injection-from-turn-execution.md) | 中文
+
+## 问题
+
+agent API 目前用三种相互重叠的方式表示面向模型的补充输入：调用方通过 `SendOptions.contexts` 附加 `HookContext[]`，拦截钩子和工具钩子返回 `additionalContexts`，插件则调用 `agent.inject()`。这些路径最终都会把上下文写入同一份模型历史，但各自携带不同的放置、元数据、准入、队列和轮次生命周期规则。
+
+将上下文原子附加到收件箱消息后，agent loop（智能体循环）必须让上下文跟随提示词准入、steering（中途引导）转换、取消和终止丢弃的完整生命周期。`prompt-prefix` 放置方式又会把上下文与直接提示词合并为一个事件，因此 transcript（文本记录）消费方需要依赖模型不可见的封套，才能还原用户实际输入。这样一来，outbox 条目、会话投影和 UI 回放都必须处理本应由生产方负责的区分。
+
+空闲状态下的 `inject()` 还暴露了另一处语义错位。注入并不请求模型执行，但当前实现仅为了满足轮次封闭不变量并获得持久性检查点，就会打开并关闭一个零步骤的 `injection` 轮次。于是，轮次有时表示「运行 agent loop」，有时却表示「不运行 agent，仅持久化上下文」。
+
+`HookContext` 的名字也描述了生产方，而非该值的职责。它可能来自原生插件、hook bridge、提示词准入或工具后处理；其稳定含义只是带来源信息的额外模型上下文。
+
+## 提案
+
+将 `inject()` 设为调用方添加补充模型输入的唯一操作，并把轮次严格定义为一次模型循环执行。
+
+移除 `SendOptions.contexts`。拥有上下文的调用方通过 `inject()` 交付上下文，再独立使用 `send()` 或 `steer()` 提交直接消息。将 `HookContext` 重命名为 `AdditionalContext`；这个共享结构只保留 `content` 和 `source`，移除放置方式与模型不可见元数据。
+
+提示词和工具扩展点仍可返回 `additionalContexts`。这些值是扩展点的输出，而不是从调用方收件箱条目捕获的附件。提示词准入在 `run()` 打开轮次之前执行。提示词获准后，它与返回的额外上下文一同进入 outbox；提示词被阻止时，两者都不写入，也不打开轮次。工具产生的额外上下文则在对应工具结果之后进入同一个 outbox。
+
+每项额外上下文都成为独立的 `user/message`，并由 `source` 记录来源。移除 `context/message`、prompt-prefix 放置方式、稳定请求分隔符和提示词封套。transcript 与 UI 消费方通过 `source` 区分直接用户消息和注入上下文，无需从合并后的模型内容中恢复隐藏的直接提示词字段。
+
+## 注入生命周期
+
+轮次打开时，`inject()` 将上下文暂存在 loop outbox 中。agent loop 会在安全的步骤边界排空 outbox，同时保持工具协议要求的相邻关系：在助手工具调用批次期间接纳的上下文，只能出现在该批次所有有序结果之后。系统整体取走 outbox，确保同一边界接纳的 steering 和注入上下文对后续同一次请求可见。
+
+没有打开的轮次时，`inject()` 会立即追加对应的 `user/message` 并启动会话刷新。它不会增加轮次编号、发出 `turn/start` 或 `turn/end`、改变 agent 状态，也不会运行模型。同步 API 仍会在异步刷新完成前返回；`whenIdle()` 和 agent dispose（资源释放）会把尚未结束的空闲注入刷新纳入静止边界。
+
+空闲刷新失败时不存在合法的轮次或步骤坐标。系统通过日志或持久化所属的错误接口报告该失败，而不是为不存在的轮次伪造 `agent/error` 载荷。内存中的事件仍已接纳，后续刷新可以重试持久化。
+
+因此，会话不变量允许 `user/message` 位于两个轮次之间，同时继续要求执行事件、steering、助手输出、工具事件以及默认的包扩展事件均受轮次边界约束。持久化、恢复、resume、fork、压缩和查询逻辑必须把合法的轮次外 `user/message` 当作已提交会话历史，而不是中断轮次或可丢弃的日志尾部。
+
+## 扩展点与调用方语义
+
+`PromptDecision.content` 仍只替换直接提示词。`PromptDecision.additionalContexts` 和工具结果的 `additionalContexts` 保留 FIFO 顺序及各自来源，但不再选择放置方式。waterfall（瀑布式事件）监听器调用 `next()` 委托时，必须保留下游返回的提示词内容和额外上下文，除非它有意返回替代值。
+
+调用方主动注入与钩子产生的额外上下文具有不同的准入归属。钩子的额外上下文只会在该钩子允许提示词或工具结果后落入日志。调用方执行 `inject(context)` 后再执行 `send(prompt)` 时，上下文已独立提交；后续提示词准入即使阻止该提示词，注入上下文仍保留在历史中。需要领域级全有或全无语义的调用方，必须在执行任一操作前自行完成准备，或提供领域专用的准入 seam。
+
+跨会话引用使用普通组合方式：宿主先准备快照，以会话引用来源调用 `inject()`，再发送或 steer 可读的直接提示词。目标日志包含两条简单消息，因此来源会话后续变化不会改变回放，transcript 消费方也不需要提示词封套。本提案取代[跨会话引用决策](../../implemented/feature/2026-07-21-cross-session-references.md)中的附件机制，但保留其快照与信任边界规则。
+
+本提案保留[移除注入内容封套](../../implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md)确立的调用方自主管理框架原则，以及[一次 send、一个轮次](../../implemented/simplification/2026-07-17-one-send-one-turn.md)确立的单条目轮次规则；同时收窄[轮次封闭决策](../../implemented/architecture/2026-06-15-turn-enclosure-invariant.md)，使轮次约束执行过程，而不是约束所有会话事件。
+
+## 曾考虑的替代方案
+
+**保留 `SendOptions.contexts` 作为原子附件。** 提示词准入阻止消息时，这种方式能保留全有或全无交付，但也会让上下文继续成为收件箱生命周期状态的一部分，并迫使每次队列转换和观察事件携带它。大多数调用方都可以通过先注入上下文、再交付消息来表达需求，通用 agent API 不应内置领域事务。
+
+**保留独立的 `context/message` 会话事件。** 独立事件可以缩小轮次外事件的例外范围，但面向模型的 user-role 输入会再次拥有两个投影完全相同的事件类型。`user/message.source` 已能为策略、transcript 和回放消费方提供所需区分。
+
+**为空闲注入保留一次性轮次。** 这种方式能保留通用轮次封闭和方便的刷新边界，却会让轮次计数与轮次观察方报告从未运行模型的工作。持久性是独立的会话关注点，无需伪造执行即可等待。
+
+**保留 `prompt-prefix` 可选放置方式。** 前缀烘焙可以让上下文和请求位于同一条提供方消息中，但它会引入直接提示词的第二种表示，并把放置处理扩散到准入、steering、日志、回放和 UI 代码。需要文本框架的生产方可以直接把它写入自身上下文内容。
+
+**让钩子直接调用 `inject()`，而不是返回额外上下文。** 直接注入会破坏扩展点的准入归属：下游监听器阻止操作之前，上游监听器就可能已经追加上下文。返回 `additionalContexts` 能维持 waterfall 结果的最终权威性，同时复用准入后的 outbox 路径。
+
+## 验收标准
+
+- `SendOptions` 与 steering 收件箱记录不再包含附加上下文；`agent/queued` 只报告保留的消息和 steering 事实。
+- `AdditionalContext` 在提示词拦截、工具执行、hook bridge、guard 和上下文生产方中取代 `HookContext`，且只包含 `content` 与 `source`。
+- 公共类型、持久事件、投影和 UI 回放中均不存在 prompt-prefix 放置方式、提示词封套与 `context/message`。
+- 空闲 `inject()` 在不产生轮次或模型调用的情况下，追加并刷新一条带来源的 `user/message`；`whenIdle()` 和 dispose 会等待该刷新。
+- 活跃轮次注入和钩子产生的上下文会在完整工具结果批次之后的安全边界排空，并在消费它们的请求之前进入日志。
+- 被提示词准入阻止的消息不会打开轮次，也不会追加提示词或钩子产生的额外上下文；调用方此前独立注入的上下文仍保留。
+- 单元测试、持久化与 resume 测试、不变量测试、ACP/TUI 回放测试，以及无需密钥的组装应用快照覆盖新的事件顺序和持久性语义。
+
+## 风险
+
+- 允许一个表层事件位于轮次之外，会削弱一条简单不变量，并可能暴露持久化扫描、崩溃恢复、fork、压缩和会话查询中的隐含假设。
+- 两条连续的 user-role 消息会取代一条烘焙后的提示词消息；提供方适配器和缓存行为必须接受并保留这一顺序。
+- 如果调用方不能接受独立提交契约，`inject()` 后跟一个被阻止的 `send()` 会留下缺少预期直接提示词的上下文。
+- 同步注入 API 无法返回刷新失败。只记录日志的结构化程度低于 `agent/error`，但仅为此场景增加新的持久化事件也可能产生另一个不必要的 seam。
+- 移除附件、放置方式、元数据、封套和一种持久事件类型，是一次影响面较广的预发布迁移，必须原子更新所有生产方和消费方。
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
new file mode 100644
index 0000000000..ba5d8cd8c9
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-30-pre-tool-input-rewrite.md: 5de605e7edf63046b14a125d53072aab9bb5d37e
+2026-06-30-pre-tool-input-rewrite.zh.md: eab80764f5dfbd0448dabf0dc3c893ba2ec94928
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 e6c5d9eb1e..5de605e7ed 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
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+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.
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
new file mode 100644
index 0000000000..eab80764f5
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md
@@ -0,0 +1,53 @@
+# Agent Note: 工具执行前输入重写——一致性设计
+
+Status: proposed
+
+[English](2026-06-30-pre-tool-input-rewrite.md) | 中文
+
+## 问题
+
+[拦截 seam Agent Note（agent 决策记录）](../../implemented/feature/2026-06-30-interception-seams.md) 将 `tools/pre-execute` 定义为一道针对执行的允许/拒绝/询问门禁，此时执行的身份标识已受保护、参数已被深度冻结。Claude Code 的 `PreToolUse` 钩子还提供了 `updatedInput`，因此忠实的桥接需要一个显式的重写机制。重写不能是对现有执行对象的可变逃逸口：它必须保持持久化历史、审计记录、展示层与实际执行值之间的一致性。
+
+## 问题本质：执行前参数的三个读取方
+
+在 agent loop（智能体循环）中，工具调用的参数在工具执行之前就已提交到日志并被实时消费方读取：
+
+1. **`assistant/message`** 在工具分发之前追加——它是 `deriveMessages()` 回放时的模型历史来源，因此携带模型自身输出的工具调用参数。
+2. **`tool/call`** 是持久化的审计记录，在 `ctx.tools.execute()` 之前追加。
+3. **展示层实时读取 `tool/call.arguments`**：ACP（Agent Client Protocol）桥接记住这些参数并传给 `presentResult`；`dsh-tool-bash` 从中派生卡片标题、rawInput、cwd 以及终端/后台处理方式。
+
+如果只做执行层面的重写，UI 会显示一条命令而实际运行的是另一条，并且结果会对着错误的参数渲染。注册表目前通过以下方式防止这种失败模式：对 `arguments` 做 structured-clone 并深度冻结，将执行身份属性设为不可写，且不暴露任何可替换它们的测试 shim 或监听路径。重写设计必须维护这一受保护的身份边界，而非削弱它。
+
+## 提案
+
+重写是一个「身份标识创建前的一致性事务」。当钩子提供 `updatedInput` 时，有效值必须在注册表构造其不可变的 `ToolExecution` 之前确定，并且必须原子地反映到全部三个读取方：
+
+- `tool/call` 审计事件记录重写后的参数（原始参数保留在一个伴随字段中，作为审计线索——钩子修改了调用，原始参数与生效参数都是值得保留的事实）。
+- 派生历史中的 `assistant/message` 必须与实际执行一致。待评估的选项：就地重写 assistant 消息中的工具调用块（改变模型「看到自己说了什么」），或记录一条单独的修正让下一次请求携带。Claude Code 的模型是让模型看到重写已生效。
+- 展示层（`presentCall`/`presentResult`）读取重写后的参数，使 UI 显示实际运行的内容。
+
+在 `PreToolDecision` 当前的触发点上做扩展是不够的：此时两条持久化记录已经存在，执行身份已受保护。实现必须将相关决策移到日志提交之前，或者增加一个专门的、更早的重写决策点来处理待定的模型调用。agent loop 将生效参数提交到历史和审计之后，再构造普通的不可变执行对象，并照常运行现有的允许/拒绝/询问和工具流水线。
+
+## 曾考虑的替代方案
+
+### 为什么不直接修改执行对象？
+
+允许 pre-execute 监听器赋值 `exec.arguments` 只能提供执行层面的重写，模型历史、审计和展示层不会随之改变。保持身份标识受保护使得这种局部行为不可表达。在一致性事务实现之前，CC/Codex 桥接对 `updatedInput` 记录日志并发出警告，而非声称已兑现；循环分发点的 `TODO(pre-tool-input-rewrite)` 标记了缺失的更早阶段。
+
+## 验收标准
+
+- 请求的重写在 `ToolExecution` 身份标识创建之前解决，并原子地反映到全部三个读取方：`tool/call` 审计记录重写后的参数（原始参数保留在伴随字段中）、派生历史与实际执行一致、展示层渲染重写后的参数。
+- 生效的 `ToolExecution.arguments` 在 pre-policy、守卫、分发、post-policy 和最终观测全程保持深度冻结且不可写；不引入任何可变 shim。
+- CC/Codex 桥接兑现 `updatedInput`，不再记录忠实但降级的警告。
+
+## 风险
+
+- 重写 `assistant/message` 中的工具调用块会改变模型「看到自己说了什么」；是否有提供方在回放时拒绝这种改动，是一个需要通过实验确定的开放问题，必须在决策形状冻结之前解决。
+- 更早的重写阶段改变了 `assistant/message`、`tool/call`、钩子审计事件与执行之间的顺序关系；设计必须固定这一顺序，同时不削弱轮次封闭性或调用/结果邻接性。
+
+## 开放问题
+
+- 重写 `assistant/message` 中的工具调用块是否会破坏某些提供方在回放时的预期？还是单独的修正更安全？
+- 原始参数是否应保留在 `tool/call` 事件（审计）上？如果是，放在什么字段？
+- 重写决策是移到日志提交之前，还是成为一个专门的更早 seam？现有的 pre-tool 允许/拒绝钩子如何避免运行两次？
+- 这与未来的权限 `ask` 流程（用户批准一个被重写的调用）如何交互？
diff --git a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.i18n.yaml b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.i18n.yaml
new file mode 100644
index 0000000000..ecb4e98def
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-07-claude-code-and-codex-subagent-backends.md: ee8576f97a9fdef8c88dcad3a73f28b63ca3ebe1
+2026-07-07-claude-code-and-codex-subagent-backends.zh.md: 14e8dde04d9526aaffc0e58be049e13858362887
diff --git a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md
index 620f39c4a4..ee8576f97a 100644
--- a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md
+++ b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-07-07-claude-code-and-codex-subagent-backends.zh.md)
+
 ## Problem
 
 The subagent seam ([the seam Agent Note](../../implemented/feature/2026-06-21-subagent-capability-seam.md)) hosts multiple named providers on `ctx.subagents`, and the ACP backend ([the ACP backend Agent Note](../../implemented/feature/2026-06-22-acp-subagent-backend.md)) proved the seam generalizes across a process boundary; its Future-providers section explicitly named the Codex app-server and the Claude Code Agent SDK as mechanically similar siblings. Those two are the engines actually worth delegating to today: a harness turn should be able to hand a self-contained task to a real Claude Code or a real Codex — a separate product with its own model, tools, and sandbox — and get back one final answer, without the parent deployment leaking its secrets into the child or the child's behavior silently depending on whatever `~/.claude` / `~/.codex` state exists on the host machine.
diff --git a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.zh.md b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.zh.md
new file mode 100644
index 0000000000..14e8dde04d
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.zh.md
@@ -0,0 +1,89 @@
+# Agent Note: Claude Code 与 Codex subagent 后端（向外部编码 agent（智能体）的进程外委派）
+
+Status: proposed
+
+[English](2026-07-07-claude-code-and-codex-subagent-backends.md) | 中文
+
+## 问题
+
+subagent seam（[seam Agent Note（agent 决策记录）](../../implemented/feature/2026-06-21-subagent-capability-seam.md)）在 `ctx.subagents` 上托管多个命名提供方，ACP（Agent Client Protocol）后端（[ACP 后端 Agent Note](../../implemented/feature/2026-06-22-acp-subagent-backend.md)）证明了该 seam 能跨越进程边界泛化；其「未来提供方」一节明确将 Codex app-server 与 Claude Code Agent SDK 列为机械上相似的兄弟。如今真正值得委派的就是这两个引擎：harness 的一个轮次应能把一个自包含任务交给真实的 Claude Code 或真实的 Codex——一个拥有自身模型、工具与沙箱的独立产品——并取回一个最终答案，同时父部署不向子进程泄漏密钥，子进程行为也不静默依赖宿主机上碰巧存在的 `~/.claude` / `~/.codex` 状态。
+
+## 提案
+
+两个兄弟提供方包（package），作为 ACP 后端的结构变体，另加一次提取：
+
+- `@deepseek-ai/dsh-subagent-claude-code`：通过 `@anthropic-ai/claude-agent-sdk` 的 `query()` 驱动一个 Claude Code 子进程（SDK 在父进程中运行，并将其内置的 `claude` CLI（命令行界面）作为子进程 spawn）。提供方名称为 `claude-code`：子进程是 Claude Code 这个*产品*，而非 Anthropic 模型适配器——「claude」保留给未来的 `dsh-llm` 适配器。
+- `@deepseek-ai/dsh-subagent-codex`：spawn `codex app-server`，通过其 JSON-RPC-over-stdio 协议驱动一个 thread/turn，使用包内一个手写的换行 JSON 客户端（约 200–300 行）。
+- `@deepseek-ai/dsh-subagent-process`：纯库（沿用 `subagent-inprocess` 的先例），提取 `dsh-subagent-acp` 已有且两个新后端都需要的内容：凭证环境清洗（`buildChildEnv`）、EOF → SIGTERM → SIGKILL 的 dispose（资源释放）阶梯，以及新的隔离配置目录辅助函数（`mkdtemp` 创建、尽力删除）。ACP 后端迁移到该库上；`bash-local` 的兄弟副本保持不动以限制变更范围。
+
+两个提供方逐字复制 ACP 后端的 seam 姿态：每次 `start` 创建全新子进程、恰好一次提示词往返、所有能力均为 `false`、`inheritsParentContext: false`、忽略 `request.parent`/`request.agentOptions`、`id = SessionId(randomUUID())`，且 `result` 从不 reject——子进程级失败扁平化为 stop reason，原始错误则通过 `onError` spec 回调送到 `ctx.logger`。模型暴露无需新代码：每个提供方各加载一次 `dsh-tool-subagent`，使用不同的 `toolName`（`subagent_claude_code`、`subagent_codex`）。无需新的会话事件——唯一的模型可见产物是工具结果，因此可重建性与 ACP 完全相同。明确边界：会话日志重建模型可见的 transcript（文本记录），而不是工作区变更历史——获准写入的子进程将文件作为日志之外的环境副作用进行修改，与 bash 工具和 ACP 后端现有行为完全一致；回放复现请求，而非磁盘。
+
+## 已验证的接口事实（固定版本）
+
+两个集成面在本提案之前均已针对固定版本进行了验证——阅读类型与打包源码、运行无需密钥的 spike——而非仅依赖厂商文档。固定版本是验证基线，不是运行时契约：后端不执行运行时版本探测（无 `codex --version` 门禁、无 SDK 版本嗅探）。兼容性在开发时强制执行——每次依赖升级都会针对真实加载路径重跑无密钥套件——在运行时则通过大声失败来保障：协议层面的意外通过 `onError` 结算为 `error`，绝不静默异常。
+
+**`@anthropic-ai/claude-agent-sdk` 0.3.202。** `options.env` 会替换子进程环境（不与 `process.env` 合并），恰好满足清洗需求。`settingSources` 默认加载所有文件系统设置——隔离要求显式传入 `[]`。结果子类型为 `success` | `error_during_execution` | `error_max_turns` | `error_max_budget_usd` | `error_max_structured_output_retries`。中止时 SDK 自行逐级加强对 CLI 子进程的终止措施：立即关闭 stdin，约 2 秒后若子进程未退出则发送 SIGTERM（已观察到；无残留进程）——无需自定义 kill 回退。`outputFormat: {type: 'json_schema'}` 和 `agents` 选项已存在，为 seam 的 `outputSchema` 能力和命名 subagent 类型提供了未来着陆点；两者均不在本 Agent Note 范围内。
+
+**codex CLI 0.142.5，`codex app-server`（v2 词汇）。** LF 分隔的 JSON，JSON-RPC 2.0 形状但省略 `"jsonrpc"` 头。
+
+- 生命周期：`initialize{clientInfo}` + `initialized` → `thread/start`（接受 `cwd`、`model`、`sandbox`、`approvalPolicy`、`ephemeral`；未认证即可成功）→ `turn/start{threadId, input:[{type:'text',text}]}` 立即返回一个 `inProgress` 的轮次；终止信号是携带 `Turn{status: completed|interrupted|failed|inProgress, error}` 的 `turn/completed` 通知。
+- 审批是服务端发起的请求——`item/commandExecution/requestApproval`、`item/fileChange/requestApproval`、`item/permissions/requestApproval`、`item/tool/requestUserInput`、`mcpServer/elicitation/request`——以 `accept`/`decline` 系列决策应答。
+- 认证：`account/login/start{type:'apiKey', apiKey}` 是一等 RPC，`account/read` 报告 `requiresOpenaiAuth`——且未认证的 `turn/start` 不会快速失败（它会挂在重试中），因此后端必须预检认证状态，并在失败时大声结算为 `error`，而非等待轮次。
+- 隔离：`CODEX_HOME` 重定向被尊重（`initialize` 响应会回显它，测试可据此断言隔离），`ephemeral: true` 的 thread 不留任何会话文件。
+
+## 隔离与凭证
+
+部署只使用 API key 认证，子进程不得看到宿主用户的 Claude Code / Codex 配置：行为必须只由 `cordis.yml` 决定。每次运行获得一个全新的 `mkdtemp` 配置目录——Claude Code 使用 `CLAUDE_CONFIG_DIR`（并显式设置 `settingSources: []`），Codex 使用 `CODEX_HOME`——dispose 时尽力删除；配置字段也可以固定一个持久目录。子进程环境通过提取逐字复用 ACP 后端的 `buildChildEnv` 语义：转发环境变量，但移除凭证形态的变量（`/KEY|SECRET|TOKEN/i`），再叠加 `config.env`——因此 `PATH`、`HOME`、`TMPDIR`、locale 和代理变量保留，CLI 正常运行；只有环境中的凭证形态变量被清洗（Claude Code 的 `ANTHROPIC_API_KEY` 通过 `config.env` 显式进入），Codex key 则通过 `account/login/start` RPC 进入隔离的 `CODEX_HOME`，而非手写 `auth.json`。
+
+## 权限与审批策略
+
+每个后端不压缩为 ACP 单一的 `permission: allow|reject` 旋钮，而把引擎原生词汇作为配置暴露，并采用保守默认值：Claude Code 获得 `permissionMode`（默认 `default`）以及 `permission: allow|reject`（默认 `reject`），后者作为所有漏过请求的 `canUseTool` 自动应答；Codex 获得 `sandboxMode`（默认 `read-only`）和 `approvalPolicy`（默认 `never`），以及同一个 `permission` 后备值，用来应答仍然到达的审批请求。默认值刻意做到不造成损害（开箱即用的子进程无法写文件）；示例演示如何开放权限（`acceptEdits` / `workspace-write`）。机械规则是：每一个服务端发起的请求都由程序迅速结算——枚举出的审批/用户输入/elicitation 请求按配置策略应答，未知请求方法用 JSON-RPC method-not-found 错误响应（绝不保持 pending），未知通知被消费——因此任何子进程请求都不会因等待永远不会到来的应答而卡住轮次。这一版中提示词不会到达人类，与 ACP 一致。
+
+## StopReason 映射
+
+Claude Code：`success` → `completed`；`error_max_turns`、`error_during_execution`、`error_max_budget_usd`、`error_max_structured_output_retries` → `error`（与 ACP 对 `max_turn_requests` 的处理对齐：未完成的任务不是成功）；生成器中止 → `aborted`；未知值 → `error`。Codex：`Turn.status` 为 `completed` → `completed`；`interrupted` → `aborted`；`failed` 且 `codexErrorInfo: 'contextWindowExceeded'` → `max-tokens`，其他 `failed` → `error`；传输/spawn/认证预检失败 → `error`（若已请求取消则为 `aborted`）。两者中，`cancel()` 采用 ACP 形状：标志位 + abort/interrupt + 一个 cancel-settled 竞争分支，使不合作的子进程无法阻塞结果。
+
+活性姿态，明确声明：teardown 时序是配置项，轮次时长不是。两个后端将 dispose 阶梯的宽限期作为带默认值的已验证配置字段（ACP 后端的 `disposeEofGraceMs`/`disposeGraceMs` 形状，由提取库承载），但刻意不设轮次时长或启动超时——与 ACP 一致：轮次期间的活性由调用方通过 `cancel()`/abort signal 掌控，subagent 轮次持续数分钟也属合理，而 Codex 认证预检消除了唯一已验证的必然挂起场景；需要墙钟上限的部署从父侧取消即可。
+
+## 测试
+
+依照根 AGENTS.md 规则在每个层级明确命名，并预先消除风险：
+
+- **无密钥单元/集成测试**：每个后端都镜像 ACP spec 清单（往返和输出累积、每种 stop 映射、两条取消路径、已中止、两种策略下的权限自动应答、未知消息容错、错误命令的 spawn 失败、HMR（热模块替换）提供方清理、导出形状、子进程环境隔离断言和临时目录删除；Codex 另加认证预检失败路径）。Claude Code harness 是通过 `pathToClaudeCodeExecutable` 接入真实 SDK 的脚本化假 `claude` 可执行文件——一个 spike 已在 24ms 内完成端到端无密钥验证（假 CLI 应答一次 `control_request/initialize`，并讲 plain stream-json，约 40 行）。Codex harness 是讲已验证协议格式的脚本化 mock app-server 子进程，沿用 `mock-acp-server.ts` 形状。
+- **有密钥 e2e 测试**：每个后端的真实引擎执行并由磁盘验证真实文件工作，固定使用开放后的配置，以免验收与不造成损害的默认值冲突——Claude Code 使用 `permissionMode: 'acceptEdits'`，Codex 使用 `sandboxMode: 'workspace-write'` + `approvalPolicy: 'never'`；自跳过会准确报告缺失的是二进制还是 key。CI 没有密钥，因此依照有密钥策略在本地运行。
+- **快照测试**：以 `TODO(claude-code-subagent-replay)` / `TODO(codex-subagent-replay)` 推迟——即 ACP 后端也推迟的独立回放形状（[按会话回放 Agent Note](../../implemented/testing/2026-06-22-subagent-snapshot-replay.md)）；在此期间由无密钥套件提供确定性覆盖。
+
+## 曾考虑的替代方案
+
+### 为什么不用官方 `@openai/codex-sdk` 而手写客户端？
+
+dispose 阶梯和环境清洗要求拥有子进程（spawn 参数、env、信号、exit 等待）；SDK 隐藏了进程。协议格式（wire format）极其简单（LF JSON），形状可按固定版本生成（`codex app-server generate-json-schema`），仓库先例（`hook-protocol`）是拥有薄协议核心而非包装他人的运行时。SDK 能节省协议演进的维护成本，但代价是失去本后端存在的意义所在的精确控制。
+
+### 为什么不用模型可见的 `subagent_type` 参数（单一 Task 风格工具）？
+
+Claude Code 自身的 Task 工具将 subagent 类型放在模型可见的 schema 中，选择一个提示词 + 工具集人格。这里的选择是在执行引擎之间做出的，而只有部署者知道哪些引擎配置了凭证——因此选择留在部署配置层，保持 `dsh-tool-subagent` 文档中的「一个提供方对应一个工具」契约。人格风格的类型选择器应是针对工具的另一个 Agent Note，而非针对后端。
+
+### 为什么不用登录态凭证和用户自身的配置？
+
+继承 `~/.claude` / `~/.codex`（订阅登录、用户设置、skill（技能）、MCP 服务器）会使子进程行为依赖宿主机状态，并在 ACP 后端和 bash 执行器确立的「凭证通过 `config.env` 显式进入，绝不隐式继承」规则上打开一个隐式例外。仅 API key 加强制配置目录隔离使运行可复现；需要共享状态的部署可以有意将配置目录字段指向一个持久目录。
+
+### 为什么不为 Claude Code 无密钥测试注入驱动层 seam？
+
+注入假的 `query()` 会 mock 我们自己的边界，使真实 SDK 加载路径未被测试（docs/testing.md 中的 real-over-mock 策略）。曾考虑此方案的风险——SDK↔CLI 的 stream-json 控制协议是内部实现——已被 spike 消除：假 CLI harness 今天能对真实固定版本的 SDK 正常工作。如果 SDK 升级破坏了 mock，无密钥套件会让升级 PR（Pull Request）失败，这正是门禁在发挥作用。
+
+### 为什么不用 ACP 适配器（如 `claude-code-acp`）复用既有后端？
+
+社区 shim 将两个引擎包装为 ACP，这会使它们在 `dsh-subagent-acp` 上变成「仅配置」。但这在 harness 与引擎之间插入了一个非官方的第三方层，抹去了本 Agent Note 暴露的原生控制面（permissionMode、sandboxMode/approvalPolicy、配置目录隔离、apiKey RPC），并以 shim 的发布节奏替换了第一方协议的稳定性。第一方接口——Agent SDK 和 app-server——才是受支持的集成点。
+
+## 验收标准
+
+在两个引擎和密钥均已配置的机器上：一个 REPL 驱动的模型通过 `subagent_claude_code` 完成一个真实文件任务，通过 `subagent_codex` 完成另一个，工具结果为子进程的最终答案，父会话日志中仅有 `tool/call` + `tool/result`。无密钥套件在无凭证环境下以逐文件 100% 覆盖率通过，断言隔离（清洗后的子进程环境、dispose 后无残留临时配置目录），并断言 `~/.claude` / `~/.codex` 的存在与否不影响子进程行为。取消父轮次后，两个后端在有界时间内完全停稳，无残留子进程。e2e 套件干净地自跳过，命名缺失的前置条件。
+
+## 风险
+
+- `codex app-server` 被 CLI 标记为实验性，其 v1/v2 词汇共存；客户端固定 0.142.5、仅实现 v2、对未知方法/通知消费而不崩溃，但未来 codex 升级仍可能迫使返工（每次升级重新生成 schema 并重跑无密钥套件——这是上述「不做运行时版本探测」立场背后的开发时强制执行）。
+- Claude Code 假 CLI mock 依赖一个内部协议：任何 SDK 升级都必须通过无密钥套件，控制协议的破坏性变更意味着返工 mock（回退方案：上面否决的驱动注入 seam 成为逃生舱口）。
+- SDK 的 optionalDependencies 每平台约 280MB——已接受，限制在单个后端包内。
+- SDK 的 SIGKILL 分支（EOF→SIGTERM 之后）未被观察到，信任其实现；e2e 保留无残留进程断言。
+- Codex 是部署前置条件（无 npm 内置二进制）；缺失或不兼容的二进制以大声的 spawn/协议 `error` 呈现，而非版本探测。
+- 每次运行付出一个全新子进程的代价，且仅最终答案浮出——思考、工具卡片和用量被消费后丢弃；连接池、中间进度浮出、`sendMessage`/`resume`、通过 SDK 的 `outputFormat` 实现 `outputSchema`、以及通过 SDK 的 `agents` 选项实现命名 subagent 类型，均为刻意推迟。
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
new file mode 100644
index 0000000000..b815cfdd2a
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-08-interactive-side-sessions.md: dfd325babe215782c9c1cbec3fd9f874783af7ab
+2026-07-08-interactive-side-sessions.zh.md: 9bc9d5c94fdef893134844551a594acc39a99d3b
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 f2e3e74ca1..dfd325babe 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
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+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.
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
new file mode 100644
index 0000000000..9bc9d5c94f
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
@@ -0,0 +1,41 @@
+# Agent Note: 交互式侧会话与合并回写
+
+Status: proposed
+
+[English](2026-07-08-interactive-side-sessions.md) | 中文
+
+## 问题
+
+用户可能希望在不改变当前会话主上下文的前提下，探索一个来自活跃会话的问题。现有原语无法提供这种产品形态：[会话存储 fork](../../implemented/feature/2026-06-30-session-store-fork-api.md)创建的是一个无关联的会话，而 [fork subagent](../../implemented/feature/2026-06-21-subagent-capability-seam.md)是模型驱动的任务，其 transcript（文本记录）会折叠为一条工具结果。两者都不能给用户一个独立的对话，也都不能将结论带着出处信息记录回父会话。
+
+## 提案
+
+**侧会话（side session）** 是一个普通的活跃会话，从源会话的最后一个已完成轮次 fork 而来，绑定到自己的 agent（智能体），定位为只读顾问，并能**合并回写**一条精简笔记。
+
+- **Fork 并绑定：** 以父会话的平衡已完成轮次前缀创建子会话，并在其元数据中标记 `parentSession` 与 `seedLength`。这组合了 `ctx.agents.create({ seed, meta })`；不新增核心服务或会话存储方法。
+- **顾问定位：** 创建后注入一条插件来源的 `context/message`，告知子会话只做解释，不执行变更或继续任务。保持系统提示词逐字节一致，可在继承的历史上保留提供方的前缀缓存。
+- **合并回写：** 向子会话请求一条有长度上限的 handback，然后向父会话注入一条插件来源的 `context/message`。父会话的下一次请求在其日志位置看到该消息，保持回放与[请求可重建性](../../implemented/architecture/2026-07-05-reconstructable-requests.md)，无需新增会话事件。
+- **呈现：** 调用方式、会话切换与 handback 渲染属于首个客户端拥有的界面。本 Agent Note（agent 决策记录）仅规定与界面无关的机制。
+
+回退产品化、会话树视图、面向模型的侧会话工具，以及 `forkName`/`mergedInto` 元数据均不在本 Agent Note 范围内。一次真实适配器 spike 已验证了源日志隔离、继承上下文、多轮子会话交互，以及合并回写在父会话下一轮次中的可见性。
+
+## 曾考虑的替代方案
+
+- **使用 subagent seam：** 否决。侧会话是用户驱动的、客户端可见的，且可能存活超过父会话的一个轮次；subagent 是模型驱动的运行，返回一条工具结果。
+- **修改子会话的系统提示词：** 默认否决，因为任何字节变化都会从第零个 token 起使前缀缓存失效。部署方仍可选择这种更强的隔离方式。
+- **新增 `sidechat/*` 事件：** 延后。插件来源的 `context/message` 已提供持久性、出处与回放能力；只有当某个界面需要差异化渲染时，专用事件才有正当理由。
+- **现在就绑定一个协议界面：** 否决。当前 UI 由客户端拥有。实时呈现最终必须从持久消息派生，以使回放渲染出相同的记录。
+
+## 验收标准
+
+- Fork 不改变源会话，创建的子会话具有平衡的已完成轮次前缀、`parentSession`、`seedLength`，以及逐字节一致的系统提示词。
+- 顾问定位在子会话追加历史的头部恰好添加一条插件来源的 `context/message`，而非修改其系统提示词。
+- 合并回写恰好添加一条有长度上限的 `context/message`，来源为 `plugin: sidechat`；父会话的下一次请求与回放在相同位置看到它。
+- 父会话与子会话并发运行，日志和流之间无串扰。
+- 单元测试覆盖 fork/attach 与合并回写；快照覆盖率随首个绑定界面一起落地。
+
+## 风险
+
+- 只读行为在 `tools/pre-execute` 拒绝门禁强制执行之前仅为建议性质；[拦截 seam](../../implemented/feature/2026-06-30-interception-seams.md) 可在不改变本机制的前提下添加该门禁。
+- 经过压缩（compaction）的源会话 fork 出的是其压缩视图，因此绑定的界面应当告知用户子会话继承的是摘要而非被替换的轮次。
+- 反复的 handback 会消耗父会话上下文。每次合并的长度上限约束了单条笔记的大小；后续的合并整理属于上下文压缩的职责。
diff --git a/.agents/notes/proposed/feature/2026-07-10-sqlite-session-query-provider.md b/.agents/notes/proposed/feature/2026-07-10-sqlite-session-query-provider.md
deleted file mode 100644
index d643d223dd..0000000000
--- a/.agents/notes/proposed/feature/2026-07-10-sqlite-session-query-provider.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Agent Note: SQLite FTS5 session search
-
-Status: proposed
-
-## Problem
-
-The exact-read `ctx.sessionQuery` service deliberately has no derived index. Large persisted histories need full-text search without scanning every event on every query, while current live sessions need an overlay newer than the last durability checkpoint. Search also needs concrete ranking, snippets, pagination, cancellation, and rebuild behavior.
-
-Splitting those concerns across a speculative provider coordinator and a database implementation would create two coupled reconciliation state machines. The first real implementation should own the source observation, extraction, SQLite transaction, generation, and query as one lifecycle.
-
-## Proposal
-
-Add `@deepseek-ai/dsh-session-query-sqlite` beside the exact-read package. The package will expose a search service or extend the family with the smallest API required by its actual consumers; phase one does not pre-commit a provider-registration protocol. It will depend on `ctx.sessions` and optional `ctx.sessionPersistence`, own a separate derived SQLite database, and reuse the canonical `foldSurface()` classification.
-
-The implementation owns one serialized reconciliation/DB transaction state machine. A transaction observes authoritative persisted metadata and live snapshots, extracts semantic documents, updates derived tables, advances relevant cursor generations, and executes or enables the corresponding query. No second service maintains parallel fingerprints, dirty flags, live-id sets, or invalidation generations.
-
-Persisted documents survive restarts. Live overrides are connection-local and shadow the persisted rows for the same session, then disappear when the live owner or database closes. The derived database remains separate from canonical persistence so index reset, corruption, tokenizer changes, and schema churn cannot endanger durable conversation logs.
-
-## Search semantics to decide with implementation
-
-The implementation must define both cross-session and within-session scopes from executable use cases. Each searchable event is one document with session metadata, event metadata, surface classification, normalized semantic text, and a bounded plain-text snippet. Session results group by their strongest matching event; numeric backend scores remain private.
-
-Search returns content-bearing result records rather than metadata-only headers. Chainable filters operate on that exact result shape and are designed and implemented with the search API instead of becoming a provider-specific pre-ranking contract. Query syntax is treated as data. Ordering includes stable tie fields. Opaque cursors bind to normalized request shape and the smallest relevant generation; unrelated session changes should not invalidate a within-session cursor. Cancellation must stop caller waiting and interrupt SQLite work where the runtime permits.
-
-Tokenizer choice remains an implementation experiment. FTS5 trigram supports substring recall but rejects useful terms shorter than three characters and increases index size; the proposal must benchmark that tradeoff against the default Unicode tokenizer before making it contract.
-
-## Extraction and reconciliation
-
-The package starts with first-party semantic extraction for messages, reasoning, tool calls/results, blocked prompts, context, steering, todos, and error/status detail. Structural events and stream chunks contribute no document. Unknown declaration-merged event/content types remain non-searchable unless a real extension consumer demonstrates the need for a public extractor registry.
-
-Reconciliation may use stable fingerprints to avoid rewriting unchanged persisted sessions, but the database package owns their calculation and storage. It must never report a row current when source observation or extraction failed. Provider-schema mismatch may reset only the derived database; ordinary source changes use transactional upsert/delete. Mounted but unreadable persistence fails affected searches without affecting canonical writes or known live exact reads.
-
-## Alternatives considered
-
-- **Add FTS tables to the canonical persistence database** — rejected because a rebuildable index must not share the authoritative log's schema/reset/failure boundary.
-- **Reintroduce phase-one provider coordination** — rejected because there is one planned implementation and no evidence for a stable multi-provider seam.
-- **Persist live overrides immediately** — rejected because live events are not canonical until the existing checkpoint commits.
-- **Return BM25 scores** — rejected because provider-specific numeric scales are unstable across corpus changes.
-
-## Acceptance criteria
-
-- Restart tests cover unchanged, new, changed, and deleted persisted sessions without rebuilding the whole index.
-- Reopening preserves persisted rows and removes live rows; live rows shadow and then reveal their persisted base.
-- Tests cover both search scopes, content-bearing results, chainable result filters, surface defaults, snippets, escaping, deterministic ties, pagination, scoped stale cursors, cancellation, dynamic persistence mount/unmount, and recovery after a failed transaction.
-- A schema mismatch resets only the derived database.
-- A keyless end-to-end test combines a real persistence backend with the real SQLite search package.
-- The Agent Note is amended to the measured tokenizer and public API actually implemented before moving to `implemented/`.
-
-## Risks
-
-A single owner is simpler but initially less reusable than a provider-neutral seam. That is intentional: a second real backend can reveal what to extract. SQLite runtime differences can affect FTS ranking and snippets, so tests must pin only contract-controlled ordering and presentation. The separate database adds configuration and lifecycle work, but preserves the canonical store's safety boundary.
diff --git a/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.i18n.yaml b/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.i18n.yaml
new file mode 100644
index 0000000000..5c7c7e9cc1
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-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
+2026-07-13-stream-workflow-progress-through-tool-calls.md: 668d38b38cab90f6ee9b613d1101d4d44302aa8a
+2026-07-13-stream-workflow-progress-through-tool-calls.zh.md: b0daba0c62c9b06f33f5e3c6319f90670941e762
diff --git a/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md b/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md
index 0c6516080a..668d38b38c 100644
--- a/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md
+++ b/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-07-13-stream-workflow-progress-through-tool-calls.zh.md)
+
 ## Problem
 
 The workflow engine intentionally emits balanced `workflow/*` observation events for run, phase, narration, and child-agent progress, but no production consumer presents them. Editors therefore show one pending workflow tool card until the final result even while the engine already reports which phase is active, what the script logged, and which children started or settled. The [dynamic-workflows decision](../../implemented/feature/2026-07-05-dynamic-workflows.md) explicitly reserves ACP progress UI for this event stream.
diff --git a/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.zh.md b/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.zh.md
new file mode 100644
index 0000000000..b0daba0c62
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.zh.md
@@ -0,0 +1,43 @@
+# Agent Note: 通过工具调用流式传输工作流进度
+
+Status: proposed
+
+[English](2026-07-13-stream-workflow-progress-through-tool-calls.md) | 中文
+
+## 问题
+
+工作流引擎有意为 run、phase、narration 和子 agent（智能体）进度发出成对的 `workflow/*` observation 事件，但目前没有生产消费方呈现这些事件。因此，编辑器在最终结果返回之前只显示一张 pending 状态的工作流工具卡片，尽管引擎已经报告了当前活跃的 phase、脚本日志内容以及哪些子 agent 已启动或已结束。[动态工作流决策](../../implemented/feature/2026-07-05-dynamic-workflows.md)明确将 ACP（Agent Client Protocol）进度 UI 保留给这一事件流。
+
+如果让 `dsh-acp` 直接监听工作流事件，就会反转能力边界：通用的 UI 桥接层将依赖一个可选的工作流包（package），并对一个工具名做特殊处理。工具流水线已经拥有实时更新所需的路由信息（agent 和 call id），但只暴露了纯粹的 pending/final 展示器，因此长时间运行的工具没有提供方无关的方式在二者之间报告瞬态 UI 状态。
+
+## 提案
+
+为 `dsh-tools` 添加一条实时进度通道。注册表所有的 `ToolExecution` 新增 `reportProgress(view): boolean`，其中 `view` 是一个独立的、提供方无关的通用进度快照，包含可选的替换标题和面向 UI 的内容块。进度不能更改调用的 args 派生卡片标签、kind、原始输入、locations、terminal intent 或 diff intent；它只更新在最初选定的展示方式内的实时标题/内容。当执行处于活跃状态时，该方法校验并快照 view，然后分发一个受限的、agent 作用域的 `tools/progress` observation，携带权威的执行标识与快照。一旦 final-result 处理开始，方法返回 `false` 且不再分发，因此迟到的异步报告者无法覆盖终态卡片。观察者异常会被记录日志，不会导致工具失败。
+
+`dsh-acp` 以通用方式消费 `tools/progress`。它通过既有的 agent 到会话映射解析执行所属的 agent，并为同一 call id 发出 in-progress 的 `tool_call_update`。由于报告仅在工具执行流水线内可用，持久化的 `tool/call` 及其 ACP `tool_call` 始终先于第一条 update；在 `tools/result` 之前关闭报告者，确保进度更新不会出现在 completed/failed 卡片之后。进度是实时 UI 状态，而非模型输入或持久历史：会话回放继续从 `tool/call` 和 `tool/result` 重建 pending 与 final 卡片，无需重放瞬态更新。
+
+`dsh-tool-workflow` 成为第一个生产者。每次工具执行在调用 `ctx.workflows.start()` 之前安装一个紧凑的事件捕获器，因为合法的引擎可能在 `start()` 内部同步发出进度。在调用返回之前，捕获器将观察到的事件按 `WorkflowRunInfo.id` 归约为候选状态；随后选取返回的 `WorkflowRun.id`，丢弃其他候选，报告累积的快照，并将后续匹配事件直接路由。如果 `start()` 抛出异常，捕获器被 dispose（资源释放），其候选状态被丢弃。这在不向 `WorkflowStartRequest` 添加观察者关联、也不要求进度等到 `start()` 返回的前提下，保持了引擎的可替换性。
+
+归约器消费既有的 start、phase、log、agent-start、agent-end 和 end 事件，报告一个替换快照，包含当前 phase、最新日志行、活跃子 agent 标签以及 completed/failed/cancelled 计数。它不累积 narration transcript（文本记录）；已结束的子 agent 离开活跃集合，变为计数器。`workflow/end`、工具结算或插件 dispose 移除归约器条目和事件捕获器。六种工作流事件及其元数据、成对的子 agent 生命周期、run handle、取消通道和观察者隔离保持不变；第三方观察者可继续直接消费这些事件。
+
+更新工具执行/展示文档、生成的事件与 API 目录、工作流包文档以及工作流数据结构目录。ACP 集成覆盖率必须使用脚本化的模型边界测试真实的工作流工具和 worker seam；主 ACP 快照套件新增一个 workflow-progress 场景，因为这改变了面向编辑器的 transcript。
+
+## 曾考虑的替代方案
+
+**删除工作流 observation 表面。** 在[折叠工作流简化提案](../../rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md)中被否决：这些事件及其成对生命周期是有意设计的，缺少的是消费方。
+
+**让 ACP 直接了解工作流。** 这可以将 `WorkflowRunInfo` 映射到会话和卡片，但会使通用桥接层依赖一个可选能力，并绕过「工具拥有展示意图」的规则。工具进度通道为每个长时间运行的工具解决了相同的路由问题。
+
+**将每条进度更新持久化为会话事件。** 这会使实时 narration 可回放，但会用一种状态永久膨胀日志，而该状态的权威持久结果已经是工具调用/结果对。如果可恢复的工作流进度成为产品需求，需要一个工作流日志化设计，而非伪装成持久事实的 UI 快照。
+
+## 验收标准
+
+- `ToolExecution.reportProgress()` 由注册表所有、agent 作用域、快照化、观察者隔离，且在终态处理开始后返回 `false` 而不分发。
+- ACP 将进度路由到正确的实时会话中的正确调用；不同会话中的并发工作流不能串扰，且 `tool_call_update` 不会出现在其 `tool_call` 之前或终态更新之后。
+- 工作流进度显示当前 phase、最新日志行、活跃子 agent 和结果计数，同时保留所有既有 `workflow/*` 事件和 run 语义；一个在 `start()` 内部同步发出 start、phase、log、child 和 end 事件的 seam 测试引擎不会丢失任何归约器状态。
+- 取消、worker 死亡、工具失败、会话关闭和插件 dispose 释放归约器状态；回放仅发出持久的 pending/final 卡片对。
+- 单元测试、工作流集成测试、ACP 集成测试、快照、类型检查、覆盖率、doc-sync（文档同步门禁）、module-graph、构建和 hygiene 门禁全部通过。
+
+## 风险
+
+本提案向工具 seam 添加了一个公开的实时进度方法和事件，因此实现方必须精确维护 active/terminal 边界，并在观察者看到快照之前将其分离。pre-start 捕获器可能短暂观察到无关的工作流 run，因此它仅按 run id 持有紧凑的候选状态，并在 `start()` 返回后立即丢弃所有不匹配的候选。一个工作流可能发出大量进度变更；有界归约器避免了 transcript 增长，但在关联完成后仍会为每个有意义的事件发送一条 UI 更新。如果经测量的客户端需要合并更新，这必须是一个带默认值的、经过校验的桥接配置，而非硬编码的节流。瞬态进度在回放时有意消失，因此最终工具结果仍是唯一持久的工作流卡片内容。
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
new file mode 100644
index 0000000000..8f00d8b537
--- /dev/null
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-api-extractor-reports.md: f110bfe3353e65442f218336aca3e9d492ac2341
+2026-06-11-api-extractor-reports.zh.md: 8cb7353e10a8811b20ccd539de15f8e06b76e6ae
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 b32dc7e2af..f110bfe335 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
@@ -2,6 +2,8 @@
 
 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](../../implemented/process/2026-06-11-doc-sync-enforcement.md). This is the deferred part 3, kept 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
new file mode 100644
index 0000000000..8cb7353e10
--- /dev/null
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: API extractor 报告
+
+Status: proposed
+
+[English](2026-06-11-api-extractor-reports.md) | 中文
+
+> 从最初的「doc-sync（文档同步门禁）与 API 报告」Agent Note（agent 决策记录）中拆出（首次提出于 2026-06-11）。第 1 至第 2 部分（文档块类型检查、事件分类体系校验）已交付，见 [doc-sync 强制](../../implemented/process/2026-06-11-doc-sync-enforcement.md)。本文是被推迟的第 3 部分，作为独立提案保留。
+
+## 问题
+
+公开 API 的变更是不可见的：没有任何机制将「此次提交改变了公开接口」变为一个显式、可评审的事实。评审者阅读 diff 时可能遗漏某个导出类型新增了字段，或某个方法签名发生了变化。
+
+## 提案
+
+使用 api-extractor（或 `tsc --emitDeclarationOnly` 加一份规范化的公开接口导出）为每个包（package）生成一份签入仓库的 `etc/<pkg>.api.md`；CI 在重新生成结果与已签入报告不一致时失败。这样，每一次公开 API 变更都会成为评审者（或评审 agent（智能体））必须看到的一行 diff。
+
+## 曾考虑的替代方案
+
+**`tsc --emitDeclarationOnly` 加规范化的公开接口导出**：如果 api-extractor 过于笨重，这是更轻量的机制；两者都能满足提案所需的「签入仓库、可 diff」的报告形态。
+
+## 验收标准
+
+- 每个包都有一份签入仓库的 `etc/<pkg>.api.md`；CI 在重新生成结果与已提交报告不一致时失败。
+- 公开 API 变更（新增导出、字段放宽、签名变化）在评审中以报告 diff 行的形式可见。
+
+## 风险
+
+该依赖笨重且难以调教（这正是它被推迟的原因），且报告格式会随编译器升级而变动，增加一个维护面；在各包尚未发布的阶段，收益有限。
+
+## 推迟原因
+
+在 doc-sync 落地时被推迟：对于一个内部 monorepo，评审者已经能看到源码 diff，价值不高；且依赖笨重、难以调教。如果各包将来对外发布，再重新评估——届时一份稳定、可 diff 的公开接口报告才值得其维护成本。
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
new file mode 100644
index 0000000000..624b671a37
--- /dev/null
+++ b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-architectural-conformance.md: f7cb0d7397d4e03df225f68417da43b1fec8de62
+2026-06-11-architectural-conformance.zh.md: aa25ef6d2772642885ef268bd548fc6dad40d3cf
diff --git a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.md b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.md
index 006aa76ad1..f7cb0d7397 100644
--- a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.md
+++ b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.md
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-06-11-architectural-conformance.zh.md)
+
 ## Problem
 
 Two architectural guarantees currently live only in prose: (1) nothing depends on the concrete loop package ([the microkernel promise](../../implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)), and (2) every LlmAdapter speaks the chunk protocol correctly. Both should be mechanical ([the quality-gates principle](../../implemented/process/2026-06-11-quality-gates.md)).
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
new file mode 100644
index 0000000000..aa25ef6d27
--- /dev/null
+++ b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 架构一致性——依赖规则与适配器套件
+
+Status: proposed
+
+[English](2026-06-11-architectural-conformance.md) | 中文
+
+## 问题
+
+目前有两项架构保证仅存在于行文中：（1）没有任何组件依赖具体的 loop 包（package）（[微内核承诺](../../implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)）；（2）每个 LlmAdapter 都正确遵循分片协议。二者都应由机制强制执行（[质量门禁原则](../../implemented/process/2026-06-11-quality-gates.md)）。
+
+## 提案
+
+**dependency-cruiser** 配合以下规则：
+
+- `packages/*`（除 agent-loop（智能体循环）自身的 tests 和 examples/ 外）禁止导入 `@deepseek-ai/dsh-agent-loop`。
+- 禁止跨包深层导入（`@deepseek-ai/dsh-*/src/...` 路径）——只允许使用公开入口点。
+- packages/ 内禁止导入循环。
+- `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) 配对）。
+
+## 计划
+
+先落地 dependency-cruiser 配置与 CI 步骤（约一小时工作量，换来永久保证）；一致性套件随其首个消费方测试（针对 MockAdapter）一起落地，并作为 V4 适配器阶段的前置条件。
+
+## 验收标准
+
+- dependency-cruiser 在 CI 中运行上述规则族；违规导入导致构建失败。
+- 一致性套件对 mock 适配器和两个正式适配器运行，新适配器包通过调用该套件并传入自己的工厂即可继承测试。
+
+## 风险
+
+随着包的增加，dep-cruiser 规则需要维护——规则应基于模式（`dsh-*`）而非逐一枚举。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.i18n.yaml b/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.i18n.yaml
new file mode 100644
index 0000000000..bf98665195
--- /dev/null
+++ b/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-supply-chain-and-vendor-drift.md: a27ae64556dc7366279824f1480e5681b1e86bf1
+2026-06-11-supply-chain-and-vendor-drift.zh.md: 25c27650709faf1a462ce9779ee6f0a909746311
diff --git a/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.md b/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.md
index a79f719751..a27ae64556 100644
--- a/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.md
+++ b/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.md
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-06-11-supply-chain-and-vendor-drift.zh.md)
+
 ## Problem
 
 The vendor manifest ([the vendoring decision](../../implemented/process/2026-06-11-vendor-cordis-as-source.md)) is enforced at commit time in the *forward* direction (vendored change ⇒ manifest update) but nothing verifies the manifest's *claims*: that vendor/ actually equals upstream-at-SHA plus exactly the logged modifications. And the handful of true npm dependencies have no advisory monitoring or update cadence.
diff --git a/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.zh.md b/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.zh.md
new file mode 100644
index 0000000000..25c2765070
--- /dev/null
+++ b/.agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 供应链检查与 vendor 漂移验证
+
+Status: proposed
+
+[English](2026-06-11-supply-chain-and-vendor-drift.md) | 中文
+
+## 问题
+
+vendor manifest（元数据清单）（见[引入 vendor 的决策](../../implemented/process/2026-06-11-vendor-cordis-as-source.md)）在提交时仅在*正向*强制执行（vendor 变更 ⇒ manifest 更新），但没有任何机制验证 manifest 的*声明*：即 vendor/ 确实等于上游指定 SHA 的内容加上所记录的修改。此外，少量真正的 npm 依赖也没有安全公告监控或更新节奏。
+
+## 提案
+
+1. **Vendor 漂移检查**（夜间 CI）：以 manifest 中记录的 SHA 浅克隆上游仓库，复制对应的包（package）源码，与 `vendor/*/src` 做 diff。除非 diff 与已记录的本地修改一致（每项修改以签入的 patch 文件保存——日志条目从行文描述变为可验证的产物），否则任务失败。
+2. **依赖安全公告**：对 lockfile 运行 osv-scanner（或 `pnpm audit`），按计划定期执行，并在涉及 lockfile 变更的 PR（Pull Request）上触发。
+3. **许可证清单**：一个脚本断言每个 vendor 包都携带其 LICENSE 文件，且 package.json 的 `license` 字段与 vendor/README.md 中的清单一致（我们混合了 vendor 的 MIT 与自有的 BSD-3）——作为 CI 步骤运行。
+4. **Renovate**（或定时 agent（智能体）任务）以小 PR 的形式提议 npm 依赖更新，这些 PR 走完整门禁套件；vendor 包不在其列（它们的更新遵循 manifest 同步流程，理想情况下是半自动化的 agent 工作流：拉取上游、重新应用 patch、运行门禁、以更新后的 manifest 表格开 PR）。
+
+## 计划
+
+第 3 项最简单，先做。第 1 项需要 CI 能通过网络访问上游仓库（私有仓库，需要 token），并将现有两项已记录的修改转换为 patch 文件。第 2 项和第 4 项是配置工作。
+
+## 曾考虑的替代方案
+
+- **用 `pnpm audit` 替代 osv-scanner**：两者都满足安全公告扫描的需求；具体选择推迟到实现阶段决定。
+- **用定时 agent 任务替代 Renovate**：在提议小型更新 PR 并走完整门禁套件方面效果等价；vendor 包无论哪种方案都不在其列（它们的更新遵循 manifest 同步流程）。
+
+## 验收标准
+
+- 许可证清单脚本在 CI 中运行，缺少 LICENSE 或 `license` 字段与 `vendor/README.md` 中的清单矛盾时失败。
+- 夜间漂移任务从 manifest SHA 加签入的 patch 文件重建 `vendor/`，出现任何无法解释的 diff 时失败。
+- 安全公告扫描按计划定期运行，并在涉及 lockfile 变更的 PR 上运行。
+
+## 风险
+
+上游仓库是私有镜像；CI 凭证与可用性是漂移检查的主要阻力。如果受阻，可改为本地定时 agent 任务而非 CI。
diff --git a/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.i18n.yaml b/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.i18n.yaml
new file mode 100644
index 0000000000..bf44db6bee
--- /dev/null
+++ b/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-discover-package-inventory.md: 50e42686cea48985dedc7fa290e06bc959ecc5d4
+2026-06-20-discover-package-inventory.zh.md: dc79162dd3ec5ba2bf3225fc8e9d44c552a514cb
diff --git a/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.md b/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.md
index f9286aeefd..50e42686ce 100644
--- a/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.md
+++ b/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.md
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-06-20-discover-package-inventory.zh.md)
+
 ## Problem
 
 Package and gate inventories are repeated across TypeScript project references, package docs, CI prose, and Knip overrides. Most restate package layout, manifest data, or aggregate command contents. Each new package therefore creates avoidable synchronization points.
diff --git a/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.zh.md b/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.zh.md
new file mode 100644
index 0000000000..dc79162dd3
--- /dev/null
+++ b/.agents/notes/proposed/process/2026-06-20-discover-package-inventory.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 通过发现机制获取包清单，而非维护静态列表
+
+Status: proposed
+
+[English](2026-06-20-discover-package-inventory.md) | 中文
+
+## 问题
+
+包（package）与门禁清单在 TypeScript project references、包文档、CI 描述和 Knip 覆盖项中反复出现。大多数只是重述包布局、manifest（元数据清单）数据或聚合命令内容。因此每新增一个包都会产生本可避免的同步点。
+
+[包层级结构](../../implemented/architecture/2026-06-20-package-hierarchy.md)已经手动消除了其中若干：`scripts/publint-all.ts` 现在从 `packages/<group>/<pkg>` 布局推导列表，两份 `tsconfig` 的 `paths` 映射也合并为一个 `@deepseek-ai/dsh-*` 通配符。剩下的是无法用 glob 消除的清单，主要是聚合配置（`tsconfig.host.json`、`tsconfig.client.json`）的 project `references`——TypeScript 要求它们是显式数组（没有通配符形式）。
+
+当静态列表编码的是策略时，它们是合理的；当它们只是重复 `package.json`、workspace glob 或包层级结构中已有的 manifest 数据或布局事实时，就是不必要的摩擦。
+
+## 提案
+
+让剩余的包与门禁清单可被发现。一个唯一的权威来源，即 `packages/<group>/<pkg>` 层级结构加上包 manifest，应当驱动聚合配置的 `references`、模块图以及任何全量包列表，并配合一个生成加校验步骤（沿用现有的 `gen-module-graph` / `gen-cordis-catalog` 模式：生成器写出产物，`--check` 模式在 `hygiene` / `doc-sync`（文档同步门禁）中发现已提交副本陈旧时失败）。模块图生成已经在读取包 manifest。`doc-sync` 应当成为定义并打印其子门禁的唯一命令，文档链接到该命令，而非重述第二份列表。
+
+层级结构不需要编码关于包的所有事实，但应当编码宽泛的维护策略：core/product 包、集成包、能力 seam 包与 support/test/example 包不应在脚本能区分它们之前先要求一份手工维护的例外列表。
+
+有一项已编目的内容根本不需要生成器：将 e2e 入口 glob 折入 Knip 的默认配置段，即可直接删除逐包的重复声明。
+
+## 验收标准
+
+- 聚合配置的 project `references` 由层级结构生成（生成器输出它们；`--check` 门禁在提交副本陈旧时报错），而非手工维护。
+- 新增一个包时，不需要为任何门禁编辑静态包列表。
+- 文档描述真源，而非重复生成的清单。
+- CI 调用聚合命令，由这些命令自行管理其子门禁列表。
+- `knip.json` 仅在编码真实信息（额外入口文件、被忽略的依赖）时才携带逐包覆盖项，绝不重述默认配置段。
+
+## 风险
+
+发现脚本可能变得过于精巧。实现应当保持朴素：读取 manifest、按显式字段过滤、打印解析后的列表，并在出错时明确失败。收益在于消除手工清单的漂移，而非发明一套构建系统。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..024adc68d9
--- /dev/null
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-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
+2026-07-04-prune-dead-core-spine-surface.md: 432aaa848540fe7d1db3039399345a02afed5bd3
+2026-07-04-prune-dead-core-spine-surface.zh.md: 2c7cc4c0dc234afc107bdfc715cf717e5ad8c55c
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 1f52bfac25..432aaa8485 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
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-07-04-prune-dead-core-spine-surface.zh.md)
+
 ## Problem
 
 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.
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
new file mode 100644
index 0000000000..2c7cc4c0dc
--- /dev/null
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
@@ -0,0 +1,63 @@
+# Agent Note: 裁剪无用的公开与结果接口
+
+Status: proposed
+
+[English](2026-07-04-prune-dead-core-spine-surface.md) | 中文
+
+## 问题
+
+若干包（package）根导出、结果字段和便利方法没有生产消费方。它们之所以存活，要么是因为测试通过公开入口导入了内部实现，要么是因为某个类型预期了一个从未出现的调用者。每一项单独看都很小，但合在一起，它们扩大了 SDK 契约、生成的 catalog、文档和回归矩阵，却没有支撑任何已交付的路径。
+
+生产语料库是 `packages/*/*/src`、示例源码/配置和运行时脚本。测试、包 README 和 Agent Note（agent 决策记录）行文是发布的证据，但不是固定调用者。`cordis_inspect` 使 `packages/cordis/tool-cordis/src/api-catalog.ts` 对模型可见，`cordis_mount` 可以通过受保护的真实服务代理调用注入的服务，因此 catalog 中的服务方法和返回形状是真正的动态产品接口。下表因此区分「没有固定的仓库调用者」与「不可达」：涉及 catalog 词汇的行有意收缩模型编写的 mount 能发现和调用的内容，而包根实现辅助函数并不通过该服务门面可达。精确符号搜索得出以下清单：
+
+| 接口 | 生产证据 | 简化方式 |
+| --- | --- | --- |
+| `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 词汇改为源码私有。 |
+| ACP 的 translation/presenter 根导出 | `agentOptions`、`streamSessionEventUpdate`、`todosToPlan`、`ToolPresenter`、`nullToolPresenter` 和 `TerminalRendering` 只有同文件或 ACP 测试消费方；唯一的包外生产消费方挂载的是插件命名空间。 | 保留 `name`、`inject`、`Config`、`AcpConfig` 和 `apply`；将 translation/presentation 辅助函数改为源码私有，在包内测试。 |
+| `providerWording` 与 `completedTurnPrefix` 根导出 | 各有一个同包生产调用者；只有 balanced-prefix 辅助函数有一个同包白盒测试。 | 改为源码私有，测试提供方行为。 |
+| `depthOf`、`SubagentDepthError`、`SENSITIVE_ENV_PATTERN`、`waitForExit` 与 `exitsWithin` 根导出 | 生产 subagent 后端消费的是进程内 runner 和子进程构造/dispose（资源释放）辅助函数，而非这些强制/测试内部实现。 | 保留深度/环境/退出行为，但将辅助函数和 error/regex 改为源码私有；通过 spawn 和 dispose 测试。 |
+| `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` 为唯一真源。 |
+| `CompactionResult.startSeq`、`summarySeq`、`endSeq` 与 `summary` | 生产消费方只读取 shadowed range/seq/token 统计；持久日志拥有 summary 和事件标识。 | 移除四个结果回显，保留两个共享的 transcript（文本记录）渲染器。 |
+| `BasicCompactService` 的 estimation/summarization 可见性 | 没有包外生产调用者调用这五个方法；已实现的 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` | 每个存储的公开值都没有生产读取者。 | 移除未读字段，保留错误消息、已解析的配置行为和任务生命周期。 |
+| 后端包根实现辅助函数 | 下方精确清单仅通过相对路径的同包导入调用。生产命名空间导入挂载的是保留的插件契约，不读取这些属性；命名根消费方都是测试。 | 保留每个适配器/提供方/服务及其配置/错误契约；停止在包根导出所列辅助函数/常量。 |
+| 消费方包根实现辅助函数 | 下方精确清单只有同包生产调用者。生产命名空间导入挂载的是插件契约，不读取辅助属性；命名根消费方都是测试。 | 保留插件契约和稳定的错误码；将测试迁移到包内模块或公开行为，停止在包根导出所列辅助函数。 |
+
+### 分组辅助导出清单
+
+- `dsh-llm-deepseek`：`httpErrorCode`、`serializeMessages`、`serializeRequest`、`DONE`、`parseSse`、`mapFinishReason`、`mapUsage` 与 `translate`；`dsh-llm-pi-ai`：`buildModel`、`mapStopReason`、`mapUsage`、`toPiContext` 与 `toStreamChunks`。
+- `dsh-bash-local`：`DEFAULT_GRACE_MS`、`ENV_OVERRIDES`、`killGroup`、`OutputCollector` 与 `runBash`；`dsh-bash-sandbox`：`shellQuote`、`classifyDenial` 与 `classifyRunnerFailure`；`dsh-sandbox-local`：`bwrapProfileArgs`、`landlockProfileArgs` 与 `seatbeltProfileArgs`。公开的可变测试注入字段及其类型不在本提案范围内。
+- `dsh-fs-local`：`applyLiteralEdit`、`listDirectory`、`probe`、`readForEdit`、`readTextForDiff`、`readWholeText`、`resolveLocalTarget`、`restoreLineEndings`、`streamWholeText` 与 `writeFileAtomic`。
+- `dsh-web-fetch-local`：`classifyContentType`、`decoderForCharset`、`isSameOrigin`、`parseCharset` 与 `validateFetchUrl`；`dsh-web-search-exa`：`mapExaResponse` 与 `mapExaResult`；`dsh-web-search-deepseek`：`citationSnippets` 与 `mapAnthropicResponse`；`dsh-web-search-perplexity`：`mapPerplexityResponse` 与 `mapPerplexityResult`。
+- `dsh-tool-fs`：`READ_LIMIT`、`STREAM_MIN_SIZE`、`READ_MAX_BYTES`、`READ_MAX_LINE_LENGTH`、`DIFF_CONTEXT`、`applyReadTool`、`parseReadArgs`、`applyWriteTool`、`formatWriteOutput`、`parseWriteArgs`、`applyEditTool`、`formatEditOutput`、`parseEditArgs`、`buildWindow`、`formatReadOutput`、`computeHunkDiffs` 与 `diffsFromMeta`。
+- `dsh-tool-web`：`WEB_SEARCH_MAX_RESULTS`、`applyWebSearchTool`、`formatSearchOutput`、`parseSearchArgs`、`presentSearchCall`、`applyWebFetchTool`、`formatFetchOutput`、`parseFetchArgs`、`presentFetchCall`、`renderBody` 与 `htmlToMarkdown`；`dsh-timeout-policy`：`toolTimeoutResult`；`dsh-compact-basic`：`resolveConfig`；`dsh-tool-bash`：`renderResult`。
+
+## 提案
+
+以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开 seam 验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳契约。
+
+## 曾考虑的替代方案
+
+**保留测试便利函数和自包含的结果字段为公开。** 公开辅助函数可以让白盒测试更方便，自包含的结果字段看起来更易用，未来的嵌入者可能需要具体循环类或枚举方法。这些好处是假设性的；当前它们让每处实现和文档都要解释没有已交付调用者能观察到的状态。真正的消费方可以引入它所需的最小契约，其所有权和失败语义明确。
+
+**保留所有 catalog 成员以供模型编写的 mount 使用。** 自引用工具集是一条真实的通用消费路径，而非生成文档的噪音。然而，它的价值来自准确、可组合的服务接口，而非无限期保留重复字段或不一致的参数对；上述每一项 catalog 收缩都移除了在同一次执行、同一个 agent（智能体）或同一结果中其他位置已可获得的事实，并在同一变更中更新 API 参考。
+
+## 验收标准
+
+- 精确符号搜索显示：在本 Agent Note 及任何已实现 Agent Note 修正之外，没有被移除的接口。
+- 本 Agent Note 列出的每个接口均按指定方式缺失或降级；清单之外有意保留的扩展/测试契约不变。
+- 工具执行、上下文压缩（context compaction）、两个 LLM 适配器、两个持久化后端、工作流隔离以及 agent 创建/恢复保持其已交付行为。
+- 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建和 hygiene 通过。
+
+## 风险
+
+大多数移除在编译时可见但对运行时无影响。上下文压缩参数清理有意禁止会话/上下文不匹配，同时保留手动 region seam。外部预发布嵌入者和现有模型编写的 mount 可能导入更少的辅助函数、传递更少的参数或接收更窄的结果形状；这是有意的产品接口收缩，而非仅仅是生成 catalog 的清理。仓库尚未发布，因此承载不受支持的接口才是更大的基础成本。
diff --git a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.i18n.yaml b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.i18n.yaml
new file mode 100644
index 0000000000..8ca0473ebe
--- /dev/null
+++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-deterministic-and-stress-testing.md: d9977be835af05f9ee303b63ec6015bc9e153170
+2026-06-11-deterministic-and-stress-testing.zh.md: eff9eecb699344dff388bafec270f6b6677f71ee
diff --git a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md
index c3b17c401a..d9977be835 100644
--- a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md
+++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-06-11-deterministic-and-stress-testing.zh.md)
+
 ## Problem
 
 Several loop tests synchronize with `setTimeout(30)` sleeps — flakiness debt that wastes agent cycles on retries and can mask ordering bugs. Separately, our core architectural promise (any session log replays to identical derived history) is asserted in two tests but is cheap to assert *everywhere*. And the inbox wakeup race was verified by hand exactly once; nothing re-verifies it continuously.
diff --git a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md
new file mode 100644
index 0000000000..eff9eecb69
--- /dev/null
+++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 确定性测试、回放不变式 fixture（测试前置数据）与竞态压力测试
+
+Status: proposed
+
+[English](2026-06-11-deterministic-and-stress-testing.md) | 中文
+
+## 问题
+
+若干 agent loop（智能体循环）测试通过 `setTimeout(30)` 睡眠来同步——这是一笔不稳定性债务，浪费 agent 的重试周期，还可能掩盖时序 bug。另外，我们的核心架构承诺（任何会话日志回放后都能得到相同的派生历史）目前只在两个测试中断言，但在*所有*测试中断言的成本极低。此外，inbox 唤醒竞态只被手动验证过一次，没有任何机制持续复验。
+
+## 提案
+
+三项措施：
+
+1. **测试中禁止挂钟睡眠。** 将 `setTimeout(N)` 等待替换为事件驱动等待（既有的 `waitForIdle` 模式，扩展为 `waitForStatus`、`waitForEvent(n)`），或在需要测试时间本身时使用 vitest 的 fake timer。通过 lint 规则禁止 `setTimeout`，适用范围是 `packages/*/tests`，白名单辅助模块除外。
+2. **通用回放 fixture。** 一个共享测试辅助函数包装 agent loop harness，使每个测试结束后，agent 的会话日志被回放到一个全新的 Session 中，并自动断言 `deriveMessages()` 相等。这样该不变式在每次 CI 运行中会被套件产生的所有场景检查数百次，而非仅两次。
+3. **夜间竞态压力测试。** 一个 CI job 以 `vitest --repeat=200`（加 `--shuffle`）运行 agent-loop 和 inbox 套件，以暴露调度依赖的失败；发现的任何不稳定测试都视为 bug 修复，绝不靠重试掩盖。
+
+## 计划
+
+措施 1 和 2 一起落地（它们改动相同的辅助模块）；在套件消除所有睡眠后再添加夜间 job，以确保重复运行速度快。
+
+## 验收标准
+
+- 不再使用 `setTimeout`；lint 规则在 `packages/*/tests` 中强制执行，白名单辅助模块除外。
+- 共享 harness 将每个测试的会话日志回放到全新的 `Session` 中，并自动断言 `deriveMessages()` 相等，覆盖整个套件。
+- 夜间 job 以 `--repeat` 和 `--shuffle` 运行 agent-loop 和 inbox 套件；发现的不稳定测试作为 bug 分诊，绝不靠重试掩盖。
+
+## 风险
+
+Fake timer 与 agent loop 中的 Promise 调度存在微妙交互——优先使用事件驱动等待；仅在测试 timer 服务行为本身时才使用 fake timer。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/proposed/testing/2026-06-11-mutation-testing.i18n.yaml b/.agents/notes/proposed/testing/2026-06-11-mutation-testing.i18n.yaml
new file mode 100644
index 0000000000..d593656c04
--- /dev/null
+++ b/.agents/notes/proposed/testing/2026-06-11-mutation-testing.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-mutation-testing.md: 591d9012644a19ee2c67a916b63092d79f78db1f
+2026-06-11-mutation-testing.zh.md: 9c22ed2f42e5c44e6be98f132614886bbdb188fd
diff --git a/.agents/notes/proposed/testing/2026-06-11-mutation-testing.md b/.agents/notes/proposed/testing/2026-06-11-mutation-testing.md
index 35df228b85..591d901264 100644
--- a/.agents/notes/proposed/testing/2026-06-11-mutation-testing.md
+++ b/.agents/notes/proposed/testing/2026-06-11-mutation-testing.md
@@ -2,6 +2,8 @@
 
 Status: proposed
 
+English | [中文](2026-06-11-mutation-testing.zh.md)
+
 ## Problem
 
 The per-file 100% coverage gate ([the quality-gates decision](../../implemented/process/2026-06-11-quality-gates.md)) proves every line *executes* under test — not that any assertion would notice if the line were wrong. Under agent-written tests, coverage pressure can produce execution-without-assertion. Mutation testing measures what coverage cannot: whether the suite *kills* deliberately injected bugs.
diff --git a/.agents/notes/proposed/testing/2026-06-11-mutation-testing.zh.md b/.agents/notes/proposed/testing/2026-06-11-mutation-testing.zh.md
new file mode 100644
index 0000000000..9c22ed2f42
--- /dev/null
+++ b/.agents/notes/proposed/testing/2026-06-11-mutation-testing.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 变异测试作为覆盖率的制衡手段
+
+Status: proposed
+
+[English](2026-06-11-mutation-testing.md) | 中文
+
+## 问题
+
+逐文件 100% 覆盖率门禁（[质量门禁决策](../../implemented/process/2026-06-11-quality-gates.md)）证明每一行代码在测试中都被*执行*了，但不能证明如果该行出错，任何断言会注意到。在 agent（智能体）编写测试的场景下，覆盖率压力可能产出「执行但不断言」的测试。变异测试衡量的正是覆盖率无法衡量的：测试套件是否能*杀死*被刻意注入的缺陷。
+
+## 提案
+
+使用 Stryker（`@stryker-mutator/vitest-runner`）对 `packages/*/src` 运行变异测试：
+
+- **PR（Pull Request）范围的增量运行**（仅变更文件），作为一个 CI job。调优后速度足以作为合并门禁。
+- **每夜全量运行**，跟踪变异分数；先记录基线，再将阈值设为观测到的基线并只升不降（与覆盖率策略一致：阈值只收紧）。
+- 存活的变异体是待办项：agent 选取一个存活体、编写杀死它的测试、循环往复——一个形态良好的自主循环。
+- 等价变异体（可证明不改变行为的）加注释排除并附理由，与 `/* v8 ignore */` 策略一致。
+
+## 计划
+
+1. 添加 Stryker 配置，范围限定在一个包（package），即 llm（最小、最具算法性），并测量运行时间。
+2. 扩展到所有包；在配置中记录基线分数。
+3. 接入每夜 job；运行时间可接受后再添加 PR 范围的增量 job。
+
+## 验收标准
+
+- Stryker 配置在 `packages/*/src` 上以 vitest runner 运行；每夜 job 记录变异分数，当分数低于记录的基线时，通过只升不降的阈值使运行失败。
+- PR 范围的增量运行在运行时间可接受后作为合并门禁；或者明确保持仅每夜运行，并将该结论记录于此。
+- 等价变异体带有注释排除及理由，与 `/* v8 ignore */` 策略一致。
+
+## 风险
+
+运行时间：变异测试开销大；逐文件 100% 覆盖率有所帮助（每个变异体至少会被执行到）。如果 PR 范围的运行始终过慢，则保持仅每夜运行，依赖分数只升不降的机制。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.i18n.yaml b/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.i18n.yaml
new file mode 100644
index 0000000000..6201a380e7
--- /dev/null
+++ b/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-11-immutable-public-surfaces.md: c9009ad923720efaecb25e2017ceab6e3eb0dbf4
+2026-06-11-immutable-public-surfaces.zh.md: 4ef67734d712e538c5858fbc05efbc6dd983c704
diff --git a/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.md b/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.md
index 0c6652a94d..c9009ad923 100644
--- a/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.md
+++ b/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.md
@@ -2,6 +2,8 @@
 
 Status: rejected — the pervasive `DeepReadonly<T>` type flip is replaced by source-owned runtime immutability in `Session` plus relational development assertions. See [source-owned session immutability and dev-mode invariants](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
 
+English | [中文](2026-06-11-immutable-public-surfaces.zh.md)
+
 ## Problem
 
 The rejected proposal targeted an ownership hole that a `readonly SessionEvent[]` type alone cannot close: its elements remain mutable at runtime, so a cast or plain JavaScript can rewrite nested history. The implemented design closes that hole in `Session` by materializing and deep-freezing every accepted event and returning frozen array snapshots. In-flight prompt waterfalls remain intentionally transformable, so immutability is an ownership boundary rather than a blanket type rule.
diff --git a/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.zh.md b/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.zh.md
new file mode 100644
index 0000000000..4ef67734d7
--- /dev/null
+++ b/.agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 深度只读的公开接口
+
+Status: rejected — 普遍采用 `DeepReadonly<T>` 的类型翻转已由 `Session` 中归属源的运行时不可变性与关系型开发断言取代。见[归属源的会话不可变性与开发模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md)。
+
+[English](2026-06-11-immutable-public-surfaces.md) | 中文
+
+## 问题
+
+被否决的提案针对的是一个所有权漏洞：仅靠 `readonly SessionEvent[]` 类型无法封堵该漏洞，因为其元素在运行时仍然可变，类型强制转换或纯 JavaScript 代码可以改写嵌套的历史记录。已实现的设计在 `Session` 中封堵了这一漏洞：对每个被接受的事件进行物化并深度冻结，返回冻结的数组快照。进行中的提示词 waterfall（瀑布式事件）有意保持可变换，因此不可变性是一条所有权边界，而非一条全局类型规则。
+
+## 提案
+
+> **实际采用了不同的实现方式——见 Status 行与[源拥有的会话不可变性与开发模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md)。** 下文的 `DeepReadonly<T>` 设计已被否决：它仅在编译期生效、对消费方噪音大、且可被强制转换绕过。`Session` 改为在每次组合中对已接受的事件和公开日志快照进行快照与深度冻结；`deriveMessages()` 返回分离的冻结投影；开发插件检查跨记录与跨 seam 的关系。
+
+在类型层面为「突变即损坏」的场景引入不可变性：
+
+- `SessionEvent` 数据在从会话输出时（`events`、`session/event` 监听器）变为 `DeepReadonly`；`append()` 仍接受普通可变输入。一个 `DeepReadonly<T>` 工具类型放在 dsh-llm 中，与 brand/never 辅助类型相邻。
+- `deriveMessages()` 返回深度只读的消息；agent loop（智能体循环）在将可变请求交给 `agent/request` waterfall 之前先克隆（该处的突变是被允许的——克隆使边界显式且代价低廉，每个步骤仅一次）。
+- `PromptAssembly` 在其 waterfall 流经期间保持可变（被允许），但注册表内部的 section 列表在每次组装时被克隆（已有此行为）。
+
+## 计划
+
+引入 `DeepReadonly`，翻转会话的读取路径，并修复消费方中由此产生的编译错误。
+
+## 风险
+
+`DeepReadonly` 类型在 waterfall 边界处（突变本身就是 API 的地方）可能产生噪音较大的错误。应将可变/只读边界精确地划在「已记录 vs 进行中」，并在会话 README 中加以说明。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.i18n.yaml b/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.i18n.yaml
new file mode 100644
index 0000000000..6a1baa8a80
--- /dev/null
+++ b/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-providerless-example-base.md: 2f41476a487775e6f9da2f113efe566e44786ff3
+2026-06-20-providerless-example-base.zh.md: e767d6b3a35dcfd52194f8a59edc496b86414b6e
diff --git a/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.md b/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.md
index 81dbe40ee4..2f41476a48 100644
--- a/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.md
+++ b/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.md
@@ -2,6 +2,8 @@
 
 Status: rejected — superseded by [Extract example apps into packages](../../implemented/architecture/2026-06-20-extract-example-app-packages.md), which moves the spine into a `dsh-agent-spine-demo` bundle and deletes the `base*.yml` files, so there is no shared base YAML left to rename.
 
+English | [中文](2026-06-20-providerless-example-base.zh.md)
+
 ## Problem
 
 The examples had two shared base files: `examples/base-core.yml` was providerless, while `examples/base.yml` included that core plus the real `llm-deepseek` adapter. Snapshot replay needs the providerless core with `llm-replay`, because loading the real adapter without a key throws. The normal demos need the real adapter. The result was a naming inversion: the file named `base.yml` was not the reusable base for all examples, while the true base was `base-core.yml`.
diff --git a/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.zh.md b/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.zh.md
new file mode 100644
index 0000000000..e767d6b3a3
--- /dev/null
+++ b/.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 使共享示例基础配置与提供方无关
+
+Status: rejected — 已由[将示例应用提取到 packages 中](../../implemented/architecture/2026-06-20-extract-example-app-packages.md)取代；后者把主干移入 `dsh-agent-spine-demo` bundle 并删除 `base*.yml` 文件，因此已不存在可重命名的共享基础 YAML。
+
+[English](2026-06-20-providerless-example-base.md) | 中文
+
+## 问题
+
+示例曾有两个共享基础文件：`examples/base-core.yml` 与提供方无关，而 `examples/base.yml` 在该核心基础上加入了真实的 `llm-deepseek` 适配器。快照回放需要与提供方无关的核心配合 `llm-replay` 使用，因为在没有密钥的情况下加载真实适配器会抛出异常。常规演示则需要真实适配器。结果是命名与实际含义倒挂：名为 `base.yml` 的文件并非所有示例可复用的基础，而真正的基础反倒是 `base-core.yml`。
+
+这种拆分可以理解，但它让每次解释配置都变得更冗长。它还导致了别扭的测试搭建方式，例如无密钥冒烟测试不得不携带一个虚拟 API key，仅仅为了让适配器能启动——尽管模型根本不会被调用。
+
+## 提案
+
+将与提供方无关的核心重命名为 `examples/base.yml`，让适配器选择在每个具体示例中显式声明。编码和 ACP（Agent Client Protocol）真实配置添加一小段 `llm-deepseek` include 或本地块；快照配置添加 `llm-replay`。删除 `examples/base-core.yml`。
+
+共享基础应仅包含提供方无关的服务与工具：`llm`、会话、系统提示词、工具、agent（智能体）、不变式、bash 执行器和 bash 工具 schema。任何涉及模型提供方选择的内容都应放在叶子配置中。
+
+## 验收标准
+
+- `examples/base.yml` 与提供方无关。
+- `examples/base-core.yml` 已删除。
+- 真实演示配置显式添加 DeepSeek 适配器。
+- 快照回放配置 include 同一个与提供方无关的基础，并加入其回放适配器。
+- [examples README](../../../../examples/README.md)、各示例 README 及 Agent Note（agent 决策记录）引用不再解释「base = base-core 加适配器」。
+
+## 放弃了什么
+
+真实演示失去了一层便利：每个演示都必须显式引入适配器。对于示例而言这是正确的默认行为，因为适配器选择是可变部分，而与提供方无关的接线才是共享的产品核心。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.i18n.yaml b/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.i18n.yaml
new file mode 100644
index 0000000000..449f33cbff
--- /dev/null
+++ b/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-generate-agent-note-index-tables.md: 6e5221f018942a0629f30b6e6f22cedfb9f4145e
+2026-07-04-generate-agent-note-index-tables.zh.md: f8ebcd51933b3ad91e0197fc71c0d8aae568bbcf
diff --git a/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.md b/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.md
index 90c942411d..6e5221f018 100644
--- a/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.md
+++ b/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.md
@@ -2,6 +2,8 @@
 
 Status: rejected — a centralized generated list is merge-prone and adds little discovery value
 
+English | [中文](2026-07-04-generate-agent-note-index-tables.zh.md)
+
 ## Problem
 
 Per-lifecycle/per-class tables would list facts that are fully derivable: an Agent Note's path encodes lifecycle and class, its filename encodes the first-proposed date, and its H1 carries the title. A hand-maintained copy of those facts would also be a high-contention docs hotspot because concurrent Agent Note branches append rows to the same few lines. [The classification Agent Note](../../implemented/process/2026-06-20-agent-note-classification.md) makes the tree itself authoritative.
diff --git a/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.zh.md b/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.zh.md
new file mode 100644
index 0000000000..f8ebcd5193
--- /dev/null
+++ b/.agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.zh.md
@@ -0,0 +1,38 @@
+# Agent Note: 生成 Agent Note 索引表
+
+Status: rejected — 集中生成的列表容易产生合并冲突，且几乎不增加发现价值
+
+[English](2026-07-04-generate-agent-note-index-tables.md) | 中文
+
+## 问题
+
+按生命周期和分类划分的表格只会列出完全可推导的事实：Agent Note（agent 决策记录）的路径编码其生命周期和分类，文件名编码首次提出日期，H1 承载标题。手工维护这些事实的副本还会成为高冲突文档热点，因为并发的 Agent Note 分支会向相同的几行追加条目。[分类 Agent Note](../../implemented/process/2026-06-20-agent-note-classification.md) 将目录树本身定为权威来源。
+
+## 提案
+
+保留策展文本，并将列表生成为完全生成的 `.agents/notes/INDEX.md`。共享的 `scripts/agent-note-index.ts` 模块将同时负责目录树遍历器和渲染器。两个轻量消费方会共用它：
+
+- `scripts/gen-agent-note-index.ts`（`pnpm run gen-agent-note-index`）将根据目录树完整重写 INDEX.md。
+- `scripts/verify-agent-note-classification.ts` 将检查结构，并断言已提交的 INDEX.md 与新鲜渲染结果逐字节一致。
+
+添加、移动或删除 Agent Note 时，只需编辑 Agent Note 文件并运行生成器。
+
+## 曾考虑的替代方案
+
+### 为什么不在 README.md 中使用标记分隔区域？
+
+README.md 中由标记分隔的表格会混合生成内容与策展文本，因而需要拼接机制并保护周围的契约。专用生成文件至少能将这些关注点分开。
+
+### 为什么不采用纯校验器模式？
+
+它能捕获错误，但每次提案编辑仍然要在手工维护的表格中触碰共享热点。作者已经命名并放置了文件，因此索引副本不增加任何信息。这与[包（package）清单提案](../../proposed/process/2026-06-20-discover-package-inventory.md)对 tsconfig 引用和 knip 配置段所做的手写列表与推导之间的判断相同。
+
+## 后果
+
+- 生成文件将是显式的，且不包含任何策展区域。
+- H1 格式错误或缺失将是硬错误，因为 H1 为每一行提供标题。
+- 即使可以通过重新运行生成器解决冲突，并发分支仍会修改同一个已提交产物。
+
+## 相关
+
+已落地的[不建立索引决策](../../implemented/process/2026-07-19-remove-generated-agent-note-index.md)保留目录树和仓库搜索作为发现机制。
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
new file mode 100644
index 0000000000..6685685e24
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-assembled-assistant-messages-only.md: ba8135a3d63f292cfedd23de8b4b9d43b4455e8c
+2026-06-20-assembled-assistant-messages-only.zh.md: 9a42a202425158edd85d7a3f2ef4b0b97e00da90
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 62dd7609e8..ba8135a3d6 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
@@ -2,6 +2,8 @@
 
 Status: rejected — high-fidelity chunk replay, partial failed streams, and snapshot replay currently depend on persisted `assistant/chunk` events. Dropping chunks is only viable with a no-information-loss replay/artifact replacement.
 
+English | [中文](2026-06-20-assembled-assistant-messages-only.zh.md)
+
 ## Problem
 
 The canonical session log currently persists every `assistant/chunk` exactly as streamed by the model. The [session persistence Agent Note](../../implemented/architecture/2026-06-14-session-persistence.md) chose this for token-level replay fidelity and contiguous `seq`, but the cost has grown: JSONL fixtures are dominated by tiny delta records, snapshot scenarios replay the model by grouping chunk events, ACP load reconstructs prior assistant output from chunks, and any future log reader must distinguish durable message history from token-level trace.
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
new file mode 100644
index 0000000000..9a42a20242
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 仅持久化组装后的 assistant 消息，不存储流式分片
+
+Status: rejected — 高保真分片回放、部分失败流与快照回放目前依赖持久化的 `assistant/chunk` 事件。只有具备不丢失信息的回放/产物替代方案后，才能删除分片。
+
+[English](2026-06-20-assembled-assistant-messages-only.md) | 中文
+
+## 问题
+
+当前的规范会话日志会持久化模型流式输出的每一个 `assistant/chunk`。[会话持久化 Agent Note（agent 决策记录）](../../implemented/architecture/2026-06-14-session-persistence.md)选择这一方案是为了 token 级别的回放保真度和连续的 `seq`，但其代价日益增长：JSONL fixture（测试前置数据）被大量微小的 delta 记录占据，快照场景通过对分片事件分组来回放模型，ACP（Agent Client Protocol）加载时从分片重建先前的 assistant 输出，而任何未来的日志读取方都必须区分持久的消息历史与 token 级别的追踪。
+
+对于成功组装出完整内容的步骤，agent loop（智能体循环）已经追加了一条 `assistant/message`。这正是 `deriveMessages()` 用来构造下一次模型请求的事件。换言之，正常的可恢复会话状态无需分片即已具备；分片是实时渲染和确定性测试的产物，不是必需的会话历史。失败或中止的流则不同：部分 assistant 输出可能仅以分片形式存在，而空的 max-token 步骤可能根本不产生 `assistant/message`。
+
+## 提案
+
+停止在规范会话日志中存储 `assistant/chunk`。持久日志保留 `assistant/message`、`tool/call`、`tool/result`、`usage`（如保留）以及轮次边界。实时 UI 仍可通过一个刻意设计为瞬态的流事件接收 token 增量。快照回放应将其模型脚本移入显式的 fixture 伴随文件，或从记录的适配器产物中派生，而非将规范的用户会话当作 token 磁带。需要部分失败流输出的场景必须在回放 fixture 中记录该输出。
+
+ACP `session/load` 可以将先前的 assistant 消息作为完整内容块回放，而非模拟原始的 token 流。加载后的 transcript（文本记录）无需重现每一个历史 delta；它必须展示相同的已完成 assistant 内容，并以有效的提供方历史恢复运行。
+
+## 验收标准
+
+- `SessionEventMap` 移除 `assistant/chunk`，或在需要过渡性实时事件时将其标记为非持久化。
+- [会话持久化文档](../../../../packages/session-persistence/session-persistence/README.md)不再要求逐字存储每个流式分片。
+- `llm-replay` 和 ACP 快照使用显式的回放 fixture 格式或伴随文件来存储模型分片。
+- `session/load` 从 `assistant/message` 渲染已完成的 assistant 消息。
+- 存储的日志大幅缩小，且在没有分片缺口的情况下保持 `seq` 连续。
+- 会话格式版本与已记录的 fixture 一并刷新；按预发布格式策略拒绝非当前版本的存储日志。
+
+## 放弃了什么
+
+规范的用户会话不再能重建旧轮次的精确 token 流。它也会丢失失败或中止流的部分 assistant 输出，除非另有事件或 fixture 记录。对于当前的恢复、加载和快照契约而言，这是过大的信息损失。需要精确确定性流的测试应当直接拥有该 fixture，前提是生产会话日志为用户可见的恢复保留了足够的保真度。
+
+## 相关
+
+本 Agent Note 取代 [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md) 中关于分片持久化的决策，并影响 [ACP 快照测试](../../implemented/testing/2026-06-19-acp-snapshot-tests.md)——其当前的回放插件从 `assistant/chunk` 事件派生脚本。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.i18n.yaml
new file mode 100644
index 0000000000..d06734c3ea
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-drop-acp-session-load.md: 2b6edf173506929f2d64e910b47aa70fb4f1d854
+2026-06-20-drop-acp-session-load.zh.md: 8e03acad17cf2831a15d5992a0419a73f275719d
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.md b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.md
index b8b9b29987..2b6edf1735 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.md
@@ -2,6 +2,8 @@
 
 Status: rejected — Zed is the current target ACP client, advertises and exercises load-capable sessions, and keeps pending-load state for concurrent `session/load`. The bridge should keep `session/load` and make the resume contract solid.
 
+English | [中文](2026-06-20-drop-acp-session-load.zh.md)
+
 ## Problem
 
 ACP advertises `loadSession: true` and implements `session/load` by injecting persistence into the bridge, validating cwd against stored metadata, reconstructing an agent from the persisted log, and replaying prior transcript updates to the client. That path has its own race handling, loading-id guard, replay presenter logic, and tests. It also depends on the canonical log retaining enough UI data to reconstruct old chunks and tool presentations.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.zh.md b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.zh.md
new file mode 100644
index 0000000000..8e03acad17
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 移除 ACP（Agent Client Protocol）session/load，直到恢复具备产品形态
+
+Status: rejected — Zed 是当前目标 ACP 客户端，它声明并实际使用支持加载的会话，还为并发的 `session/load` 保留待加载状态。桥接层应保留 `session/load` 并巩固恢复契约。
+
+[English](2026-06-20-drop-acp-session-load.md) | 中文
+
+## 问题
+
+ACP 声明 `loadSession: true` 并实现 `session/load`：向 bridge 注入持久化能力、校验 cwd 与存储元数据的一致性、从持久化日志重建 agent（智能体），并向客户端回放先前的 transcript（文本记录）更新。该路径有自己的竞态处理、loading-id 守卫、回放展示逻辑和测试。它还依赖规范日志保留足够的 UI 数据，以重建旧的分片和工具展示。
+
+持久化仍然是基础能力，但编辑器可见的恢复尚未经过产品流程设计。目前没有会话选择器、没有标题/预览元数据，也没有明确的加载失败或部分加载的用户体验。bridge 正在为一个仅被测试、文档和当前目标客户端的会话模型所使用的功能付出复杂度代价。
+
+## 提案
+
+当前阶段，ACP 仅启动全新会话。`initialize` 声明 `loadSession: false` 或省略该能力，`session/load` 不予支持。持久化仍可供 agent loop（智能体循环）和测试使用；如果其他消费方需要，恢复仍可作为底层工厂存在。编辑器 bridge 应在具备真正的会话选择 UX 和稳定的 load transcript 契约后，再重新引入 `session/load`。
+
+## 验收标准
+
+- ACP 不再注入 `sessionPersistence`；它原本仅供 `session/load` 使用。
+- `initialize` 不再声明 load 支持。
+- `session/load` handler、loading-id 追踪、已加载会话的 cwd 预检以及 load 回放测试均被移除。
+- 快照 fixture（测试前置数据）不再依赖 load 回放展示。
+- [ACP 文档](../../../../packages/ui/acp/README.md)仅描述全新会话的支持。
+
+## 放弃的能力
+
+编辑器无法通过 ACP 重新打开先前持久化的会话。这确实是一项产品功能，但当前实现超前于 UX 设计，且将 bridge 绑定到 token 级别的日志回放。保留持久化但移除编辑器 load，可将 bridge 收窄到它当前能干净呈现的工作流。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.i18n.yaml
new file mode 100644
index 0000000000..45949d3fcf
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-drop-acp-terminal-meta.md: 79da387ac1a7a0e6767e3bf24baa6039e39ef90d
+2026-06-20-drop-acp-terminal-meta.zh.md: d29fd54618611f56fd071a0ee4a63bc207895d89
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.md b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.md
index 8ce4803f73..79da387ac1 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.md
@@ -2,6 +2,8 @@
 
 Status: rejected — Zed is the current target client, and the terminal `_meta` convention is intentional Zed UX with a plain ACP fallback for other clients.
 
+English | [中文](2026-06-20-drop-acp-terminal-meta.zh.md)
+
 ## Problem
 
 The ACP bridge implements a Zed-specific terminal-card convention through `_meta.terminal_info`, `_meta.terminal_output`, and `_meta.terminal_exit`. The implemented [rich ACP bash rendering Agent Note](../../implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) deliberately avoided ACP's client-side `terminal/create` because bash execution belongs in the harness, but still adopted the reference agents' display-only `_meta` convention. That gives a nicer Zed card at the cost of bridge state, capability negotiation, terminal ids, special update mapping, text fallback tests, and exit-pill parsing in `dsh-tool-bash`.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.zh.md b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.zh.md
new file mode 100644
index 0000000000..d29fd54618
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 移除 ACP（Agent Client Protocol）终端 `_meta` 渲染
+
+Status: rejected — Zed 是当前目标客户端，terminal `_meta` 约定是有意设计的 Zed UX，同时为其他客户端保留普通 ACP 回退。
+
+[English](2026-06-20-drop-acp-terminal-meta.md) | 中文
+
+## 问题
+
+ACP 桥接层通过 `_meta.terminal_info`、`_meta.terminal_output` 和 `_meta.terminal_exit` 实现了一套 Zed 特有的终端卡片约定。已实现的[富 ACP bash 渲染 Agent Note（agent 决策记录）](../../implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md)刻意回避了 ACP 客户端侧的 `terminal/create`（因为 bash 执行属于 harness 职责），但仍采用了参考 agent（智能体）的纯展示 `_meta` 约定。这在 Zed 中带来了更好的卡片效果，代价是桥接状态、能力协商、终端 id、特殊的 update 映射、文本回退测试，以及 `dsh-tool-bash` 中的 exit-pill 解析。
+
+回退路径已经存在：将工具调用和完成输出渲染为普通 ACP 内容块。非 Zed 客户端本来就依赖这条路径，但 Zed 终端卡片是当前目标客户端的功能特性，而非推测性装饰。
+
+## 提案
+
+忽略 `clientCapabilities._meta.terminal_output`，通过纯 ACP 内容路径渲染 bash 结果。执行仍由 agent 侧的 `dsh-bash` 完成；仅移除展示相关的终端元数据。如果 ACP 日后标准化了 agent 执行的终端，或产品决定 Zed 特有展示值得其维护成本，终端卡片可以再回来。
+
+本提案比[收拢工具自有 UI 展示](2026-06-20-generic-tool-rendering.md)更窄：如果通用的 `presentCall`/`presentResult` 保留，本提案不影响它们，只移除终端子形态与 `_meta` 映射。
+
+## 验收标准
+
+- ACP 不再读取或存储 `_meta.terminal_output` 能力状态。
+- `TerminalRendering`、终端 id、终端 cwd 解析与 `_meta.terminal_*` update 映射从 `@deepseek-ai/dsh-acp` 中消失。
+- `ToolTerminal` 从 `@deepseek-ai/dsh-tools` 中消失，或在展示清理中因未使用而删除。
+- Bash 结果展示不再为终端 pill 解析退出状态。
+- 已实现的[富 ACP bash 渲染 Agent Note](../../implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) 作为已交付历史保留在 `implemented/` 中；如被本提案取代，则加上交叉链接。
+
+## 放弃的内容
+
+Zed 用户将失去专用终端卡片：没有 cwd 头部、终端展示或 exit pill。他们仍能以纯内容形式看到命令和输出。在 ACP 桥接层尚未发布、`_meta` 键只是约定而非标准的阶段，这是合理的简化。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.i18n.yaml
new file mode 100644
index 0000000000..e09db8fbbf
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-drop-bash-output-spill-files.md: b2bd1a04ee1524bab29814ffa7c22712a83ee5f7
+2026-06-20-drop-bash-output-spill-files.zh.md: c1b5670fac28a90cc4eb229ba0013e39067af8eb
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md b/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
index 939255f91e..b2bd1a04ee 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
@@ -2,6 +2,8 @@
 
 Status: rejected — full-output recovery is a real bash behavior. A future artifact/blob service may generalize it, but dropping spill files before that replacement would lose useful command output.
 
+English | [中文](2026-06-20-drop-bash-output-spill-files.zh.md)
+
 ## Problem
 
 `dsh-bash-local` keeps bounded in-memory output and spills large stdout/stderr streams into private temp files. That requires a private directory, random owner-only file creation, close-failure handling, byte-offset incremental reads, lossy read reporting, path rendering in model-facing text, and cleanup discipline. The tool then tells the model to read a local spill path when output was truncated.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.zh.md b/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.zh.md
new file mode 100644
index 0000000000..c1b5670fac
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 移除 bash 完整输出溢出文件
+
+Status: rejected — 完整输出恢复是真实的 bash 行为。未来的产物/blob 服务或许能将其泛化，但在替代方案就位前删除溢出文件会丢失有用的命令输出。
+
+[English](2026-06-20-drop-bash-output-spill-files.md) | 中文
+
+## 问题
+
+`dsh-bash-local` 在内存中保留有界的输出，并将大体量的 stdout/stderr 流溢出到私有临时文件。这要求一个私有目录、仅所有者可写的随机文件创建、关闭失败处理、基于字节偏移的增量读取、有损读取报告、在面向模型的文本中渲染路径，以及清理纪律。当输出被截断时，该工具会告知模型去读取一个本地溢出路径。
+
+这解决了一个真实问题，但方式狭隘且有泄漏。溢出路径是一个暴露在模型输出中的进程级文件系统产物，而非具有作用域访问控制、保留策略或 UI 支持的持久化 harness 产物。它还使后台任务的读取变得复杂，因为有损增量读取必须指向一个或两个溢出文件。
+
+## 提案
+
+保留尾部截断，移除完整输出溢出文件。bash 结果包含有界的尾部内容加一个明确的截断标记；不输出路径。如果用户需要恢复完整输出，则添加一个通用的产物/blob 服务（具有明确的所有权、清理和 UI 渲染），然后让 bash 将大体量输出附加到该服务。
+
+本提案可以独立于[通用长时间运行工具运行时](../../implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)落地。如果后台任务保留，`bash_output` 仍应报告输出已被丢弃，但不再提供溢出路径。
+
+## 验收标准
+
+- `CollectedOutput` 不再携带溢出路径。
+- `OutputCollector` 仅保留有界缓冲区，删除临时文件机制。
+- `renderResult()` 报告截断时不包含文件系统路径。
+- 测试覆盖尾部截断，不再断言完整输出文件的内容。
+- [docs/defensive-patterns.md](../../../../docs/defensive-patterns.md) 中的安全指导不再将私有溢出文件视为面向模型的接口。
+
+## 放弃的能力
+
+模型或用户无法再从临时文件恢复大体量命令输出中被省略的前缀。在真正的产物服务出现之前，这是可以接受的。当前的溢出路径为一个生命周期和权限均未经设计的功能引入了过多的定制机制。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..698d5a5ad6
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-drop-durable-step-boundaries.md: c5c4f269a378e334c4dc509d1288146d77d9a520
+2026-06-20-drop-durable-step-boundaries.zh.md: f2150699c74b16557d936d6833fcba02e7d76e69
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.md b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.md
index b2bf42a348..c5c4f269a3 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.md
@@ -2,6 +2,8 @@
 
 Status: rejected — `step/end` is the durable indication that a model step finished, and keeping the symmetric `step/start` / `step/end` pair makes crash repair, invariants, and transcript inspection clearer than inferring completion from adjacent step-scoped events.
 
+English | [中文](2026-06-20-drop-durable-step-boundaries.zh.md)
+
 ## Problem
 
 The session log stores `step/start` and `step/end` events even though every step-scoped event already carries `{ turn, step }`: assistant chunks, assistant messages, tool calls, tool results, usage, and errors. `deriveMessages()` ignores step boundaries, ACP ignores them for UI, and the main consumers are invariants, tests, snapshot expected outputs, and crash repair.
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
new file mode 100644
index 0000000000..f2150699c7
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: 移除持久化的步骤边界事件
+
+Status: rejected — `step/end` 是模型步骤已完成的持久信号；保留对称的 `step/start` / `step/end` 对，比从相邻的步骤作用域事件推断完成状态更便于理解崩溃修复、不变式与 transcript（文本记录）检查。
+
+[English](2026-06-20-drop-durable-step-boundaries.md) | 中文
+
+## 问题
+
+会话日志存储了 `step/start` 和 `step/end` 事件，尽管每个步骤作用域的事件本身已经携带 `{ turn, step }`：assistant 分片、assistant 消息、工具调用、工具结果、用量和错误。`deriveMessages()` 忽略步骤边界，ACP（Agent Client Protocol）在 UI 层面也忽略它们，主要消费方是不变式检查、测试、快照预期输出和崩溃恢复。
+
+被否决的论点是：边界事件使日志更像仪式而非信息。实际上，`step/end` 是具体信息：读者无需从下一个事件推导状态，就能判断一次模型请求是已完成、已崩溃还是正在修复。同样，一个孤立的 `step/start` 对于「模型请求已发起但在产生任何分片之前就失败了」的场景也有价值。
+
+## 提案
+
+将轮次作为唯一的持久化边界。`step/start` 和 `step/end` 将从 `SessionEventMap` 中移除；在需要分组的事件上保留数值型 `step` 字段。agent loop（智能体循环）递增步骤计数器并以该编号记录步骤作用域的事件，但不再追加开/关边界事件。消费方通过共享 `(turn, step)` 的连续事件推断步骤分组。
+
+不变式插件应当强制步骤作用域的事件在一个已打开的轮次内具有有效的正整数步骤编号，而非要求独立的边界记录包围它们。崩溃恢复不应合成 `step/end`；如果一个被中断的轮次被保留，修复路径仍然可以关闭该轮次而无需捏造步骤边界记录。
+
+## 验收标准
+
+- `SessionEventMap` 不再包含 `step/start` 或 `step/end`。
+- agent loop 中不再有 `closeStep()` 终结路径。
+- ACP 快照和持久化契约 fixture（测试前置数据）不再期望步骤边界行。
+- `deriveMessages()` 和回放从步骤作用域的事件推导出相同的消息历史。
+- [事件分类体系文档](../../../../docs/architecture.md)将轮次描述为持久化边界，将步骤描述为步骤作用域记录上的一个字段。
+- 会话格式版本和已记录的 fixture 被刷新；按预发布格式策略，非当前版本的已存储日志被拒绝。
+
+## 放弃了什么
+
+日志不再将「一次模型请求已发起但进程死亡前未产生任何事件」记录为持久化事实，也不再有显式的「此步骤已完成」标记。在会话日志仍是持久化回放与审计表面的当下，这一损失不可接受。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.i18n.yaml
new file mode 100644
index 0000000000..a9913a8849
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-drop-unused-session-lineage.md: 605f1949999435b24404e0c5a72320416303ae52
+2026-06-20-drop-unused-session-lineage.zh.md: 981f44189f4b8f11f513261db7094afdc650dffa
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.md b/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.md
index c85e943476..605f194999 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.md
@@ -2,6 +2,8 @@
 
 Status: rejected — `parentSession` is part of the documented fork/sub-agent seam and is already preserved by the agent/session resume path. The field is future-facing, but it is not accidental dead state.
 
+English | [中文](2026-06-20-drop-unused-session-lineage.zh.md)
+
 ## Problem
 
 `SessionHeader.parentSession` records the session a new session was forked from. It is defined in `dsh-session`, preserved by persistence backends, copied through resume, documented as lineage metadata, and covered by round-trip tests. The repo has no production fork UI or sub-agent flow that reads it. The planned sub-agent/fork seam is still a TODO, so the field is currently stored future shape.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.zh.md b/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.zh.md
new file mode 100644
index 0000000000..981f44189f
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 移除未使用的会话血缘元数据
+
+Status: rejected — `parentSession` 是已记录的 fork/subagent seam 的一部分，并已由 agent（智能体）/会话恢复路径保留。该字段面向未来，但并非意外遗留的死状态。
+
+[English](2026-06-20-drop-unused-session-lineage.md) | 中文
+
+## 问题
+
+`SessionHeader.parentSession` 记录新会话从哪个会话 fork 而来。它在 `dsh-session` 中定义，被持久化后端保留，在恢复流程中复制，作为血缘元数据被文档记录，并有往返测试覆盖。然而仓库中没有任何生产环境的 fork UI 或 subagent 流程读取它。计划中的 subagent/fork seam 仍是 TODO，因此该字段目前只是预存的未来形状。
+
+单个文件的成本虽小，但在格式层面影响面广：每个后端 schema 和元数据序列化器都在保留一个尚无已完成功能读取的值。由于 header 是磁盘契约，即使是占位字段也会成为未来重构必须维护、迁移或有意打破的东西。
+
+## 提案
+
+移除 `parentSession`，使其不再属于 `SessionHeader`，直到真正的 fork/恢复功能需要血缘信息时再引入。如果存在相应 API，fork 仍然可以用先前事件来初始化新会话，但持久化的父指针应当与读取它的功能和解释它的 UX 一同引入。
+
+如果血缘信息回归，届时再决定它应放在不可变 header 中、会话图索引中，还是作为一等事件。当前字段不应预先锁定那个设计。
+
+## 验收标准
+
+- `SessionHeader` 仅包含 version、id、createdAt 和可选的 cwd。
+- JSONL 与 SQLite 元数据 schema 不再存储父会话 id。
+- 恢复与列表 API 不再往返传递 `parentSession`。
+- 文档和测试移除没有生产消费方支撑的 fork 血缘声明。
+- 会话格式版本、后端 schema 版本与记录的 fixture（测试前置数据）按需刷新；按预发布格式策略，非当前版本的存储数据将被拒绝，不提供迁移路径。
+
+## 放弃了什么
+
+代码库失去了一个为未来 fork/subagent UX 预备的现成血缘钩子。这是有意为之。该字段在功能存在时很容易重新引入，而未发布的立场允许格式变更无需迁移。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..5f3e15ee98
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-fold-session-persistence-interface.md: 895b868b2a80d8655284bae1364a85e19e174da7
+2026-06-20-fold-session-persistence-interface.zh.md: c124b16531f904eb72cb8ac3842642d819309e14
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 8e5d59172f..895b868b2a 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
@@ -2,6 +2,8 @@
 
 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.
 
+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.
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
new file mode 100644
index 0000000000..c124b16531
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 将持久化接口合并进 dsh-session
+
+Status: rejected — 独立的持久化接口包是为持久后端设计的模块化能力 seam。将其折叠进 `dsh-session` 虽能减少包数量，却会牺牲更清晰的后端边界。
+
+[English](2026-06-20-fold-session-persistence-interface.md) | 中文
+
+## 问题
+
+`dsh-session-persistence` 是一个接口包（package），其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和契约辅助工具。后端包依赖它，`agent-loop`（智能体循环）也需要可选地查找一个同级服务来实现恢复。
+
+当持久化还是一个全新的可替换后端设计时，能力 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` 导出持久化服务类型、协调器和契约辅助工具。
+- 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)说明后端实现为何仍保持独立。
+
+## 放弃了什么
+
+`dsh-session` 变得更重：它同时拥有内存日志和持久化接口。这就是代价。如果第三方持久化后端已经形成公开生态，独立的接口包会是更清晰的 SDK 边界；但在预发布阶段，在尚无外部消费方时，多出的包看起来更像是过早的抽象。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.i18n.yaml
new file mode 100644
index 0000000000..da93063670
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-generic-tool-rendering.md: 6fc610546da04e7d1e16fc17ada87483a142aa3c
+2026-06-20-generic-tool-rendering.zh.md: 11386b87d845129950a8473eb1cf4ea6ce697ac8
diff --git a/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.md b/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.md
index dbc6ffed44..6fc610546d 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.md
@@ -2,6 +2,8 @@
 
 Status: rejected — tool-owned presentation should wait for more real tools before being generalized or deleted. Bash and ACP currently need the existing richer presentation path.
 
+English | [中文](2026-06-20-generic-tool-rendering.zh.md)
+
 ## Problem
 
 Tools can define `presentCall()` and `presentResult()` callbacks that return `ToolCallPresentation`, `ToolResultPresentation`, and optional `ToolTerminal` fields. The code itself flags the design as muddy: title, kind, raw input, content, terminal cwd, terminal output, exit code, and signal grew incrementally into a bag of optional fields. ACP then maintains pending call state to pair a result with the original args, creates replay-only presenters on `session/load`, and maps terminal subfields into Zed-specific `_meta`. `dsh-tool-bash` even parses exit status back out of rendered text because the pure replay-safe presenter no longer has the structured `BashRunResult`.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.zh.md b/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.zh.md
new file mode 100644
index 0000000000..11386b87d8
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 收拢工具自有的 UI 展示逻辑
+
+Status: rejected — 工具拥有的呈现机制应等到出现更多真实工具后再进行泛化或删除。Bash 与 ACP（Agent Client Protocol）目前仍需要现有的丰富呈现路径。
+
+[English](2026-06-20-generic-tool-rendering.md) | 中文
+
+## 问题
+
+工具可以定义 `presentCall()` 和 `presentResult()` 回调，返回 `ToolCallPresentation`、`ToolResultPresentation` 以及可选的 `ToolTerminal` 字段。代码本身就标记了这个设计的混乱：title、kind、raw input、content、terminal cwd、terminal output、exit code 和 signal 逐步增长为一堆可选字段。ACP 随后维护 pending call 状态以将 result 与原始 args 配对，在 `session/load` 时创建仅用于回放的 presenter，并将 terminal 子字段映射为 Zed 特有的 `_meta`。`dsh-tool-bash` 甚至从渲染后的文本中反向解析退出状态，因为纯回放安全的 presenter 已经拿不到结构化的 `BashRunResult`。
+
+真正的第一方用途是为 ACP 提供 bash 展示。这不足以作为冻结一个跨包（package）UI 展示 API 的依据。
+
+## 提案
+
+暂时移除工具自有的 UI 展示回调。规范的工具事件已经携带工具名、原始参数字符串、结果内容和错误状态。UI 从这些字段渲染一个通用的工具卡片。工具特有的富展示可以在至少有两个真实工具和两个真实消费方来验证词汇之后，以带标签的 render-intent union 形式回归。
+
+## 曾考虑的替代方案
+
+作为更小的替代方案，可以在一个 PR（Pull Request）中将当前的可选字段集合替换为一个显式 union；但如果目标是简化，更彻底的做法是删除回调、保留通用路径。
+
+## 验收标准
+
+- `ToolDefinition` 移除 `presentCall` 和 `presentResult`。
+- `ToolCallPresentation`、`ToolResultPresentation`、`ToolTerminal` 和 `ToolCallKind` 消失，除非一个最小的通用 UI 类型仍需要其中之一。
+- ACP 不再维护 presenter pending 状态，也不再在实时流式输出/加载回放期间调用工具回调。
+- `dsh-tool-bash` 不再解析渲染文本来恢复退出状态以供 UI pill 使用。
+- 快照预期输出展示通用工具卡片和文本结果。
+
+## 放弃了什么
+
+Bash 失去其自定义的终端风格卡片和模型生成描述的放置位置。回退方案仍然合理：命令作为工具输入展示，输出作为文本展示。富展示应当在产品拥有足够的 UI/工具多样性、足以支撑一份稳定的展示契约时再行设计。
+
+## 相关
+
+这是[移除 ACP terminal 元数据](2026-06-20-drop-acp-terminal-meta.md)的宽泛版本。如果本 Agent Note（agent 决策记录）被接受，那个更窄的 Agent Note 就不再必要。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.i18n.yaml
new file mode 100644
index 0000000000..3ca6a50ef7
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-retire-mid-turn-steering.md: a8812b3222739244d77f4d4dab60cf7c0cd6907d
+2026-06-20-retire-mid-turn-steering.zh.md: 81a211a167daeb8c57b98f2a1c1451dbc54d09e4
diff --git a/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.md b/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.md
index b26243f197..a8812b3222 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.md
@@ -2,6 +2,8 @@
 
 Status: rejected — mid-turn steering is an intentional agent capability for between-step user/plugin input and future goal/loop workflows. It is complexity with a product direction, not an accidental duplicate of `send()`.
 
+English | [中文](2026-06-20-retire-mid-turn-steering.zh.md)
+
 ## Problem
 
 The agent exposes two user-message paths that look close but have different lifecycle semantics: `send()` queues a normal user turn, while `steer()` injects a message between steps of the currently running turn and falls back to `send()` when idle. That distinction leaks through the whole stack: `Agent.steer()` is public API, the session log has a durable `steering/message` event, the agent event taxonomy has `agent/steering`, the loop maintains a steering FIFO beside the queued-message FIFO, cancellation clears both queues, and `deriveMessages()` has to render steering as a tagged synthetic user message rather than a normal prompt.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.zh.md b/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.zh.md
new file mode 100644
index 0000000000..81a211a167
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 移除轮次中途引导
+
+Status: rejected — 轮次中途 steering（中途引导）是一项有意设计的 agent（智能体）能力，用于接收步骤之间的用户/插件输入以及未来的 goal/loop 工作流。它是面向产品方向的复杂度，而非 `send()` 的意外重复。
+
+[English](2026-06-20-retire-mid-turn-steering.md) | 中文
+
+## 问题
+
+agent 暴露了两条用户消息路径，外观相近但生命周期语义不同：`send()` 将一条普通用户轮次排入队列，而 `steer()` 在当前运行轮次的步骤之间注入一条消息，空闲时则回退为 `send()`。这一区分贯穿整个栈：`Agent.steer()` 是公开 API；会话日志有持久化的 `steering/message` 事件；agent 事件分类体系有 `agent/steering`；agent loop（智能体循环）在排队消息 FIFO 之外还维护一个 steering FIFO；取消操作需要清空两个队列；`deriveMessages()` 必须将 steering 渲染为带标签的合成用户消息，而非普通提示词。
+
+续行 seam 进一步放大了成本。`agent/turn-continuation` 默认条件为 `hadToolCalls || steeringInjected`，因此同一轮次内的 steering 消息即使模型未请求工具调用，也会强制循环再次调用模型。注释中提到了未来 `/goal`、`/loop` 和预算守卫的用途，但当前仓库没有生产级监听器；只有测试注册了该 waterfall（瀑布式事件）。另外，唯一调用 `steer()` 的生产 UI 是 stdio 演示。ACP（Agent Client Protocol）在轮次运行期间已经通过普通队列发送提示词。
+
+## 提案
+
+暂时删除轮次中途的用户 steering。`Agent.send()` 成为提交用户内容的唯一公开方式；当 agent 正在运行时，内容等待下一个轮次。循环仅因工具调用而在轮次内继续，不因用户在某个步骤运行期间输入内容而继续。调用方若要中断当前轮次，使用 `cancel()` 后再 `send()`。
+
+移除 `Agent.steer()`、steering FIFO、`steering/message`、`agent/steering`、由 steering 驱动的续行逻辑，以及取消操作中区分排队消息与 steering 消息的逻辑。除非实现 PR（Pull Request）发现了生产级监听器，否则在同一变更中一并移除 `agent/turn-continuation`；没有 steering 后，当前仓库不再有具体的续行消费方。如果将来真正的预算或目标插件需要强制续行，应以该插件为具体消费方重新引入一个更窄的 seam。
+
+## 验收标准
+
+- `Agent` 暴露唯一的用户消息入口 `send()`。
+- 持久化会话事件词汇不再包含 `steering/message`。
+- `deriveMessages()` 渲染普通用户消息和上下文注入，不存在 steering 标签路径。
+- 循环只有一个排队消息 FIFO，没有同轮次用户消息续行路径。
+- `agent/turn-continuation` 被移除，或收窄到有具名的生产级消费方。
+- stdio UI 和文档将运行期间的输入描述为「排入下一轮次的输入」。
+- 会话格式版本和已录制的 fixture（测试前置数据）已刷新；非当前版本的存储日志按预发布格式策略被拒绝。
+
+## 放弃了什么
+
+用户无法在模型处于工具步骤之间时添加同轮次 steering 内容。这种行为在理论上对「你已经在工作了，也考虑一下 X」的场景有用，但它不是 ACP 当前暴露的行为，且使轮次边界更难推理。更简单的行为是合理的：用户输入成为下一条提示词，取消操作仍是替换进行中工作的显式手段。
+
+## 相关
+
+本提案与[移除持久化步骤边界](2026-06-20-drop-durable-step-boundaries.md)天然配对，因为移除同轮次 steering 和 `agent/turn-continuation` 后，工具调用成为一个轮次包含多个模型步骤的唯一原因。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.i18n.yaml
new file mode 100644
index 0000000000..66138d0995
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-single-session-acp-bridge.md: e99de76854390a0979d1b66866d1d48aacbc0036
+2026-06-20-single-session-acp-bridge.zh.md: 660e4ccf6f2fba8672315bfed30872870f401554
diff --git a/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.md b/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.md
index 83c6f598d4..e99de76854 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.md
@@ -2,6 +2,8 @@
 
 Status: rejected — Zed is the current target ACP client and its ACP implementation is explicitly multi-session: it stores live sessions in a `HashMap<SessionId, AcpSession>`, tracks `pending_sessions`, joins concurrent loads for the same id, and tests close-during-load behavior.
 
+English | [中文](2026-06-20-single-session-acp-bridge.zh.md)
+
 ## Problem
 
 The ACP bridge now supports multiple live sessions on one JSON-RPC connection. That capability brings multi-entry session maps, reverse session/agent lookups, per-session prompt state, loading ids, demux for every event, cross-session teardown, and isolation concerns for future permission prompts and background tasks. The older [multi-session ACP proposal](../../implemented/feature/2026-06-14-acp-multi-session.md) still tracks the unfinished permission-ownership piece; this Agent Note is the competing simplification path.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.zh.md b/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.zh.md
new file mode 100644
index 0000000000..660e4ccf6f
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 将 ACP（Agent Client Protocol）桥接恢复为每连接一个活跃会话
+
+Status: rejected — Zed 是当前目标 ACP 客户端，其 ACP 实现明确支持多会话：它把活跃会话存入 `HashMap<SessionId, AcpSession>`，跟踪 `pending_sessions`，合并同一 id 的并发加载，并测试加载期间关闭的行为。
+
+[English](2026-06-20-single-session-acp-bridge.md) | 中文
+
+## 问题
+
+ACP 桥接现在支持在一条 JSON-RPC 连接上承载多个活跃会话。这一能力带来了多条目会话映射、反向会话/agent（智能体）查找、逐会话的提示词状态、加载中 id、每条事件的解复用、跨会话拆除，以及未来权限提示与后台任务的隔离问题。较早的[多会话 ACP 提案](../../implemented/feature/2026-06-14-acp-multi-session.md)仍在追踪未完成的权限归属部分；本 Agent Note（agent 决策记录）是与之竞争的简化路径。
+
+产品目标已经证明它需要在一个 harness 进程上承载并发的编辑器对话：Zed 的 ACP 连接拥有多个会话和加载状态。快照回放层仍然避免并发模型流，因为其回放条目是位置相关的；这是测试 fixture（测试前置数据）的局限，而非移除桥接多路复用的理由。
+
+## 提案
+
+将 ACP 的范围收回到每连接一个活跃会话。`session/new` 或 `session/load` 创建唯一的会话记录；在现有会话被 dispose（资源释放）或连接关闭之前，第二个活跃会话请求将被拒绝。如果编辑器需要多个聊天标签页，可以启动多个 agent 子进程，直到桥接具备具体的多会话 UX 和权限模型。
+
+移除多会话映射和解复用逻辑，改用单一的 `SessionRecord | undefined` 即可。桥接仍可保留使 dispose 正确的 agent/会话生命周期 seam；简化仅针对在同一传输层上多路复用多个活跃会话这一点。
+
+## 验收标准
+
+- ACP 每连接只有一条活跃会话记录。
+- 当该记录存在时，`session/new` 和 `session/load` 拒绝请求。
+- 事件处理器不再在 `Map<sessionId, record>` 上做解复用。
+- 多会话测试被移除，或移至继续支持多路复用的提案下。
+- 既有的[多会话 ACP 提案](../../implemented/feature/2026-06-14-acp-multi-session.md)更新为链接本 Agent Note，并继续作为当前方向。
+
+## 放弃了什么
+
+ACP 客户端无法在一个服务器进程上承载多个并发对话。这是一项有实质意义的能力削减。对于一个尚未发布的 harness 而言，更简单的模型仍然合理：一个编辑器对话对应一个 agent 进程，跨会话的权限/后台任务隔离不再是活跃的正确性负担。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..98845d7e03
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-06-20-truncate-interrupted-turns.md: af18618ad4c41af125e37c51b9fd971dd8eae64e
+2026-06-20-truncate-interrupted-turns.zh.md: a20d0169f7735aa7a9437c10c958580c00704171
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 a685765197..af18618ad4 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
@@ -2,6 +2,8 @@
 
 Status: rejected — a single turn can contain substantial real work, including many steps and large tool output. Preserving interrupted turns is preferable to silently dropping that tail on load.
 
+English | [中文](2026-06-20-truncate-interrupted-turns.zh.md)
+
 ## Problem
 
 The current persistence contract preserves a final turn that was durably written but never closed. On load, `interruptedTurnClosers()` scans the tail, synthesizes error `tool/result` events for unanswered tool calls, appends a `step/end` when a step is open, appends `turn/end { kind: 'interrupted' }`, and asks the backend to durably commit that repair. The coordinator, JSONL backend, SQLite backend, session event vocabulary, invariants, docs, and tests all model this synthetic close 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
new file mode 100644
index 0000000000..a20d0169f7
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 加载时截断被中断的最终轮次
+
+Status: rejected — 单个轮次可以包含大量真实工作，包括多个步骤和大量工具输出。保留被中断的轮次，优于在加载时静默丢弃这段尾部。
+
+[English](2026-06-20-truncate-interrupted-turns.md) | 中文
+
+## 问题
+
+当前的持久化契约会保留已持久写入但从未关闭的最终轮次。加载时，`interruptedTurnClosers()` 扫描尾部，为未应答的工具调用合成 error `tool/result` 事件，在步骤处于打开状态时追加 `step/end`，追加 `turn/end { kind: 'interrupted' }`，并要求后端持久提交这次修复。协调器、JSONL 后端、SQLite 后端、会话事件词汇、不变式、文档和测试都对这条合成关闭路径进行了建模。
+
+这是一套庞大的机制，只为保留上次崩溃轮次中的部分工作。它还会凭空创造从未发生过的事件。合成的工具结果虽然有用（因为它使提供方历史保持合法），但也意味着恢复后的日志中包含了模型可见、却并非任何工具产出的文本。当前设计在尚无已发布产品、也没有真实恢复 UX 来证明部分轮次恢复确有价值的情况下，就优化了最大化尾部保留。
+
+## 提案
+
+加载时只保留最后一个已完成的轮次。后端仍然容忍并截断撕裂的最终记录，但如果解析出的持久前缀止于一个打开的 `turn/start` 之后，规范的修复方式是丢弃上一个 `turn/end` 之后的所有事件。不合成 `tool/result`，不合成 `step/end`，不追加 `turn/end { interrupted }`，也不引入 `interrupted` 轮次结束原因。
+
+这使持久化的轮次边界变得简单：一个已完成的 `turn/end` 就是检查点。最后一个检查点之后的内容都是崩溃尾部。下一次提示词从最后一个已知合法的提供方 transcript（文本记录）恢复，而不是从部分重建的最终轮次恢复。
+
+## 验收标准
+
+- `TurnEndReasonMap` 移除 `interrupted` 变体。
+- `interruptedTurnClosers()` 及其测试删除。
+- 持久化协调器的修复钩子截断后端特有的撕裂/打开尾部状态，不追加关闭事件。
+- [会话持久化文档](../../../../packages/session-persistence/session-persistence/README.md)说明加载返回最后一个已完成的轮次，不包含部分最终轮次。
+- 快照与契约测试随其所固定的行为一同更新。
+- 会话格式版本与记录的 fixture（测试前置数据）刷新；按预发布格式策略，非当前版本的存储日志被拒绝，不提供迁移路径。
+
+## 放弃的内容
+
+崩溃可能丢失最终轮次中的真实工作：上一个 `turn/end` 之后追加的助手文本、工具调用和工具输出。这是有意为之的简化。产品尚未发布，最终轮次恢复的语义未经用户验证，而一个干净的「已完成轮次即检查点」模型在解释、测试和实现上都容易得多。未来若需「恢复部分崩溃工作」功能，应设计为面向用户的显式恢复视图，而非静默插入规范 transcript 的合成事件。
+
+## 相关
+
+本提案是对[会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md)与[轮次封闭不变式](../../implemented/architecture/2026-06-15-turn-enclosure-invariant.md)的直接简化。它还移除了持久化步骤边界事件的大部分动机，使[移除持久化步骤边界事件](2026-06-20-drop-durable-step-boundaries.md)的改动更小。
+
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
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
new file mode 100644
index 0000000000..9720d3c114
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-04-prune-unimplemented-subagent-vocabulary.md: 890aca31f09f97ab6d9bf7c00f738d894695d9ad
+2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md: 7837759604a30ee8f58d922bb5f55f6730d1ddcb
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
index 582673f185..890aca31f0 100644
--- 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
@@ -2,6 +2,8 @@
 
 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:
@@ -9,7 +11,7 @@ The [subagent seam](../../implemented/feature/2026-06-21-subagent-capability-sea
 - **`outputSchema`/`structured` and `toolFilter`** (`SubagentCapabilities`, `SubagentStartRequest`, `SubagentResult` in `packages/subagent/subagent/src/types.ts`): at the decision point, every real provider declared `outputSchema: false, toolFilter: false` (`packages/subagent/subagent-spawn/src/index.ts`, `packages/subagent/subagent-fork/src/index.ts`, `packages/subagent/subagent-acp/src/index.ts`); the sole production `ctx.subagents.start` caller (`packages/subagent/tool-subagent/src/index.ts`) built `{ prompt, parent, signal?, agentOptions? }` and structurally could not set either; `structured` appeared only in the scripted test fixture. The service's capability check carried two assert rows whose only exercisers were the rejection tests.
 - **`SubagentRun.sendMessage` / `SubagentRun.resume`** (same file): implemented by NO provider — not even the mock; the spawn spec asserts their *absence*.
 
-The only reason `dsh-subagent` depends on `dsh-tools` at all is `outputSchema`'s `SchemaSpec` type. Three subsequent subagent workstreams (per-session snapshot replay, the fork seed boundary, the ACP backend) landed around this surface without growing a single consumer.
+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
 
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
new file mode 100644
index 0000000000..7837759604
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md
@@ -0,0 +1,39 @@
+# 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/dev 依赖应从 `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（agent 决策记录）的能力目录。
+
+**保留** `depthLimit`/`maxDepth` 与能力检查。进程内后端已强制执行该限制，尽管当前发布的工具尚未设置它。递归是已知的 seam 风险，因此恰当的后续工作是提供一个工具默认值，而非删除正在工作的强制逻辑。
+
+审视过但有意不动的相邻接口面：`SubagentService.getProvider()`/`list()` 仅有测试 harness 消费方，但 [prune-dead-seam-methods 实现说明](../../implemented/simplification/2026-06-20-prune-dead-seam-methods.md)恰好记录了这种形态从 bash 执行器中被移除后又被回退的经过——对于一个基于已跟踪 map 的单行访问器而言，测试 harness 就是消费方。`SubagentRunEndInfo.lastAssistantMessage` 是一个已记录的保留项（[subagent 观测/丰富化 Agent Note](../../implemented/feature/2026-06-30-subagent-observe-enrich.md)的评审删除了 `agentType` 但有意保留了它，因为它是进程外子 agent（智能体）唯一的最终消息通道）；它当前未接通的桥接转发是一个待补的缺口或待记录的消费方，不是本 Agent Note 要裁剪的接口面。
+
+这是[从持久化 seam 裁剪死方法](../../implemented/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-12-collapse-workflow-to-foreground-core.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
new file mode 100644
index 0000000000..1b4e9c4b54
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-12-collapse-workflow-to-foreground-core.md: 629e2140523c3ae7caf533de99821206d05f1b8e
+2026-07-12-collapse-workflow-to-foreground-core.zh.md: 3ae5e026a0b123a6b695b339010bf14a99515912
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 dcfdfa13e6..629e214052 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
@@ -2,6 +2,8 @@
 
 Status: rejected — Workflow progress is an intentional observation surface; make it useful through a consumer instead of deleting it.
 
+English | [中文](2026-07-12-collapse-workflow-to-foreground-core.zh.md)
+
 ## Problem
 
 The workflow capability executes foreground JavaScript that composes subagents, but it also carries an unconsumed progress-observation system. No production listener subscribes to any of the six `workflow/*` events; listeners exist only in workflow tests. Nevertheless the seam defines run/phase/agent outcome payloads, the worker sends phase/log/agent lifecycle protocol messages, the host forwards them through a `liveAgents` pairing ledger, and the engine maintains run ids solely to correlate those notifications.
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
new file mode 100644
index 0000000000..3ae5e026a0
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 将工作流收缩至已使用的前台核心
+
+Status: rejected — 工作流进度是有意设计的观测接口面；应通过消费方使其发挥作用，而非删除它。
+
+[English](2026-07-12-collapse-workflow-to-foreground-core.md) | 中文
+
+## 问题
+
+工作流能力执行前台 JavaScript 来编排 subagent，但它同时携带了一套无人消费的进度观测系统。没有任何生产环境的监听器订阅六个 `workflow/*` 事件中的任何一个；监听器仅存在于工作流测试中。尽管如此，seam 定义了 run/phase/agent（智能体） outcome 载荷，worker 发送 phase/log/agent 生命周期协议消息，host 通过一个 `liveAgents` 配对账本转发它们，引擎维护 run id 仅仅是为了关联这些通知。
+
+这套进度词汇不仅仅是未被使用；它在不经重新设计的情况下也无法服务于其唯一已命名的未来消费方。`WorkflowRunInfo` 包含 `{id, meta}` 但没有父 agent、会话或工具调用标识，而面向模型的工具也从不暴露 run id。一个全局 ACP（Agent Client Protocol）监听器无法将事件路由到正确的客户端会话。`meta.phases` 从未被查询，`phase(title)` 不对其做校验，phase 的 `detail`/`model` 和 agent 的 `label`/`phase` 仅供事件消费，`whenToUse` 被校验和复制但从未被渲染或用于选择。`phase()` 和 `log()` 仍然跨越 worker 边界，尽管没有接收方。
+
+live handle 在观测者消失后仍重复事件时代的数据。`WorkflowRun.id` 没有非事件消费方，而工具读取 `run.meta.name` 只是为了渲染一个它已经以 `args.meta.name` 形式持有的值；两者都不属于执行/取消 handle。
+
+取消机制也为一个同步启动提供了两条公开通道。`WorkflowStartRequest.signal` 被传递给 worker host，而唯一的生产调用方另外将同一个 signal 桥接到 `WorkflowRun.cancel()`。因为 `start()` 在控制权让出之前就返回了 run，不存在需要请求时取消的就绪窗口；重复的 signal 增加了 host 的 listener/disarm 状态却没有封堵任何竞态。
+
+`WorkflowError.fatal` 是同一种推测性分支的微缩版：所有生产环境的构造都是 fatal 的，`fatal: false` 仅存在于测试中，组合子已经通过 `instanceof` 区分工作流失败。
+
+## 提案
+
+保留已使用的核心：`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（agent 决策记录），并更新 seam/工具/worker README、工具 schema、生成的 catalog 与包（package）依赖图、worker type-equiv 记录、单元测试以及工作流快照/header fixture（测试前置数据）。如果进度 UI 工作被立项，应从一份命名了父 agent/会话/工具调用的关联契约出发，而非原样复活这套协议。
+
+## 曾考虑的替代方案
+
+**为未来 UI 保留预建的观测词汇。** 当前形态类似 Claude Code 的动态工作流元数据，host 有意地将每个转发的 agent start 与 worker 的 end 或一个合成的终止 end 配对。移除它意味着放弃形态兼容性，使进度 UI 成为一项全新的设计任务；但现有载荷仍缺少可路由的归属信息，因此仅靠平衡的生命周期也无法在不重新设计的情况下让已命名的 ACP 消费方可行。
+
+## 验收标准
+
+- 工作流公开 seam 仅包含有生产消费方的执行、取消、结果与 dispose 契约。
+- 不再保留任何工作流事件、phase/log 协议消息、run-id 生成器、仅供进度使用的元数据、host 配对账本或 fatal 模式分支。
+- run handle 不再有 id/meta 回显，取消在同步 `start()` 返回后只有一条持有者拥有的通道。
+- parallel/pipeline 行为、上限、取消后的完全停稳、worker 隔离、结构化输出与面向模型的工作流场景保持测试覆盖。
+- 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建与 hygiene 全部通过。
+
+## 风险
+
+这是对工作流 DSL、事件分类体系、handle 与 start request 的编译可见收缩。现有提供描述性元数据的工作流调用，以及使用 `phase`、`log` 或 label 的脚本，都必须相应精简；程序化调用方需自行将 abort source 桥接到返回的 handle；未来的观测者必须添加一个关联性更好的 seam。使工作流有用的执行语义不变。
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
new file mode 100644
index 0000000000..3b97a7fb1e
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-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
+2026-07-12-prune-unused-skill-registry-surface.md: 5a13effa04a6cd9954741a0a33ebc6fc3512fab8
+2026-07-12-prune-unused-skill-registry-surface.zh.md: 46d49a02c294c492abdd6e7e611a5c92eb317c12
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 e96215a651..5a13effa04 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
@@ -2,6 +2,8 @@
 
 Status: rejected — Direct runtime skill registration is an intentional extension path for third-party plugins.
 
+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.
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
new file mode 100644
index 0000000000..46d49a02c2
--- /dev/null
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 裁剪 skill（技能）注册表中未使用的接口
+
+Status: rejected — 直接在运行时注册 skill 是为第三方插件保留的有意扩展路径。
+
+[English](2026-07-12-prune-unused-skill-registry-surface.md) | 中文
+
+## 问题
+
+skill 服务的嵌入式运行时子系统中，`ctx.skills.register()` 没有任何生产调用方。它引入了一个保留的 `runtime` 提供方名称、一套运行时 map/rank/source、重复策略、缓存键中的第二个 revision、规范化逻辑、dispose（资源释放）器以及相应测试——而所有已交付的 skill 都只使用提供方 seam。`SkillSummary.whenToUse` 和 candidate/definition 的 `path` 被解析和复制，但没有任何生产消费方读取它们：模型目录只渲染 name/description，资源加载使用 `resourceBase`，提供方自行管理其定位器。有意开放的 `metadata` 扩展点保留不动。
+
+## 提案
+
+移除 `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（agent 决策记录）、README、JSDoc、目录文件与测试。agent（智能体）作用域的系统提示词段、工具提供方和变量明确不在本提案范围内：[agent 作用域贡献者契约](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)有意允许在 `setup(agentCtx)` 期间通过 agent 拥有的上下文注册这三者，因此仓库内没有固定的作用域注册并不能证明它们未被使用。
+
+## 曾考虑的替代方案
+
+**保留面向嵌入方的运行时 skill 注册。** 这是已实现的 skill Agent Note 中有意提供的同步直接定义便利接口。一个小型提供方包装层可以在 effect 拥有的生命周期下暴露相同的嵌入数据，但它必须实现异步 `list()`/`get()`、携带提供方身份，并接受提供方的重复语义。本提案选择只保留一条统一的提供方路径，而非维护第二套排序、校验、缓存失效与查找路径。
+
+## 验收标准
+
+- skill 收集只有一条提供方驱动的路径，已完成缓存仅以 cwd 为键，revision epoch 仅用于进行中的失效检测；保留的 skill 字段要么有生产读取方，要么有记录在案的有意扩展契约。
+- agent 作用域的提示词段、变量、工具提供方、工具守卫，以及原生模式和 Code Mode 下的 structured-output 提交行为保持不变。
+- 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建与 hygiene 全部通过。
+
+## 风险
+
+这是对预发布 skill 注册表的编译可见收缩。外部编程式 `list()`/`get()` 消费方将失去 `whenToUse` 路由提示和 candidate/definition 的 `path`；已交付的模型目录从未渲染它们，资源解析保留了显式的 `resourceBase` 加上提供方自有的不透明 locator，但这些字段并非观测等价。skill 本地 frontmatter 解析必须继续保留并校验所支持的 metadata schema，外部提供方仍可提供嵌入式、文件系统、远程或其他 skill 来源。
diff --git a/.agents/skills/dsh-translate-docs/SKILL.md b/.agents/skills/dsh-translate-docs/SKILL.md
index 8786eb5e6b..8c28d4afda 100644
--- a/.agents/skills/dsh-translate-docs/SKILL.md
+++ b/.agents/skills/dsh-translate-docs/SKILL.md
@@ -20,7 +20,7 @@ These are authoritative; read them at the source so this skill never drifts out
 - **[docs/i18n/README.md](../../../docs/i18n/README.md)** — the pairing contract: the three-file pair (`foo.md`, `foo.zh.md`, `foo.i18n.yaml`), the consistency record's both-side blob hashes, the language-switcher lines, scope/exclusions, and the rollout manifest.
 - **[docs/i18n/translation-rules.md](../../../docs/i18n/translation-rules.md)** — how to translate: faithfulness, structure preservation, terminology discipline, typography (MUST/SHOULD levels).
 - **[docs/i18n/terminology.md](../../../docs/i18n/terminology.md)** — the terminology table, binding in both directions. Load it BEFORE translating, not when a term feels uncertain; the terms you don't notice are the ones that drift.
-- **[docs/i18n/translation-prompt.md](../../../docs/i18n/translation-prompt.md)** — the automated pipeline's machine-consumed template. Agents using this skill do not render it; the renderer injects `translation-rules.md` so rules have only one home.
+- **[docs/i18n/translation-prompt.md](../../../docs/i18n/translation-prompt.md)** — the automated pipeline's calibrated machine-consumed template. Agents using this skill do not render it; the terminology table is the only repository file the automated renderer injects, while this skill and `translation-rules.md` remain binding for agent-authored translations.
 - **[dsh-prose-standard](../dsh-prose-standard/SKILL.md)** — required prose coverage and editorial judgment. Apply it to both sides without adding or dropping source propositions.
 
 ## Find the work
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
new file mode 100644
index 0000000000..e48e16ca40
--- /dev/null
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: record-browser-gif
+description: Record browser or Web UI interaction demos as optimized local GIFs using the available built-in browser, state-based frame capture, and deterministic encoding. Use when Codex is asked to make, record, or generate a GIF that demonstrates a browser workflow, including real-server or real-API behavior. Stop after returning the verified local artifact; do not upload it or edit a pull request.
+---
+
+# Record Browser GIF
+
+Produce a short, truthful UI demonstration as a local GIF. Use the browser-control skill for interaction and the bundled encoder for repeatable timing, dimensions, and size.
+
+## Keep the boundary explicit
+
+- Produce frame images and one local `.gif` artifact only.
+- Never upload the artifact, post a comment, or change a pull request, issue, or document under this skill. Hand those actions to a separate workflow if the user requests them.
+- 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.
+- Never read or expose credential values. Use the application's normal configuration path and a benign demonstration prompt.
+
+## 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.
+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 initial, typed, submitted, and completed. 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. Store frames in an absolute artifact directory outside the Git worktree unless the user requests another location, and name them lexically: `00-initial.png`, `01-typed.png`, and so on.
+5. 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.
+6. 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.
+
+## Encode the GIF
+
+Require `python3`, `ffmpeg`, and `ffprobe`. If either media binary is missing, report the dependency instead of installing software without authorization.
+
+Set `GIF_SKILL_DIR` to this skill's absolute directory, then encode the lexically ordered frames:
+
+```sh
+python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
+  /absolute/path/to/frames \
+  /absolute/path/to/demo.gif \
+  --durations 1.5,1.5,1.5,3.5 \
+  --fps 10 \
+  --max-width 1200 \
+  --colors 128
+```
+
+One duration applies to every frame; otherwise provide one comma-separated positive duration per frame. The encoder rejects fewer than two frames, mismatched dimensions or durations, invalid limits, accidental overwrite, unexpected duration, and output above `--max-bytes`.
+
+For a large artifact, reduce `--max-width` first, then `--colors` or `--fps`; retain readable text and the final state long enough to inspect. Use `--force` only after resolving the exact output path.
+
+## Verify and deliver
+
+1. Read the encoder's JSON summary and confirm the output path, source and encoded frame counts, dimensions, duration, and byte size.
+2. Inspect the first and final source frames and the resulting GIF. Confirm that the transition is legible, the last state is held long enough, and no sensitive content appears.
+3. If capture occurred near a repository, run `git status --short` and confirm the artifact did not dirty the worktree.
+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. Stop without uploading it or editing remote content.
diff --git a/.agents/skills/record-browser-gif/agents/openai.yaml b/.agents/skills/record-browser-gif/agents/openai.yaml
new file mode 100644
index 0000000000..720f55f7dc
--- /dev/null
+++ b/.agents/skills/record-browser-gif/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Record Browser GIF"
+  short_description: "Record and optimize local browser demo GIFs"
+  default_prompt: "Use $record-browser-gif to record this browser flow as a verified local GIF."
diff --git a/.agents/skills/record-browser-gif/scripts/encode_gif.py b/.agents/skills/record-browser-gif/scripts/encode_gif.py
new file mode 100755
index 0000000000..2a14ae47fd
--- /dev/null
+++ b/.agents/skills/record-browser-gif/scripts/encode_gif.py
@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Encode lexically ordered browser screenshots into a verified GIF."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import NoReturn
+
+
+DEFAULT_MAX_BYTES = 5 * 1024 * 1024
+
+
+def fail(message: str) -> NoReturn:
+    """Exit with a concise user-correctable error."""
+    raise SystemExit(f"error: {message}")
+
+
+def positive_float(value: str) -> float:
+    """Parse one finite positive command-line number."""
+    try:
+        parsed = float(value)
+    except ValueError:
+        fail(f"expected a number, got {value!r}")
+    if not math.isfinite(parsed) or parsed <= 0:
+        fail(f"expected a positive finite number, got {value!r}")
+    return parsed
+
+
+def positive_int(value: str) -> int:
+    """Parse one positive command-line integer."""
+    try:
+        parsed = int(value)
+    except ValueError:
+        fail(f"expected an integer, got {value!r}")
+    if parsed <= 0:
+        fail(f"expected a positive integer, got {value!r}")
+    return parsed
+
+
+def parse_durations(value: str, frame_count: int) -> list[float]:
+    """Expand one hold duration or validate one duration per source frame."""
+    parts = [part.strip() for part in value.split(",")]
+    if not parts or any(not part for part in parts):
+        fail("--durations must be a number or a comma-separated list of numbers")
+    durations = [positive_float(part) for part in parts]
+    if len(durations) == 1:
+        return durations * frame_count
+    if len(durations) != frame_count:
+        fail(f"--durations supplied {len(durations)} values for {frame_count} frames")
+    return durations
+
+
+def require_binary(name: str) -> str:
+    """Resolve a required media binary or fail without attempting installation."""
+    path = shutil.which(name)
+    if path is None:
+        fail(f"required binary {name!r} is not available on PATH")
+    return path
+
+
+def run_json(command: list[str]) -> dict[str, object]:
+    """Run a media probe and parse its JSON object."""
+    try:
+        completed = subprocess.run(command, check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as error:
+        detail = error.stderr.strip() or error.stdout.strip() or str(error)
+        fail(detail)
+    try:
+        value = json.loads(completed.stdout)
+    except json.JSONDecodeError as error:
+        fail(f"media probe returned invalid JSON: {error}")
+    if not isinstance(value, dict):
+        fail("media probe returned a non-object JSON value")
+    return value
+
+
+def probe_stream(ffprobe: str, path: Path) -> dict[str, object]:
+    """Read the first video stream's dimensions and timing metadata."""
+    result = run_json(
+        [
+            ffprobe,
+            "-v",
+            "error",
+            "-select_streams",
+            "v:0",
+            "-show_entries",
+            "stream=width,height,nb_frames,duration,r_frame_rate",
+            "-of",
+            "json",
+            str(path),
+        ]
+    )
+    streams = result.get("streams")
+    if not isinstance(streams, list) or len(streams) != 1 or not isinstance(streams[0], dict):
+        fail(f"expected one video stream in {path}")
+    return streams[0]
+
+
+def stream_int(stream: dict[str, object], key: str, path: Path) -> int:
+    """Read a positive integer stream field."""
+    try:
+        value = int(stream[key])
+    except (KeyError, TypeError, ValueError):
+        fail(f"missing integer {key!r} in media probe for {path}")
+    if value <= 0:
+        fail(f"non-positive {key!r} in media probe for {path}")
+    return value
+
+
+def ffconcat_quote(path: Path) -> str:
+    """Quote an ffconcat path while preserving literal backslashes."""
+    value = str(path)
+    if "\n" in value or "\r" in value:
+        fail(f"frame path contains a newline: {path}")
+    return "'" + value.replace("'", "'\\''") + "'"
+
+
+def write_concat_manifest(path: Path, frames: list[Path], durations: list[float]) -> None:
+    """Write an ffconcat manifest that materializes the final frame's hold."""
+    lines = ["ffconcat version 1.0"]
+    for frame, duration in zip(frames, durations):
+        lines.append(f"file {ffconcat_quote(frame)}")
+        lines.append(f"duration {duration:.6f}")
+    lines.append(f"file {ffconcat_quote(frames[-1])}")
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line contract."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("frames", type=Path, help="directory containing lexically ordered frames")
+    parser.add_argument("output", type=Path, help="output .gif path")
+    parser.add_argument("--pattern", default="*.png", help="frame glob within the input directory")
+    parser.add_argument(
+        "--durations",
+        default="2",
+        help="one hold duration or one comma-separated value per frame",
+    )
+    parser.add_argument("--fps", type=positive_int, default=10, help="encoded frames per second")
+    parser.add_argument(
+        "--max-width",
+        type=positive_int,
+        default=1200,
+        help="maximum output width",
+    )
+    parser.add_argument(
+        "--colors",
+        type=positive_int,
+        default=128,
+        help="palette colors, from 4 through 256",
+    )
+    parser.add_argument(
+        "--max-bytes",
+        type=positive_int,
+        default=DEFAULT_MAX_BYTES,
+        help="maximum output size",
+    )
+    parser.add_argument("--force", action="store_true", help="replace an existing output file")
+    return parser
+
+
+def main() -> None:
+    """Validate inputs, encode the GIF, verify it, and print a JSON summary."""
+    args = build_parser().parse_args()
+    frame_dir = args.frames.resolve()
+    output = args.output.resolve()
+
+    if not frame_dir.is_dir():
+        fail(f"frame directory does not exist: {frame_dir}")
+    if output.suffix.lower() != ".gif":
+        fail(f"output must end in .gif: {output}")
+    if output.exists() and not args.force:
+        fail(f"output already exists (pass --force to replace it): {output}")
+    if not 4 <= args.colors <= 256:
+        fail("--colors must be between 4 and 256")
+    if args.fps > 30:
+        fail("--fps must not exceed 30")
+
+    frames = sorted(path.resolve() for path in frame_dir.glob(args.pattern) if path.is_file())
+    if len(frames) < 2:
+        fail(f"expected at least two frames matching {args.pattern!r} in {frame_dir}")
+    if output in frames:
+        fail("output path must not match an input frame")
+
+    durations = parse_durations(args.durations, len(frames))
+    expected_duration = sum(durations)
+    ffmpeg = require_binary("ffmpeg")
+    ffprobe = require_binary("ffprobe")
+
+    dimensions = {
+        (stream_int(stream, "width", frame), stream_int(stream, "height", frame))
+        for frame in frames
+        for stream in [probe_stream(ffprobe, frame)]
+    }
+    if len(dimensions) != 1:
+        fail(f"all frames must have identical dimensions, got {sorted(dimensions)}")
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="record-browser-gif-") as temporary:
+        manifest = Path(temporary) / "frames.ffconcat"
+        write_concat_manifest(manifest, frames, durations)
+        scale = f"scale='min({args.max_width},iw)':-2:flags=lanczos"
+        palette = f"palettegen=max_colors={args.colors}:stats_mode=full"
+        filters = (
+            f"fps={args.fps},{scale},split[base][palette_input];"
+            f"[palette_input]{palette}[palette];"
+            "[base][palette]paletteuse=dither=bayer:bayer_scale=3:diff_mode=rectangle"
+        )
+        command = [
+            ffmpeg,
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-f",
+            "concat",
+            "-safe",
+            "0",
+            "-i",
+            str(manifest),
+            "-vf",
+            filters,
+            "-loop",
+            "0",
+            "-t",
+            f"{expected_duration:.6f}",
+            "-y" if args.force else "-n",
+            str(output),
+        ]
+        try:
+            subprocess.run(command, check=True)
+        except subprocess.CalledProcessError as error:
+            fail(f"ffmpeg failed with exit code {error.returncode}")
+
+    stream = probe_stream(ffprobe, output)
+    width = stream_int(stream, "width", output)
+    height = stream_int(stream, "height", output)
+    encoded_frames = stream_int(stream, "nb_frames", output)
+    try:
+        actual_duration = float(stream["duration"])
+    except (KeyError, TypeError, ValueError):
+        fail(f"missing duration in media probe for {output}")
+    tolerance = max(0.2, 2 / args.fps)
+    if abs(actual_duration - expected_duration) > tolerance:
+        fail(f"expected about {expected_duration:.3f}s, encoded {actual_duration:.3f}s")
+    if width > args.max_width:
+        fail(f"expected width at most {args.max_width}, encoded {width}")
+    if encoded_frames < 2:
+        fail(f"expected an animated GIF, encoded {encoded_frames} frame")
+
+    byte_size = output.stat().st_size
+    if byte_size > args.max_bytes:
+        fail(f"output is {byte_size} bytes, above --max-bytes {args.max_bytes}")
+
+    print(
+        json.dumps(
+            {
+                "output": str(output),
+                "sourceFrames": len(frames),
+                "encodedFrames": encoded_frames,
+                "width": width,
+                "height": height,
+                "durationSeconds": actual_duration,
+                "fps": args.fps,
+                "bytes": byte_size,
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e9d5630d33..2eceefa114 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -27,19 +27,15 @@ env:
 
 jobs:
 
-  # One enterprise runner pays setup once, then executes the complete
-  # unsharded primary Node inventory with repository-level concurrency.
+  # Three enterprise jobs isolate coverage, static analysis, and the
+  # build-backed consumer tail. The static job publishes its exact build so
+  # consumers do not repeat the longest part of their critical path.
   node-24:
     if: github.event_name == 'pull_request'
-    runs-on: dsh-enterprise-ubuntu-24-04-32core-test
-    name: node 24 / complete
+    runs-on: dsh-enterprise-ubuntu-latest-32core-test
+    name: node 24 / static
     env:
-      DSH_COVERAGE_MAX_WORKERS: '16'
-      DSH_ESLINT_CACHE: '1'
-      DSH_ESLINT_CONCURRENCY: '16'
-      DSH_GATE_CONCURRENCY: '10'
-      DSH_PUBLINT_CONCURRENCY: '16'
-      DSH_SNAPSHOT_MAX_CONCURRENCY: '8'
+      DSH_GATE_CONCURRENCY: '8'
     steps:
       - uses: actions/checkout@v6
         with:
@@ -54,6 +50,103 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
 
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+      - name: Enable corepack and install dependencies
+        run: |
+          corepack enable
+          pnpm install --frozen-lockfile
+
+      - name: Run static gates
+        run: pnpm run check:ci:static
+
+      - name: Pack built tree
+        run: >-
+          tar -czf "$RUNNER_TEMP/node-24-built-tree.tar.gz"
+          apps/*/lib packages/*/*/lib vendor/*/lib
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: node-24-built-tree
+          path: ${{ runner.temp }}/node-24-built-tree.tar.gz
+          if-no-files-found: error
+          retention-days: 1
+          compression-level: 0
+
+  node-24-coverage:
+    if: github.event_name == 'pull_request'
+    runs-on: dsh-enterprise-ubuntu-24-04-32core-test
+    name: node 24 / coverage
+    env:
+      DSH_COVERAGE_MAX_WORKERS: '24'
+      DSH_GATE_CONCURRENCY: '8'
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: actions/cache/restore@v4
+        with:
+          path: /home/runner/.local/share/pnpm/store/v11
+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+      - name: Enable corepack, install dependencies, and prepare bubblewrap
+        run: |
+          corepack enable
+          pnpm install --frozen-lockfile &
+          install_pid=$!
+          bash scripts/prepare-ci-bubblewrap.sh &
+          sandbox_pid=$!
+          install_status=0
+          wait "$install_pid" || install_status=$?
+          sandbox_status=0
+          wait "$sandbox_pid" || sandbox_status=$?
+          if (( install_status != 0 )); then exit "$install_status"; fi
+          exit "$sandbox_status"
+
+      - name: Run exhaustive coverage
+        run: pnpm run check:ci:coverage
+
+  node-24-consumers:
+    needs: node-24
+    if: github.event_name == 'pull_request'
+    runs-on: dsh-enterprise-ubuntu-latest-32core-test
+    name: node 24 / snapshots and artifacts
+    env:
+      DSH_ESLINT_CACHE: '1'
+      DSH_ESLINT_CONCURRENCY: '8'
+      DSH_GATE_CONCURRENCY: '8'
+      DSH_NODE_COMPAT_SKIP_TYPECHECK: '1'
+      DSH_PUBLINT_CONCURRENCY: '8'
+      DSH_SNAPSHOT_MAX_CONCURRENCY: '32'
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: node-24-built-tree
+          path: ${{ runner.temp }}
+
+      - name: Restore built tree
+        run: tar -xzf "$RUNNER_TEMP/node-24-built-tree.tar.gz"
+
+      - uses: actions/cache/restore@v4
+        with:
+          path: /home/runner/.local/share/pnpm/store/v11
+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
       - uses: actions/cache/restore@v4
         with:
           path: .cache/eslint
@@ -79,8 +172,45 @@ jobs:
           if (( install_status != 0 )); then exit "$install_status"; fi
           exit "$sandbox_status"
 
-      - name: Run complete unsharded primary Node CI concurrently
-        run: pnpm run check:ci
+      - name: Run compatibility, snapshot, and artifact gates
+        run: |
+          pnpm run check:ci:lint &
+          lint_pid=$!
+          pnpm run check:node-compat &
+          compat_pid=$!
+          DSH_EXAMPLE_MODE=lib pnpm run test:snapshot &
+          snapshot_pid=$!
+          pnpm run publint &
+          publint_pid=$!
+          pnpm run verify-node-next-types &
+          node_next_pid=$!
+          pnpm run verify-built-package-invariants &
+          built_invariants_pid=$!
+          DSH_EXAMPLE_MODE=lib pnpm exec vitest run --config vitest.e2e.config.ts \
+            examples/headless-agent/tests/keyless-smoke.e2e.ts \
+            examples/tui-agent/tests/tui-keyless-smoke.e2e.ts \
+            packages/examples/cli-demo/tests/built-bin.e2e.ts \
+            packages/examples/acp-demo/tests/built-bin.e2e.ts \
+            packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts \
+            packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts \
+            packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts &
+          built_bin_pid=$!
+
+          final_status=0
+          capture_status() {
+            local child_status=0
+            wait "$1" || child_status=$?
+            if (( final_status == 0 && child_status != 0 )); then
+              final_status=$child_status
+            fi
+          }
+          for child_pid in \
+            "$lint_pid" "$compat_pid" "$snapshot_pid" \
+            "$publint_pid" "$node_next_pid" "$built_invariants_pid" "$built_bin_pid"
+          do
+            capture_status "$child_pid"
+          done
+          exit "$final_status"
 
 
   node-compat:
@@ -148,27 +278,19 @@ jobs:
         run: uv run --python 3.10 --group test --project python/sdk pytest
 
   # One Windows box shares setup across the required build/site checks and the
-  # complete observational portability inventory. run-gates reports failures
-  # from observational gates without allowing them to fail the required job.
+  # observational portability inventory. Linux owns duplicate lint, coverage,
+  # and snapshots so they do not dominate the paid Windows critical path.
   windows:
     if: github.event_name == 'pull_request'
     runs-on: dsh-enterprise-windows-2025-32core-test
     name: windows node 24 / complete
     env:
       DSH_COVERAGE_MAX_WORKERS: '12'
-      DSH_ESLINT_CACHE: '1'
       DSH_GATE_CONCURRENCY: '16'
       DSH_PUBLINT_CONCURRENCY: '16'
     steps:
       - uses: actions/checkout@v6
 
-      - uses: actions/cache/restore@v4
-        with:
-          path: .cache/eslint
-          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'tsconfig.base.json', 'tsconfig.base.client.json', 'tsconfig.host.json', 'tsconfig.client.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
-          restore-keys: |
-            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full-
-
       - name: Enable Developer Mode (symlink support)
         shell: pwsh
         run: >-
@@ -565,7 +687,7 @@ jobs:
   all-checks-passed:
     name: all checks passed
     runs-on: ubuntu-latest
-    needs: [node-24, node-compat, python-sdk, windows]
+    needs: [node-24, node-24-coverage, node-24-consumers, node-compat, python-sdk, windows]
     if: always() && github.event_name == 'pull_request'
     steps:
       - name: Fail if any needed job did not succeed
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 41a7a06404..c6390e407a 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: 27774fd3e0ffc821e7287f6153906a5d21530dc2
-README.zh.md: b7d08f2bc948d0a6d388dd672c5a702bc7da6f6f
+README.md: 8b3a46081503ac9a29cc791cc302066e33e0f995
+README.zh.md: c73e2c70119d5b82d4629041a7a16848f7acbe92
diff --git a/README.md b/README.md
index 27774fd3e0..8b3a460815 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ The installer clones DeepSeek Harness to `~/.dsh/source`, links `dsh` into `~/.l
 For the recommended local interface, build the frontend after installation and after each update, then start the Web UI:
 
 ```sh
-pnpm --dir ~/.dsh/source run build:web
+pnpm --dir ~/.dsh/source run build && pnpm --dir ~/.dsh/source run build:web
 dsh web
 ```
 
diff --git a/README.zh.md b/README.zh.md
index b7d08f2bc9..c73e2c7011 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -25,7 +25,7 @@ curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/m
 推荐在本地使用 Web UI。安装完成后以及每次更新后，请先构建前端，再启动 Web UI：
 
 ```sh
-pnpm --dir ~/.dsh/source run build:web
+pnpm --dir ~/.dsh/source run build && pnpm --dir ~/.dsh/source run build:web
 dsh web
 ```
 
diff --git a/apps/cli/README.md b/apps/cli/README.md
index 15765090a0..43360ef589 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -7,12 +7,12 @@ Argv is parsed once through a [Commander](https://github.com/tj/commander.js) ad
 The TUI surface:
 
 - boots the shipped default config (`examples/tui-agent/cordis.yml`) or an explicit config argument, through [`dsh-app-boot`](../../packages/ui/app-boot/README.md);
-- resumes a persisted session with `dsh --resume <session-id>` — the form the TUI prints on exit and lists under `/resume`; the flag sets `RESUME_SESSION_ID` before boot so the shipped config rehydrates that session, and a missing or unreadable id fails loud and exits nonzero;
+- 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 flag; runtimes without process replacement keep the displayed command fallback, the flag still sets `RESUME_SESSION_ID` before boot, 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;
 - 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)): `.env` fills environment gaps (ambient > project `.env` > personal `.env`), `config.yaml` patches the booted tree.
 
-The Web surface treats its invoking directory as the default project and loads applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget.
+The Web surface treats its invoking directory as the default project, loads applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opts into first-message model titles. The headless surface retains deterministic fallback titles without making the auxiliary title-model request.
 
 ## Install (developer machine)
 
@@ -22,4 +22,4 @@ Symlink the source-running launcher onto your PATH; it resolves the checkout thr
 ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh
 ```
 
-`pnpm run demo:tui` runs the same entry from the repo root. The built form (`lib/bin.js`, via `pnpm run build`) needs `node --expose-internals` for the shipped config's HMR entry, exactly like the demo bins.
+`pnpm run demo:tui` runs the same entry from the repo root. The built form (`lib/bin.js`, via `pnpm run build`) boots the same config under plain Node.
diff --git a/apps/cli/package.json b/apps/cli/package.json
index 791a44f98b..d87132798c 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -14,12 +14,24 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-hmr": "workspace:^",
+    "@deepseek-ai/dsh-client-i18n": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-question": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
     "@deepseek-ai/dsh-frontend": "workspace:^",
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
     "@deepseek-ai/dsh-host-runtime": "workspace:^",
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "commander": "^15.0.0"
+    "@deepseek-ai/dsh-tui": "workspace:^",
+    "commander": "^15.0.0",
+    "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.ts
index e45393e8c6..61e99cca44 100644
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -31,11 +31,12 @@ interface HeadlessInvocation {
   prompt: string
 }
 
-/** Browser UI: `dsh web`. Host constrained to {@link LOOPBACK_HOST}/{@link ALL_INTERFACES_HOST}; port already coerced and range-checked. */
+/** Browser UI: `dsh web`. Host constrained to {@link LOOPBACK_HOST}/{@link ALL_INTERFACES_HOST}; port already coerced and range-checked; `dev` mounts the client HMR driver and bundle watch. */
 interface WebInvocation {
   mode: 'web'
   host: string
   port: number
+  dev: boolean
 }
 
 /** `--help` or `--version` requested: `bin.ts` prints `text` to stdout and exits 0. */
@@ -108,10 +109,11 @@ function parseWeb(argv: readonly string[], version: string): DshInvocation {
     .description('serve the browser UI')
     .addOption(new Option('--host <host>', 'bind host').choices([LOOPBACK_HOST, ALL_INTERFACES_HOST]).default(LOOPBACK_HOST))
     .addOption(new Option('--port <port>', 'listen port').default(DEFAULT_WEB_PORT).argParser(parsePort))
+    .option('--dev', 'mount the client HMR driver and watch plugin bundles for rebuilds')
   const settled = settle(web, argv, sink)
   if (settled !== undefined) return settled
-  const { host, port } = web.opts<{ host: string; port: number }>()
-  return { mode: 'web', host, port }
+  const { host, port, dev } = web.opts<{ host: string; port: number; dev?: boolean }>()
+  return { mode: 'web', host, port, dev: dev ?? false }
 }
 
 /** Parse the default (TUI / headless) arguments: `[config]`, `-p/--prompt`, `--resume`. */
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index 5880c68407..3e5f38a859 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -32,7 +32,7 @@ const invocation = parseDshArgs(process.argv.slice(2), readVersion())
 switch (invocation.mode) {
   case 'web': {
     const { runWeb } = await import('./web.ts')
-    await runWeb(invocation.host, invocation.port)
+    await runWeb(invocation.host, invocation.port, invocation.dev)
     break
   }
   case 'headless': {
diff --git a/apps/cli/src/tui.ts b/apps/cli/src/tui.ts
index aa8fb9af5f..819cb22e42 100644
--- a/apps/cli/src/tui.ts
+++ b/apps/cli/src/tui.ts
@@ -18,18 +18,15 @@ import {
   installFailLoud,
   loadEnv,
   loadPersonalPatches,
+  RESUME_SESSION_ID_KEY,
   resolveConfigPath,
 } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import type { Context } from 'cordis'
+import type { TuiResumeHost } from '@deepseek-ai/dsh-tui'
 
 const NAME = 'dsh'
 
-// The env var the shipped tui-agent config reads (`resumeSessionId: !!js
-// process.env.RESUME_SESSION_ID`) to rehydrate a persisted session. The
-// `--resume <id>` flag is CLI sugar that sets it before boot, so the printed
-// `dsh --resume <id>` exit hint runs back through this same intake.
-const RESUME_SESSION_ID_ENV = 'RESUME_SESSION_ID'
-
 // Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit
 // one directory under apps/cli, so the shipped default config resolves with
 // the same relative hop from either artifact.
@@ -47,7 +44,9 @@ const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
  * @param config - a config path to boot instead of the shipped default, or
  * `undefined` for the default; already parsed from the optional positional.
  * @param resumeSessionId - a persisted session id to resume, or `undefined`;
- * already parsed and non-empty-validated from `--resume`.
+ * already parsed and non-empty-validated from `--resume`. It is provided on the
+ * boot context under {@link RESUME_SESSION_ID_KEY}, which the shipped config
+ * reads through `!!js` to rehydrate that session.
  */
 export async function runTui(config: string | undefined, resumeSessionId: string | undefined): Promise<void> {
   // Refuse pipes BEFORE booting: a compose-time throw inside the Loader tree
@@ -61,10 +60,48 @@ export async function runTui(config: string | undefined, resumeSessionId: string
   // The bin already loaded the invoking directory's .env; the personal .env
   // only fills what is still unset (process.loadEnvFile never overrides).
   loadEnv(NAME, resolveDshHome())
-  // An explicit `--resume` flag beats any ambient RESUME_SESSION_ID, so set it
-  // after loadEnv and before boot reads it through the config's `!!js`.
-  if (resumeSessionId !== undefined) process.env[RESUME_SESSION_ID_ENV] = resumeSessionId
-  const ctx = await boot(NAME, resolveConfigPath(config ?? DEFAULT_CONFIG, undefined), loadPersonalPatches(NAME))
+  // The in-place `/resume` handoff re-execs `dsh` with a normalized `--resume`
+  // flag, so the resumed process rehydrates through this same intake. The host
+  // is offered only when Node exposes `process.execve` and knows its own entry.
+  const entry = process.argv[1]
+  const execve = process.execve?.bind(process)
+  const app: { current?: Context } = {}
+  const resumeHost: TuiResumeHost | undefined = entry === undefined || execve === undefined ? undefined : {
+    async handoff(sessionId): Promise<never> {
+      const current = app.current
+      if (current === undefined) throw new Error(`${NAME}: app boot has not completed`)
+      // Rebuild argv from the parsed config plus the selected id: TUI mode's
+      // only arguments are the optional config positional and `--resume <id>`.
+      const nextArgv = [
+        process.execPath,
+        ...process.execArgv,
+        entry,
+        ...config !== undefined ? [config] : [],
+        '--resume',
+        sessionId,
+      ]
+      try {
+        await current.fiber.dispose()
+        execve(process.execPath, nextArgv, process.env)
+        throw new Error('process replacement returned unexpectedly')
+      } catch (error) {
+        process.stderr.write(`${NAME}: resume handoff failed after terminal release: ${String(error)}\n`)
+        process.exit(1)
+      }
+    },
+  }
+  const ctx = await boot(
+    NAME,
+    resolveConfigPath(config ?? DEFAULT_CONFIG, undefined),
+    loadPersonalPatches(NAME),
+    (hostCtx) => {
+      // Inject the resume id (or undefined) so the shipped config's `!!js`
+      // reads it as a bare identifier; then offer the in-place handoff host.
+      hostCtx.provide(RESUME_SESSION_ID_KEY, resumeSessionId)
+      if (resumeHost !== undefined) hostCtx.provide('tuiResumeHost', resumeHost)
+    },
+  )
+  app.current = ctx
   addHarnessSourceSection(ctx, SOURCE_ROOT)
 }
 /* v8 ignore stop */
diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts
index 106585529f..ed6e0a4e1d 100644
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -10,30 +10,83 @@ import { mountWebPlugins, startHost } from '@deepseek-ai/dsh-host-runtime'
 import { createHostWebPluginRegistry, startWebServer } from '@deepseek-ai/dsh-host-webserver'
 import { ALL_INTERFACES_HOST, LOOPBACK_HOST } from './args.ts'
 
+// --- Client composition (composition decisions live in the composing app) ---
+// The composition layer owns one decision: which plugin packages mount (the
+// roster). Dependency edges and the boot prefetch tier live in each package's
+// dshClient declaration.
+
 /**
- * Serve the browser UI. Host and port are already validated by the argument
- * adapter (host constrained to loopback/all-interfaces, port a 0–65535 integer).
+ * Dev-only plugin: the client HMR driver. Whether it composes in is a
+ * deployment decision — the dev graph includes its row, the prod graph does
+ * not mount it at all.
+ */
+const CLIENT_HMR_ID = '@deepseek-ai/dsh-client-hmr'
+
+/** Bundle stat-poll interval for --dev (held here so the startup log states the real value). */
+const CLIENT_BUNDLE_POLL_MS = 500
+
+/** The client plugin roster (flat; per-row boot behavior comes from manifests). */
+const CLIENT_PACKAGES = [
+  '@deepseek-ai/dsh-client-connection',
+  '@deepseek-ai/dsh-client-runtime',
+  '@deepseek-ai/dsh-client-ui-theme',
+  '@deepseek-ai/dsh-client-i18n',
+  '@deepseek-ai/dsh-client-ui-layout',
+  '@deepseek-ai/dsh-client-ui-sidebar',
+  '@deepseek-ai/dsh-client-ui-conversation',
+  '@deepseek-ai/dsh-client-ui-question',
+  '@deepseek-ai/dsh-client-ui-trajectory',
+] as const
+
+/**
+ * Serve the browser UI. Host, port, and dev are already validated by the
+ * argument adapter (host constrained to loopback/all-interfaces, port a
+ * 0–65535 integer).
  * @param hostAddress - the bind host: {@link LOOPBACK_HOST} or {@link ALL_INTERFACES_HOST}.
  * @param port - the listen port; `0` lets the OS choose a free port.
+ * @param dev - mount the client HMR driver and watch plugin bundles for rebuilds.
  */
-export async function runWeb(hostAddress: string, port: number): Promise<void> {
+export async function runWeb(hostAddress: string, port: number, dev: boolean): Promise<void> {
   // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
   const host = await startHost({
     boot: {
       persistenceRoot: './.sessions',
       workspaceContext: { maxBytes: 65_536 },
+      sessionTitleLlm: true,
     },
   })
 
-  // Web UI plugin chain: in-memory Loader tree over the eight UI packages,
-  // then the registry that feeds __DSH_BOOT__ and /plugins/<id>/client.js.
-  const mounted = await mountWebPlugins(host.ctx)
+  // Client plugin chain: in-memory Loader tree over the composed roster, then
+  // the registry that feeds the __DSH_BOOT__ entry graph and
+  // /plugins/<id>/client.js. All row content comes from dshClient discovery
+  // over the mounted roster (dev adds the HMR driver row and turns on the
+  // bundle watch that drives rebuilt frames).
+  const roster = [...CLIENT_PACKAGES, ...dev ? [CLIENT_HMR_ID] : []]
+  const mounted = await mountWebPlugins(host.ctx, roster, import.meta.url)
   const webPlugins = createHostWebPluginRegistry({
     ctx: host.ctx,
     loader: mounted.loader,
     resolvePkgJson: mounted.resolvePkgJson,
     onError: (err: Error) => { process.stderr.write(`dsh web: plugin rescan: ${String(err)}\n`) },
+    ...dev ? { watch: { intervalMs: CLIENT_BUNDLE_POLL_MS } } : {},
   })
+  if (dev) {
+    // Dev visibility (the registry is a library and never prints): list what
+    // the bundle watch covers, then log every observed rebuild. This is a
+    // second onRebuilt subscription — the SSE relay inside the webserver is
+    // unaffected (multicast).
+    const revs = new Map(webPlugins.graph().entries.map(row => [row.id, row.rev]))
+    const bundlePaths = [...revs.keys()]
+      .map(id => webPlugins.clientPath(id))
+      .filter((path): path is string => path !== undefined)
+    console.log(
+      `dsh web: watching ${String(bundlePaths.length)} plugin bundles (${String(CLIENT_BUNDLE_POLL_MS)}ms poll):\n  ${bundlePaths.join('\n  ')}`,
+    )
+    webPlugins.onRebuilt((id, rev) => {
+      console.log(`dsh web: plugin rebuilt: ${id} rev ${revs.get(id) ?? '?'} -> ${rev}`)
+      revs.set(id, rev)
+    })
+  }
   // Published so the webserver invariant companion can audit manifest/bundle
   // consistency; nothing else reads this key.
   host.ctx.reflect.provide('webPlugins', webPlugins)
diff --git a/apps/cli/tests/args.spec.ts b/apps/cli/tests/args.spec.ts
index c9d3c236ad..f207a04f43 100644
--- a/apps/cli/tests/args.spec.ts
+++ b/apps/cli/tests/args.spec.ts
@@ -9,9 +9,10 @@ describe('parseDshArgs', () => {
     expect(parse(['custom.yml'])).toEqual({ mode: 'tui', config: 'custom.yml' })
     expect(parse(['--resume', 'sess', 'app.yml'])).toEqual({ mode: 'tui', config: 'app.yml', resume: 'sess' })
     expect(parse(['-p', 'do the thing'])).toEqual({ mode: 'headless', prompt: 'do the thing' })
-    expect(parse(['web'])).toEqual({ mode: 'web', host: LOOPBACK_HOST, port: 3080 })
+    expect(parse(['web'])).toEqual({ mode: 'web', host: LOOPBACK_HOST, port: 3080, dev: false })
     expect(parse(['web', '--host', ALL_INTERFACES_HOST, '--port', '8080']))
-      .toEqual({ mode: 'web', host: ALL_INTERFACES_HOST, port: 8080 })
+      .toEqual({ mode: 'web', host: ALL_INTERFACES_HOST, port: 8080, dev: false })
+    expect(parse(['web', '--dev'])).toEqual({ mode: 'web', host: LOOPBACK_HOST, port: 3080, dev: true })
   })
 
   it('fails loud instead of silently starting fresh or serving on bad input', () => {
diff --git a/apps/cli/tsconfig.json b/apps/cli/tsconfig.json
index ee9382171a..b33280943a 100644
--- a/apps/cli/tsconfig.json
+++ b/apps/cli/tsconfig.json
@@ -8,12 +8,59 @@
     "src"
   ],
   "references": [
-    { "path": "../../vendor/cordis" },
-    { "path": "../../packages/host/apiproxy" },
-    { "path": "../../packages/host/runtime" },
-    { "path": "../../packages/host/webserver" },
-    { "path": "../../packages/core/session" },
-    { "path": "../../packages/ui/app-boot" },
-    { "path": "../../packages/util/paths" }
+    {
+      "path": "../../vendor/cordis"
+    },
+    {
+      "path": "../../packages/host/apiproxy"
+    },
+    {
+      "path": "../../packages/host/runtime"
+    },
+    {
+      "path": "../../packages/host/webserver"
+    },
+    {
+      "path": "../../packages/core/session"
+    },
+    {
+      "path": "../../packages/ui/app-boot"
+    },
+    {
+      "path": "../../packages/ui/tui"
+    },
+    {
+      "path": "../../packages/util/paths"
+    },
+    {
+      "path": "../../packages/client/connection"
+    },
+    {
+      "path": "../../packages/client/hmr"
+    },
+    {
+      "path": "../../packages/client/runtime"
+    },
+    {
+      "path": "../../packages/client/ui-theme"
+    },
+    {
+      "path": "../../packages/client/i18n"
+    },
+    {
+      "path": "../../packages/client/ui-layout"
+    },
+    {
+      "path": "../../packages/client/ui-sidebar"
+    },
+    {
+      "path": "../../packages/client/ui-conversation"
+    },
+    {
+      "path": "../../packages/client/ui-trajectory"
+    },
+    {
+      "path": "../../packages/client/ui-question"
+    }
   ]
 }
diff --git a/apps/web/package.json b/apps/web/package.json
index 1b55f75d0d..a6b5a9b43f 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -20,7 +20,7 @@
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-modules": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-client-web-react": "workspace:^",
diff --git a/apps/web/src/node-module-stub.ts b/apps/web/src/node-module-stub.ts
new file mode 100644
index 0000000000..c64f307f7c
--- /dev/null
+++ b/apps/web/src/node-module-stub.ts
@@ -0,0 +1,16 @@
+/**
+ * Browser stand-in for `node:module`, mapped by the vite alias in
+ * vite.config.ts (design §2.4). The vendored Loader's internal.ts imports
+ * `createRequire` at module scope but only calls it inside
+ * `ModuleLoader.fromInternal()`, whose version probe is compiled to the
+ * `"0.0.0"` define in the browser build — so this throw is a fail-loud
+ * tripwire for any path that would genuinely need Node's module machinery.
+ */
+
+/** Throwing stand-in for node:module's createRequire (never reached in the browser boot). */
+export const createRequire = (): never => {
+  throw new Error('node:module is not available in the browser')
+}
+
+/** Erased type peer for the vendored loader's type-only LoadHookContext import. */
+export type LoadHookContext = never
diff --git a/apps/web/tests/session-title.snapshot.ts b/apps/web/tests/session-title.snapshot.ts
new file mode 100644
index 0000000000..78023d5455
--- /dev/null
+++ b/apps/web/tests/session-title.snapshot.ts
@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { act, cleanup, fireEvent, screen, waitFor, within } from '@testing-library/react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import type { WebBootEntry } from '@deepseek-ai/dsh-client-modules'
+import { bootWebShell } from '@deepseek-ai/dsh-client-web'
+
+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-i18n', dir: 'i18n', url: '/plugins/i18n.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'] },
+  { id: '@deepseek-ai/dsh-client-ui-trajectory', dir: 'ui-trajectory', 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'),
+]))
+
+interface FixtureTiming {
+  appendTitle(id: string, title: string): void
+}
+
+interface FixtureWindow extends Window {
+  __DSH_BOOT__?: { rev: string; entries: WebBootEntry[] }
+  __ModuleLoader__?: unknown
+}
+
+class ResizeObserverStub {
+  observe(): void {}
+  disconnect(): void {}
+  unobserve(): void {}
+}
+
+const win = window as FixtureWindow
+let unmount: (() => void) | undefined
+
+beforeEach(() => {
+  localStorage.clear()
+  history.replaceState(null, '', '/?fixture')
+  document.title = 'DeepSeek Harness'
+  const root = document.createElement('div')
+  root.id = 'root'
+  document.body.appendChild(root)
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+    setTimeout(() => { callback(0) }, 0) as unknown as number)
+  vi.stubGlobal('cancelAnimationFrame', (id: number) => { clearTimeout(id) })
+  win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ dir: _dir, ...plugin }) => plugin) }
+})
+
+afterEach(() => {
+  act(() => { unmount?.() })
+  unmount = undefined
+  cleanup()
+  delete win.__DSH_BOOT__
+  delete win.__ModuleLoader__
+  delete (globalThis as Record<string, unknown>).__fxTiming
+  document.body.innerHTML = ''
+  document.head.querySelectorAll('style[data-plugin]').forEach((style) => { style.remove() })
+  document.title = ''
+  history.replaceState(null, '', '/')
+  vi.unstubAllGlobals()
+})
+
+/** Read only the stable, user-facing title surfaces from the assembled app. */
+function titleSurfaces(label: string): { sidebar: string; breadcrumb: string; documentTitle: string } {
+  const tree = screen.getByRole('tree', { name: 'Sessions' })
+  const sidebar = within(tree).getByText(label).textContent ?? ''
+  const breadcrumb = within(screen.getByRole('navigation', { name: '会话层级' }))
+    .getByRole('button', { name: label }).textContent ?? ''
+  return { sidebar, breadcrumb, documentTitle: document.title }
+}
+
+it('projects initial and revised durable titles through the built eight-plugin fixture app', async () => {
+  const root = document.querySelector<HTMLElement>('#root')
+  if (root === null) throw new Error('snapshot root missing')
+  act(() => {
+    unmount = bootWebShell(root, {
+      fetchBundle: (url) => {
+        const code = bundles.get(url)
+        return code === undefined ? Promise.reject(new Error(`missing built bundle ${url}`)) : Promise.resolve(code)
+      },
+      executeBundle: (code) => { (0, eval)(code) },
+    })
+  })
+
+  const projectLabel = await screen.findByText('fixture', {}, { timeout: 10_000 })
+  const projectRow = projectLabel.closest<HTMLElement>('[role="treeitem"]')
+  if (projectRow === null) throw new Error('fixture project row missing')
+  fireEvent.click(projectRow)
+
+  const initialLabel = 'Fixture 历史会话'
+  const initialRowLabel = await screen.findByText(initialLabel)
+  const initialRow = initialRowLabel.closest<HTMLElement>('[role="treeitem"]')
+  if (initialRow === null) throw new Error('fixture session row missing')
+  fireEvent.click(initialRow)
+  await waitFor(() => { expect(document.title).toBe(`${initialLabel} — DeepSeek Harness`) })
+  const initial = titleSurfaces(initialLabel)
+
+  const revisedLabel = 'Fixture 修订标题'
+  const timing = (globalThis as Record<string, unknown>).__fxTiming as FixtureTiming
+  act(() => { timing.appendTitle('fx-alpha', revisedLabel) })
+  await waitFor(() => { expect(document.title).toBe(`${revisedLabel} — DeepSeek Harness`) })
+  const revised = titleSurfaces(revisedLabel)
+
+  await expect(`${JSON.stringify({ initial, revised }, null, 2)}\n`)
+    .toMatchFileSnapshot('./snapshots/session-title.json')
+})
diff --git a/apps/web/tests/smoke-fixture.e2e.ts b/apps/web/tests/smoke-fixture.e2e.ts
index 3fccde9a79..0726d14c8b 100644
--- a/apps/web/tests/smoke-fixture.e2e.ts
+++ b/apps/web/tests/smoke-fixture.e2e.ts
@@ -1,39 +1,67 @@
-// Keyless boot-chain smoke over the REAL carrier: startWebServer + web-plugins
-// registry surface + __DSH_BOOT__ injection + built shell dist in a real
-// chromium. First describe: manifest injection + static serving. Second
-// describe: the settled success pass — seven REAL tsdown bundles (the
-// infrastructure four + layout/sidebar/conversation) load through the DI
-// chain in ?fixture mode and the three-column frame appears in one flip. The
-// full conversation round lands in smoke-real under the W5 real-host standard.
+// Keyless boot-chain smoke over the REAL carrier: startWebServer + entry
+// graph (__DSH_BOOT__ web2 shape) injection + built shell dist in a real
+// chromium. First describe: graph injection + the fail-loud half. Second
+// describe: the settled success pass — all nine REAL tsdown bundles load
+// through the module system + vendored Loader chain in ?fixture mode (the
+// infrastructure four ride the immediately prefetch tier, the UI rows fetch
+// on demand), the three-column frame appears in one flip, and the resident
+// question completes through the real UI stack. The full model round lands
+// in smoke-real under the W5 real-host standard.
 import { existsSync } from 'node:fs'
 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 { startWebServer } from '@deepseek-ai/dsh-host-webserver'
-import type { WebPluginBootEntry } from '@deepseek-ai/dsh-host-webserver'
+import type { WebBootEntry, WebBootGraph } from '@deepseek-ai/dsh-host-webserver'
 import { DIST_INDEX, probeFreePort, requireDist, saveFailureShot } from './support.ts'
 
 const bundlePath = (dir: string): string =>
   fileURLToPath(new URL(`../../../packages/client/${dir}/lib/client.js`, import.meta.url))
 
-/** id ↔ bundle table for the success pass (immediately four + layout/sidebar). */
-const REAL_PLUGINS: { id: string; dir: string; inject: string[]; immediately?: boolean }[] = [
-  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', inject: [], immediately: true },
+const LAYOUT_ID = '@deepseek-ai/dsh-client-ui-layout'
+const SIDEBAR_ID = '@deepseek-ai/dsh-client-ui-sidebar'
+
+/** id ↔ bundle table for the success pass (the complete Web UI assembly). */
+const REAL_PLUGINS: { id: string; dir: string; inject?: string[]; immediately?: boolean }[] = [
+  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', immediately: true },
   { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true },
-  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-i18n', dir: 'i18n', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-ui-layout', dir: 'ui-layout', inject: ['@deepseek-ai/dsh-client-runtime'] },
-  { id: '@deepseek-ai/dsh-client-ui-sidebar', dir: 'ui-sidebar', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
-  { id: '@deepseek-ai/dsh-client-ui-conversation', dir: 'ui-conversation', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', immediately: true },
+  { id: '@deepseek-ai/dsh-client-i18n', dir: 'i18n', immediately: true },
+  { id: LAYOUT_ID, dir: 'ui-layout', inject: ['@deepseek-ai/dsh-client-runtime'] },
+  { id: SIDEBAR_ID, dir: 'ui-sidebar', inject: [LAYOUT_ID] },
+  { id: '@deepseek-ai/dsh-client-ui-conversation', dir: 'ui-conversation', inject: [LAYOUT_ID] },
+  { id: '@deepseek-ai/dsh-client-ui-question', dir: 'ui-question', inject: ['@deepseek-ai/dsh-client-ui-conversation'] },
+  { id: '@deepseek-ai/dsh-client-ui-trajectory', dir: 'ui-trajectory', inject: ['@deepseek-ai/dsh-client-ui-conversation'] },
 ]
 
-/** Manifest served by the fake registry: one live bundle row, one missing row. */
-const ROWS: WebPluginBootEntry[] = [
-  { id: '@deepseek-ai/dsh-client-ui-layout', url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js', inject: [] },
-  { id: '@probe/absent', url: '/plugins/@probe/absent/client.js', inject: [] },
-]
-const LAYOUT_BUNDLE = bundlePath('ui-layout')
+const BUNDLE_PATHS = new Map(REAL_PLUGINS.map(p => [p.id, bundlePath(p.dir)]))
+
+const row = (id: string, extra?: Partial<WebBootEntry>): WebBootEntry =>
+  ({ id, url: `/plugins/${id}/client.js?rev=e2e`, rev: 'e2e', ...extra })
+
+const graphRows: WebBootEntry[] = REAL_PLUGINS.map(p => row(p.id, {
+  ...(p.inject !== undefined ? { inject: p.inject } : {}),
+  ...(p.immediately === true ? { immediately: true } : {}),
+}))
+
+/** Graph for the fail-loud half: the immediately tier, one live UI row, one missing row. */
+const FAIL_GRAPH: WebBootGraph = {
+  rev: 'e2e-fail',
+  entries: [...graphRows.filter(r => r.immediately === true), row(LAYOUT_ID), row('@probe/absent')],
+}
+
+/** Graph for the success pass: the complete assembly. */
+const OK_GRAPH: WebBootGraph = { rev: 'e2e-ok', entries: graphRows }
+
+/** Registry stub over a fixed graph (the real HostWebPluginRegistry is webserver-side production code). */
+function fixedRegistry(graph: WebBootGraph, byId: ReadonlyMap<string, string>) {
+  return {
+    graph: () => graph,
+    clientPath: (id: string) => byId.get(id),
+    onRebuilt: () => () => undefined,
+  }
+}
 
 describe('web boot chain (keyless, real carrier)', () => {
   let server: Awaited<ReturnType<typeof startWebServer>>
@@ -50,10 +78,7 @@ describe('web boot chain (keyless, real carrier)', () => {
       port,
       distIndex: DIST_INDEX,
       apiHandler,
-      webPlugins: {
-        snapshot: () => ROWS,
-        clientPath: id => (id === ROWS[0]!.id ? LAYOUT_BUNDLE : undefined),
-      },
+      webPlugins: fixedRegistry(FAIL_GRAPH, BUNDLE_PATHS),
     }, (err) => { pageErrors.push(`server: ${String(err)}`) })
     browser = await chromium.launch()
     page = await browser.newPage()
@@ -66,16 +91,25 @@ describe('web boot chain (keyless, real carrier)', () => {
     await server?.close()
   })
 
-  it('GET / injects the manifest verbatim', async () => {
+  it('GET / injects the entry graph verbatim', async () => {
     onTestFailed(() => saveFailureShot(page, 'smoke-boot-manifest'))
     const boot = await page.evaluate(() => (window as { __DSH_BOOT__?: unknown }).__DSH_BOOT__)
-    expect(boot).toEqual({ plugins: ROWS })
+    expect(boot).toEqual(FAIL_GRAPH)
   })
 
   it('serves a real bundle through the plugins endpoint', async () => {
-    const res = await page.request.get(`${new URL(page.url()).origin}${ROWS[0]!.url}`)
+    const res = await page.request.get(`${new URL(page.url()).origin}/plugins/${LAYOUT_ID}/client.js`)
     expect(res.status()).toBe(200)
-    expect(await res.text()).toContain('window.DSHClientProxy.loadPlugin')
+    expect(await res.text()).toContain('window.__ModuleLoader__.load')
+  })
+
+  it('boots to the loading page and fail-louds the absent entry', async () => {
+    onTestFailed(() => saveFailureShot(page, 'smoke-boot-fail-loud'))
+    await page.waitForSelector('text=HARNESS', { timeout: 10_000 })
+    await page.waitForSelector('text=Failed to load plugins', { timeout: 10_000 })
+    await page.waitForSelector('text=@probe/absent', { timeout: 2000 })
+    // The real UI must not have flipped in: the gate opens only on settled.
+    expect(await page.locator('[class*="frame"]').count()).toBe(0)
   })
 
   it('applies the token sheets before any plugin CSS', async () => {
@@ -84,8 +118,7 @@ describe('web boot chain (keyless, real carrier)', () => {
   })
 })
 
-describe('web boot chain success pass (keyless, seven real bundles, ?fixture)', () => {
-  const missing = REAL_PLUGINS.filter(p => !existsSync(bundlePath(p.dir)))
+describe('web boot chain success pass (keyless, nine real bundles, ?fixture)', () => {
   let server: Awaited<ReturnType<typeof startWebServer>>
   let browser: Browser
   let page: Page
@@ -93,14 +126,9 @@ describe('web boot chain success pass (keyless, seven real bundles, ?fixture)',
 
   beforeAll(async () => {
     requireDist()
+    const missing = REAL_PLUGINS.filter(p => !existsSync(bundlePath(p.dir)))
     if (missing.length > 0) throw new Error(`client bundles not built (pnpm --filter <pkg> bundle): ${missing.map(m => m.dir).join(', ')}`)
     const port = await probeFreePort()
-    const rows: WebPluginBootEntry[] = REAL_PLUGINS.map((p) => {
-      const row: WebPluginBootEntry = { id: p.id, url: `/plugins/${p.id}/client.js`, inject: p.inject }
-      if (p.immediately === true) row.immediately = true
-      return row
-    })
-    const byId = new Map(REAL_PLUGINS.map(p => [p.id, bundlePath(p.dir)]))
     // ?fixture never opens HTTP streams; /api is a tripwire like the first describe.
     const apiHandler = { fetch: () => Promise.resolve(new Response('fixture mode must not call /api', { status: 500 })) }
     server = await startWebServer({
@@ -108,7 +136,7 @@ describe('web boot chain success pass (keyless, seven real bundles, ?fixture)',
       port,
       distIndex: DIST_INDEX,
       apiHandler,
-      webPlugins: { snapshot: () => rows, clientPath: id => byId.get(id) },
+      webPlugins: fixedRegistry(OK_GRAPH, BUNDLE_PATHS),
     }, (err) => { pageErrors.push(`server: ${String(err)}`) })
     browser = await chromium.launch()
     page = await browser.newPage()
@@ -133,8 +161,8 @@ describe('web boot chain success pass (keyless, seven real bundles, ?fixture)',
   it('every plugin CSS landed with its ownership tag', async () => {
     const owners = await page.evaluate(() =>
       [...document.querySelectorAll('style[data-plugin]')].map(s => (s as HTMLElement).dataset['plugin']))
-    expect(owners).toContain('@deepseek-ai/dsh-client-ui-layout')
-    expect(owners).toContain('@deepseek-ai/dsh-client-ui-sidebar')
+    expect(owners).toContain(LAYOUT_ID)
+    expect(owners).toContain(SIDEBAR_ID)
   })
 
   it('collapsed sidebar animates to a 56px rail with the four controls', async () => {
@@ -147,25 +175,27 @@ describe('web boot chain success pass (keyless, seven real bundles, ?fixture)',
     const settledTrack = async (px: string): Promise<void> => {
       await expect.poll(firstTrack, { timeout: 2000 }).toBe(px)
     }
+    // The brand wordmark is decorative svg (aria-hidden) — presence tracks the wide chrome.
+    const brand = () => page.locator('[class*="brand"]').count()
     await page.getByRole('button', { name: 'Collapse sidebar' }).click()
     // Mid-collapse the wide chrome is still mounted, fading — not swapped out.
-    expect(await page.locator('text=HARNESS').count()).toBe(1)
+    expect(await brand()).toBe(1)
     await settledTrack('56px')
-    await expect.poll(() => page.locator('text=HARNESS').count(), { timeout: 2000 }).toBe(0)
-    for (const name of ['Expand sidebar', 'New session', 'New workspace', 'Search sessions', 'Settings']) {
+    await expect.poll(brand, { timeout: 2000 }).toBe(0)
+    for (const name of ['Open sidebar', 'New session', 'New workspace', 'Search sessions', 'Settings']) {
       await expect(page.getByRole('button', { name }).isVisible(), name).resolves.toBe(true)
     }
-    await page.getByRole('button', { name: 'Expand sidebar' }).click()
-    await settledTrack('300px')
+    await page.getByRole('button', { name: 'Open sidebar' }).click()
+    await settledTrack('280px')
     await expect(page.getByRole('button', { name: 'Collapse sidebar' }).isVisible()).resolves.toBe(true)
     // Rail search: collapse again, the search control expands and lands in the box.
     await page.getByRole('button', { name: 'Collapse sidebar' }).click()
     await settledTrack('56px')
     await page.getByRole('button', { name: 'Search sessions' }).click()
-    await settledTrack('300px')
-    const focused = await page.evaluate(() =>
-      (document.activeElement as HTMLInputElement | null)?.placeholder ?? '')
-    expect(focused).toContain('Search')
+    await settledTrack('280px')
+    // Focus is deferred past the slide (EXPAND_SLIDE_MS) — poll for it.
+    await expect.poll(() => page.evaluate(() =>
+      (document.activeElement as HTMLInputElement | null)?.placeholder ?? ''), { timeout: 2000 }).toContain('Search')
   })
 
   it('renders file tool rows and expands fixture reasoning from either click target', async () => {
@@ -196,6 +226,65 @@ describe('web boot chain success pass (keyless, seven real bundles, ?fixture)',
     expect(await writeRoot.getByText('notes/new-demo.txt', { exact: true }).count()).toBe(1)
   })
 
+  it('keeps Markdown semantic while a fixture reply streams and finalizes', async () => {
+    onTestFailed(() => saveFailureShot(page, 'smoke-markdown-stream'))
+    await page.getByRole('button', { name: 'New session', exact: true }).click()
+    const input = page.locator('textarea[placeholder]')
+    await input.waitFor({ timeout: 15_000 })
+    await input.fill('render markdown')
+    await page.getByRole('button', { name: '发送' }).click()
+
+    const streaming = page.locator('[data-streaming="true"]')
+    await streaming.getByRole('heading', { name: 'Markdown fixture' }).waitFor({ timeout: 15_000 })
+    await streaming.waitFor({ state: 'detached', timeout: 15_000 })
+
+    const finalHeading = page.getByRole('heading', { name: 'Markdown fixture' })
+    expect(await finalHeading.evaluate(element => element.tagName)).toBe('H1')
+    expect(await page.locator('pre code').filter({ hasText: 'const markdown = true' }).count()).toBe(1)
+    const external = page.getByRole('link', { name: 'DeepSeek' })
+    expect(await external.getAttribute('target')).toBe('_blank')
+    expect(await external.getAttribute('rel')).toBe('noopener noreferrer')
+  })
+
+  it('renders and completes the resident question through the composer slot', async () => {
+    onTestFailed(() => saveFailureShot(page, 'smoke-question-composer'))
+    const sessionTree = page.getByRole('tree', { name: 'Sessions' })
+    const projectRow = sessionTree.getByRole('treeitem').filter({ hasText: '3 sessions' })
+    if (await projectRow.getAttribute('aria-expanded') === 'false') await projectRow.click()
+    await sessionTree.getByText('Fixture 历史会话', { exact: true }).click()
+    const composer = page.locator('[data-question-key]')
+    await composer.waitFor({ timeout: 15_000 })
+    expect({
+      question: await composer.getByRole('heading').innerText(),
+      progress: await composer.getByText('1 / 3', { exact: true }).innerText(),
+      options: await composer.getByRole('radio').allTextContents(),
+      custom: await composer.getByRole('button', { name: '其他，请填写自定义答案' }).innerText(),
+    }).toMatchInlineSnapshot(`
+      {
+        "custom": "其他，请填写自定义答案",
+        "options": [
+          "1工程落地型推荐更看重能直接做 runtime、tool executor、sandbox、trace 和线上问题排查。",
+          "2研究潜力型更看重 Agent 理解、训练评测思路和长期成长空间。",
+          "3均衡型同时要求工程能力和 Agent 认知，但可能筛选门槛更高。",
+        ],
+        "progress": "1 / 3",
+        "question": "你现在更想招哪类 Agent/Harness 候选人？",
+      }
+    `)
+
+    await composer.getByRole('radio', { name: '工程落地型' }).click()
+    await composer.getByText('2 / 3', { exact: true }).waitFor()
+    await composer.getByRole('button', { name: '跳过本题', exact: true }).click()
+    await composer.getByRole('checkbox', { name: '系统设计' }).click()
+    await composer.getByRole('checkbox', { name: 'Agent 产品判断' }).click()
+    await composer.getByRole('checkbox', { name: 'Agent 产品判断' }).press('Enter')
+
+    await composer.waitFor({ state: 'detached' })
+    const restoredInput = page.locator('textarea[placeholder]')
+    await restoredInput.waitFor()
+    expect(await restoredInput.getAttribute('placeholder')).toBe('回复生成中，可停止后再输入')
+  })
+
   it('stayed clean: no page errors across the whole load chain', () => {
     expect(pageErrors).toEqual([])
   })
diff --git a/apps/web/tests/smoke-real.e2e.ts b/apps/web/tests/smoke-real.e2e.ts
index 9ccdcad606..9cd34530be 100644
--- a/apps/web/tests/smoke-real.e2e.ts
+++ b/apps/web/tests/smoke-real.e2e.ts
@@ -77,6 +77,55 @@ async function rpc<T>(baseUrl: string, method: string, payload: unknown): Promis
   return body.result.value
 }
 
+interface HistoryPage {
+  events: { event: { type: string; data: unknown } }[]
+  hasMore: boolean
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function providerTitle(page: HistoryPage): string | undefined {
+  for (let index = page.events.length - 1; index >= 0; index--) {
+    const event = page.events[index]!.event
+    if (event.type !== 'session/title' || !isRecord(event.data)) continue
+    const source = event.data.source
+    if (typeof event.data.title === 'string' && isRecord(source) && source.kind === 'provider') {
+      return event.data.title
+    }
+  }
+  return undefined
+}
+
+function hasAssistantMarker(page: HistoryPage, marker: string): boolean {
+  return page.events.some(({ event }) => {
+    if (event.type !== 'assistant/message' || !isRecord(event.data) || !Array.isArray(event.data.content)) return false
+    return event.data.content.some(block =>
+      isRecord(block) && block.type === 'text' && typeof block.text === 'string' && block.text.includes(marker))
+  })
+}
+
+async function history(baseUrl: string, sessionId: string): Promise<HistoryPage> {
+  return rpc<HistoryPage>(baseUrl, 'session.history', { sessionId, maxMessages: 10 })
+}
+
+async function waitForProviderTitle(baseUrl: string, sessionId: string): Promise<string> {
+  let observed: string | undefined
+  await expect.poll(async () => {
+    observed = providerTitle(await history(baseUrl, sessionId))
+    return observed
+  }, { timeout: 90_000 }).toEqual(expect.any(String))
+  if (observed === undefined) throw new Error('provider-backed session title was not observed')
+  return observed
+}
+
+async function waitForAssistantMarker(baseUrl: string, sessionId: string, marker: string): Promise<void> {
+  await expect.poll(async () => hasAssistantMarker(await history(baseUrl, sessionId), marker), {
+    timeout: 120_000,
+  }).toBe(true)
+}
+
 /** W5 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`) })
@@ -95,10 +144,11 @@ async function detailsTrack(page: Page): Promise<number> {
   return Number(cols.split(' ').pop()!.replace('px', ''))
 }
 
-// Readiness gate: `dsh web` serves ALL eight manifest plugins; until every UI
+// Readiness gate: `dsh web` serves ALL nine manifest plugins; until every UI
 // plugin's client bundle exists and exports apply, the loader fail-louds and
 // the frame never appears.
-const UI_PLUGIN_DIRS = ['connection', 'runtime', 'ui-theme', 'i18n', 'ui-layout', 'ui-sidebar', 'ui-conversation', 'ui-trajectory']
+const UI_PLUGIN_DIRS = ['connection', 'runtime', 'ui-theme', 'i18n', 'ui-layout', 'ui-sidebar', 'ui-conversation', 'ui-question', 'ui-trajectory']
+const ROUND_DONE_MARKER = 'WEB_ROUND_DONE'
 const notReady = UI_PLUGIN_DIRS.filter((dir) => {
   const bundle = join(REPO_ROOT, 'packages/client', dir, 'lib/client.js')
   return !existsSync(bundle) || !readFileSync(bundle, 'utf8').includes('exports.apply')
@@ -280,7 +330,8 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     const input = page.locator('textarea').first()
     await input.waitFor({ timeout: 10_000 })
     await screen(page, '02-empty-state')
-    await input.fill('请简单介绍事件溯源，两句话即可，最后以「介绍完毕」结尾')
+    const prompt = `Please answer this request carefully: explain event sourcing in two sentences, ending with exactly ${ROUND_DONE_MARKER}.`
+    await input.fill(prompt)
     await input.press('Enter')
     // startSession chain: session mounts, composer moves to the bottom.
     // Regression pin (P0, 585671106): this send used to white-screen the tree
@@ -288,7 +339,32 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     // near-empty here means that class of bug is back.
     await page.waitForFunction(() => document.body.innerText.length > 50, undefined, { timeout: 15_000 })
     expect(pageErrors).toEqual([])
-    await page.waitForFunction(() => document.body.innerText.includes('介绍完毕'), undefined, { timeout: 120_000 })
+    await page.waitForFunction(
+      () => document.title !== 'DeepSeek Harness' && document.title.endsWith(' — DeepSeek Harness'),
+      undefined,
+      { timeout: 15_000 },
+    )
+    await expect.poll(async () => (await rpc<{ items: { sessionId: string }[] }>(baseUrl, 'session.list', {})).items.length, {
+      timeout: 15_000,
+    }).toBe(1)
+    const sessions = await rpc<{ items: { sessionId: string }[] }>(baseUrl, 'session.list', {})
+    const sessionId = sessions.items[0]?.sessionId
+    if (sessionId === undefined) throw new Error('created Web session was not listed')
+    const durableTitle = await waitForProviderTitle(baseUrl, sessionId)
+    await page.waitForFunction(
+      expected => document.title === `${expected} — DeepSeek Harness`,
+      durableTitle,
+      { timeout: 15_000 },
+    )
+    const sessionTree = page.getByRole('tree', { name: 'Sessions' })
+    const projectRow = sessionTree.getByRole('treeitem').first()
+    if (await projectRow.getAttribute('aria-expanded') === 'false') await projectRow.click()
+    await Promise.all([
+      sessionTree.getByText(durableTitle, { exact: true }).waitFor({ timeout: 10_000 }),
+      page.getByRole('navigation').getByText(durableTitle, { exact: true }).waitFor({ timeout: 10_000 }),
+    ])
+    await waitForAssistantMarker(baseUrl, sessionId, ROUND_DONE_MARKER)
+    await page.locator('p').filter({ hasText: ROUND_DONE_MARKER }).waitFor({ timeout: 10_000 })
     await screen(page, '04-round-complete')
   }, 150_000)
 
@@ -308,10 +384,10 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await input.fill('请用 bash 工具运行命令 echo w5marker 然后告诉我结果')
     await input.press('Enter')
     // Wait for the tool ROW, not response text (the reply echoes any marker).
-    // bash renders through the third-party sample registration (data-sample) —
-    // that IS the differential-rendering acceptance; the generic path renders
-    // data-variant rows with the handler on the data-clickable inner row.
-    const toolRow = page.locator('[data-sample], [data-variant] [data-clickable]').first()
+    // Bash renders through the third-party sample registration. Match that
+    // exact row: other clickable variants (for example Think disclosure)
+    // may precede the tool call in document order.
+    const toolRow = page.locator('[data-sample="bash-global"]')
     await toolRow.waitFor({ timeout: 120_000 })
     await screen(page, '08-bash-round')
     expect(await detailsTrack(page)).toBe(0)
@@ -363,7 +439,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     onTestFailed(() => saveFailureShot(page, 'w5-reload'))
     await page.reload({ waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
-    await page.waitForFunction(() => document.body.innerText.includes('介绍完毕'), undefined, { timeout: 30_000 })
+    await page.locator('p').filter({ hasText: ROUND_DONE_MARKER }).waitFor({ timeout: 30_000 })
     await screen(page, '12-reload-recovery')
   })
 
diff --git a/apps/web/tests/snapshots/session-title.json b/apps/web/tests/snapshots/session-title.json
new file mode 100644
index 0000000000..2063036803
--- /dev/null
+++ b/apps/web/tests/snapshots/session-title.json
@@ -0,0 +1,12 @@
+{
+  "initial": {
+    "sidebar": "Fixture 历史会话",
+    "breadcrumb": "Fixture 历史会话",
+    "documentTitle": "Fixture 历史会话 — DeepSeek Harness"
+  },
+  "revised": {
+    "sidebar": "Fixture 修订标题",
+    "breadcrumb": "Fixture 修订标题",
+    "documentTitle": "Fixture 修订标题 — DeepSeek Harness"
+  }
+}
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 8cf0acfd37..998996304e 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -9,14 +9,23 @@
       "DOM",
       "DOM.Iterable"
     ],
-    "types": ["node"]
+    "types": [
+      "node"
+    ]
   },
   "include": [
     "src",
     "tests"
   ],
   "references": [
-    { "path": "../../packages/client/web" },
-    { "path": "../../packages/host/webserver" }
+    {
+      "path": "../../packages/client/web"
+    },
+    {
+      "path": "../../packages/host/webserver"
+    },
+    {
+      "path": "../../packages/client/modules"
+    }
   ]
 }
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 1622371a8a..5a805cbeb3 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -10,17 +10,28 @@ export default defineConfig({
     // Workspace packages resolve to SOURCE: package.json exports point at lib
     // 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 static surface is aliased — UI plugin packages are NOT
-    // bundled here; they arrive as dynamic bundles through the client loader.
-    // Order matters — subpath aliases must win over bare-name prefixes.
+    // Only the shell's normal-package surface is aliased — plugin packages are
+    // NEVER bundled here (web2 shell self-sufficiency); they arrive as runtime
+    // bundles through the client module system. Order matters — subpath
+    // aliases must win over bare-name prefixes.
     alias: [
+      // Browserization of the vendored cordis Loader: its only node-only
+      // import; the two process probes are mapped by `define` below.
+      { find: /^node:module$/, replacement: src('./src/node-module-stub.ts') },
       { find: /^@deepseek-ai\/dsh-client-web$/, replacement: src('../../packages/client/web/src/boot.tsx') },
-      { find: /^@deepseek-ai\/dsh-client-web-react\/store$/, replacement: src('../../packages/client/web-react/src/store/index.ts') },
       { find: /^@deepseek-ai\/dsh-client-web-react$/, replacement: src('../../packages/client/web-react/src/index.ts') },
       { find: /^@deepseek-ai\/dsh-client-ui-slots$/, replacement: src('../../packages/client/ui-slots/src/index.ts') },
       { find: /^@deepseek-ai\/dsh-client-ui-primitives$/, replacement: src('../../packages/client/ui-primitives/src/index.ts') },
-      { find: /^@deepseek-ai\/dsh-client-runtime\/loader$/, replacement: src('../../packages/client/runtime/src/client/loader/index.ts') },
-      { find: /^@deepseek-ai\/dsh-client-runtime$/, replacement: src('../../packages/client/runtime/src/index.ts') },
+      { find: /^@deepseek-ai\/dsh-client-modules$/, replacement: src('../../packages/client/modules/src/index.ts') },
     ],
   },
+  define: {
+    // vendored loader internal.ts: fromInternal() probes the Node major —
+    // "0.0.0" takes neither branch, returning undefined (exactly the empty
+    // internal slot the shell boot fills with the client module loader).
+    'process.versions.node': '"0.0.0"',
+    'process.execArgv': '[]',
+    // vendored loader index.ts: envData falls to its default branch.
+    'process.env.CORDIS_SHARED': 'undefined',
+  },
 })
diff --git a/bin/dsh b/bin/dsh
index 88eaa0ab71..040cfface2 100755
--- a/bin/dsh
+++ b/bin/dsh
@@ -2,7 +2,6 @@
 # dsh launcher: runs the apps/cli `dsh` bin FROM SOURCE with this checkout's
 # tsx, so a symlink from anywhere (e.g. ~/.local/bin/dsh) always executes the
 # current working tree — code changes apply on the next launch, no build step.
-# --expose-internals: the shipped config mounts HMR, which needs Loader internals.
 set -eu
 
 # Resolve symlink chains without readlink -f (not on every macOS).
@@ -19,4 +18,4 @@ root=$(CDPATH='' cd -- "$(dirname -- "$script")/.." && pwd)
 # tsx is imported by absolute path because bare `--import tsx` resolves from
 # the invoking cwd, which is usually outside this repository.
 export TSX_TSCONFIG_PATH="$root/tsconfig.json"
-exec node --expose-internals --import "$root/node_modules/tsx/dist/loader.mjs" "$root/apps/cli/src/bin.ts" "$@"
+exec node --import "$root/node_modules/tsx/dist/loader.mjs" "$root/apps/cli/src/bin.ts" "$@"
diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index b732708e1f..5f1e43eb17 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -17,8 +17,8 @@ sequenceDiagram
   participant Session
   participant Persistence
   participant SDK as UI or SDK listener
-  User->>Agent: send(content)
-  Agent-->>SDK: <code>agent/queued</code>
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/enqueue</code>
   Agent->>Driver: queued work wakes driver
   Driver-->>SDK: <code>agent/status</code> running
   Driver->>Session: <code>turn/start</code>
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index e3c52e2536..214e2c9fba 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
-architecture.md: 6ff2aa1ad4ca2ef051322f9d95631fe626d26e84
-architecture.zh.md: b4b26efec16d85f1fb26589c5c9bffbb35e39564
+architecture.md: 76c58e03282ef6d736da7d65b05c534c05c4c318
+architecture.zh.md: dddccf1e9238e617a453395731ee3f620ba5749d
diff --git a/docs/architecture.md b/docs/architecture.md
index 6ff2aa1ad4..76c58e0328 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -6,7 +6,7 @@ English | [中文](architecture.zh.md)
 
 ## Overview
 
-Harnesses are [Cordis](cordis-primer.md) contexts whose packages contribute services, typed events, and disposable registrations.
+Harnesses are [Cordis](cordis-primer.md) contexts with package-contributed services, typed events, and disposable registrations.
 
 `packages/core/` groups the default agent flow; capabilities remain plugins.
 
@@ -42,14 +42,14 @@ Harnesses are [Cordis](cordis-primer.md) contexts whose packages contribute serv
 | `ctx.tasks` | [`tasks/`](../packages/tasks/README.md) | background task registry + generic `task_*` control tools |
 | `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 storage for session logs |
-| `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | live-preferred logical-corpus exact reads and relationship traces |
-| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | log-backed fallback titles and one optional asynchronous provider |
-| `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | registry and package-name selection for package-owned runtime checks |
+| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable session-log storage |
+| `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | `session-query` interface: concrete live-preferred exact/filter/trace; exactly two abstract FTS methods via `session-query-sqlite` |
+| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | log-backed fallbacks plus one optional asynchronous provider |
+| `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | package-name-selected registry for package-owned runtime checks |
 
 ## Event
 
-Events form the service extension API; see the exhaustive [events catalog](cordis-catalog/events.md) and [producer/consumer map](event-producer-consumer.md).
+Events form the service extension API; see the [catalog](cordis-catalog/events.md) and [producer/consumer map](event-producer-consumer.md).
 
 ### Event Domains
 
@@ -63,11 +63,11 @@ Waterfall events behave like around-middleware: a listener delegates by calling
 
 ## Default Loop Lifecycle
 
-The shipped loop runs prompt-to-checkpoint work through plugin services and events.
+The loop runs through plugin services and events.
 
-A **session** is append-only. Each ordinary **turn** claims one queued `send()` item; injection claims none. A successor awaits the preceding claimed turn's checkpoint but may share its `running` interval ([decision](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)). A turn ends when model and plugins stop it; a **step** is one model request plus tools. In the [sequence below](agent-lifecycle.md), quotes mark durable events.
+A **session** is append-only. Each ordinary **turn** claims one queued message; injection claims none. Successors await the preceding checkpoint but may share its `running` interval ([decision](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)). A **step** is one model request plus tools; quotes in the [sequence below](agent-lifecycle.md) mark durable events.
 
-Without an id, creation mints `<config-id>-session-<uuid>`; `sessionId` resumes or creates, while `resumeSessionId` requires history. Resume restores lineage and delegation depth before publication. Setup failures emit `agent-loop/config-start-failed`; teardown is silent.
+Creation without an id mints `<config-id>-session-<uuid>`; `sessionId` resumes or creates, while `resumeSessionId` requires history. Resume restores lineage and delegation depth before publication. Setup failures emit `agent-loop/config-start-failed`; teardown is silent.
 
 ### Turn Flow
 
@@ -115,37 +115,37 @@ forever:
     checkpoint persistence and notify idle/running status
 ```
 
-Each step assembles ordered prompt sections, tool schemas, and variables; unknown references fail the turn. `dsh-system-prompt` owns identity and persona, while the loop supplies `model` and `cwd` ([prompt ownership](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)).
+Steps assemble ordered prompt sections, tool schemas, and variables; unknown references fail turns. `dsh-system-prompt` owns identity and persona; the loop supplies `model` and `cwd` ([ownership](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)).
 
-Tool-time context—including async `inject()` and post-tool `additionalContexts`—settles after results. Steering drains before `agent/post-step`, which sees durable output, results, context, and steering. Leftovers queue. Terminal `agent/turn-stop` remains authoritative through close/flush; later steering is discarded while queued prompts remain.
+Async `inject()` and post-tool `additionalContexts` settle after results; steering drains before `agent/post-step`. Leftovers queue. Terminal `agent/turn-stop` remains authoritative through close/flush and discards later steering, not queued prompts.
 
-Pruning precedes summaries; overflow retries require durable progress. Bounded transient retries compose on `agent/request-error`; cancellation wins ([compaction](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md), [retry](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)).
+Pruning precedes summaries; overflow retries require durable progress. Bounded retries compose on `agent/request-error`; cancellation wins ([compaction](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md), [retry](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)).
 
 ### Failure Boundaries
 
-Adapter failures close the step before `agent/request-error` with exact `Error`, `LlmFailure`, and history. Retry opens another step; success clears history; exhaustion stores failure on `turn/end`. Failed chunks commit no message/tool.
+Adapter failures close the step before `agent/request-error` with exact `Error`, `LlmFailure`, and history. Retries open steps; success clears history; exhaustion stores failure on `turn/end`. Failed chunks commit nothing.
 
-Other failures use `agent/error`. Cancellation and disposal beat recovery; undispatched tool calls get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. The turn signal retires before `turn/end`. Effective `cancel()` emits its typed cause before clearing queues and aborting; observers cannot veto, idle calls emit nothing, and durability records `aborted`. Disposal awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
+Other failures use `agent/error`. Cancellation and disposal beat recovery; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. The signal retires before `turn/end`. Effective `cancel()` emits its cause, clears queues, and aborts; observers cannot veto, idle calls emit nothing, and durability records `aborted`. Disposal awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
 
-Session events are turn-enclosed. Reload closes an interrupted tail with a synthetic `interrupted` turn end. Post-close failures report only through `agent/error`; no safe in-turn position remains. Each turn has one `TurnEndReason`; [TurnEndReasonMap](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap) owns the variants.
+Session events are turn-enclosed; reload closes an interrupted tail with a synthetic `interrupted` turn end. Post-close failures use `agent/error`. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap).
 
 ### Agent Handles
 
-`ctx.agents` owns live agents and returns `AgentHandle { agent, dispose() }`. Plugins use `send()`, `steer()`, `inject()`, `cancel()`, and `whenIdle()`. The caller fiber, factory provider, and consumer handle co-own teardown through one awaited disposer.
+`ctx.agents` returns `AgentHandle { agent, dispose() }`. Plugins use intent helpers `followup()`, `queue()`, `steer()`, and `inject()`; callers with exact routing facts use mandatory-field `send()` ([decision](../.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.md)). `cancel()` and `whenIdle()` control lifecycle. Caller, provider, and handle co-own teardown.
 
 ### Agent Scope
 
-Each agent owns a scoped `agent.ctx`; shared storage overlays global tool, prompt, and command entries while preserving domain views ([decision](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)). Scoped listeners filter dispatch, and every scoped contribution unwinds with awaited cleanup. `CreateAgentOptions.setup(agentCtx)` composes before publication. Typed resolvers derive carrier checks from merged `Events` and `scopeTarget` ([semantic gates](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)). See [agent scope](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md) and [subagent composition](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md). `AgentLoop` runs inside `ctx.agents.withInitiator()`; private orchestration derives `agent.session`, while turn, step, signal, cwd, and authority remain explicit ([decision](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
+Each agent owns a scoped `agent.ctx` over global tool, prompt, and command storage ([decision](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)); scoped listeners filter and contributions unwind with awaited cleanup. `CreateAgentOptions.setup(agentCtx)` composes before publication; typed resolvers derive carrier checks from `Events` and `scopeTarget` ([gates](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)). `AgentLoop` runs inside `ctx.agents.withInitiator()`; private orchestration derives `agent.session`, while turn, step, signal, cwd, and authority stay explicit ([decision](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)). See [agent scope](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md) and [subagent composition](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md).
 
 ## State
 
 ### Session Log
 
-The session log is authoritative. `deriveMessages()` projects model history; raw `assistant/chunk` events remain for replay and UI fidelity. Fork, resume, transcript rendering, telemetry, and persistence derive from the same stream.
+The session log is authoritative. `deriveMessages()` projects model history; raw `assistant/chunk` events preserve replay and UI fidelity. Fork, resume, transcripts, telemetry, and persistence share that stream.
 
-**Model-visible ⟺ logged**: the log reconstructs every request — messages at `step/start` fronted by the header's session prefix, and headers by folding `request/header` — and the package-owned `dsh-agent-loop/invariant` can assert it through `ctx.invariants` ([reconstructability](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)).
+**Model-visible ⟺ logged**: `step/start` messages plus the header's session prefix and folded `request/header` reconstruct every request; `dsh-agent-loop/invariant` asserts this through `ctx.invariants` ([decision](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)).
 
-Durability is a plugin concern. Backends buffer synchronous `session/event` notifications. The semantic checkpoint policy drains requests before adapter dispatch, recorded top-level calls before tool dispatch, and complete response/result batches at `agent/post-step`; the loop retains the final turn-end checkpoint. `SessionPersistence` stores `SessionEvent` directly and metadata in `SessionHeader`; JSONL defaults to checksummed Zstandard, with SQLite under one contract ([decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)).
+Durability is a plugin concern; backends buffer synchronous `session/event` notifications. Checkpoints drain before adapter dispatch, recorded top-level tool calls before tool dispatch, complete response/result batches at `agent/post-step`, and final turn ends. `SessionPersistence` stores `SessionEvent` plus `SessionHeader` metadata; JSONL defaults to checksummed Zstandard, with SQLite under one contract ([decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)).
 
 `ctx.sessions.appendOutOfBand()` joins plugin-owned log-only events to an open turn or creates a balanced, flushed zero-step turn. `session/title` folds latest-wins with source seqs and provenance; its immediate fallback and sole optional async provider never delay the agent response. Forks inherit titles ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
 
@@ -185,7 +185,7 @@ New behavior attaches to a documented extension point; a loop change updates thi
 | Confine spawned processes | a `ctx.sandbox` backend; consumers wrap their argv before spawning |
 | Intercept a request, tool, or turn | use its `agent/*` or `tools/*` event; `agent/turn-stop` is the serial terminal stop |
 | Add a session-stable prefix outside history | compose `agent/session-prefix`; the request header logs it |
-| Add UI or editor integration | drive `ctx.agents` and render from `session/event` |
+| Add UI or editor integration | drive `ctx.agents` and render from `session/event`; terminal-only overlays use `ctx.tui` |
 | Add durable session state | add a `SessionEventMap` member and render/replay from the log |
 | Add asynchronous session-title generation | register the sole provider on `ctx.sessionTitle` |
 | Manage a same-session objective | use `ctx.goals`; continue through `Agent` and `agent/*` |
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index b4b26efec1..dddccf1e92 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -42,14 +42,14 @@
 | `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.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | 实时优先的逻辑语料精确读取和关系追踪 |
-| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | 基于日志的回退标题和单个可选异步提供方 |
-| `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | 按包名选择包自有运行时检查的注册表 |
+| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | 会话日志的持久化存储 |
+| `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | `session-query` 接口：精确检索、过滤与追踪采用实时优先的具体实现；恰有两个全文搜索方法为抽象方法，由 `session-query-sqlite` 实现 |
+| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | 基于日志的回退标题，以及单个可选的异步提供方 |
+| `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | 按包名筛选包自有运行时检查的注册表 |
 
 ## 事件
 
-事件构成服务的扩展 API；完整清单见[事件目录](cordis-catalog/events.md)和[生产方与消费方映射](event-producer-consumer.md)。
+事件构成服务的扩展 API；参见[事件目录](cordis-catalog/events.md)和[生产方与消费方映射](event-producer-consumer.md)。
 
 ### 事件域
 
@@ -63,9 +63,9 @@ waterfall（瀑布式事件）的行为类似环绕中间件：监听器调用 `
 
 ## 默认循环生命周期
 
-已交付的循环通过插件服务和事件，处理从提示词到检查点的工作。
+循环通过插件服务和事件运行。
 
-**会话**采用仅追加方式。每个普通**轮次**领取一项已排队的 `send()` 输入；注入不领取输入。后续轮次会等待前一个已领取轮次的检查点，但可以与其共用同一个 `running` 区间（[决策](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)）。模型和插件停止轮次时，该轮次结束；一个**步骤**包含一次模型请求及其工具。在[下文时序](agent-lifecycle.md)中，引号标记持久事件。
+**会话**采用仅追加方式。每个普通**轮次**领取一条已排队的消息；注入不领取消息。后续轮次会等待前一个检查点，但可以与前一轮次共用同一个 `running` 区间（[决策](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)）。一个**步骤**包含一次模型请求及其工具；在[下文时序](agent-lifecycle.md)中，引号标记持久事件。
 
 未提供 id 时，创建流程会生成 `<config-id>-session-<uuid>`；`sessionId` 用于恢复或创建会话，而 `resumeSessionId` 要求已有历史。恢复流程在发布前还原沿袭关系和委托深度。初始化失败会发出 `agent-loop/config-start-failed`；拆卸过程保持静默。
 
@@ -115,37 +115,37 @@ forever:
     checkpoint persistence and notify idle/running status
 ```
 
-每个步骤都会组装有序提示词片段、工具 schema 和变量；未知引用会使该轮次失败。`dsh-system-prompt` 负责身份和角色设定，循环则提供 `model` 和 `cwd`（[提示词归属](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)）。
+各步骤会组装有序提示词片段、工具 schema 和变量；未知引用会使轮次失败。`dsh-system-prompt` 负责身份和角色设定；循环提供 `model` 和 `cwd`（[归属](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)）。
 
-工具执行阶段的上下文，包括异步 `inject()` 和工具执行后的 `additionalContexts`，会在结果产生后稳定。steering（中途引导）会在 `agent/post-step` 前排空；该事件会观察持久输出、结果、上下文和 steering。余留内容进入队列。终止型 `agent/turn-stop` 在关闭和刷写期间始终具有最终决定权；后续 steering 会被丢弃，排队提示词仍予保留。
+异步 `inject()` 和工具执行后的 `additionalContexts` 会在结果产生后稳定；steering（中途引导）会在 `agent/post-step` 前排空。余留内容进入队列。终止型 `agent/turn-stop` 在关闭和刷写期间始终具有最终决定权，会丢弃后续 steering，而不丢弃排队提示词。
 
-裁剪先于摘要；溢出重试必须取得持久进展。有界的瞬态重试在 `agent/request-error` 上组合；取消优先（[压缩](../.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)）。
+裁剪先于摘要；溢出重试必须取得持久进展。有界重试在 `agent/request-error` 上组合；取消优先（[压缩](../.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)）。
 
 ### 失败边界
 
-适配器故障会先关闭步骤，再进入 `agent/request-error`；该事件会收到准确的 `Error`、`LlmFailure` 和历史记录。重试会开启另一个步骤；成功会清除历史记录；重试耗尽后，故障存入 `turn/end`。失败分片不会提交消息或工具。
+适配器故障会先关闭步骤，再进入 `agent/request-error`；该事件会收到准确的 `Error`、`LlmFailure` 和历史记录。重试会开启步骤；成功会清除历史记录；重试耗尽后，故障存入 `turn/end`。失败分片不会提交任何内容。
 
-其他故障使用 `agent/error`。取消和资源释放均优先于恢复；尚未分派的工具调用会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。轮次信号会在 `turn/end` 前失效。实际生效的 `cancel()` 会在清空队列和中止前发出类型化原因；观察方不能否决该操作，空闲状态下的调用不发出任何事件，持久化会记录 `aborted`。dispose（资源释放）会等待系统停稳（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
+其他故障使用 `agent/error`。取消和资源释放均优先于恢复；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。信号会在 `turn/end` 前失效。实际生效的 `cancel()` 会发出原因、清空队列并中止；观察方不能否决该操作，空闲状态下的调用不发出任何事件，持久化会记录 `aborted`。dispose（资源释放）会等待系统停稳（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
 
-会话事件均位于轮次边界内。重新加载会用合成的 `interrupted` 轮次结束事件闭合中断的日志尾部。关闭后的故障只通过 `agent/error` 报告；此时已没有安全的轮次内位置。每个轮次有一个 `TurnEndReason`；各变体由 [TurnEndReasonMap](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap) 统一定义。
+会话事件均位于轮次边界内；重新加载会用合成的 `interrupted` 轮次结束事件闭合中断的日志尾部。关闭后的故障使用 `agent/error`。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。
 
 ### Agent 句柄
 
-`ctx.agents` 拥有活跃 agent，并返回 `AgentHandle { agent, dispose() }`。插件使用 `send()`、`steer()`、`inject()`、`cancel()` 和 `whenIdle()`。调用方 fiber、工厂提供方和消费方句柄通过同一个需等待完成的 disposer 共同拥有拆卸过程。
+`ctx.agents` 返回 `AgentHandle { agent, dispose() }`。插件使用按意图命名的辅助方法 `followup()`、`queue()`、`steer()` 和 `inject()`；持有确切路由信息的调用方使用各字段均为必填项的 `send()`（[决策](../.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.md)）。`cancel()` 和 `whenIdle()` 控制生命周期。调用方、提供方和句柄共同拥有拆卸过程。
 
 ### Agent 作用域
 
-每个 agent 都拥有一个作用域化的 `agent.ctx`；共享存储会在全局工具、提示词和命令条目之上叠加作用域条目，同时保留各领域视图（[决策](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)）。作用域监听器会过滤分派，每项作用域贡献都会在撤销时等待清理完成。`CreateAgentOptions.setup(agentCtx)` 在发布前完成组合。类型化解析器从合并后的 `Events` 和 `scopeTarget` 推导载体检查（[语义门禁](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)）。参见 [agent 作用域](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md)和 [subagent 组合](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)。`AgentLoop` 在 `ctx.agents.withInitiator()` 内运行；私有编排会派生 `agent.session`，而轮次、步骤、信号、cwd 和权限仍保持显式（[决策](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)）。
+每个 agent 都拥有一个作用于全局工具、提示词和命令存储的作用域化 `agent.ctx`（[决策](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)）；作用域监听器会过滤分派，各项贡献会在撤销时等待清理完成。`CreateAgentOptions.setup(agentCtx)` 在发布前完成组合；类型化解析器从 `Events` 和 `scopeTarget` 推导载体检查（[门禁](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)）。`AgentLoop` 在 `ctx.agents.withInitiator()` 内运行；私有编排会派生 `agent.session`，而轮次、步骤、信号、cwd 和权限仍保持显式（[决策](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)）。参见 [agent 作用域](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md)和 [subagent 组合](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)。
 
 ## 状态
 
 ### 会话日志
 
-会话日志是权威依据。`deriveMessages()` 投影出模型历史；原始 `assistant/chunk` 事件留在日志中，以保证回放和 UI 保真。fork、恢复、transcript（文本记录）渲染、遥测和持久化均派生自同一个事件流。
+会话日志是权威依据。`deriveMessages()` 投影出模型历史；原始 `assistant/chunk` 事件保留回放和 UI 保真。fork、恢复、transcript（文本记录）、遥测和持久化共用该事件流。
 
-**模型可见 ⟺ 已记录**：日志可以重建每个请求，包括由请求头会话前缀置于开头的 `step/start` 时消息，以及通过折叠 `request/header` 得到的请求头；开发期不变量会断言这一点（[可重建性](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)）。
+**模型可见 ⟺ 已记录**：`step/start` 消息、请求头中的会话前缀和折叠后的 `request/header` 共同重建每个请求；`dsh-agent-loop/invariant` 通过 `ctx.invariants` 断言这一点（[决策](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)）。
 
-持久性由插件负责。后端会缓冲同步的 `session/event` 通知。语义检查点策略会在适配器分发前刷写请求，在工具分发前刷写已记录的顶层调用，并在 `agent/post-step` 刷写完整的响应与结果批次；循环仍保留最终的轮次结束检查点。`SessionPersistence` 直接存储 `SessionEvent`，并将元数据存入 `SessionHeader`；JSONL 默认采用带校验和的 Zstandard，SQLite 则遵循同一契约（[决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)）。
+持久性由插件负责；后端会缓冲同步的 `session/event` 通知。检查点会在适配器分发前排空，在工具分发前刷写已记录的顶层工具调用，在 `agent/post-step` 刷写完整的响应与结果批次，并刷写最终的轮次结束。`SessionPersistence` 存储 `SessionEvent` 和 `SessionHeader` 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 则遵循同一契约（[决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)）。
 
 `ctx.sessions.appendOutOfBand()` 会把插件所属的纯日志事件加入开放轮次，或创建一个平衡且已刷写的零步骤轮次。`session/title` 按后写覆盖方式折叠，并携带源 seq 和来源信息；其即时回退标题和唯一可选异步提供方都不会延迟 agent 响应。fork 会继承标题（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
 
@@ -185,7 +185,7 @@ forever:
 | 限制生成的进程 | 使用 `ctx.sandbox` 后端；消费方在生成进程前包装 argv |
 | 拦截请求、工具或轮次 | 使用相应的 `agent/*` 或 `tools/*` 事件；`agent/turn-stop` 是串行终止判定点 |
 | 添加历史记录之外的会话稳定前缀 | 组合 `agent/session-prefix`；请求头会记录该前缀 |
-| 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染 |
+| 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染；仅终端可用的浮层使用 `ctx.tui` |
 | 添加持久会话状态 | 添加一个 `SessionEventMap` 成员，并从日志渲染和回放 |
 | 添加异步会话标题生成 | 在 `ctx.sessionTitle` 上注册唯一提供方 |
 | 管理同会话目标 | 使用 `ctx.goals`；通过 `Agent` 和 `agent/*` 续跑 |
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 54951fd9b4..a27d325e31 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -24,6 +24,7 @@ flowchart LR
   pkg_cli_demo["cli-demo"]
   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"]
@@ -35,7 +36,7 @@ flowchart LR
   pkg_hooks_claude["hooks-claude"]
   pkg_hooks_codex["hooks-codex"]
   pkg_acp["acp"]
-  svc_sessionQuery["ctx.sessionQuery<br/>Exact session-history reads and traces"]
+  svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"]
   pkg_session_reference["session-reference"]
   svc_sessionReferences["ctx.sessionReferences<br/>Cross-session snapshot preparation"]
   pkg_tui["tui"]
@@ -61,6 +62,7 @@ flowchart LR
   svc_planMode["ctx.planMode<br/>Plan collaboration state"]
   pkg_commands["commands"]
   svc_commands["ctx.commands<br/>Human command registry"]
+  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"]
@@ -155,6 +157,7 @@ flowchart LR
   pkg_session_persistence_jsonl --> svc_sessionPersistence
   pkg_session_persistence_sqlite --> svc_sessionPersistence
   pkg_session_query --> svc_sessionQuery
+  pkg_session_query_sqlite --> svc_sessionQuery
   pkg_session_reference --> svc_sessionReferences
   pkg_session_title --> svc_sessionTitle
   pkg_session_title_all_messages_llm --> svc_sessionTitle
@@ -172,6 +175,7 @@ flowchart LR
   pkg_token_meter --> svc_tokenMeter
   pkg_tool_bash --> svc_bashEnv
   pkg_tools --> svc_tools
+  pkg_tui --> svc_tui
   pkg_tui --> svc_userInteraction
   pkg_user_interaction --> svc_userInteraction
   pkg_web --> svc_web
@@ -216,6 +220,7 @@ flowchart LR
   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_sessionQuery --> pkg_session_reference
   svc_sessionReferences --> pkg_acp
@@ -223,8 +228,10 @@ flowchart LR
   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_skills --> pkg_tool_skill
   svc_spillStore --> pkg_spill_policy
@@ -266,10 +273,10 @@ 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), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | 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.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), [`acp`](../packages/ui/acp), [`session-query`](../packages/session-query/session-query) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
-| `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | - | [`session-reference`](../packages/context/session-reference) | - | Resolves live and optional persisted logs into one logical corpus for exact reads and relationship traces. |
+| `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), [`acp`](../packages/ui/acp), [`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.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations on the same service. |
 | `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | - | 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. |
@@ -277,6 +284,7 @@ flowchart LR
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | - | 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) | - | [`acp`](../packages/ui/acp) | - | 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), [`acp`](../packages/ui/acp) | - | Plugins register direct human commands; TUI and ACP consume the same effective per-agent catalog without sending invocations to the model. |
+| `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/ui/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. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 4d2c803de0..49a0a1510f 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -58,7 +58,7 @@ export interface Config {
   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`. */
+  /** 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 `false`. */
   packChunks?: boolean
@@ -83,7 +83,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)
 
-Source: [`packages/examples/acp-demo/src/index.ts:43`](../packages/examples/acp-demo/src/index.ts)
+Source: [`packages/examples/acp-demo/src/index.ts:44`](../packages/examples/acp-demo/src/index.ts)
 
 ## `@deepseek-ai/dsh-agent-loop`
 
@@ -297,20 +297,17 @@ export interface Config {
    * nobody will resolve).
    */
   maxWallMs?: number
-  /** Shared byte budget for captured log text (console + raw stream writes), truncation marked in-band. */
-  maxLogBytes?: number
   /**
-   * Byte cap for the completion value, measured by its real cross-boundary
-   * size (string bytes, or structured-clone wire size); an oversized or
-   * non-cloneable value crosses as a capped string rendering.
+   * Hard cap for serialized log-array, completion-value, and failure-message payloads;
+   * fixed result-envelope syntax is excluded.
    */
-  maxValueBytes?: number
+  maxOutputBytes?: number
   /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */
   maxOldGenerationSizeMb?: number
 }
 ```
 
-Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:21`](../packages/code-runtime/code-runtime-worker/src/index.ts)
+Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:24`](../packages/code-runtime/code-runtime-worker/src/index.ts)
 
 ## `@deepseek-ai/dsh-compact-basic`
 
@@ -535,6 +532,8 @@ export interface Config {
   thinking?: 'enabled' | 'disabled'
   /** Thinking effort (only meaningful with thinking enabled). */
   reasoningEffort?: 'high' | 'max'
+  /** Positive context capacity used when the selected model has no exact value. */
+  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). */
@@ -755,7 +754,7 @@ export interface StreamableHttpConfig {
 }
 ```
 
-Source: [`packages/mcp/mcp-client/src/index.ts:91`](../packages/mcp/mcp-client/src/index.ts)
+Source: [`packages/mcp/mcp-client/src/index.ts:93`](../packages/mcp/mcp-client/src/index.ts)
 
 ## `@deepseek-ai/dsh-permission`
 
@@ -801,7 +800,7 @@ export interface PlanModeConfig {
 }
 ```
 
-Source: [`packages/plan/plan-mode/src/index.ts:57`](../packages/plan/plan-mode/src/index.ts)
+Source: [`packages/plan/plan-mode/src/index.ts:58`](../packages/plan/plan-mode/src/index.ts)
 
 ## `@deepseek-ai/dsh-pty-local`
 
@@ -936,7 +935,9 @@ 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 per-cwd subdirectories.
+   * (bash calls, subprocesses). Sessions group under per-cwd subdirectories. An
+   * existing root must be a readable directory; an absent root is created on
+   * first materialization.
    */
   root: string
   /**
@@ -956,7 +957,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:37`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:39`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-sqlite`
 
@@ -995,21 +996,38 @@ export interface Config {
 export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 ```
 
-Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:55`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
+Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:58`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
 
-## `@deepseek-ai/dsh-session-query`
+## `@deepseek-ai/dsh-session-query-sqlite`
 
 Requires: `sessions`
 
 ```ts config-catalog
-/** Configuration for exact session-query reads and traces. */
-export interface Config {
-  /** Maximum accepted raw read context on either side. Defaults to 50. */
-  readWindowMax?: number
+/** Combined session-query configuration backed by SQLite full-text search. */
+export interface Config extends SessionQueryConfig {
+  /**
+   * Dedicated derived-index path; `:memory:` is supported for tests. Missing
+   * directories and database files are created owner-only on POSIX filesystems;
+   * existing modes are preserved.
+   */
+  path: string
+  /** 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
 }
+
+/** Supported SQLite journal modes. */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 ```
 
-Source: [`packages/session-query/session-query/src/config.ts:9`](../packages/session-query/session-query/src/config.ts)
+Depends on: [`SessionQueryConfig`](../packages/session-query/session-query/src/index.ts)
+
+Source: [`packages/session-query/session-query-sqlite/src/index.ts:74`](../packages/session-query/session-query-sqlite/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-reference`
 
@@ -1135,7 +1153,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/spill/spill-policy/src/index.ts:45`](../packages/spill/spill-policy/src/index.ts)
+Source: [`packages/spill/spill-policy/src/index.ts:51`](../packages/spill/spill-policy/src/index.ts)
 
 ## `@deepseek-ai/dsh-subagent-acp`
 
@@ -1275,7 +1293,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/bash/tool-bash/src/index.ts:40`](../packages/bash/tool-bash/src/index.ts)
+Source: [`packages/bash/tool-bash/src/index.ts:41`](../packages/bash/tool-bash/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-cordis`
 
@@ -1369,6 +1387,22 @@ export interface Config {
 
 Source: [`packages/lsp/tool-lsp/src/index.ts:58`](../packages/lsp/tool-lsp/src/index.ts)
 
+## `@deepseek-ai/dsh-tool-pty`
+
+Requires: `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
+}
+```
+
+Source: [`packages/pty/tool-pty/src/index.ts:35`](../packages/pty/tool-pty/src/index.ts)
+
 ## `@deepseek-ai/dsh-tool-ralph`
 
 Requires: `tools` · `workflows` · `subagents` · `systemPrompt`
@@ -1387,7 +1421,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/workflow/tool-ralph/src/index.ts:22`](../packages/workflow/tool-ralph/src/index.ts)
+Source: [`packages/workflow/tool-ralph/src/index.ts:23`](../packages/workflow/tool-ralph/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-skill`
 
@@ -1457,7 +1491,7 @@ export interface Config {
 
 Depends on: [`AgentOptions`](core-data-structures/core.md)
 
-Source: [`packages/subagent/tool-subagent/src/index.ts:23`](../packages/subagent/tool-subagent/src/index.ts)
+Source: [`packages/subagent/tool-subagent/src/index.ts:24`](../packages/subagent/tool-subagent/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-tasks`
 
@@ -1473,7 +1507,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/tasks/tool-tasks/src/index.ts:21`](../packages/tasks/tool-tasks/src/index.ts)
+Source: [`packages/tasks/tool-tasks/src/index.ts:23`](../packages/tasks/tool-tasks/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-web`
 
@@ -1511,7 +1545,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/workflow/tool-workflow/src/index.ts:26`](../packages/workflow/tool-workflow/src/index.ts)
+Source: [`packages/workflow/tool-workflow/src/index.ts:27`](../packages/workflow/tool-workflow/src/index.ts)
 
 ## `@deepseek-ai/dsh-tools`
 
@@ -1533,11 +1567,11 @@ export interface Config {
 export type ToolPresentationMode = 'native' | 'code' | 'both'
 ```
 
-Source: [`packages/core/tools/src/index.ts:419`](../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:529`](../packages/core/tools/src/index.ts)
 
 ## `@deepseek-ai/dsh-tui`
 
-Requires: `agents` · `commands` · `userInteraction` · `tools` · `llm` · `systemPrompt` · `tokenMeter`
+Requires: `agents` · `sessions` · `commands` · `userInteraction` · `tools` · `llm` · `systemPrompt` · `tokenMeter`
 
 ```ts config-catalog
 /** Serializable plugin configuration. */
@@ -1547,16 +1581,15 @@ export interface Config extends TuiConfig {
   /** Exact shared agent/session identity driven by this terminal. Defaults to `main`. */
   sessionId?: string
   /**
-   * Shell command template shown for resuming this session: printed on exit and
-   * listed by `/resume`, with every `{session}` occurrence replaced by the live
-   * session id. Absent disables both surfaces. Deployments set it only when a
-   * persistence backend makes the session resumable (e.g.
-   * `RESUME_SESSION_ID={session} dsh`).
+   * Shell command fallback printed on exit or after selecting a session when
+   * the host cannot hand off in place. Every `{session}` becomes the selected
+   * id; the TUI never executes this text. Absent disables only the fallback,
+   * not the interactive selector.
    */
   resumeCommand?: string
 }
 
-/** Presentation settings for the pi-tui terminal mode. */
+/** Interaction and presentation settings for the pi-tui terminal mode. */
 export interface TuiConfig {
   /** Render model reasoning blocks. */
   showReasoning?: boolean
@@ -1566,6 +1599,8 @@ export interface TuiConfig {
   maxQuestionOptions?: number
   /** Maximum models visible at once in the model selector. */
   maxModelOptions?: number
+  /** Maximum sessions visible at once in the resume selector. */
+  maxResumeOptions?: number
   /** User-question panel width in terminal columns, clamped to the terminal. */
   questionDialogWidth?: number
   /** User-question panel maximum height in terminal rows. */
@@ -1574,6 +1609,12 @@ export interface TuiConfig {
   modelDialogWidth?: number
   /** Model-selector maximum height in terminal rows. */
   modelDialogMaxHeight?: number
+  /** Maximum fuzzy file candidates displayed for one `@` query. */
+  fileSearchMaxResults?: number
+  /** Maximum paths retained in one `@` workspace index. */
+  fileSearchMaxEntries?: number
+  /** Directory basenames excluded from `@` traversal and completion. */
+  fileSearchExcludedDirectories?: string[]
   /** Show the terminal's hardware cursor at the pi editor's IME marker. */
   showHardwareCursor?: boolean
   /** Apply the built-in ANSI color palette. */
@@ -1590,7 +1631,7 @@ export interface TuiConfig {
 }
 ```
 
-Source: [`packages/ui/tui/src/index.ts:161`](../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/index.ts:270`](../packages/ui/tui/src/index.ts)
 
 ## `@deepseek-ai/dsh-tui-demo`
 
@@ -1613,7 +1654,7 @@ export interface Config {
   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`. */
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
   persistenceRoot?: string
   /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
   persistenceCompression?: JsonlCompression
@@ -1647,7 +1688,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:38`](../packages/examples/tui-demo/src/index.ts)
+Source: [`packages/examples/tui-demo/src/index.ts:39`](../packages/examples/tui-demo/src/index.ts)
 
 ## `@deepseek-ai/dsh-user-approval`
 
@@ -1853,10 +1894,12 @@ 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-connection` ([`packages/client/connection/src/index.ts`](../packages/client/connection/src/index.ts))
+- `@deepseek-ai/dsh-client-hmr` ([`packages/client/hmr/src/index.ts`](../packages/client/hmr/src/index.ts))
 - `@deepseek-ai/dsh-client-i18n` ([`packages/client/i18n/src/index.ts`](../packages/client/i18n/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-conversation` ([`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/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-question` — requires `tools` · `userInteraction` ([`packages/client/ui-question/src/index.ts`](../packages/client/ui-question/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-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))
@@ -1873,7 +1916,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-tasks` ([`packages/tasks/tasks/src/index.ts`](../packages/tasks/tasks/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-tool-pty` — requires `pty` · `tools` · `systemPrompt` ([`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/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-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts))
 
@@ -1887,6 +1929,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-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-query` — abstract `SessionQueryService` ([`packages/session-query/session-query/src/index.ts`](../packages/session-query/session-query/src/index.ts))
 - `@deepseek-ai/dsh-spill` — abstract `SpillStore` ([`packages/spill/spill/src/index.ts`](../packages/spill/spill/src/index.ts))
 - `@deepseek-ai/dsh-workflow` — abstract `WorkflowService` ([`packages/workflow/workflow/src/index.ts`](../packages/workflow/workflow/src/index.ts))
 
@@ -1899,6 +1942,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@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-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
+- `@deepseek-ai/dsh-client-modules` ([`packages/client/modules/src/index.ts`](../packages/client/modules/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))
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index 8dc6c89aea..2c8f18513b 100644
--- a/docs/cookbook/adding-a-tool.i18n.yaml
+++ b/docs/cookbook/adding-a-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
-adding-a-tool.md: 9e8fa1287c854f33f62a4c6a1ed93adfccc19471
-adding-a-tool.zh.md: be4e0800036ac9bde949a11d8a35e49cfb92efd7
+adding-a-tool.md: 788c967cffa9df06e8d96e190930d69b9f2182ed
+adding-a-tool.zh.md: 4ff9ce25a66625435ccba4454f2ac4b5472e5668
diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md
index 9e8fa1287c..788c967cff 100644
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -22,10 +22,14 @@ export function apply(ctx: Context) {
       path: { type: 'string', required: true, description: 'Absolute path' },
       limit: { type: 'number' },                     // optional by default
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args, exec) {
       // args is TYPED from the schema: { path: string; limit?: number }
       // exec carries immutable identity + token; signal is the operational field
-      return [{ type: 'text', text: await readFile(args.path, { encoding: 'utf8', signal: exec.signal }) }]
+      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
     },
   }))
 }
@@ -35,31 +39,34 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool (w
 
 ## Rules of the execute() contract
 
-- **Args are validated for you.** `defineTool` validates the model-generated `arguments` against the `SchemaSpec` before `execute` runs (type, required keys, enum membership, nested objects/arrays — [runtime arg validation](../../.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md)), so inside `execute` the args already match `InferArgs`. You still hand-check value constraints the DSL can't express (non-empty strings, positive numbers, cross-field rules); throw a descriptive Error for those. Raw JSON-Schema tools registered directly (MCP) are NOT validated by the harness — they validate their own input.
+- **Args are validated for you.** `defineTool` validates model-generated `arguments` against the unified `ParameterSchemaSpec` before `execute` runs (types, required keys, literal constraints, exact-one unions, and nested values — [runtime arg validation](../../.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md)), so inside `execute` the args match `InferArgs`. Explicit object nodes declare `additionalProperties: true | false`; the implicit parameter root stays open. You still hand-check constraints the DSL does not express, such as non-empty strings, positive numbers, or cross-field rules. Raw JSON-Schema tools registered directly own their input validation.
 - **Registration borrows your readonly definition.** A typed same-process contribution is not a serialization boundary; do not mutate its schema or replace callbacks after registration. `schemas()` materializes only the explicit model-facing projection. To hot-swap a tool, dispose its owning effect and register the replacement; mutable state inside the callback's closure remains ordinary plugin state.
 - **Execution identity is protected.** The registry materializes `arguments` as detached lossless JSON in one recursive pass, freezes that value before policy starts, and assigns an opaque `exec.token`; `callId`, `name`, `arguments`, `agent`, `token`, the required caller-owned `signal`, and an optional enclosing-transport `parent` token stay immutable through dispatch. `parent` is identity-only and exposes no live outer execution. Treat `args` as readonly input. Only an around-dispatch wrapper receives a mutable view, and it may replace and restore the required `exec.signal` to impose a deadline but cannot remove it.
-- **Throwing or returning non-JSON data means `isError`.** The registry catches throws and materializes the final result before observers run. A malformed or non-JSON result becomes `{ isError: true }`, preventing a live success that cannot be logged. Throw for infrastructure failures; report domain failures in result text when the model must interpret them.
+- **Declare and return one canonical JSON value.** `output.schema` uses `ValueSchemaSpec` and may have an object, array, scalar, or null root. `execute` returns only the inferred value; the registry snapshots it as lossless JSON, validates it, freezes it, and passes it to `output.render(args, value)`. Do not return content blocks from the body or make callers parse prose for ids and fields.
+- **Throwing or returning an invalid value means `isError`.** The registry catches throws and contains schema, renderer, metadata-projector, and lossless-JSON failures before observers run. Throw for infrastructure failures. Represent a successful domain outcome in the canonical value even when its Native renderer explains a non-ideal state, such as a non-zero process exit.
 - **Honor `exec.signal`.** Cancel in-flight work when it fires.
-- **Attach durable card data with `meta` (optional).** `execute` may return `{ content, meta }` instead of a bare `ContentBlock[]` — `meta` is a JSON-serializable payload the core treats as opaque, persisted on the `tool/result` event and handed back to your `presentResult` (so a card that needs more than `args`, like `write`/`edit`'s applied-hunk diff, survives a session replay). Keep UI-only data here, never in the model-facing `content`.
+- **Project durable card data with `presentationMeta` (optional).** `output.presentationMeta(args, value)` derives replayable JSON from the same canonical value. The core persists it on `tool/result` and hands it to `presentResult`, so a card that needs result-time facts—such as `write`/`edit` applied hunks—survives replay without persisting the canonical value. The projector is skipped for nested Code dispatches because they have no cards.
 - **Use `exec.agent` for async notifications.** `agent.inject(content, {source: {kind: 'plugin', plugin: '<name>'}})` appends durable context the NEXT model request sees — it is not a wake-up (an idle agent stays idle). Guard against disposed agents (try/catch).
 
 ## Long-running work
 
-Gate `run_in_background` with producer config, then register through `ctx.tasks.start({ kind, label, owner: exec.agent, run })`. The registry skips a pre-aborted invocation before the producer body; the runtime validates ownership and control-surface availability before `run()` starts work, then supplies the id, session fence, generic control tools, notices, and owner cleanup.
+Gate `run_in_background` with producer config, then register through `ctx.tasks.start({ kind, label, owner: exec.agent, run })`. The registry rejects a pre-aborted invocation before the producer body; the runtime validates ownership and control-surface availability before `run()` starts work, then supplies the id, session fence, generic control tools, notices, and owner cleanup. A successful background branch returns a typed canonical handle such as `{ kind: 'background', taskId }`; its Native renderer may keep human prose such as `started background task bash-1`, but Code Mode must never parse that prose to recover the id.
 
-The producer supplies synchronous `cancel`, non-rejecting `done` that settles after resource cleanup, and optional consuming `readOutput` with bounded-output formatting. Once the id is returned, use a task-owned cancellation signal rather than `exec.signal`. See the [background task runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and `dsh-tool-bash` for a stream producer.
+The producer supplies synchronous `cancel`, non-rejecting `done` that settles after resource cleanup, and optional consuming `readOutput` with bounded-output formatting. A pre-aborted call is a failure because no task exists whose id could satisfy the successful output schema. Once `ctx.tasks.start()` publishes the id, use a task-owned cancellation signal rather than `exec.signal`: later outer-call cancellation stops waiting for the call but does not kill published work; `task_kill`, owner disposal, and service teardown own that lifetime. Foreground work remains coupled to `exec.signal`. See the [background task runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and `dsh-tool-bash` for a stream producer.
 
 ## Execution policy and observation
 
-Prefer not to build deployment policy into the tool. Use `tools/pre-execute` for extensible allow/deny/ask policy (the [permission-gate example](extension-cookbook.md#a-hook-plugin-permission-gate-example)), `ctx.tools.guard()` for a final monotonic deny that later listeners cannot undo, `tools/execute` to wrap core dispatch with a deadline/retry/metrics scope, `tools/post-execute` to transform or attach model-facing context, and `tools/result` to observe the immutable normalized outcome without changing it. A sandboxing implementation can also sit behind the tool's executor capability seam; the exact contracts are in the [`dsh-tools` README](../../packages/core/tools/README.md#extension-points).
+Prefer not to build deployment policy into the tool. Use `tools/pre-execute` for extensible allow/deny/ask policy (the [permission-gate example](extension-cookbook.md#a-hook-plugin-permission-gate-example)), `ctx.tools.guard()` for a final monotonic deny that later listeners cannot undo, `tools/execute` to wrap canonical dispatch with a deadline/retry/metrics scope, `tools/post-execute` to replace either presentation content or the canonical value, block, or attach model-facing context, and `tools/result` to observe the immutable normalized outcome. A content replacement leaves programmatic access to `value` intact; confidentiality policy blocks or replaces the value. A sandboxing implementation can also sit behind the tool's executor capability seam; the exact contracts are in the [`dsh-tools` README](../../packages/core/tools/README.md#extension-points).
 
 ## Code Mode reaches your tool for free
 
-In [Code Mode](../../packages/core/tools/README.md), every visible registered tool is available as `await tools.<name>(args)` without extra integration. The SDK derives parameters from the same JSON Schema, and calls re-enter the normal execution pipeline. Write descriptions as model-facing API docs; non-text result blocks become placeholders in programs.
+In [Code Mode](../../packages/core/tools/README.md), every visible registered tool is available as `await tools.<name>(args)` without extra integration. The generated `ToolArgsMap` and `ToolOutputMap` derive exact argument and canonical-return types from the same schemas, and calls re-enter the normal execution pipeline. A successful call resolves to the final canonical JSON value after policy, not to rendered Native content. A failed call rejects with the real `ToolCallError`; programs can inspect only its `name`, `toolName`, and human-readable `message`, not internal error codes or a failure union.
+
+Design `output.schema` as a useful programmatic API: return handles and fields directly, allow scalar/array/null roots when they are the honest value, and keep human explanation in `output.render`. Intermediate values are execution-local, are not persisted or prompt-truncated, and have no byte cap, so the producer's truthful acquisition bounds and process memory still matter. Only the outer `run_code` logs/result cross the configurable output cap and model-facing spill pipeline.
 
 ## How your tool renders in an editor (ACP presentation)
 
-Your tool's `execute` returns model-facing content; its **editor card** is a separate, optional concern you declare with two pure display methods on the `defineTool` options. Design this alongside `execute`, not after — an editor (Zed, over the ACP bridge) shows the card, and a tool with no presentation falls back to a bland generic card (title = tool name, raw args as input).
+Your tool's `output.render` returns model-facing content; its **editor card** is a separate concern declared through pure presentation projections and optional `presentCall` / `presentResult` methods. Design these alongside the canonical value—an editor (Zed, over the ACP bridge) shows the card, and a tool with no UI presentation falls back to a generic card (title = tool name, raw args as input).
 
 Both methods return a **`card`-tagged render intent** — pick the card kind that matches what your tool does:
 
@@ -70,16 +77,16 @@ Both methods return a **`card`-tagged render intent** — pick the card kind tha
 - `presentResult(args, { content, isError, meta? })` returns the completed card:
   - `generic` supplies an optional title and content.
   - `terminal` supplies raw output and optional exit metadata; the bridge renders the capability-specific or fenced fallback view.
-  - `diff` supplies applied hunks, often carried in persisted `result.meta` so replay reproduces them. Mutation tools keep a diff result because an ACP update replaces the pending card's content.
+  - `diff` supplies applied hunks, often derived by `output.presentationMeta` and carried in persisted `result.meta` so replay reproduces them. Mutation tools keep a diff result because an ACP update replaces the pending card's content.
 
 Hard rules (they bite if broken):
 
 - **Purity.** These run on live streaming AND on session-log REPLAY, so they must be pure functions of `args` (+ the result) — NO I/O, NO reading session state, NO clock/random. A diff is derived from the args (`write` uses `oldText: null` because a call-time presenter has no prior file content); the BRIDGE, not the tool, fills the session cwd and relativizes a display-path title. If you find yourself wanting the file's old content or the working directory inside `presentCall`, stop — that belongs on the bridge or a future result-event shape, not the presenter.
-- **UI-only formatting stays out of the model result.** A fenced ` ```console ` block, a diff, a relativized path — none of these may appear in what `execute` returns to the model; they live only in the presentation. (A `terminal` result view carries RAW `output`; the bridge adds the fences.)
+- **UI-only formatting stays out of the model result.** A fenced ` ```console ` block, a diff, a relativized path—none of these belongs in the canonical value or Native content merely to serve an editor. `output.render` owns model-facing prose; `presentationMeta` plus the card presenters own replayable UI state. A `terminal` result view carries raw output and the bridge adds fences.
 - **`defineTool` soft-validates the display path.** A malformed/older logged arg shape makes the wrapper return `undefined` (a generic fallback) rather than throw — display must never crash a replay.
 
 The neutral vocabulary lives in `dsh-tools` (never import an ACP type into a tool); the ACP bridge maps each `card` to the wire. The design and the why are in [the render-intent-union Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md); `dsh-tool-fs` (generic/diff) and `dsh-tool-bash` (terminal) are the reference implementations.
 
 ## Tests every tool needs
 
-Cover argument rejection, every result shape, and HMR disposal. For a side-effecting tool, drive the real tool through the agent loop with a scripted `MockAdapter` and assert its `tool/call` and `tool/result` session events. For an editor card, assert the exact `presentCall` and `presentResult` views and add an [ACP snapshot](../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md) through the real bridge; a terminal card's scenario sets `terminalOutput: true` to exercise the capable-client path.
+Cover argument rejection, every canonical value and Native rendering shape, output-schema rejection, and HMR disposal. For a side-effecting tool, drive the real tool through the agent loop with a scripted `MockAdapter` and assert its `tool/call` and projected `tool/result` session events; prove the canonical value itself is not persisted. For an editor card, assert the exact `presentCall` and `presentResult` views and add an [ACP snapshot](../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md) through the real bridge; a terminal card's scenario sets `terminalOutput: true` to exercise the capable-client path.
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index be4e080003..4ff9ce25a6 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -22,10 +22,14 @@ export function apply(ctx: Context) {
       path: { type: 'string', required: true, description: 'Absolute path' },
       limit: { type: 'number' },                     // optional by default
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args, exec) {
       // args is TYPED from the schema: { path: string; limit?: number }
       // exec carries immutable identity + token; signal is the operational field
-      return [{ type: 'text', text: await readFile(args.path, { encoding: 'utf8', signal: exec.signal }) }]
+      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
     },
   }))
 }
@@ -35,31 +39,34 @@ export function apply(ctx: Context) {
 
 ## execute() 契约的规则
 
-- **参数已为你校验。** `defineTool` 在 `execute` 运行前，会根据 `SchemaSpec` 校验模型生成的 `arguments`（类型、必填键、枚举成员、嵌套对象/数组——见[运行时参数校验](../../.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md)），因此 `execute` 内部的 args 已匹配 `InferArgs`。你仍需手动检查 DSL 无法表达的值约束（非空字符串、正数、跨字段规则），对这些情况抛出描述性 Error。直接注册的原始 JSON-Schema 工具（MCP）不由 harness 校验，它们自行校验输入。
+- **参数已为你校验。** `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 其所属副作用并注册替代品；回调闭包内的可变状态仍是普通的插件状态。
 - **执行身份受保护。** 注册表在一次递归遍历中将 `arguments` 物化为分离的无损 JSON，在策略开始前冻结该值，并分配一个不透明的 `exec.token`；`callId`、`name`、`arguments`、`agent`、`token`、必填且由调用方持有的 `signal`，以及可选的外层传输 `parent` token 在整个分发过程中保持不可变。`parent` 仅用于身份标识，不暴露活跃的外层执行。请将 `args` 视为只读输入。只有 around-dispatch 包装器会收到可变视图；它可以替换并恢复必填的 `exec.signal` 以施加截止时间，但不能移除该信号。
-- **抛出异常或返回非 JSON 数据意味着 `isError`。** 注册表捕获异常，并在观察者运行前物化最终结果。格式错误或非 JSON 的结果变为 `{ isError: true }`，防止出现无法记录的活跃成功。基础设施故障请抛异常；当模型需要解读领域失败时，请在结果文本中报告。
+- **声明并返回一个规范 JSON 值。** `output.schema` 使用 `ValueSchemaSpec`，根可以是对象、数组、标量或 null。`execute` 只返回推导出的值；注册表将其快照为无损 JSON，完成校验和冻结后，再传给 `output.render(args, value)`。工具主体不要返回内容块，也不要迫使调用方从自然语言中解析 id 和字段。
+- **抛出异常或返回无效值意味着 `isError`。** 注册表会捕获异常，并在观察者运行前收敛 schema、渲染器、元数据投影器和无损 JSON 失败。基础设施故障请抛异常。成功的领域结果即使表示不理想的状态，也应写入规范值；其 Native 渲染器可以解释该状态，例如进程以非零状态退出。
 - **遵守 `exec.signal`。** 信号触发时取消进行中的工作。
-- **使用 `meta` 附加持久化的卡片数据（可选）。** `execute` 可以返回 `{ content, meta }` 而非裸的 `ContentBlock[]`。`meta` 是 JSON 可序列化的载荷，核心将其视为不透明数据，持久化在 `tool/result` 事件上并回传给你的 `presentResult`（这样需要 `args` 之外信息的卡片——如 `write`/`edit` 的已应用 hunk diff——在会话回放中依然存活）。仅在此处放 UI 数据，绝不放入模型可见的 `content`。
+- **使用 `presentationMeta` 投影持久化的卡片数据（可选）。** `output.presentationMeta(args, value)` 从同一个规范值派生可回放的 JSON。核心将其持久化在 `tool/result` 上并传给 `presentResult`，因此需要结果期事实的卡片——例如 `write`／`edit` 的已应用 hunk——无需持久化规范值也能在回放中重现。嵌套 Code 分发没有卡片，因此会跳过该投影器。
 - **使用 `exec.agent` 发送异步通知。** `agent.inject(content, {source: {kind: 'plugin', plugin: '<name>'}})` 追加持久化上下文，下一次模型请求会看到它——这不是唤醒（空闲的 agent（智能体）保持空闲）。请防范已 dispose 的 agent（try/catch）。
 
 ## 长时间运行的工作
 
-通过 producer 配置控制 `run_in_background`，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前跳过已预先中止的调用；运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。
+通过 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 后，应使用 task 自有的取消信号，而不是 `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` 观测不可变的归一化结果而不改变它。沙箱实现也可以位于工具执行器的能力 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)` 调用，无需额外集成。SDK 从同一份 JSON Schema 派生参数，调用重新进入正常的执行流水线。请将描述写成面向模型的 API 文档；非文本结果块在程序中变为占位符。
+在 [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` 日志／结果会受到可配置输出上限和面向模型的输出落盘流水线约束。
 
 ## 工具在编辑器中的渲染方式（ACP 展示）
 
-工具的 `execute` 返回模型可见的内容；其**编辑器卡片**是一个独立的、可选的关注点，通过 `defineTool` 选项中的两个纯展示方法声明。请与 `execute` 同步设计，而非事后补充——编辑器（如 Zed，通过 ACP（Agent Client Protocol）桥接）会展示该卡片，没有展示方法的工具回退为一个朴素的通用卡片（标题 = 工具名，原始 args 作为输入）。
+工具的 `output.render` 返回模型可见的内容；其**编辑器卡片**是另一项独立关注点，通过纯展示投影以及可选的 `presentCall`／`presentResult` 方法声明。请将这些内容与规范值一并设计：编辑器（如 Zed，通过 ACP（Agent Client Protocol）桥接）会展示该卡片，没有 UI 展示方法的工具则回退到通用卡片（标题 = 工具名，原始 args 作为输入）。
 
 两个方法都返回一个 **`card` 标签的渲染意图**——选择与你的工具行为匹配的卡片类型：
 
@@ -70,16 +77,16 @@ producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的
 - `presentResult(args, { content, isError, meta? })` 返回完成后的卡片：
   - `generic` 提供可选的标题和内容。
   - `terminal` 提供原始输出和可选的退出元数据；桥接层渲染能力特定或围栏回退视图。
-  - `diff` 提供已应用的 hunk，通常由持久化的 `result.meta` 携带，使回放能重现它们。变更类工具保留 diff 结果，因为 ACP 更新会替换 pending 卡片的内容。
+  - `diff` 提供已应用的 hunk，通常由 `output.presentationMeta` 派生并通过持久化的 `result.meta` 携带，使回放能重现它们。变更类工具保留 diff 结果，因为 ACP 更新会替换 pending 卡片的内容。
 
 硬性规则（违反会出问题）：
 
 - **纯函数。** 这些方法在实时流式输出和会话日志回放时都会运行，因此必须是 `args`（加 result）的纯函数——不做 I/O、不读会话状态、不用时钟/随机数。diff 从 args 派生（`write` 使用 `oldText: null`，因为调用时的展示器没有文件先前内容）；**桥接层**（而非工具）填充会话 cwd 并相对化展示路径标题。如果你发现自己想在 `presentCall` 内获取文件旧内容或工作目录，请停下——那属于桥接层或未来的 result-event 形态，不属于展示器。
-- **UI 格式不进入模型结果。** 围栏 ` ```console ` 块、diff、相对化路径——这些都不得出现在 `execute` 返回给模型的内容中；它们只存在于展示层。（`terminal` 结果视图携带原始 `output`；桥接层添加围栏。）
+- **UI 格式不进入模型结果。** 围栏 ` ```console ` 块、diff、相对化路径均不应仅为服务编辑器而进入规范值或 Native 内容。`output.render` 负责模型可见的自然语言；`presentationMeta` 和卡片展示器负责可回放的 UI 状态。`terminal` 结果视图携带原始输出，由桥接层添加围栏。
 - **`defineTool` 对展示路径做软校验。** 格式错误或旧版日志中的 arg 形态会使包装器返回 `undefined`（通用回退）而非抛异常——展示绝不能导致回放崩溃。
 
 中性词汇定义在 `dsh-tools` 中（绝不在工具中导入 ACP 类型）；ACP 桥接层将每个 `card` 映射到协议格式（wire format）。设计与原因见[渲染意图联合体 Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)；`dsh-tool-fs`（generic/diff）和 `dsh-tool-bash`（terminal）是参考实现。
 
 ## 每个工具必须的测试
 
-覆盖参数拒绝、每种结果形态和 HMR dispose。对于有副作用的工具，使用脚本化的 `MockAdapter` 驱动真实工具通过 agent loop（智能体循环），并断言其 `tool/call` 和 `tool/result` 会话事件。对于编辑器卡片，断言 `presentCall` 和 `presentResult` 的精确视图，并通过真实桥接层添加一个 [ACP 快照](../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)；终端卡片的场景设置 `terminalOutput: true` 以覆盖 capable-client 路径。
+覆盖参数拒绝、每种规范值和 Native 渲染形态、输出 schema 拒绝以及 HMR dispose。对于有副作用的工具，使用脚本化的 `MockAdapter` 驱动真实工具通过 agent loop（智能体循环），并断言其 `tool/call` 和投影后的 `tool/result` 会话事件；同时证明规范值本身未被持久化。对于编辑器卡片，断言 `presentCall` 和 `presentResult` 的精确视图，并通过真实桥接层添加一个 [ACP 快照](../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)；终端卡片的场景设置 `terminalOutput: true` 以覆盖 capable-client 路径。
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index f0dc01c523..a6d2ca2e38 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-extension-cookbook.md: 8873cac21960e2e2efe0e8c6c5868c3a8e7ee75c
-extension-cookbook.zh.md: f34e9f2fa707be69b13ac408cc1ede1a86310fae
+extension-cookbook.md: c13b46e06a3b34512cd371e6a4868a6e932a575f
+extension-cookbook.zh.md: ef099ff318488ba26a3ba4fe736c5f320bdce4f3
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index 8873cac219..c13b46e06a 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -36,7 +36,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.send()` / `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()`.
 
 ```ts
 import type { Context } from 'cordis'
@@ -54,13 +54,13 @@ export function apply(ctx: Context) {
       render(event.data.chunk.text)
     }
   })
-  onUserInput(text => ctx.agents.get(SessionId('client-session'))?.send([{ type: 'text', text }]))
+  onUserInput(text => ctx.agents.get(SessionId('client-session'))?.followup([{ type: 'text', text }]))
 }
 ```
 
 ## A client-driver plugin (external protocol bridge)
 
-A *client driver* is a UI plugin for a wire-protocol peer. It owns stdio, so stdout logging must be disabled, creates or resumes agents through the factory, maps harness events to protocol messages, and maps requests to `send()` or `cancel()`. Settle each request exactly once from durable `turn/end`, even if rendering fails, and tear agents down with `AgentHandle.dispose()` so disposal reaches quiescence.
+A *client driver* is a UI plugin for a wire-protocol peer. It owns stdio, so stdout logging must be disabled, creates or resumes agents through the factory, maps harness events to protocol messages, and maps requests to `followup()` or `cancel()`. Settle each request exactly once from durable `turn/end`, even if rendering fails, and tear agents down with `AgentHandle.dispose()` so disposal reaches quiescence.
 
 `packages/ui/acp` is the worked example: it bridges the agent to the Agent Client Protocol (JSON-RPC over stdio) so Zed and other ACP editors can drive it. See its README for the full method surface and the permission-prompt answerer it registers on the approval seam.
 
@@ -99,9 +99,9 @@ Every product feature maps to a listener on a documented extension seam — the
 |---|---|
 | Hook system (user + project level) | listeners on `agent/session-start`, `agent/prompt-submit`, `agent/request`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation` — each interception waterfall returns a typed Decision; the `dsh-hooks-claude` / `dsh-hooks-codex` bridges map hook config files onto these seams |
 | `/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, `send()` the next iteration; or force-continue |
+| `/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 terminal `agent/turn-stop` |
-| Queued + steering messages | core `Agent.send()` / `Agent.steer()` |
+| 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/post-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) |
 | System prompt configurability | `ctx.systemPrompt.section()` with ordering and scope-local shadowing |
 | AGENTS.md (root) | a section provider reading the file |
@@ -113,13 +113,13 @@ Every product feature maps to a listener on a documented extension seam — the
 | Monotonic terminal turn policy | return `{ action: 'stop' }` from serial `agent/turn-stop`, after continuation and steering have already been folded |
 | 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]`, and the user-reviewed `exit_plan_mode` exit; enforcement stays on the independent sandbox/approval axes |
+| 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 |
 | Sub-agent delegation | the `ctx.subagents` provider registry (`dsh-subagent-spawn`/`-fork`/`-acp`) + `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 |
 | Memory | section provider + tool |
-| Scheduled tasks (cron) | a plugin registers model-callable scheduling tools; timer fires → `send(…, {source: {kind: 'cron', …}})` when idle / `inject()` notification when busy |
-| UI (GUI; CLI emits JSONL) | listen `session/event` (assistant chunks, boundaries, tool activity); input → `send()` |
+| 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()` |
 | 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 f34e9f2fa7..ef099ff318 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -36,7 +36,7 @@ export function apply(ctx: Context) {
 
 ## UI 插件
 
-UI 插件从 `session/event` 事件流渲染（助手 token 流以 `assistant/chunk` 形式到达，加上轮次/步骤边界与工具活动），并通过 `agent.send()` / `agent.steer()` 将输入驱动回去。
+UI 插件从 `session/event` 事件流渲染（助手 token 流以 `assistant/chunk` 形式到达，加上轮次/步骤边界与工具活动），并通过 `agent.followup()` / `agent.steer()` 将输入驱动回去。
 
 ```ts
 import type { Context } from 'cordis'
@@ -54,13 +54,13 @@ export function apply(ctx: Context) {
       render(event.data.chunk.text)
     }
   })
-  onUserInput(text => ctx.agents.get(SessionId('client-session'))?.send([{ type: 'text', text }]))
+  onUserInput(text => ctx.agents.get(SessionId('client-session'))?.followup([{ type: 'text', text }]))
 }
 ```
 
 ## 客户端驱动插件（外部协议桥接）
 
-*客户端驱动*是面向协议格式（wire format）对端的 UI 插件。它拥有 stdio，因此必须禁用 stdout 日志；通过工厂创建或恢复 agent（智能体）；将 harness 事件映射为协议消息；将请求映射为 `send()` 或 `cancel()`。每个请求从持久的 `turn/end` 恰好结算一次（即使渲染失败），并通过 `AgentHandle.dispose()` 拆除 agent 以使 dispose（资源释放）达到静止状态。
+*客户端驱动*是面向协议格式（wire format）对端的 UI 插件。它拥有 stdio，因此必须禁用 stdout 日志；通过工厂创建或恢复 agent（智能体）；将 harness 事件映射为协议消息；将请求映射为 `followup()` 或 `cancel()`。每个请求从持久的 `turn/end` 恰好结算一次（即使渲染失败），并通过 `AgentHandle.dispose()` 拆除 agent，确保 dispose（资源释放）流程完全停稳。
 
 `packages/ui/acp` 是完整的工作示例：它将 agent 桥接到 ACP（Agent Client Protocol）（基于 stdio 的 JSON-RPC），使 Zed 及其他 ACP 编辑器能够驱动它。其 README 描述了完整的方法接口以及它在审批 seam 上注册的权限提示应答器。
 
@@ -99,9 +99,9 @@ export function apply(ctx: Context) {
 |---|---|
 | 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/prompt-submit`、`agent/request`、`agent/step-result`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-continuation` 上的监听器——每个拦截 waterfall 返回一个类型化 Decision；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
 | `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话回合，独立的命令/工具生产方分别提供人类/模型控制 |
-| `/loop` | 在 `turn/end` 会话事件上 `send()` 下一次迭代；或强制继续 |
+| `/loop` | 在 `turn/end` 会话事件上 `followup()` 下一次迭代；或强制继续 |
 | 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的 prompt/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和终端 `agent/turn-stop` 来强制输出 |
-| 排队消息 + steering（中途引导） | 核心 `Agent.send()` / `Agent.steer()` |
+| 排队消息 + steering（中途引导） | 核心 `Agent.followup()` / `Agent.steer()` |
 | 上下文压缩（context compaction）（自动 + 手动） | `ctx.compact` seam + `dsh-compact-basic`；自动压力检查运行在串行 `agent/post-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 |
@@ -113,13 +113,13 @@ export function apply(ctx: Context) {
 | 单调终端轮次策略 | 从串行 `agent/turn-stop` 返回 `{ action: 'stop' }`，此时 continuation 和 steering 已折叠完毕 |
 | 子进程沙箱（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]`，以及经用户评审的 `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` 出口；强制约束留在独立的沙箱/审批轴上 |
 | 子 agent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
 | MCP | 每个服务器一个插件：发现工具 → `ctx.tools.register()` |
 | Skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
 | 记忆 | section provider + 工具 |
-| 定时任务（cron） | 插件注册面向模型的调度工具；定时器触发 → 空闲时 `send(…, {source: {kind: 'cron', …}})`／忙碌时 `inject()` 通知 |
-| UI（GUI；CLI 输出 JSONL） | 监听 `session/event`（助手分片、边界、工具活动）；输入 → `send()` |
+| 定时任务（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（热模块替换）直接生效 |
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 4ca3fd0601..ed9bebdc92 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -32,7 +32,7 @@ Effective broad cancellation was requested, before queued/steering work is clear
 
 Types: [Agent](../core-data-structures/core.md) · [AgentCancelCause](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:217`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:350`](../../packages/core/agent/src/types.ts)
 
 ### `agent/created` — emit
 
@@ -54,7 +54,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:179`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:285`](../../packages/core/agent/src/types.ts)
 
 ### `agent/disposed` — emit
 
@@ -74,7 +74,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:188`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:294`](../../packages/core/agent/src/types.ts)
 
 ### `agent/error` — emit
 
@@ -96,7 +96,77 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:365`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:498`](../../packages/core/agent/src/types.ts)
+
+### `agent/inbox/dequeue` — 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.
+
+```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 message - the claimed message (matching the `id` from its `agent/inbox/enqueue`).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void
+```
+
+Types: [Agent](../core-data-structures/core.md) · [AgentMessage](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+
+Source: [`packages/core/agent/src/types.ts:326`](../../packages/core/agent/src/types.ts)
+
+### `agent/inbox/discard` — emit
+
+Pending inbox items were dropped without delivering them, so every enqueued id receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. Emitters: `cancel()` without `keepInbox` (after `agent/cancel-requested`, before the abort); a terminal `agent/turn-stop` dropping pending steering (in-turn and on the post-turn late-steering drain); and disposal of any still-pending items (before `agent/status('disposed')`). Fires once per drop with every dropped item.
+
+```ts cordis-catalog
+/**
+ * Pending inbox items were dropped without delivering them, so every
+ * enqueued id receives exactly one terminal `agent/inbox/dequeue` OR
+ * `agent/inbox/discard`. Emitters: `cancel()` without `keepInbox` (after
+ * `agent/cancel-requested`, before the abort); a terminal `agent/turn-stop`
+ * dropping pending steering (in-turn and on the post-turn late-steering
+ * drain); and disposal of any still-pending items (before
+ * `agent/status('disposed')`). Fires once per drop with every dropped item.
+ * @param agent - the agent whose inbox items were dropped.
+ * @param messages - the discarded messages 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/discard'(this: Scoped<Agent>, agent: Agent, messages: AgentMessage[]): void
+```
+
+Types: [Agent](../core-data-structures/core.md) · [AgentMessage](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+
+Source: [`packages/core/agent/src/types.ts:340`](../../packages/core/agent/src/types.ts)
+
+### `agent/inbox/enqueue` — emit
+
+A detached, frozen item entered the agent's inbox (queued or steering FIFO). Source defaults are already applied, so `message` holds the exact accepted values. This is the enqueue-time live signal; the durable record is the eventual `user/message`/`steering/message`. Injection through `agent.inject()` or equivalent `send()` routing bypasses the FIFOs and does not emit this.
+
+```ts cordis-catalog
+/**
+ * A detached, frozen item entered the agent's inbox (queued or steering
+ * FIFO). Source defaults are already applied, so `message` holds the exact
+ * accepted values. This is the enqueue-time live signal; the durable record
+ * is the eventual `user/message`/`steering/message`. Injection through
+ * `agent.inject()` or equivalent `send()` routing bypasses the FIFOs
+ * and does not emit this.
+ * @param agent - the agent whose inbox received the item.
+ * @param message - the accepted message (its returned `id`, content, source, contexts, steering, and wakeup facts).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void
+```
+
+Types: [Agent](../core-data-structures/core.md) · [AgentMessage](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+
+Source: [`packages/core/agent/src/types.ts:316`](../../packages/core/agent/src/types.ts)
 
 ### `agent/post-step` — serial
 
@@ -119,7 +189,7 @@ Awaited serial checkpoint after the response, real or synthetic tool results, in
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:315`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:448`](../../packages/core/agent/src/types.ts)
 
 ### `agent/pre-step` — serial
 
@@ -142,7 +212,7 @@ Awaited serial checkpoint before `step/start`; appends land outside the pending
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:246`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:379`](../../packages/core/agent/src/types.ts)
 
 ### `agent/prompt-submit` — waterfall
 
@@ -169,28 +239,7 @@ Allow, rewrite, or block one claimed prompt before it becomes a user message. Ca
 
 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) · [PromptDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:262`](../../packages/core/agent/src/types.ts)
-
-### `agent/queued` — emit
-
-Detached, frozen content entered the agent's inbox. Source defaults have already been applied, so these are the exact values retained for the log.
-
-```ts cordis-catalog
-/**
- * Detached, frozen content entered the agent's inbox. Source defaults have
- * already been applied, so these are the exact values retained for the log.
- * @param agent - the agent whose inbox received the message.
- * @param content - the accepted content blocks retained by the inbox.
- * @param info - the accepted source, contexts, and whether it entered as steering.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; contexts: HookContext[]; steering: boolean }): void
-```
-
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [HookContext](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:207`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:395`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request` — waterfall
 
@@ -215,7 +264,7 @@ Replace the frozen call configuration. Model-visible content must use logged cha
 
 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:276`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:409`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request-error` — waterfall
 
@@ -241,7 +290,7 @@ Recover a model-request failure after its failed step has closed. `retry` opens
 
 Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestError](../core-data-structures/core.md) · [RequestErrorDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:330`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:463`](../../packages/core/agent/src/types.ts)
 
 ### `agent/session-prefix` — waterfall
 
@@ -267,7 +316,7 @@ Compose request-only messages placed before derived history. The frozen result i
 
 Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:291`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:424`](../../packages/core/agent/src/types.ts)
 
 ### `agent/session-start` — emit
 
@@ -289,16 +338,16 @@ 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:230`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:363`](../../packages/core/agent/src/types.ts)
 
 ### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
+Agent status changed (`idle` ⇄ `running`, or → `disposed`). A waking delivery does not enter `running` synchronously; drive lifecycle from this event.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does
- * not enter `running` synchronously; drive lifecycle from this event.
+ * Agent status changed (`idle` ⇄ `running`, or → `disposed`). A waking
+ * delivery 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.
@@ -309,7 +358,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no
 
 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:197`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:303`](../../packages/core/agent/src/types.ts)
 
 ### `agent/step-result` — waterfall
 
@@ -332,7 +381,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
 
 Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:303`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:436`](../../packages/core/agent/src/types.ts)
 
 ### `agent/turn-continuation` — waterfall
 
@@ -354,7 +403,7 @@ Override whether the turn continues. The default continues after tool calls or s
 
 Types: [Agent](../core-data-structures/core.md) · [ContinuationDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:341`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:474`](../../packages/core/agent/src/types.ts)
 
 ### `agent/turn-stop` — serial
 
@@ -376,7 +425,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a
 
 Types: [Agent](../core-data-structures/core.md) · [ContinuationStop](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:352`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:485`](../../packages/core/agent/src/types.ts)
 
 ## `agent-loop/*`
 
@@ -773,7 +822,7 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai
 'tools/change'(): void
 ```
 
-Source: [`packages/core/tools/src/index.ts:123`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:143`](../../packages/core/tools/src/index.ts)
 
 ### `tools/execute` — waterfall
 
@@ -795,7 +844,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 
 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)
 
-Source: [`packages/core/tools/src/index.ts:93`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:113`](../../packages/core/tools/src/index.ts)
 
 ### `tools/post-execute` — waterfall
 
@@ -818,7 +867,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 
 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)
 
-Source: [`packages/core/tools/src/index.ts:105`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:125`](../../packages/core/tools/src/index.ts)
 
 ### `tools/pre-execute` — waterfall
 
@@ -839,7 +888,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 
 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)
 
-Source: [`packages/core/tools/src/index.ts:82`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:102`](../../packages/core/tools/src/index.ts)
 
 ### `tools/result` — emit
 
@@ -858,7 +907,7 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 
 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)
 
-Source: [`packages/core/tools/src/index.ts:113`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:133`](../../packages/core/tools/src/index.ts)
 
 ## `workflow/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 0fcb2fc28e..0d6cc97086 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -317,11 +317,11 @@ list(): BashEnvVariableInfo[]
 
 Types: [DshEnvironment](../core-data-structures/bash.md) · [ToolExecution](../core-data-structures/tools.md)
 
-Source: [`packages/bash/tool-bash/src/index.ts:103`](../../packages/bash/tool-bash/src/index.ts)
+Source: [`packages/bash/tool-bash/src/index.ts:104`](../../packages/bash/tool-bash/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 while treating 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 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
 /**
@@ -338,7 +338,7 @@ abstract run(request: CodeRunRequest): Promise<CodeRunResult>
 
 Types: [CodeRunRequest](../core-data-structures/code-runtime.md) · [CodeRunResult](../core-data-structures/code-runtime.md)
 
-Source: [`packages/code-runtime/code-runtime/src/index.ts:30`](../../packages/code-runtime/code-runtime/src/index.ts)
+Source: [`packages/code-runtime/code-runtime/src/index.ts:33`](../../packages/code-runtime/code-runtime/src/index.ts)
 
 ## `ctx.commands` — `CommandService`
 
@@ -759,7 +759,7 @@ set(agent: Agent, active: boolean): void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/plan/plan-mode/src/index.ts:141`](../../packages/plan/plan-mode/src/index.ts)
+Source: [`packages/plan/plan-mode/src/index.ts:142`](../../packages/plan/plan-mode/src/index.ts)
 
 ## `ctx.pty` — `PtyService`
 
@@ -788,6 +788,13 @@ listBackends(): string[]
  */
 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.
@@ -834,7 +841,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:95`](../../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)
 
@@ -904,10 +911,9 @@ abstract locate(meta: SessionHeader): SessionLocation | undefined
 abstract create(meta: SessionHeader): Promise<void>
 
 /**
- * Durably persist a batch of events (called from the write-behind drain at
- * the `session/flush` checkpoint). 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-
+ * 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.
@@ -918,34 +924,93 @@ abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
  * Load a header and balanced contiguous log. 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.
+ * 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 with its stored header as a durable snapshot, while an
+ * open live turn rejects.
+ * A coordinator-backed cold load reserves the identity across storage awaits,
+ * so concurrent publication of a same-id live Session rejects.
  * @param id - the persisted session to reload.
  * @returns the header and a log ending on a balanced `turn/end`.
  */
 abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
 
+/**
+ * Inspect a header and its valid contiguous stored prefix without repairing
+ * a torn tail, closing an interrupted turn, or publishing coordinator state.
+ * This read is serialized with writes for the same id and returns detached
+ * values, so observers cannot mutate backend-owned state.
+ * @param id - the persisted session to inspect.
+ * @returns the header and valid stored event prefix exactly as observed.
+ */
+abstract inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
 /**
  * Lightweight listing from metadata, without a full-log parse.
  * @returns one header per materialized session.
  */
 abstract list(): 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.
+ * @returns one header and opaque revision per materialized session without loading full logs.
+ */
+abstract listSnapshots(): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionLocation](../core-data-structures/persistence.md)
+Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionLocation](../core-data-structures/persistence.md) · [SessionPersistenceSnapshot](../core-data-structures/persistence.md)
 
-Source: [`packages/session-persistence/session-persistence/src/index.ts:42`](../../packages/session-persistence/session-persistence/src/index.ts)
+Source: [`packages/session-persistence/session-persistence/src/index.ts:52`](../../packages/session-persistence/session-persistence/src/index.ts)
 
-## `ctx.sessionQuery` — `SessionQueryService`
+## `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
 
-Live-preferred logical-corpus exact-read and relationship-tracing service.
+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 in deterministic relevance order.
+ */
+abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionEventSearchHit>>
+
 /**
  * List the complete logical corpus using live-preferred records.
  * @returns deterministic newest-first cloned session records.
  */
 listSessions(): 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.
+ * @returns matching cloned records in deterministic newest-first order.
+ */
+async filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]>
+
 /**
  * Fold the latest log-backed title from one live-preferred logical session.
  * @param sessionId - live or persisted session id to read.
@@ -960,6 +1025,14 @@ async readTitle(sessionId: SessionId): Promise<SessionTitleSnapshot | undefined>
  */
 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.
@@ -992,9 +1065,9 @@ async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>
 async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>
 ```
 
-Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventTrace](../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) · [SessionRecord](../core-data-structures/session-query.md) · [SessionSurfaceSnapshot](../core-data-structures/session-query.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
+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) · [SessionEventSearchHit](../core-data-structures/session-query.md) · [SessionEventSearchRequest](../core-data-structures/session-query.md) · [SessionEventTrace](../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) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
 
-Source: [`packages/session-query/session-query/src/index.ts:41`](../../packages/session-query/session-query/src/index.ts)
+Source: [`packages/session-query/session-query/src/index.ts:74`](../../packages/session-query/session-query/src/index.ts)
 
 ## `ctx.sessionReferences` — `SessionReferenceService`
 
@@ -1173,7 +1246,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId):
 
 Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [OutOfBandSessionEventType](../core-data-structures/session.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md) · [SessionEventMap](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md) · [TurnTrigger](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/index.ts:605`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:606`](../../packages/core/session/src/index.ts)
 
 ## `ctx.sessionTitle` — `SessionTitleService`
 
@@ -1458,7 +1531,7 @@ 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)
 
-Source: [`packages/tasks/tasks/src/index.ts:76`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:77`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tokenMeter` — `TokenMeterService`
 
@@ -1540,7 +1613,7 @@ Tool registry and execution pipeline. Scoped registrations shadow globals; one v
 /**
  * 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 - the tool schema, execution, and optional presentation functions.
+ * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
  * @returns the exact disposer that unregisters the tool.
  */
 register(definition: ToolDefinition): () => void
@@ -1595,10 +1668,11 @@ schemas(scope?: ScopeKey): ToolSchema[]
 executionMode(exec: ToolExecutionInput): ToolExecutionMode
 
 /**
- * Execute through pre-policy, guards, around-dispatch, post-policy, 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
+ * 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
@@ -1612,7 +1686,30 @@ 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)
 
-Source: [`packages/core/tools/src/index.ts:524`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:634`](../../packages/core/tools/src/index.ts)
+
+## `ctx.tui` — `TuiExtensionService` (abstract seam)
+
+Optional terminal-local interaction service provided by one mounted TUI.
+
+The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugins receive only effect-owned overlay sessions.
+
+```ts cordis-catalog
+/**
+ * Queue an interactive overlay owned by the calling plugin fiber.
+ *
+ * The TUI displays one overlay at a time in FIFO order. Disposing the caller
+ * removes a queued overlay or closes an active one before plugin teardown
+ * settles. This live presentation is neither logged nor replayed.
+ *
+ * @param request - component factory, layout constraints, and cancellation.
+ * @returns the effect-owned overlay session.
+ * @throws when the TUI has begun shutting down.
+ */
+abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession
+```
+
+Source: [`packages/ui/tui/src/index.ts:150`](../../packages/ui/tui/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 
diff --git a/docs/cordis-primer.i18n.yaml b/docs/cordis-primer.i18n.yaml
new file mode 100644
index 0000000000..ef52bf6812
--- /dev/null
+++ b/docs/cordis-primer.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
+cordis-primer.md: ee65e6e702ecaeb506ce7334032c38e09c936cda
+cordis-primer.zh.md: ee4f6864ba7864fc95b5eb8e31acbcaea6e99825
diff --git a/docs/cordis-primer.md b/docs/cordis-primer.md
index 64230564b7..ee65e6e702 100644
--- a/docs/cordis-primer.md
+++ b/docs/cordis-primer.md
@@ -1,5 +1,7 @@
 # Cordis Primer
 
+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 In Five Ideas
diff --git a/docs/cordis-primer.zh.md b/docs/cordis-primer.zh.md
new file mode 100644
index 0000000000..ee4f6864ba
--- /dev/null
+++ b/docs/cordis-primer.zh.md
@@ -0,0 +1,48 @@
+# Cordis 入门
+
+[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)。
+
+## 五个核心概念
+
+- **插件是实现 Service 的对象。** 它可以是一个带有可选 `inject` 和 `apply(ctx)` 字段的函数，也可以是一个 `Service` 子类，其生命周期由 Cordis 挂载到当前上下文中。
+- **上下文是服务的容器。** 一个服务占据一个稳定的 `ctx.<key>`（如 `ctx.tools`、`ctx.llm`、`ctx.sessions`）；其他插件通过 key 查找服务，而非导入具体实现。
+- **通过 `inject` 声明服务依赖。** 插件声明所需的服务后，会等待这些服务就绪才启动；加载顺序通过服务依赖表达，而非手动编排启动序列。
+- **类型化事件用于通信。** 服务通过 TypeScript 声明合并注册事件名，然后以 `emit`、`waterfall`（瀑布式事件）、`parallel` 或 `serial` 方式分发，分别对应监听者观察、包装、并行扇出或按序执行。
+- **注册是可逆的副作用。** 提示词片段、工具 schema、适配器、提供方和监听器通过 `ctx.effect()` 或 `ctx.on()` 安装，reload 和 teardown 时可预期地回卷。
+
+## 分发模式
+
+每个事件具有以下分发模式之一，且只能通过对应方法分发。
+
+| 模式 | 是否 await？ | 分发顺序 | 是否有返回值？ |
+|---|---|---|---|
+| `emit` | 否 | 监听器按注册顺序观察 | 否 |
+| `waterfall` | 否 | 监听器按注册顺序观察 | 是 |
+| `parallel` | 是 | 所有监听器并行观察事件 | 否 |
+| `serial` | 是 | 监听器按注册顺序观察 | 是 |
+
+分发模式是事件公开契约的一部分。新的 harness 事件通过 `@mode` 标签记录模式，以便生成的目录可以将声明与分发调用点做交叉校验。
+
+<a id="cordis-waterfall-semantics"></a>
+
+## Cordis Waterfall 语义
+
+`ctx.waterfall` 是环绕中间件。监听器接收 `(...args, next)`。调用 `next()` 会执行下游监听器；下游返回值通过 `next()` 返回当前包装层，可由该层包装后继续向外返回。不调用 `next()` 直接返回则短路。
+
+协作式监听器通常修改一个共享的请求或决策对象，然后委托。监听器也可以选择完全替换结果，下游监听器将只看到替换后的结果。仅当监听器必须在普通注册之前运行时才使用 `prepend: true`。
+
+对于单决策事件，短路是设计意图。策略监听器在拥有决策权时可以不调用 `next()` 直接返回，而仅做标注或观察的监听器则必须委托。
+
+<a id="loader-configuration"></a>
+
+## Loader 配置
+
+`@cordisjs/plugin-include` 将 `!!js` 解析为表达式节点，但 Loader 仅在挂载插件前对条目的 `config` 做插值。条目元数据（`id`、`name`、`group`、`disabled`、`inject`、`intercept` 和 `isolate`）保持字面值；因此 `disabled: !!js ...` 是一个 truthy 对象，会始终禁用该条目。需要根据环境选择挂载哪些插件时，请使用显式的配置覆盖层。
+
+## 实践规则
+
+将行为封装为插件：工具流水线事件属于 `ctx.tools`，模型流式输出属于 `ctx.llm`，实时 agent（智能体）协调属于 `ctx.agents`。拦截和策略优先使用事件；直接能力调用优先使用服务方法。
+
+每个注册都应有对应的 disposer（dispose（资源释放）函数）：要么从 `ctx.effect()` 返回一个，要么使用 Cordis 提供的辅助方法自动处理。如果 teardown 顺序有要求，请将相关工作放在同一个 effect 中，以确保资源释放按预期顺序回卷。
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.md b/docs/cordis-tutorial/06-composition-and-hmr.md
index b11fdbe45c..bb236cc169 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.md
+++ b/docs/cordis-tutorial/06-composition-and-hmr.md
@@ -39,10 +39,10 @@ In `tmp/cordis-tutorial`, write `cordis.yml`:
 
 Two support plugins joined the list: HMR logs through the Cordis logger service, so without a console exporter you would not see its messages, and it `inject`s the `timer` service for debouncing — without `@cordisjs/plugin-timer` it sits in PENDING forever, silently. That silence is the subject of the next section.
 
-HMR also needs Node's loader internals:
+HMR reads Node's loader internals through the Loader's native helper. Run Cordis under tsx:
 
 ```sh
-node --expose-internals --import tsx ../../vendor/cordis/bin.js
+node --import tsx ../../vendor/cordis/bin.js
 ```
 
 Now edit `hello.ts` — change the log message — and save:
diff --git a/docs/cordis-tutorial/07-into-the-harness.md b/docs/cordis-tutorial/07-into-the-harness.md
index d25419afd5..a86c538d48 100644
--- a/docs/cordis-tutorial/07-into-the-harness.md
+++ b/docs/cordis-tutorial/07-into-the-harness.md
@@ -21,8 +21,12 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true, description: 'Who to greet' },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 
@@ -40,7 +44,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-Every pattern here is from the earlier chapters: `inject: ['tools']` ([chapter 3](03-services.md)) holds the plugin until the tool registry exists; `ctx.tools.register(...)` attaches the registration disposer to the plugin ([chapter 2](02-lifecycle-and-effects.md)), so unloading unregisters the tool. `defineTool` converts the `parameters` spec to the JSON Schema shown to the model, infers the type of `args`, and validates model-supplied arguments before `execute` runs.
+Every pattern here is from the earlier chapters: `inject: ['tools']` ([chapter 3](03-services.md)) holds the plugin until the tool registry exists; `ctx.tools.register(...)` attaches the registration disposer to the plugin ([chapter 2](02-lifecycle-and-effects.md)), so unloading unregisters the tool. `defineTool` converts the `parameters` spec to the JSON Schema shown to the model, infers the type of `args`, and validates model-supplied arguments before `execute` runs. The tool returns the canonical value declared by `output.schema`; `output.render` separately produces the Native and durable result content.
 
 ## An observer plugin
 
diff --git a/docs/core-data-structures/approval.i18n.yaml b/docs/core-data-structures/approval.i18n.yaml
new file mode 100644
index 0000000000..c9f6b1600c
--- /dev/null
+++ b/docs/core-data-structures/approval.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
+approval.md: c9b411e38508fc7e8ac2e2dd923d9c8cc2f475a3
+approval.zh.md: c3d67b195a0c04186911285ccb76cd89eceb421b
diff --git a/docs/core-data-structures/approval.md b/docs/core-data-structures/approval.md
index 8634415a62..c9b411e385 100644
--- a/docs/core-data-structures/approval.md
+++ b/docs/core-data-structures/approval.md
@@ -1,5 +1,7 @@
 # User Approval
 
+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 such as [dsh-acp](../../packages/ui/acp) provide answerers; 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)
diff --git a/docs/core-data-structures/approval.zh.md b/docs/core-data-structures/approval.zh.md
new file mode 100644
index 0000000000..c3d67b195a
--- /dev/null
+++ b/docs/core-data-structures/approval.zh.md
@@ -0,0 +1,90 @@
+# 用户审批
+
+[English](approval.md) | 中文
+
+[dsh-user-approval](../../packages/ui/user-approval) 的用户审批 seam 回答一个问题：这个具体操作是否可以继续？它拥有共享的请求/结果词汇、`ctx.approval` 分发服务、`approval/request` 应答者 waterfall（瀑布式事件）、仅记录日志的审计事件对，以及按会话的 `ask`/`never` 策略。UI 通道如 [dsh-acp](../../packages/ui/acp) 提供应答者；调用方如 [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)
+
+## 标识与结果
+
+每个请求都会获得一个全新的 `ApprovalRequestId`。该品牌类型将 `approval/asked` 与 `approval/decided` 审计事件配对，同时不会让审批 id 与工具调用 id 或 agent（智能体）/会话 id 互换。
+
+```ts type-equiv
+/**
+ * Pairs one `approval/asked` audit event with its `approval/decided`.
+ * Service-issued (one fresh id per {@link ApprovalService.request} call).
+ */
+type ApprovalRequestId = Branded<'ApprovalRequestId'>
+```
+
+`ApprovalOutcome` 是闭合的，且默认拒绝。`allowed-once` 仅授权所询问的那一个操作；调用方对 `rejected`、`cancelled` 和 `unavailable` 均执行拒绝。缺失、无所有权、抛异常或不合规的应答者会产生 `unavailable`，而非放行。
+
+```ts type-equiv
+/**
+ * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
+ * request, or unavailable answerer. Callers fail closed on `unavailable`.
+ */
+type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
+```
+
+## 按会话策略
+
+`ApprovalPolicy` 决定在交互式应答者运行之前发生什么。`ask` 委托给组合的应答者链，链的无应答默认值为 `unavailable`；`never` 确定性地返回 `rejected`，不分发任何应答者。生效值为会话日志中最后一条 `approval/policy` 事件，回退到服务配置。`setApprovalPolicy(session, policy)` 是唯一的写入路径，因此回放能重建覆盖值。
+
+```ts type-equiv
+/**
+ * A session's approval policy — what happens to an {@link ApprovalService}
+ * ask BEFORE any interactive answerer sees it:
+ *
+ * - `'ask'` (the default) — delegate to the composed answerers; with none
+ *   composed the chain falls through to the fail-closed `'unavailable'`
+ *   (exactly today's behavior).
+ * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
+ *   deterministically. The strict headless stance (CI, unattended runs) and
+ *   the only policy value stated in the system prompt — unlike `'ask'`, its
+ *   outcome is knowable without asking, so stating it cannot overclaim.
+ */
+type ApprovalPolicy = 'ask' | 'never'
+```
+
+提示词段落会声明 `never` 的确定性行为，并以服务自有的标记记录当前策略。重启后，步骤前叙述器从已记录的请求头中读取该标记，而非从部署 persona 行文中推断状态。ACP（Agent Client Protocol）空闲切换会在 bridge 中保持，直到下一个 `turn/start`，因为审批审计和策略事件必须保持在轮次内，以确保持久回放的正确性。
+
+## 审批请求
+
+`ApprovalRequest` 以足够精确的方式标识 agent 和工具操作，以便路由和审计该问题。它有意省略工具参数：应答者通过 `callId` 将提示附加到已流式输出的工具调用上，而非渲染一份可能漂移的副本。
+
+```ts type-equiv
+/**
+ * Readonly same-process permission question. `callId` links to an already
+ * presented tool call, so arguments are not duplicated here.
+ */
+interface ApprovalRequest {
+  /**
+   * The agent on whose behalf the question is asked. Routes the question (a
+   * UI answerer only answers for agents it owns) and receives the audit
+   * events on its session log.
+   */
+  readonly agent: Agent
+  /** The tool the question is about (presentation and audit). */
+  readonly toolName: string
+  /**
+   * The exact tool call being decided, when the asker has one — lets a UI
+   * attach the prompt to the tool call it already streamed.
+   */
+  readonly callId?: CallId
+  /** The asker's human-readable explanation of WHY it is asking. */
+  readonly reason?: string
+  /**
+   * Aborting withdraws the question: the request settles `'cancelled'`
+   * immediately and a late answer from a still-pending answerer is discarded.
+   */
+  readonly signal?: AbortSignal
+}
+```
+
+## 分发与审计
+
+`ctx.approval.request(req)` 要求发起请求的会话处于一个打开的轮次内。它追加 `approval/asked`，获取一个结果，追加对应的 `approval/decided`，然后以该结果 resolve。`never` 策略在服务内部、waterfall 分发之前强制执行，因此即使后来以 `prepend` 注册的应答者也无法绕过它。应答者在拥有该请求时返回结果，否则调用 `next()` 委托；第一个应答占据唯一的决策槽位。
+
+审计事件仅写入日志，不进入模型 transcript（文本记录）。模型可见的行为是调用方派生的工具结果，而请求头记录的是模型实际看到的提示词策略。服务 dispose（资源释放）时会一并移除其提示词段落和步骤前叙述器；应答者监听器独立地通过 effect 绑定到其所属插件。
diff --git a/docs/core-data-structures/bash.i18n.yaml b/docs/core-data-structures/bash.i18n.yaml
new file mode 100644
index 0000000000..98855cdc0c
--- /dev/null
+++ b/docs/core-data-structures/bash.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
+bash.md: 35cf2061588907dde41123efb01e453eb9cc929d
+bash.zh.md: 0cfeb9e1a858f7057e720215c41a757588751122
diff --git a/docs/core-data-structures/bash.md b/docs/core-data-structures/bash.md
index b639e55927..35cf206158 100644
--- a/docs/core-data-structures/bash.md
+++ b/docs/core-data-structures/bash.md
@@ -1,5 +1,7 @@
 # Bash Executor
 
+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.
 
 Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)
diff --git a/docs/core-data-structures/bash.zh.md b/docs/core-data-structures/bash.zh.md
new file mode 100644
index 0000000000..0cfeb9e1a8
--- /dev/null
+++ b/docs/core-data-structures/bash.zh.md
@@ -0,0 +1,241 @@
+# Bash 执行器
+
+[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）。通用后台任务的 id、所有权与控制位于 [tasks.md](tasks.md)；本 seam 返回一个不含任务概念的进程句柄。
+
+源码：[`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)
+
+## 受管 shell 环境命名空间
+
+`DSH_*` 变量是归 Harness 所有的子进程事实。面向模型的 bash 工具通过 `ctx.bashEnv` 收集它们，再经由 `BashExecRequest.dshEnv` 传递；执行器在合并当前快照之前会移除继承而来的 `DSH_*` 名称。
+
+```ts type-equiv
+/** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
+type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`
+```
+
+```ts type-equiv
+/** Trusted DeepSeek Harness variables for one bash execution. */
+type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>
+```
+
+## 请求与规格：`resolve()` 拆分
+
+该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`——这具体落实了仓库的「包（package） seam 上显式优于隐式」规则：`BashExecSpec` 的读者不必猜测工作目录或输出预算来自何处。
+
+```ts type-equiv
+/**
+ * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
+ * filled by {@link BashExecutor.resolve} from the implementation's config.
+ * This is the model-/plugin-facing shape; pass it to `resolve()` to obtain a
+ * fully-resolved {@link BashExecSpec}.
+ */
+interface BashExecRequest {
+  command: string
+  /** Working directory override (default: implementation-configured). */
+  workdir?: string | undefined
+  /** Timeout override in milliseconds (implementations cap it). */
+  timeoutMs?: number | undefined
+  /**
+   * Foreground stdout capture budget in bytes. Absent uses the executor's
+   * default output cap. Trusted in-process consumers use this when they must
+   * parse complete stdout up to their own bounded limit; the model-facing bash
+   * tool does not expose it as a parameter.
+   */
+  stdoutMaxBytes?: number | undefined
+  /** Abort signal — implementations kill the command when it fires. */
+  signal?: AbortSignal | undefined
+  /**
+   * Bytes to write to the command's stdin, then close it. Absent leaves stdin
+   * closed/empty (the default for model-driven tool calls). Set by in-process
+   * plugins (e.g. the hooks bridges, which write a hook command's JSON payload
+   * to its stdin); the model-facing bash tool does not expose it as a parameter
+   * (a model that needs stdin uses shell syntax like a heredoc or a pipe).
+   */
+  stdin?: string | undefined
+  /**
+   * Ordinary environment entries for the command, merged after the credential
+   * scrub. `DSH_*` is reserved for {@link dshEnv} and implementations reject it
+   * here. Set by in-process plugins (the hooks bridges set
+   * `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the model-facing bash tool
+   * does not expose it as a parameter.
+   */
+  env?: Record<string, string> | undefined
+  /**
+   * Harness-owned `DSH_*` variables for this execution. Executors discard
+   * ambient `DSH_*` entries before merging this snapshot, so an unavailable
+   * current fact cannot inherit a stale value from the harness process, and
+   * reject non-`DSH_*` names supplied through this managed channel.
+   */
+  dshEnv?: DshEnvironment | undefined
+  /** Fully resolved per-call sandbox policy; sandboxing executors default it. */
+  sandboxPolicy?: SandboxExecutionPolicy | undefined
+}
+```
+
+```ts type-equiv
+/**
+ * A resolved execution spec. {@link BashExecutor.resolve} fills and caps the
+ * required fields; {@link BashExecutor.start} ignores `timeoutMs` because
+ * background processes have no executor timeout.
+ */
+interface BashExecSpec {
+  command: string
+  workdir: string
+  timeoutMs: number
+  /**
+   * Resolved foreground stdout capture budget in bytes. `run()` uses it for
+   * stdout; background tasks and stderr keep the executor's own output cap.
+   */
+  stdoutMaxBytes: number
+  /** Abort signal — implementations kill the command when it fires. */
+  signal?: AbortSignal | undefined
+  /** Bytes to write to stdin before closing it; absent means no stdin. */
+  stdin?: string | undefined
+  /**
+   * Ordinary environment entries carried through from
+   * {@link BashExecRequest.env}. `DSH_*` remains reserved for {@link dshEnv}.
+   * OPTIONAL on the spec for the same reason as `stdin`: absent means no
+   * ordinary extra environment.
+   */
+  env?: Record<string, string> | undefined
+  /** Managed `DSH_*` snapshot; implementations reject ordinary names. */
+  dshEnv?: DshEnvironment | undefined
+  /** Resolved sandbox policy; ignored by executors that do not confine. */
+  sandboxPolicy: SandboxExecutionPolicy | undefined
+}
+```
+
+`stdin` 和 `env` 是受信任的进程内插件输入，不由 `dsh-tool-bash` 暴露。本地执行器会先清除环境中的凭据，再合并调用方显式提供的 env。见 [bash-stdin-env Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。
+
+`stdoutMaxBytes` 同样仅供受信任插件使用。它让前台消费方能在有界解析预算内请求完整 stdout，而不会改变 stderr、后台任务或面向模型的 bash 工具的常规输出上限。
+
+## 前台运行：`BashRunResult`
+
+一次已完成（或被终止）的前台运行的结果。正交的结果**独立报告**：一个进程可以同时超时并以退出码 0 退出（因为它捕获了信号），因此 `timedOut`、`aborted`、`signal` 和 `exitCode` 各自独立为一个字段；调用方永远不会把一次被截断的运行误读为干净的成功。
+
+```ts type-equiv
+/** The outcome of one completed (or killed) foreground run. */
+interface BashRunResult {
+  /** Exit code; null when the process died from a signal. */
+  exitCode: number | null
+  /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
+  signal: NodeJS.Signals | null
+  /**
+   * True when the executor's own timeout was the FIRST cause to cut the command
+   * short. Mutually exclusive with {@link aborted}: one fused deadline drives
+   * both the timeout and the caller's cancellation, so a timeout and an abort
+   * racing before process close report the single first-abort cause, not both
+   * (see the [timeout-library Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
+   */
+  timedOut: boolean
+  /**
+   * True when the caller's `AbortSignal` was the FIRST cause to kill the command
+   * (and it was not the executor's own timeout). Mutually exclusive with
+   * {@link timedOut} — see there for the first-cause classification.
+   */
+  aborted: boolean
+  /** The effective timeout applied to this run (after defaulting/capping). */
+  timeoutMs: number
+  stdout: CollectedOutput
+  stderr: CollectedOutput
+  /** Sandbox execution facts, absent for an unsandboxed executor. */
+  sandbox?: BashSandboxInfo
+}
+```
+
+每个流是一个 `CollectedOutput`：（可能被截断的）文本加恢复信息。截断时，`text` 是**尾部**，完整流溢出到一个私有文件：
+
+```ts type-equiv
+/** One captured stream: the (possibly truncated) text plus recovery info. */
+interface CollectedOutput {
+  /** Collected text — the TAIL of the stream when truncated. */
+  text: string
+  /** True when bytes were dropped from `text`. */
+  truncated: boolean
+  /** Path to a file holding the COMPLETE stream, when truncated and available. */
+  spillPath?: string
+}
+```
+
+## 文件沙箱：`BashSandboxInfo`
+
+使用沙箱的执行器通过 `BashExecutor.sandboxMode` 暴露其已配置的模式回退值。工具层请求 [`@deepseek-ai/dsh-sandbox-policy`](../../packages/sandbox/sandbox-policy/README.md)，把每个调用会话的持久 `sandbox/mode` 覆盖值与不可变 cwd 解析为 `BashExecRequest.sandboxPolicy`；经用户批准、严格更宽松的调用只替换模式。模式/root/enforcement 词汇归 [`@deepseek-ai/dsh-sandbox` 沙箱 seam](sandbox.md) 所有；模式仅管辖文件效果。
+
+沙箱化运行会报告其模式、保守的拒绝分类与强制执行完整度。`runnerFailed` 标记命令运行前沙箱 runner 已失败；前台执行会抛出 `SANDBOX_UNAVAILABLE`，而已结束的后台进程只能通过其事实通道报告。
+
+```ts type-equiv
+/**
+ * Sandbox facts for one run, present iff a sandboxing executor handled it.
+ * Facts are reported independently of process exit status so callers can
+ * distinguish command failures from policy denials and runner failures.
+ */
+interface BashSandboxInfo {
+  /** The mode the command actually ran under. */
+  mode: SandboxMode
+  /** Whether the sandbox denied a file operation. */
+  denied: boolean
+  /** How completely the selected runner enforced the requested mode. */
+  enforcement?: SandboxEnforcement
+  /** Whether the sandbox runner failed before the command could run. */
+  runnerFailed?: boolean
+}
+```
+
+最后一项补全了这套词汇：当受限模式没有可用后端时，`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`
+
+`start()` 返回不含 id 或所有者的句柄。`dsh-tool-bash` 将它适配为 `ctx.tasks.start()` 钩子；随后由通用运行时拥有任务标识与生命周期。`done` 在进程关闭时 resolve 且绝不 reject；进程结束后仍可读取，并且沙箱事实会在 `done` resolve 前写入。
+
+```ts type-equiv
+/**
+ * A background process handle returned by {@link BashExecutor.start}. It is the
+ * only access path; buffered output remains readable after exit. Executor
+ * disposal kills running processes and awaits {@link done}.
+ */
+interface BashProcess {
+  /** Process lifecycle state (settled exactly once). */
+  status: BashProcessStatus
+  /** Exit code once finished (null = killed by signal / still running). */
+  exitCode: number | null
+  /** Terminating signal name, when signal-killed. */
+  signal: NodeJS.Signals | null
+  /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */
+  readonly done: Promise<void>
+  /** Sandbox facts, stamped once a confined process settles. */
+  sandbox?: BashSandboxInfo
+  /**
+   * Read output produced since the previous read (consuming — consecutive
+   * reads never re-deliver). Reads that lost data flag `lossy` and point at
+   * full-stream spill files when available.
+   */
+  readOutput(): BashProcessRead
+  /**
+   * Kill the process group. Returns false when it had already finished
+   * (no-op); idempotent.
+   */
+  kill(): boolean
+}
+```
+
+`readOutput()` 返回增量 delta 与 spill 恢复事实：
+
+```ts type-equiv
+/** One incremental {@link BashProcess.readOutput} read. */
+interface BashProcessRead {
+  /** Output produced since the previous read (stderr in a marked section). */
+  delta: string
+  /** True when truncation dropped unread bytes the delta cannot include. */
+  lossy: boolean
+  /** Full stdout spill file, when stdout truncation occurred and a safe path is available. */
+  stdoutSpillPath?: string
+  /** Full stderr spill file, when stderr truncation occurred and a safe path is available. */
+  stderrSpillPath?: string
+}
+```
+
+## 服务
+
+`BashExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有进程组、超时/中止处理、有界收集器、spill 文件、凭据清除以及 dispose（资源释放）后完全停稳。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](tasks.md)。
diff --git a/docs/core-data-structures/code-runtime.i18n.yaml b/docs/core-data-structures/code-runtime.i18n.yaml
new file mode 100644
index 0000000000..218ef4eea9
--- /dev/null
+++ b/docs/core-data-structures/code-runtime.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
+code-runtime.md: 64de3c45d4f1d1d981daa6c6f074abb667e0aa52
+code-runtime.zh.md: 4b14aeb2183010e8140540258ce8109df9f59910
diff --git a/docs/core-data-structures/code-runtime.md b/docs/core-data-structures/code-runtime.md
index af3fdbc649..64de3c45d4 100644
--- a/docs/core-data-structures/code-runtime.md
+++ b/docs/core-data-structures/code-runtime.md
@@ -1,6 +1,8 @@
 # Code Runtime
 
-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 the tool-registry consumer (Code Mode) are specified in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md).
+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).
 
 Source: [`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
 
@@ -45,12 +47,12 @@ The result reports an error as a **field**, never a rejection of `run()` — rep
 interface CodeRunResult {
   /**
    * The program's completion value (its top-level `return`), when it ran to
-   * completion and the value survived the runtime's serialization boundary;
-   * a non-transferable value is replaced by a string rendering, and a failed
-   * or value-less run leaves this absent.
+   * completion and the value crossed the runtime's lossless-JSON boundary.
+   * Invalid or over-limit completions fail the run instead of substituting a
+   * rendered string; a failed or value-less run leaves this absent.
    */
-  value?: unknown
-  /** Text the program emitted, in order (capped by the implementation). */
+  value?: CodeJsonValue
+  /** Text the program emitted, in order, bounded only as part of the outer result. */
   logs: string[]
   /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
   error?: CodeRunFailure
@@ -59,7 +61,23 @@ interface CodeRunResult {
 
 ## Bindings: host functions as program globals
 
-Each `CodeBindingNamespace` becomes one global object of async callables inside the program (the Code Mode consumer passes one: `tools`). Arguments and resolutions must be structured-cloneable — a runtime may bridge calls across a serialization boundary — and a runtime treats binding names as hostile input (`__proto__` is an ordinary own property, never a prototype collision):
+Each `CodeBindingNamespace` becomes one global object of async callables inside the program (the Code Mode consumer passes one: `tools`). Arguments and resolutions must be lossless JSON and cross without a seam-level byte cap; the runtime may bridge them through structured clone. A namespace may declare a program-visible error class without making the runtime know the consumer's names: the runtime injects the real constructor and turns rejected calls into its instances. A runtime also treats binding names as hostile input (`__proto__` is an ordinary own property, never a prototype collision):
+
+```ts type-equiv
+/**
+ * Program-visible typed rejection for one binding namespace. The runtime
+ * injects a real error constructor under `name`; rejected member calls become
+ * its instances and expose the exact member name through
+ * `memberNameProperty`. Both strings are runtime data rather than knowledge
+ * of a particular consumer such as Code Mode.
+ */
+interface CodeBindingErrorClass {
+  /** Constructor global and resulting `Error.name` (must be a usable JS identifier). */
+  name: string
+  /** Non-empty own property for the member name; cannot replace `name`, `message`, or `stack`. */
+  memberNameProperty: string
+}
+```
 
 ```ts type-equiv
 /**
@@ -74,24 +92,32 @@ interface CodeBindingNamespace {
   global: string
   /** The callable members, keyed by the exact name the program calls. */
   functions: Record<string, CodeBindingFunction>
+  /** Optional program-visible typed rejection contract for this namespace. */
+  errorClass?: CodeBindingErrorClass
 }
 ```
 
+```ts type-equiv
+/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
+```
+
 ```ts type-equiv
 /**
  * One host-side function exposed to the program as an async callable. The
  * runtime bridges calls to it (possibly across a serialization boundary), so
- * `args` and the resolution value MUST be structured-cloneable; a runtime
- * rejects a non-cloneable value with a descriptive error rather than
- * corrupting the run. A rejection of this function surfaces inside the
- * program as a rejection of the corresponding call.
+ * `args` and the resolution value MUST be lossless JSON. A runtime rejects a
+ * lossy or non-cloneable value with a descriptive error rather than corrupting
+ * the run. No seam-level byte cap applies to a binding resolution. A rejection
+ * of this function surfaces inside the program as a rejection of the
+ * corresponding call.
  */
-type CodeBindingFunction = (args: unknown) => Promise<unknown>
+type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>
 ```
 
 ## Captured output and the failure taxonomy
 
-Logs are plain strings in emission order. The runtime captures the program's console and stream output, but channel and console-method metadata are not part of the seam because consumers render only the text. Implementations cap the aggregate output and mark truncation in-band.
+Logs are plain strings in emission order. The runtime captures the program's console and stream output, but channel and console-method metadata are not part of the seam because consumers render only the text. Implementations cap the serialized outer log-array plus completion-value or failure-message payload; fixed result-envelope syntax and consumer presentation whitespace are not part of that variable-payload ledger. Overflow is an explicit failure rather than in-band value substitution.
 
 Failure kinds are **orthogonal outcomes reported independently** (per [defensive-patterns](../defensive-patterns.md)): a budget expiry is not an exception, an abort is not a timeout, and a substrate death (e.g. OOM) is neither:
 
@@ -105,10 +131,12 @@ Failure kinds are **orthogonal outcomes reported independently** (per [defensive
  * - `'timeout'` — an implementation-owned budget expired; the message says which.
  * - `'abort'` — {@link CodeRunRequest.signal} fired.
  * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
+ * - `'invalid-output'` — the completion value was not lossless JSON.
+ * - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
  */
 interface CodeRunFailure {
   /** The failure class (see the interface doc for each kind's meaning). */
-  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit'
+  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
   /** Human-readable detail, suitable for feeding back to a model to self-correct. */
   message: string
 }
diff --git a/docs/core-data-structures/code-runtime.zh.md b/docs/core-data-structures/code-runtime.zh.md
new file mode 100644
index 0000000000..4b14aeb218
--- /dev/null
+++ b/docs/core-data-structures/code-runtime.zh.md
@@ -0,0 +1,147 @@
+# 代码运行时
+
+[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`）针对宿主提供的异步 binding 运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 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)
+
+## 运行：请求进，结果出
+
+`CodeRunRequest` 携带**运行时所需的一切**。按照「包（package）边界处显式优于隐式」的规则，默认值（时间预算、输出上限）来自实现的已校验配置，绝不是 `run()` 内部隐藏的 `??`：
+
+```ts type-equiv
+/**
+ * One run: the program source plus everything the runtime acts on. Per the
+ * explicit-over-implicit convention, defaulting (time budgets, output caps)
+ * is the implementation's validated config — a request carries no optional
+ * tuning knobs for a hidden `??` to fill in.
+ */
+interface CodeRunRequest {
+  /**
+   * The program source, in the runtime's {@link ../index.ts | language}. It
+   * runs as the body of an async function: top-level `await` and `return`
+   * are available, and the completion value becomes
+   * {@link CodeRunResult.value}.
+   */
+  program: string
+  /** Host functions exposed to the program, one global object per namespace. */
+  bindings: CodeBindingNamespace[]
+  /**
+   * Abort the run: the runtime stops the program (hard, even mid-loop) and
+   * resolves with a {@link CodeRunFailure} of kind `'abort'`. In-flight
+   * binding calls are the CALLER's to settle — the runtime only stops asking.
+   */
+  signal?: AbortSignal
+}
+```
+
+结果将错误报告为一个**字段**，而非 `run()` 的 rejection。报告失败的程序是调用方的职责，不走异常路径（与 `BashExecutor.run` 的 resolve-on-failure 契约一致）：
+
+```ts type-equiv
+/**
+ * The outcome of one run. An error is a FIELD on a resolved result, never a
+ * rejection of `run()` — reporting a failed program is the caller's job, not
+ * an exception path.
+ */
+interface CodeRunResult {
+  /**
+   * The program's completion value (its top-level `return`), when it ran to
+   * completion and the value crossed the runtime's lossless-JSON boundary.
+   * Invalid or over-limit completions fail the run instead of substituting a
+   * rendered string; a failed or value-less run leaves this absent.
+   */
+  value?: CodeJsonValue
+  /** Text the program emitted, in order, bounded only as part of the outer result. */
+  logs: string[]
+  /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
+  error?: CodeRunFailure
+}
+```
+
+## 绑定：宿主函数作为程序全局变量
+
+每个 `CodeBindingNamespace` 在程序内成为一个由异步可调用函数组成的全局对象（Code Mode 消费方传入一个：`tools`）。参数与返回值必须是无损 JSON，且跨越边界时不受 seam 层字节上限约束；运行时可以通过结构化克隆桥接它们。命名空间可以声明程序可见的错误类，而无需让运行时知道消费方的名称：运行时会注入真实构造函数，并将被拒绝的调用转为该类的实例。运行时也将绑定名视为不可信输入（`__proto__` 是普通自有属性，绝不会发生原型碰撞）：
+
+```ts type-equiv
+/**
+ * Program-visible typed rejection for one binding namespace. The runtime
+ * injects a real error constructor under `name`; rejected member calls become
+ * its instances and expose the exact member name through
+ * `memberNameProperty`. Both strings are runtime data rather than knowledge
+ * of a particular consumer such as Code Mode.
+ */
+interface CodeBindingErrorClass {
+  /** Constructor global and resulting `Error.name` (must be a usable JS identifier). */
+  name: string
+  /** Non-empty own property for the member name; cannot replace `name`, `message`, or `stack`. */
+  memberNameProperty: string
+}
+```
+
+```ts type-equiv
+/**
+ * A named group of {@link CodeBindingFunction}s the runtime exposes to the
+ * program as one global object (e.g. `tools`). Function names are arbitrary
+ * strings — a runtime must treat names like `__proto__` or `constructor` as
+ * ordinary own properties (null-prototype construction), never as prototype
+ * collisions.
+ */
+interface CodeBindingNamespace {
+  /** The global identifier the program sees (must be a valid JS identifier). */
+  global: string
+  /** The callable members, keyed by the exact name the program calls. */
+  functions: Record<string, CodeBindingFunction>
+  /** Optional program-visible typed rejection contract for this namespace. */
+  errorClass?: CodeBindingErrorClass
+}
+```
+
+```ts type-equiv
+/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
+```
+
+```ts type-equiv
+/**
+ * One host-side function exposed to the program as an async callable. The
+ * runtime bridges calls to it (possibly across a serialization boundary), so
+ * `args` and the resolution value MUST be lossless JSON. A runtime rejects a
+ * lossy or non-cloneable value with a descriptive error rather than corrupting
+ * the run. No seam-level byte cap applies to a binding resolution. A rejection
+ * of this function surfaces inside the program as a rejection of the
+ * corresponding call.
+ */
+type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>
+```
+
+## 捕获的输出与失败分类体系
+
+日志是按发出顺序排列的纯字符串。运行时捕获程序的 console 与流输出，但通道和 console 方法的元数据不属于 seam，因为消费方只渲染文本。实现会对序列化后的外层日志数组，以及完成值或失败消息的组合载荷设置上限；固定的结果封装语法与消费方展示空白不计入这份可变载荷计量。超限会显式失败，而不会在值中插入替代内容。
+
+失败类型是**正交的结果，独立报告**（见 [defensive-patterns](../defensive-patterns.md)）：预算耗尽不是异常，中止不是超时，基底崩溃（如 OOM）也不是二者中的任何一个：
+
+```ts type-equiv
+/**
+ * Why a run failed. The kinds are orthogonal outcomes reported independently
+ * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
+ * abort is not a timeout, and a substrate death is neither.
+ *
+ * - `'exception'` — the program threw or failed to parse/transform.
+ * - `'timeout'` — an implementation-owned budget expired; the message says which.
+ * - `'abort'` — {@link CodeRunRequest.signal} fired.
+ * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
+ * - `'invalid-output'` — the completion value was not lossless JSON.
+ * - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
+ */
+interface CodeRunFailure {
+  /** The failure class (see the interface doc for each kind's meaning). */
+  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
+  /** Human-readable detail, suitable for feeding back to a model to self-correct. */
+  message: string
+}
+```
+
+## 服务
+
+`CodeRuntime`（`ctx.codeRuntime`，抽象服务，定义于 [`packages/code-runtime/code-runtime/src/index.ts`](../../packages/code-runtime/code-runtime/src/index.ts)）由 `run(request)` 加两个只读描述符组成：`language`（程序必须使用的语言，`'typescript'` 是已知值；生成语言相关展示的消费方据此切换，遇到无法展示的语言时应显式报错）和 `isolation`（执行基底，`'worker-thread'`、`'process'`、`'container'`；仅为诊断标签，**不构成安全承诺**）。实现必须保证各次运行彼此隔离（无跨运行状态），并在 dispose（资源释放）时等待系统完全停稳：teardown 完成前，进行中的运行都已终止并等待结束。
diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/core-data-structures/compaction.i18n.yaml
new file mode 100644
index 0000000000..3f192f0194
--- /dev/null
+++ b/docs/core-data-structures/compaction.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
+compaction.md: 71bbe7d9c17c6a3d35684a6c87d3072ab4f88df1
+compaction.zh.md: 35e9c9ef0050f01c5249d1502bb2782511acc819
diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md
index 6fa281a96c..71bbe7d9c1 100644
--- a/docs/core-data-structures/compaction.md
+++ b/docs/core-data-structures/compaction.md
@@ -1,5 +1,7 @@
 # Compaction
 
+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 consumer (a `/compact` tool, deferred). 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)
diff --git a/docs/core-data-structures/compaction.zh.md b/docs/core-data-structures/compaction.zh.md
new file mode 100644
index 0000000000..35e9c9ef00
--- /dev/null
+++ b/docs/core-data-structures/compaction.zh.md
@@ -0,0 +1,97 @@
+# 压缩（compaction）
+
+[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) 后端）和消费方（延期实现的 `/compact` 工具）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包（package）。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。
+
+源码：[`packages/compact/compact/src/types.ts`](../../packages/compact/compact/src/types.ts)
+
+## `compact/*` 会话事件
+
+压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——记录压缩锁及其 provenance，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。关于复用 `user/message` 为何是如实建模而非权宜之计，见对应 Agent Note。
+
+| 事件 | 载荷 | 作用 |
+|---|---|---|
+| `compact/start` | `{ turn }` | 获取日志记录的锁 |
+| `compact/summary` | `{ summary, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens? }` | provenance：摘要块、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note） |
+| `compact/end` | `{ turn, error? }` | 释放锁（摘要调用抛出异常时设置 `error`） |
+
+锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。
+
+这些变体在 `declare module '@deepseek-ai/dsh-session'` 块内合并，因此——与其他子页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
+
+## `CompactionResult`
+
+成功压缩向调用方返回：记账事件 seq、原始摘要、被遮蔽的范围与 seq，以及估算 token 数。
+
+```ts type-equiv
+/** Result of a successful compaction operation. */
+interface CompactionResult {
+  /** The seq of the appended `compact/start` event. */
+  startSeq: number
+  /** The seq of the appended `compact/summary` event. */
+  summarySeq: number
+  /** The seq of the appended `compact/end` event. */
+  endSeq: number
+  /** The summary content blocks produced by the backend. */
+  summary: ContentBlock[]
+  /**
+   * The surface-boundary pair that was shadowed: the seqs of the first
+   * (`start`) and last (`end`) surface nodes of the replaced range. A
+   * surface-POSITION span, not a numeric seq interval — after a prior replace
+   * lands a fresh high-seq summary node at an older range's position, `start`
+   * can be GREATER than `end`. {@link CompactionResult.shadowedSeqs} is the
+   * authoritative set of shadowed nodes, in surface order.
+   */
+  shadowedRange: { start: number; end: number }
+  /** The seqs of all shadowed surface nodes, in surface order. */
+  shadowedSeqs: number[]
+  /** Estimated token count of the shadowed content. */
+  shadowedTokenCount: number
+}
+```
+
+## 服务
+
+自动调用方会说明策略为何运行；实现可以比普通压力更激进地处理已确认的溢出。
+
+```ts type-equiv
+/** Why automatic policy is asking a backend to consider compaction. */
+type CompactionTrigger = 'pressure' | 'context-overflow'
+```
+
+`CompactService` 暴露 `compactIfNeeded(agent, trigger, signal)` 以执行自动 `pressure` 或 `context-overflow` 策略；没有可安全执行的工作时返回 `null`。它还针对显式、两端均包含的 surface 范围暴露 `compactRegion(...)`。每个后端都使用包导出的 `COMPACT_CHECKPOINT_SOURCE` 标记其替换用的 `user/message`；消费方调用 `isCompactCheckpointSource()`，而不是把检查点识别逻辑耦合到某一个后端。实现必须把传入的 signal 转发给摘要流程。该 seam 不拥有计价 API：单例 [`ctx.tokenMeter`](token-meter.md) 直接拥有估算与回放，而 `dsh-compact-basic` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。
+
+压力压缩在串行 `agent/post-step` 中运行：此时成功的 assistant 输出、工具结果、缓冲上下文和 steering（中途引导）已持久化，但 `step/end` 尚未发生。一旦压力或规范化溢出满足条件，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)规定。
+
+## 工具结果剪枝产出
+
+可选的工具结果剪枝服务会报告每次持久内容替换以及 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. */
+interface PrunedEntry {
+  /** Full-fidelity tool-result event shadowed by the replacement. */
+  readonly originalSeq: number
+  /** Newly appended pruned tool-result event. */
+  readonly replacementSeq: number
+  /** Tool call shared by the original and replacement. */
+  readonly callId: CallId
+  /** Original text size in Unicode code points. */
+  readonly charsBefore: number
+  /** Replacement text size in Unicode code points. */
+  readonly charsAfter: number
+}
+```
+
+```ts type-equiv
+/** Aggregate outcome of one stable-surface pruning pass. */
+interface PruneResult {
+  /** Replacements in the snapshotted surface order. */
+  readonly pruned: readonly PrunedEntry[]
+  /** Total Unicode code points removed across replacements. */
+  readonly charsRemoved: number
+}
+```
diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml
new file mode 100644
index 0000000000..47310dd09b
--- /dev/null
+++ b/docs/core-data-structures/core.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
+core.md: 781267cccdb5bbda33e5be6a9e807fdbe47dbc83
+core.zh.md: d0f67983b98b0cf679a8e599a5f8ab3c64490dd0
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index 6b5596b782..781267cccd 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -1,5 +1,7 @@
 # Core Data Structures
 
+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.
 
 ## What counts as "core"
@@ -11,7 +13,7 @@ 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 `SchemaSpec`/`InferArgs` DSL 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 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.
 
 | Sub-page | Owns |
 |---|---|
@@ -22,7 +24,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [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()`, the turn-enclosure invariant |
 | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
-| [session-query.md](session-query.md) | logical records, bounded exact-event reads, and relationship traces |
+| [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 |
@@ -163,6 +165,8 @@ Adapters emit a raw **chunk** protocol; the loop logs the chunks (replay fidelit
 
 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)).
@@ -238,10 +242,10 @@ interface GenerateOptions {
   sessionId?: Branded<'SessionId'>
   /**
    * Provider-neutral classification for an auxiliary model call. Adapters may
-   * map the purpose to model-hidden transport metadata. Ordinary conversation
-   * requests leave it unset.
+   * map the purpose to model-hidden transport metadata or purpose-specific
+   * generation policy. Ordinary conversation requests leave it unset.
    */
-  purpose?: 'compaction'
+  purpose?: 'compaction' | 'session-title'
 }
 ```
 
@@ -323,7 +327,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`, `context/message`, `steering/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.
@@ -351,7 +355,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-The fourteen event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `prompt/blocked`, `context/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 turn-enclosure invariant 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 thirteen event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `prompt/blocked`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the turn-enclosure invariant 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
 
@@ -361,8 +365,9 @@ Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types
 
 ```ts type-equiv
 /**
- * Message options. An omitted source attests direct human input as `{ kind: 'user' }`
- * and may authorize policy consumers, so non-human producers must label their content.
+ * Options for {@link Agent.followup}, {@link Agent.queue}, and {@link Agent.steer}.
+ * An omitted source attests direct human input as `{ kind: 'user' }` and may
+ * authorize policy consumers, so non-human producers must label their content.
  */
 interface SendOptions {
   source?: MessageSource
@@ -372,19 +377,90 @@ interface SendOptions {
    * records them directly at its next checkpoint.
    */
   contexts?: HookContext[]
+  /** Opaque JSON state retained on the durable message but hidden from the model. */
+  meta?: JsonValue
 }
 ```
 
-`InjectOptions` accepts ordinary message attribution and durable model-hidden JSON metadata. Attached contexts belong only to queued or steering input, so synthetic injection cannot accept them:
-
 ```ts type-equiv
 /** Options specific to durable synthetic context injection. */
-interface InjectOptions extends Omit<SendOptions, 'contexts'> {
-  /** Opaque JSON state retained in the session event but hidden from the model. */
+interface InjectOptions {
+  /** Defaults to `{ kind: 'plugin', plugin: '' }`; non-human producers should identify themselves. */
+  source?: MessageSource
+  /** Opaque JSON state retained on the durable message but hidden from the model. */
   meta?: JsonValue
 }
 ```
 
+The advanced acceptance form makes every default explicit and rules out attached contexts on injection:
+
+```ts type-equiv
+/**
+ * Fully specified input for {@link Agent.send}. Unlike the intent-named
+ * helpers, this form applies no defaults: callers provide content, source,
+ * contexts, metadata (including explicit `undefined`), target, and wakeup.
+ * The union excludes attached contexts from non-waking next-step injection.
+ */
+type ResolvedAgentInput = {
+  content: ContentBlock[]
+  source: MessageSource
+  meta: JsonValue | undefined
+} & (
+  | { target: 'next-turn'; wakeup: boolean; contexts: HookContext[] }
+  | { target: 'next-step'; wakeup: true; contexts: HookContext[] }
+  | { target: 'next-step'; wakeup: false; contexts: [] }
+)
+```
+
+FIFO delivery methods return an opaque `AgentMessageId`, stable across that message's `agent/inbox/*` events. Injection returns an id but bypasses those events:
+
+```ts type-equiv
+/**
+ * Opaque id assigned to one accepted agent input. FIFO inputs carry the same id
+ * on their `agent/inbox/*` events; injection bypasses those events.
+ */
+type AgentMessageId = Branded<'AgentMessageId'>
+```
+
+The `agent/inbox/*` live events carry one accepted message; injection bypasses the FIFOs and never appears on them:
+
+```ts type-equiv
+/**
+ * One accepted FIFO message, carried by the `agent/inbox/*` live events. `id`
+ * is the value returned by the accepting helper or {@link Agent.send},
+ * stable across this message's enqueue, dequeue, and discard events. Source
+ * defaults, when applicable, are already applied, so these are the exact values
+ * the item was accepted with.
+ * `steering` is true for an item drained between steps; otherwise it is claimed
+ * at a turn boundary. `SendOptions.meta` is intentionally omitted: it is durable
+ * model-hidden state that lands on the eventual `user/message`/
+ * `steering/message`, not live-event routing data.
+ */
+interface AgentMessage {
+  /** The id returned by the accepting helper or {@link Agent.send}. */
+  id: AgentMessageId
+  content: ContentBlock[]
+  source: MessageSource
+  contexts: HookContext[]
+  /** Whether the item joined the steering FIFO rather than the queued FIFO. */
+  steering: boolean
+  /** Whether the item wakes the driver or requests another step. */
+  wakeup: boolean
+}
+```
+
+```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
+}
+```
+
 ```ts type-equiv
 /** Stable runtime cause accepted by {@link Agent.cancel}. */
 type AgentCancelCause =
@@ -392,65 +468,103 @@ type AgentCancelCause =
   | { readonly kind: 'parent' }
 ```
 
+The structural `Agent` interface exposes four intent helpers plus the fully resolved acceptance method. The concrete driver implements the matrix once, and each helper supplies its fixed routing and defaults.
+
 ```ts type-equiv
 /** Public agent handle; its concrete implementation is internal to `@deepseek-ai/dsh-agent-loop`. */
 interface Agent {
   /** The single identity shared with {@link session}. */
   readonly id: SessionId
+  /** 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
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
   /**
-   * Queue one detached, frozen lossless-JSON item. If claimed, it is the sole
-   * ordinary message in its FIFO-ordered turn; the next claimed item waits for
-   * that turn's checkpoint.
-   * Attached contexts share the same snapshot and ownership boundary. Invalid
-   * input throws synchronously before notification or enqueue.
+   * Queue an ordinary message as its own FIFO-ordered turn and wake the driver.
+   * Content, resolved source, and attached contexts are detached, validated,
+   * and frozen together; invalid input throws synchronously before notification
+   * or enqueue.
+   * @param content - the prompt content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
    */
-  send(content: ContentBlock[], options?: SendOptions): void
+  followup(content: ContentBlock[], options?: SendOptions): AgentMessageId
 
   /**
-   * Submit steering while the agent is `running`. An open turn records it at
-   * the next steering checkpoint before a request or continuation decision;
-   * policy may stop before another step. After turn close and its checkpoint,
-   * any remainder is queued for a later turn; terminal `agent/turn-stop`,
-   * cancellation, or disposal may discard it. Uses the same synchronous
-   * snapshot-and-validation boundary as {@link send}; when idle, delegates to it.
+   * Queue an ordinary message without waking an idle driver. The item retains
+   * FIFO order and is claimed only after another input wakes the driver. A lone
+   * queued item leaves `whenIdle()` resolved.
+   * @param content - the prompt content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
    */
-  steer(content: ContentBlock[], options?: SendOptions): void
+  queue(content: ContentBlock[], options?: SendOptions): AgentMessageId
+
+  /**
+   * Submit steering into the running turn and request another step. An open turn
+   * records it at the next steering checkpoint before a request or continuation
+   * decision; policy may stop before another step. After turn close and its
+   * checkpoint, any remainder is queued for a later turn; terminal
+   * `agent/turn-stop`, cancellation, or disposal may discard it. Idle steering
+   * becomes a waking ordinary turn.
+   * @param content - the steering content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
+   */
+  steer(content: ContentBlock[], options?: SendOptions): AgentMessageId
 
   /**
    * Append detached model-facing context without running the model. An open-turn
    * injection joins at the current log position unless the current tool batch is
-   * executing; then it waits FIFO until that batch settles and drains before turn
-   * close even when interrupted. Idle injection uses a one-shot turn and durability
-   * checkpoint. Disposal awaits idle checkpoints; flush failures report through `agent/error`.
+   * executing; then it waits FIFO until that batch settles and drains before
+   * turn close even when interrupted. Idle injection uses a one-shot turn and
+   * durability checkpoint. Disposal awaits idle checkpoints; flush failures
+   * report through `agent/error`. An omitted source defaults to
+   * `{ kind: 'plugin', plugin: '' }`.
+   * @param content - the injected context content blocks.
+   * @param options - source and durable model-hidden meta.
+   * @returns the accepted injection's {@link AgentMessageId}; injection emits no `agent/inbox/*` events.
    */
-  inject(content: ContentBlock[], options?: InjectOptions): void
+  inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId
 
   /**
-   * Clear all queued and steering work, including items waiting to start, 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. Omission means `{ kind: 'user' }`. Idle cancellation is a no-op
-   * and does not arm later work. The active turn snapshots and freezes the cause.
-   * @param cause - the stable caller intent carried by the current turn signal.
+   * Accept one fully specified input through the same snapshot and routing path
+   * as the four intent-named helpers. `next-turn` targets the ordinary FIFO;
+   * `next-step`/wakeup targets steering (falling back to an ordinary waking turn
+   * while idle); and `next-step` without wakeup injects durable context without
+   * running the model. Every field is mandatory and no source or routing default
+   * is applied. Invalid input throws synchronously before notification, enqueue,
+   * or append.
+   * @param input - the resolved content, attribution, context, metadata, and routing facts.
+   * @returns the accepted input's {@link AgentMessageId}, carried by FIFO lifecycle events when applicable.
    */
-  cancel(cause?: AgentCancelCause): void
+  send(input: ResolvedAgentInput): AgentMessageId
+
+  /**
+   * 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. Omitted cause
+   * means `{ kind: 'user' }`. Idle cancellation is a no-op and does not arm
+   * later work. The active turn snapshots and freezes the cause.
+   * @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>
-
 }
 ```
 
 `AgentStatus` is `'idle' | 'running' | 'disposed'`, and `SessionId` is branded. `running` describes the driver-wide drain interval, which can span turn close, its durability checkpoint, and consecutive queued turns; it does not prove a turn is still open. `AgentOptions` is merge-extensible: core declares `provider?` and `model?` (dispatch requires both after `agent/request`). 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 holder copies its discriminant into the runtime-only `AbortSignal.reason`; it is retired before `turn/end` publication. `agentInterruptReasonOf(signal)` recognizes `user`, `parent`, and lifecycle-only `disposed` without consulting ambient initiator state. 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. `agentInterruptReasonOf(signal)` recognizes `user`, `parent`, and lifecycle-only `disposed` without consulting ambient initiator state. 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.
 
@@ -460,7 +574,7 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,
 
 ## Interception decisions
 
-Each `agent/*` interception waterfall returns a small, seam-specific typed union — the unified Decision idiom (the tool seams' `PreToolDecision`/`PostToolDecision` in [tools.md](tools.md) follow the same shape). A CC/Codex hook bridge maps its `permissionDecision`/`decision`/`continue`/`additionalContext` fields onto these; a native plugin returns them directly. Prompt and post-tool decisions share one model-facing context shape, `HookContext`, which carries a REQUIRED `source` (a missing source would default to `{kind:'user'}` and mislabel plugin context as a user prompt). Its `content` reaches the model verbatim as user-role input, while JSON `meta` persists plugin state without exposing it to the model. Absent or `separate` placement becomes `context/message`; `prompt-prefix` placement is available to prompt and steering inbox attachments and bakes the context before the effective request in the same message. Both decisions carry `additionalContexts[]` so every entry preserves its own provenance, metadata, and placement. Continuation reasons are steering messages instead and deliberately use the narrower content/source shape.
+Each `agent/*` interception waterfall returns a small, seam-specific typed union — the unified Decision idiom (the tool seams' `PreToolDecision`/`PostToolDecision` in [tools.md](tools.md) follow the same shape). A CC/Codex hook bridge maps its `permissionDecision`/`decision`/`continue`/`additionalContext` fields onto these; a native plugin returns them directly. Prompt and post-tool decisions share one model-facing context shape, `HookContext`, which carries a REQUIRED `source` (a missing source would default to `{kind:'user'}` and mislabel plugin context as a user prompt). Its `content` reaches the model verbatim as user-role input, while JSON `meta` persists plugin state without exposing it to the model. Absent or `separate` placement becomes an injected `user/message` (plugin/goal source); `prompt-prefix` placement is available to prompt and steering inbox attachments and bakes the context before the effective request in the same message. Both decisions carry `additionalContexts[]` so every entry preserves its own provenance, metadata, and placement. Continuation reasons are steering messages instead and deliberately use the narrower content/source shape.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
@@ -470,8 +584,8 @@ interface HookContext {
   content: ContentBlock[]
   source: MessageSource
   /**
-   * Model placement. Absent or `separate` records an independent
-   * `context/message`; `prompt-prefix` prepends this context and a stable
+   * Model placement. Absent or `separate` records an independent injected
+   * `user/message`; `prompt-prefix` prepends this context and a stable
    * request delimiter to the same user-role message as its attached prompt.
    */
   placement?: 'separate' | 'prompt-prefix'
@@ -544,6 +658,6 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## `ToolDefinition`
 
-The one pipeline-authoring type that is core: what every registered tool *is* — a model-facing `ToolSchema` plus an `execute` function and optional UI presenters. 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.
+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`/`SchemaSpec`/`InferArgs` typed schema DSL, the `ToolExecution`/`ToolExecutionResult` waterfall shapes, and the tool-presentation UI vocabulary are on **[tools.md](tools.md)**.
+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)**.
diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md
new file mode 100644
index 0000000000..d0f67983b9
--- /dev/null
+++ b/docs/core-data-structures/core.zh.md
@@ -0,0 +1,671 @@
+# 核心数据结构
+
+[English](core.md) | 中文
+
+本目录编目 DeepSeek Harness 的**数据结构**：每个核心类型代表什么、它的字面形状，以及完整细节在哪里。它与 [architecture.md](../architecture.md) 互补——后者描述*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；本页描述行为所操作的*词汇*。
+
+## 什么算"核心"
+
+harness 是一个微内核：一个极小的核心加上众多插件。大多数类型属于某一个插件或某一项能力。但有少数类型构成**主干**——agent loop（智能体循环）及其事件在*每一个*轮次中使用的语言，无论加载了哪些可选插件。这些就是"核心"。
+
+精确地说，一个数据结构是**核心**的，当且仅当满足以下条件之一：
+
+1. 它流经 agent loop 主干——循环在每个轮次中持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄本身），与当前加载了哪些插件无关；**或者**
+2. 它是插件作者面向某条流水线编写的代表性类型——`ToolDefinition`（每个工具*是什么*）。
+
+其他一切都记录在**子页面**上，而非本页。划线的规则是：*你编写、持有或接收的类型是核心；为它提供类型推导、渲染或持久化的机制是子页面细节*。因此 `ToolDefinition` 是核心，但为它提供类型推导的 `ValueSchemaSpec`/`ParameterSchemaSpec` 机制、为它提供渲染意图的 `ToolCallView`/`ToolResultView` 词汇，以及存储事件日志的 `SessionPersistence` seam 都不是——它们分别在下列子页面中。
+
+| 子页面 | 负责内容 |
+|---|---|
+| [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` 上下文 |
+| [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` |
+| [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` 句柄 |
+| [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` 致命性 |
+
+> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](../cordis-catalog/services.md)。
+
+<a id="the-map--derived-union-pattern"></a>
+
+## `…Map → derived-union` 模式
+
+harness 中几乎所有可扩展的和类型都遵循同一形状：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包（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'; /* … */ }
+  }
+}
+```
+
+六个规范 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) |
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
+| `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
+| `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
+
+消费方最常 `switch` 的两个大型判别联合类型是：**`StreamChunk`**（流式协议）和 **`SessionEvent`**（日志条目）。按仓库约定，对标签做 `switch`——不要链式 `if`——这样每个分支都能窄化类型，拼错的标签会编译失败。
+
+<a id="branded-ids"></a>
+
+## 品牌化 ID
+
+跨越包边界的 ID 都经过**品牌化**——结构上是字符串，但在类型层面不可互换（不能把 `SessionId` 传给需要 `CallId` 的位置）。每种类型通过各自的工厂构造；比较、日志记录和 JSON 行为与普通字符串相同。
+
+`Branded<B>` 原语位于独立的纯类型包 [dsh-brand](../../packages/util/brand) 中（没有运行时代码，也不依赖 Harness 包），因此任何包都能品牌化其拥有的 id，而无需依赖无关的能力包。
+
+源码：[`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 }
+```
+
+两个核心 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/压缩支持。
+
+`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
+/**
+ * A single message in a conversation history. Loop-derived assistant messages
+ * always carry provenance; callers may omit it on hand-built foreign history.
+ */
+interface Message {
+  role: 'system' | 'user' | 'assistant'
+  content: ContentBlock[]
+  /** Present only on assistant messages produced by a routed adapter. */
+  provenance?: AssistantProvenance
+}
+```
+
+消息来源本身也是一个可合并扩展的和类型：
+
+```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 }
+}
+```
+
+## 流式输出
+
+适配器发出原始**分片**协议；循环记录分片（回放保真度），同时将同一批分片送入 `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
+/** 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
+}
+```
+
+```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
+/** A single model request, fully assembled. */
+interface GenerateOptions {
+  /** Registered provider route selecting the adapter instance. */
+  provider: string
+  model: string
+  /**
+   * Ordered conversation messages, exactly as the provider sees them (after
+   * the `system` slot). A loop-built request assembles them as
+   * `EpochHeader.messagePrefix` + 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` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型或采样参数。`agent/session-prefix` 为每个循环实例组合一次仅用于请求的 prefix 消息，header 记录实际使用的确切结果。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
+
+在协议格式上，循环构建的请求按此顺序读取：`system` 槽位（渲染后的提示词组装）→ `messagePrefix`（冻结的会话前缀）→ 派生历史——边界快照，其尾部在轮次首步是最新的 `user/message`，在后续步骤是上一步的工具结果。前缀从不进入派生历史；它的持久记录是 header 事件，开发不变式针对每个循环构建的请求精确重算此等式。
+
+FIXME(call-config-shape)：重新审视此类型的精确定义——出于缓存目的，哪些字段确实属于 epoch 层级（`model` 肯定属于；采样标量目前出于谨慎放在这里），以及适配器需要时，提供方特有的额外项（推理选项、额外 body 参数）应归属何处。
+
+```ts type-equiv
+/**
+ * Provider + model + sampling scalars of one conversation's requests. Every field maps
+ * 1:1 onto the same-named `GenerateOptions` field; the loop builds requests
+ * from the logged header rather than accepting these per call.
+ */
+interface LlmCallConfig {
+  provider: string
+  model: string
+  temperature?: number
+  maxTokens?: number
+  stop?: string[]
+}
+```
+
+## 会话
+
+`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`、`prompt/blocked`、`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
+/**
+ * Options for {@link Agent.followup}, {@link Agent.queue}, and {@link Agent.steer}.
+ * An omitted source attests direct human input as `{ kind: 'user' }` and may
+ * authorize policy consumers, so non-human producers must label their content.
+ */
+interface SendOptions {
+  source?: MessageSource
+  /**
+   * Model-facing contexts captured with this inbox item. A queued prompt exposes
+   * them through the default `agent/prompt-submit` allow decision, while steering
+   * records them directly at its next checkpoint.
+   */
+  contexts?: HookContext[]
+  /** Opaque JSON state retained on the durable message but hidden from the model. */
+  meta?: JsonValue
+}
+```
+
+```ts type-equiv
+/** Options specific to durable synthetic context injection. */
+interface InjectOptions {
+  /** Defaults to `{ kind: 'plugin', plugin: '' }`; non-human producers should identify themselves. */
+  source?: MessageSource
+  /** Opaque JSON state retained on the durable message but hidden from the model. */
+  meta?: JsonValue
+}
+```
+
+高级接收形式会显式给出所有默认值，并禁止为注入附加上下文：
+
+```ts type-equiv
+/**
+ * Fully specified input for {@link Agent.send}. Unlike the intent-named
+ * helpers, this form applies no defaults: callers provide content, source,
+ * contexts, metadata (including explicit `undefined`), target, and wakeup.
+ * The union excludes attached contexts from non-waking next-step injection.
+ */
+type ResolvedAgentInput = {
+  content: ContentBlock[]
+  source: MessageSource
+  meta: JsonValue | undefined
+} & (
+  | { target: 'next-turn'; wakeup: boolean; contexts: HookContext[] }
+  | { target: 'next-step'; wakeup: true; contexts: HookContext[] }
+  | { target: 'next-step'; wakeup: false; contexts: [] }
+)
+```
+
+FIFO 投递方法返回不透明的 `AgentMessageId`，该 id 在同一条消息的各个 `agent/inbox/*` 事件中保持稳定。注入也返回 id，但会绕过这些事件：
+
+```ts type-equiv
+/**
+ * Opaque id assigned to one accepted agent input. FIFO inputs carry the same id
+ * on their `agent/inbox/*` events; injection bypasses those events.
+ */
+type AgentMessageId = Branded<'AgentMessageId'>
+```
+
+`agent/inbox/*` 实时事件承载一条已接收的消息；注入绕过两个 FIFO，从不出现在这些事件中：
+
+```ts type-equiv
+/**
+ * One accepted FIFO message, carried by the `agent/inbox/*` live events. `id`
+ * is the value returned by the accepting helper or {@link Agent.send},
+ * stable across this message's enqueue, dequeue, and discard events. Source
+ * defaults, when applicable, are already applied, so these are the exact values
+ * the item was accepted with.
+ * `steering` is true for an item drained between steps; otherwise it is claimed
+ * at a turn boundary. `SendOptions.meta` is intentionally omitted: it is durable
+ * model-hidden state that lands on the eventual `user/message`/
+ * `steering/message`, not live-event routing data.
+ */
+interface AgentMessage {
+  /** The id returned by the accepting helper or {@link Agent.send}. */
+  id: AgentMessageId
+  content: ContentBlock[]
+  source: MessageSource
+  contexts: HookContext[]
+  /** Whether the item joined the steering FIFO rather than the queued FIFO. */
+  steering: boolean
+  /** Whether the item wakes the driver or requests another step. */
+  wakeup: boolean
+}
+```
+
+```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
+}
+```
+
+```ts type-equiv
+/** Stable runtime cause accepted by {@link Agent.cancel}. */
+type AgentCancelCause =
+  | { readonly kind: 'user' }
+  | { readonly kind: 'parent' }
+```
+
+结构化 `Agent` 接口公开四个按意图命名的辅助方法，以及接受完全解析输入的方法。具体驱动器只需实现一次这套路由矩阵，每个辅助方法提供其固定路由与默认值。
+
+```ts type-equiv
+/** Public agent handle; its concrete implementation is internal to `@deepseek-ai/dsh-agent-loop`. */
+interface Agent {
+  /** The single identity shared with {@link session}. */
+  readonly id: SessionId
+  /** 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
+  /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
+  readonly ctx: Context
+
+  /**
+   * Queue an ordinary message as its own FIFO-ordered turn and wake the driver.
+   * Content, resolved source, and attached contexts are detached, validated,
+   * and frozen together; invalid input throws synchronously before notification
+   * or enqueue.
+   * @param content - the prompt content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
+   */
+  followup(content: ContentBlock[], options?: SendOptions): AgentMessageId
+
+  /**
+   * Queue an ordinary message without waking an idle driver. The item retains
+   * FIFO order and is claimed only after another input wakes the driver. A lone
+   * queued item leaves `whenIdle()` resolved.
+   * @param content - the prompt content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
+   */
+  queue(content: ContentBlock[], options?: SendOptions): AgentMessageId
+
+  /**
+   * Submit steering into the running turn and request another step. An open turn
+   * records it at the next steering checkpoint before a request or continuation
+   * decision; policy may stop before another step. After turn close and its
+   * checkpoint, any remainder is queued for a later turn; terminal
+   * `agent/turn-stop`, cancellation, or disposal may discard it. Idle steering
+   * becomes a waking ordinary turn.
+   * @param content - the steering content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
+   */
+  steer(content: ContentBlock[], options?: SendOptions): AgentMessageId
+
+  /**
+   * Append detached model-facing context without running the model. An open-turn
+   * injection joins at the current log position unless the current tool batch is
+   * executing; then it waits FIFO until that batch settles and drains before
+   * turn close even when interrupted. Idle injection uses a one-shot turn and
+   * durability checkpoint. Disposal awaits idle checkpoints; flush failures
+   * report through `agent/error`. An omitted source defaults to
+   * `{ kind: 'plugin', plugin: '' }`.
+   * @param content - the injected context content blocks.
+   * @param options - source and durable model-hidden meta.
+   * @returns the accepted injection's {@link AgentMessageId}; injection emits no `agent/inbox/*` events.
+   */
+  inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId
+
+  /**
+   * Accept one fully specified input through the same snapshot and routing path
+   * as the four intent-named helpers. `next-turn` targets the ordinary FIFO;
+   * `next-step`/wakeup targets steering (falling back to an ordinary waking turn
+   * while idle); and `next-step` without wakeup injects durable context without
+   * running the model. Every field is mandatory and no source or routing default
+   * is applied. Invalid input throws synchronously before notification, enqueue,
+   * or append.
+   * @param input - the resolved content, attribution, context, metadata, and routing facts.
+   * @returns the accepted input's {@link AgentMessageId}, carried by FIFO lifecycle events when applicable.
+   */
+  send(input: ResolvedAgentInput): AgentMessageId
+
+  /**
+   * 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. Omitted cause
+   * means `{ kind: 'user' }`. Idle cancellation is a no-op and does not arm
+   * later work. The active turn snapshots and freezes the cause.
+   * @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>
+}
+```
+
+`AgentStatus` 为 `'idle' | 'running' | 'disposed'`，`SessionId` 是品牌类型。`running` 描述整个驱动器的排空区间，可能跨越轮次关闭、其持久化检查点以及连续的排队轮次；它不能证明某个轮次仍然打开。`AgentOptions` 可合并扩展：core 声明 `provider?` 与 `model?`（在 `agent/request` 后，分发要求两者都存在）。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
+
+cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancellation` 持有者会把其判别字段复制到仅运行时的 `AbortSignal.reason`，并在发布 `turn/end` 前退役；冻结后的 `AbortSignal.reason` 仍可读取。`agentInterruptReasonOf(signal)` 无需查询环境中的 initiator 状态，即可识别 `user`、`parent` 与仅用于生命周期的 `disposed`。持久 `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)规定。
+
+## 拦截决策
+
+每个 `agent/*` 拦截 waterfall 都返回一个小型、特定于 seam 的类型化联合——统一的 Decision 惯用形状（[tools.md](tools.md) 中工具 seam 的 `PreToolDecision`/`PostToolDecision` 也采用相同形状）。CC/Codex 钩子桥接层把其 `permissionDecision`/`decision`/`continue`/`additionalContext` 字段映射到这些联合上；原生插件则直接返回它们。提示词决策与工具后决策共享一种面向模型的上下文形状 `HookContext`，它必须携带 `source`（缺少 source 会默认成 `{kind:'user'}`，从而把插件上下文错标为用户提示词）。其中的 `content` 作为 user-role 输入逐字到达模型，而 JSON `meta` 持久保存插件状态但不向模型暴露。未指定放置方式或指定为 `separate` 时，上下文会成为一条注入的 `user/message`（来源类别为插件或 goal）；`prompt-prefix` 放置方式可用于提示词和 steering 收件箱附件，会在同一条消息中把上下文置于最终生效的请求之前。两种决策都携带 `additionalContexts[]`，使每一项保留各自的 provenance、元数据与放置方式。Continuation reason 则是 steering 消息，并有意使用更窄的 content/source 形状。
+
+源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
+
+```ts type-equiv
+/** Model-facing context injected by a listener or atomically attached to one inbox message. */
+interface HookContext {
+  content: ContentBlock[]
+  source: MessageSource
+  /**
+   * Model placement. Absent or `separate` records an independent injected
+   * `user/message`; `prompt-prefix` prepends this context and a stable
+   * request delimiter to the same user-role message as its attached prompt.
+   */
+  placement?: 'separate' | 'prompt-prefix'
+  /** Opaque JSON state retained in the session event but hidden from the model. */
+  meta?: JsonValue
+}
+```
+
+`agent/prompt-submit` 返回 `PromptDecision`（允许该轮次已领取的排队消息——可选地改写其 `content` 或附加 `additionalContexts`——或者记录 `prompt/blocked` 并以 `rejected` 结束这个零步骤轮次）：
+
+```ts type-equiv
+/**
+ * Prompt interception result. `allow.content` replaces the prompt. Each
+ * `additionalContexts` entry follows its declared placement: separate context
+ * message by default, or a prefix inside the prompt's user-role message.
+ * `block` records a durable `prompt/blocked` and ends the claimed prompt's
+ * zero-step turn as rejected. An `allow` returned by a listener is
+ * authoritative: a listener wrapping `next()` preserves downstream `content`
+ * and `additionalContexts` unless it intentionally replaces them.
+ */
+type PromptDecision =
+  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
+  | { kind: 'block'; reason: string }
+```
+
+`agent/turn-continuation` 返回 `ContinuationDecision`（步骤有工具调用或注入了 steering 时，循环默认为 `continue`，否则为 `stop`；`continue` 的 `reason` 会记录为同一轮次中下一个步骤的 steering，因此不携带上下文元数据——即类型化 `/goal` 模式）：
+
+```ts type-equiv
+/** Turn continuation override; a continue reason is recorded as next-step steering in the same turn. */
+type ContinuationDecision =
+  | { action: 'stop' }
+  | { action: 'continue'; reason?: { content: ContentBlock[]; source: MessageSource } }
+```
+
+`agent/request-error` 接收确切的原始 `RequestError`、其不可变 `LlmFailure`、在连续序列中已批准另一次请求的不可变失败列表、轮次信号以及 `next()`。恢复插件按 `failure.code` 路由，而不是按活跃错误的消息路由；每项策略只统计自身的 code，一次成功请求会清空历史：
+
+```ts type-equiv
+/** Model-request failure with an optional machine-routable provider code. */
+type RequestError = Error & { code?: string }
+```
+
+它返回 `RequestErrorDecision`；`retry` 在恢复 listener 的持久变更之后打开一个带新编号的步骤，而 `fail` 在 `turn/end` 上保留结构化失败：
+
+```ts type-equiv
+/** Failed-request recovery decision; `retry` opens another numbered step while listeners delegate by calling `next()`. */
+type RequestErrorDecision = { action: 'fail' } | { action: 'retry' }
+```
+
+`agent/post-step` 会在 assistant 输出、真实或合成的工具结果、缓冲上下文与 steering 持久化之后、`step/end` 之前被 await。被取消的工具批次在排空后携带 aborted signal 到达这里；其签名为 `(agent, turn, step, signal)`，可回放事实保留在会话日志中，而不是瞬态 payload 中。
+
+`agent/turn-stop` 返回仅停止的 `ContinuationStop` 子集或 `undefined`。循环在折叠普通决策、其 reason 和待处理 steering 之后调用此串行检查点；stop 是终态，会丢弃待处理的 steering。
+
+```ts type-equiv
+/**
+ * The terminal subset of {@link ContinuationDecision}. A listener on
+ * `agent/turn-stop` returns this to make the already-composed continuation
+ * outcome terminal; `undefined` abstains.
+ */
+type ContinuationStop = Extract<ContinuationDecision, { action: 'stop' }>
+```
+
+`agent/session-start` 携带 `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'
+```
+
+`agent/session-prefix` 在每个循环实例中组合一次 `Message[]`。深度冻结的结果被记录在请求 header 中，并前置于每次派生历史，使其成为会话稳定开场白的归属。恢复的实例会重新组合；会话中途的变更使用仅追加的上下文通道。该 waterfall 直接返回内容，因为它是贡献而非决策。
+
+## `ToolDefinition`
+
+唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
+
+其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/core-data-structures/filesystem.i18n.yaml
new file mode 100644
index 0000000000..e360dd99d3
--- /dev/null
+++ b/docs/core-data-structures/filesystem.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
+filesystem.md: 110c1fd428b15c5094f9dcc94050cad61c324373
+filesystem.zh.md: aca450364c05c6f756c36fccc11be7246767f3a4
diff --git a/docs/core-data-structures/filesystem.md b/docs/core-data-structures/filesystem.md
index 84d1ce9c5a..110c1fd428 100644
--- a/docs/core-data-structures/filesystem.md
+++ b/docs/core-data-structures/filesystem.md
@@ -1,5 +1,7 @@
 # Filesystem
 
+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 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.
@@ -205,7 +207,7 @@ interface FsPolicyExec {
 
 ## Read outcome (consumer / read rendering)
 
-A text read is bounded by line window, byte cap, and backend limits. The outcome the model-facing `read` tool renders is purely presentational; there is no `full`/`partial` view — authorization is freshness-based (the tool emits `fs/observed` with the stat's version directly), so any windowed read can authorize a later write/edit when the file is unchanged. Read windowing and this outcome shape live in `dsh-tool-fs` (the executor that owns the read), not in the policy plugin.
+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.
 
 ```ts type-equiv
 /** Outcome of a bounded text read — what {@link formatReadOutput} renders. */
@@ -214,9 +216,9 @@ interface FileReadOutcome {
   offset: number
   /** Returned lines, already numbered. */
   lines: FileTextLine[]
-  /** Total line count in the file, unless `truncatedByBytes` stopped scanning early. */
+  /** Exact total line count in the file. */
   totalLines: number
-  /** Whether selected output hit the byte cap before EOF or the requested limit. */
+  /** Whether selected output hit the byte cap. */
   truncatedByBytes?: true
 }
 ```
diff --git a/docs/core-data-structures/filesystem.zh.md b/docs/core-data-structures/filesystem.zh.md
new file mode 100644
index 0000000000..aca450364c
--- /dev/null
+++ b/docs/core-data-structures/filesystem.zh.md
@@ -0,0 +1,259 @@
+# 文件系统
+
+[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。
+
+该模型是**加法式而非减法式**的：`ctx.fs` 本身就是一个完整、无约束的文本存储 seam（`write` 无条件创建或覆盖，`edit` 无条件替换字面文本）。`dsh-fs-policy` 是一个插件，通过裁决 `fs/*` waterfall（瀑布式事件）在上层*叠加*策略；移除它只会暴露裸提供方，而不会破坏工具，因为工具与策略之间没有方法级耦合。加载了 `dsh-tool-fs` 的部署通常也应加载 `dsh-fs-policy`，使默认行为为「先读后写/编辑」。
+
+提供方源码：[`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），也不得假设它是本地绝对路径。
+
+```ts type-equiv
+/**
+ * A path resolved by a backend into a stable identity. `resolve()` produces
+ * this; every other operation takes it.
+ */
+interface FsTarget {
+  /** Opaque key for stale guards and target lookup. */
+  targetKey: FsTargetKey
+  /**
+   * Path for model/UI-facing output. May be a local absolute path,
+   * workspace-relative path, or remote URI depending on the backend.
+   */
+  displayPath: string
+}
+```
+
+后端拥有文件版本 token，即 write/edit 所守卫的新鲜度 token。策略插件存储它们以进行陈旧检查；消费方不解释其内容。两个 id 都是品牌化的不透明字符串。
+
+```ts type-equiv
+/**
+ * Opaque key for stale guards and target lookup. The local backend uses a
+ * realpath-like string; a remote backend might use a workspace URI or file id.
+ * Consumers MUST NOT parse it or assume it is a local absolute path.
+ */
+type FsTargetKey = Branded<'FsTargetKey'>
+```
+
+```ts type-equiv
+/**
+ * Opaque file-version token — the freshness token a write/edit guards against.
+ * The local backend derives it from high-resolution stat identity and freshness
+ * fields; a remote backend might use a revision id. The policy layer records it
+ * for stale checks; consumers may display related metadata but MUST NOT
+ * interpret this token.
+ */
+type FsVersion = Branded<'FsVersion'>
+```
+
+`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。
+
+```ts type-equiv
+/**
+ * Metadata about a target — what {@link FileSystem.stat} returns. Lets the
+ * policy layer reject directories/special files before reading and choose
+ * `readText` vs `streamText` from `size` without probing by failure. `version`
+ * is the freshness token. `undefined` from `stat` means the target is absent.
+ */
+interface FsInfo {
+  /** Opaque freshness token of the target right now. */
+  version: FsVersion
+  /** Whether the target is a regular file, a directory, or something else. */
+  type: 'file' | 'directory' | 'other'
+  /** Byte size of a regular file, when the backend can report it. */
+  size?: number
+}
+```
+
+`lstat` 是路径层级、不跟随链接的元数据原语。它接收路径而不是 `FsTarget`，因为 `resolve` 会有意跟随 symlink 以产生稳定标识；需要检查信任边界的消费方可以先调用 `lstat`，在解析前拒绝 `symlink`。
+
+```ts type-equiv
+/**
+ * Metadata about a path without following the final path component when it is a
+ * symbolic link. Unlike {@link FsInfo}, this path-level probe can report
+ * `symlink` so consumers with trust-boundary rules can reject repository-owned
+ * links before resolving a target.
+ */
+interface FsPathInfo {
+  /** Opaque freshness token of the path entry right now. */
+  version: FsVersion
+  /** Whether the path entry is a regular file, directory, symlink, or other. */
+  type: 'file' | 'directory' | 'symlink' | 'other'
+  /** Byte size of the path entry, when the backend can report it. */
+  size?: number
+}
+```
+
+`listDir` 按稳定的名称顺序返回直接子条目。每个条目携带子项的 basename、类型、已解析目标，以及后端能报告时的廉价元数据。它禁止读取文件内容，因此 `size` 仅用于普通文件，`version` 来自元数据。已损坏或已消失的子项可以作为 `other` 返回且不带元数据；列出或解析子项元数据时的权限或后端 I/O 失败会以 `FS_PERMISSION_DENIED` 或 `FS_IO_ERROR` 使整个列表操作失败。
+
+```ts type-equiv
+/**
+ * One direct child returned by {@link FileSystem.listDir}. Listing returns
+ * metadata and resolved targets only; it must not read file contents.
+ */
+interface FsDirEntry {
+  /** Basename of the child inside the listed directory. */
+  name: string
+  /** Whether the child is a regular file, a directory, or something else. */
+  type: 'file' | 'directory' | 'other'
+  /** Resolved child target for follow-up operations. */
+  target: FsTarget
+  /** Opaque freshness token when the backend can report metadata cheaply. */
+  version?: FsVersion
+  /** Byte size of a regular file, when the backend can report it. */
+  size?: number
+}
+```
+
+## 写入与编辑守卫（提供方 seam）
+
+`writeText` 和 `editText` 的版本守卫都是可选的：省略它执行无条件（裸提供方）变更，提供它则启用守卫。`writeText` 的守卫是 `FsWriteIntent`：`createIfAbsent` 在目标缺失时创建，目标已存在时以 `FS_NOT_OBSERVED` 拒绝；`replaceIfVersion` 仅在目标存在且版本匹配时替换，否则报 `FS_STALE_VERSION`。省略 `expected` 则无条件创建或覆盖。联合类型本身只包含两种有守卫的意图；「无守卫」通过省略表达，因此 write 和 edit 共享同一个对称的 `expected?` 形状。
+
+```ts type-equiv
+/**
+ * Guarded write intent. `createIfAbsent` rejects an existing target with
+ * `FS_NOT_OBSERVED`; `replaceIfVersion` rejects absence or mismatch with
+ * `FS_STALE_VERSION`. Omitting the intent from `writeText` means unconditional
+ * create-or-overwrite, not a third union arm.
+ */
+type FsWriteIntent =
+  | { kind: 'createIfAbsent' }
+  | { kind: 'replaceIfVersion'; version: FsVersion }
+```
+
+```ts type-equiv
+/** Outcome of a full-file write. */
+interface FsWriteOutcome {
+  /** Whether the write created a new file or replaced an existing one. */
+  operation: 'create' | 'update'
+  /** Opaque version of the file after the write. */
+  version: FsVersion
+  /**
+   * The file's content BEFORE the write, or `null` when the file did not exist
+   * (a create) or was undiffable (binary/non-UTF-8). LF-normalized storage text
+   * (the diff basis), never a diff — a consumer computes the result-time
+   * contextual diff from `before`/`after` when `before` is present, else falls
+   * back to a whole-file diff.
+   */
+  before: string | null
+  /** The file's content AFTER the write, LF-normalized to share `before`'s diff basis. */
+  after: string
+}
+```
+
+`editText` 是提供方级别的变更操作，而非在别处组合的 `read` 加 `write`。带守卫时，它在字面匹配之前先验证预期版本（因此对陈旧内容的编辑报 `FS_STALE_VERSION`，而非对更新内容的匹配失败）；不带守卫时，它编辑当前内容。无论哪种路径，它都应用替换并原子写入——将匹配、行尾处理、陈旧检查和原子替换保持在一个变更临界区内——目标缺失时两条路径都报 `FS_STALE_VERSION`。
+
+```ts type-equiv
+/** A literal-replacement edit request. */
+interface FsEditRequest {
+  /** Literal non-empty text to replace. Must match exactly (after line-ending normalization). */
+  oldString: string
+  /** Literal replacement text. An empty string deletes the matched text. */
+  newString: string
+  /** Replace every match instead of requiring exactly one. */
+  replaceAll: boolean
+}
+```
+
+```ts type-equiv
+/** Outcome of a literal edit. */
+interface FsEditOutcome {
+  /** Opaque version of the file after the edit. */
+  version: FsVersion
+  /**
+   * The file's content BEFORE the edit. Raw storage text (LF-normalized by the
+   * backend), never a diff — a consumer computes the result-time contextual diff
+   * (the applied hunk with context) from `before`/`after`.
+   */
+  before: string
+  /** The file's content AFTER the edit. */
+  after: string
+}
+```
+
+## fs 策略事件（提供方 seam 词汇）
+
+`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/*` 事件携带的不透明 `object` actor 来推导观测状态的所有者。`ToolExecution` 满足此形状，因此 `dsh-tool-fs` 将其执行对象作为 actor 直接传递，而无需让 `dsh-fs-policy` 导入工具、agent 或会话包（package）。
+
+```ts type-equiv
+/**
+ * Minimal structural view of a tool execution the policy plugin needs to derive
+ * an observed-state owner. `@deepseek-ai/dsh-tools`' `ToolExecution` satisfies
+ * this shape, so the tool passes its `exec` straight through as the opaque
+ * `object` actor on the `fs/*` events; this plugin narrows that actor to this
+ * shape without importing `dsh-tools`, `dsh-agent`, or `dsh-session`.
+ *
+ * The owner is `agent.session` when present. It is treated as an opaque object
+ * identity (a `WeakMap` key); this package never reads any of its fields.
+ */
+interface FsPolicyExec {
+  /** The agent on whose behalf the call runs, when there is one. */
+  agent?: {
+    /** The session that owns observed-file state, used as an opaque key. */
+    session?: object
+  }
+}
+```
+
+## 读取结果（消费方 / 读取渲染）
+
+文本读取受行窗口、字节上限和后端限制约束。达到字节上限后，扫描仍会继续，但不再保留更多行，因此 `totalLines` 仍为精确值。面向模型的 `read` 工具渲染的结果纯粹是展示性的；不存在 `full`/`partial` 视图区分——授权基于新鲜度（工具直接用 stat 的版本 emit `fs/observed`），因此任何窗口化读取在文件未变时都能授权后续的 write/edit。读取窗口化与此结果形状位于 `dsh-tool-fs`（拥有读取操作的执行器）中，而非策略插件中。
+
+```ts type-equiv
+/** Outcome of a bounded text read — what {@link formatReadOutput} renders. */
+interface FileReadOutcome {
+  /** 1-based first line requested. */
+  offset: number
+  /** Returned lines, already numbered. */
+  lines: FileTextLine[]
+  /** Exact total line count in the file. */
+  totalLines: number
+  /** Whether selected output hit the byte cap. */
+  truncatedByBytes?: true
+}
+```
+
+## 已观测文件状态（策略插件）
+
+已观测状态是 `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 分支而无需解析文本。
+
+```ts type-equiv
+/**
+ * Stable, machine-routable codes for filesystem failures. Carried on
+ * {@link FsError}; the tool registry surfaces `{ name, code }` on `isError`
+ * results so retry/permission/UI layers can branch without parsing messages.
+ */
+type FsErrorCode =
+  | 'FS_NOT_FOUND'
+  | 'FS_NOT_DIRECTORY'
+  | 'FS_NOT_TEXT'
+  | 'FS_NOT_REGULAR_FILE'
+  | 'FS_PERMISSION_DENIED'
+  | 'FS_SANDBOX_DENIED'
+  | 'FS_IO_ERROR'
+  | 'FS_STALE_VERSION'
+  | 'FS_NOT_OBSERVED'
+  | 'FS_AMBIGUOUS_EDIT'
+  | 'FS_EDIT_NOT_FOUND'
+  | '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`。
+
+## 服务与插件
+
+`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` 签名。
diff --git a/docs/core-data-structures/goal.md b/docs/core-data-structures/goal.md
index d45847ba0f..c0351f2f77 100644
--- a/docs/core-data-structures/goal.md
+++ b/docs/core-data-structures/goal.md
@@ -69,7 +69,7 @@ interface GoalView extends GoalSnapshot {
 
 ## Durable changes
 
-Every mutation is a `context/message` whose metadata is either a complete snapshot or a clear tombstone. The version, metadata, goal source, and verbatim rendered content form one replay invariant.
+Every mutation is a round-zero goal-sourced `user/message` whose metadata is either a complete snapshot or a clear tombstone. The version, metadata, goal source, and verbatim rendered content form one replay invariant.
 
 ```ts type-equiv
 /** Full-snapshot goal mutation retained in a model-visible context event. */
diff --git a/docs/core-data-structures/llm-streaming.i18n.yaml b/docs/core-data-structures/llm-streaming.i18n.yaml
new file mode 100644
index 0000000000..28191bd56c
--- /dev/null
+++ b/docs/core-data-structures/llm-streaming.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
+llm-streaming.md: cb99c935aea2dc9cc769e3056fdb98a2e5c9eacb
+llm-streaming.zh.md: 740fa1f796088e63d0195cfbecf975adb236381c
diff --git a/docs/core-data-structures/llm-streaming.md b/docs/core-data-structures/llm-streaming.md
index 257ce90cda..cb99c935ae 100644
--- a/docs/core-data-structures/llm-streaming.md
+++ b/docs/core-data-structures/llm-streaming.md
@@ -1,5 +1,7 @@
 # LLM Streaming
 
+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.
 
 Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
diff --git a/docs/core-data-structures/llm-streaming.zh.md b/docs/core-data-structures/llm-streaming.zh.md
new file mode 100644
index 0000000000..740fa1f796
--- /dev/null
+++ b/docs/core-data-structures/llm-streaming.zh.md
@@ -0,0 +1,218 @@
+# LLM（大语言模型）流式输出
+
+[English](llm-streaming.md) | 中文
+
+[dsh-llm](../../packages/llm/llm) 的协议格式（wire format）级流式输出词汇。[core.md](core.md) 介绍了 `StreamChunk`、`Message` 与 `ContentBlock`；本页拥有完整的分片协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。
+
+源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+## `StreamChunk`：原始协议
+
+一个流式响应交错包含多种类型的块（文本、推理（reasoning）、多个工具调用）。`index` 将每个 delta 关联到其所属块；`block-end` 携带完整组装好的 `ContentBlock`，消费方无需自行重新组装 delta。这是一个**封闭的**可辨识联合类型：对 `type` 的 `switch` 以 `assertNever` 结尾，因此新增变体会在每个必须处理它的消费方处触发编译错误。
+
+```ts type-equiv
+/**
+ * Raw streaming protocol emitted by adapters.
+ * Block indexes correlate interleaved deltas, and `block-end` carries the
+ * assembled block. Adapters emit usage before the terminal finish and nothing
+ * afterward; tool arguments remain raw JSON strings. Failures either throw or
+ * end with `error`/`aborted`, and consumers must handle both paths.
+ */
+type StreamChunk =
+  | { type: 'block-start'; index: number; blockType: ContentBlockType }
+  | { type: 'text-delta'; index: number; text: string }
+  | { type: 'reasoning-delta'; index: number; text: string }
+  | { type: 'tool-call-delta'; index: number; id: CallId; name?: string; argumentsDelta: string }
+  | { type: 'block-end'; index: number; block: ContentBlock }
+  | { type: 'usage'; usage: TokenUsage }
+  | {
+    type: 'finish'
+    reason: FinishReason
+    /** Adapter-private lossless-JSON state for replaying a successful response. */
+    replayState?: unknown
+  }
+```
+
+## `LlmFailure`
+
+每个抛出的失败或最终适配器的带内失败都会规范化为一种可序列化、提供方无关的 payload。`providerRetryAfterMs` 是经校验、由提供方请求的正数延迟，而不是重试决策；`ProviderRequestId` 是用于诊断的不透明品牌字符串。
+
+```ts type-equiv
+/** Serializable provider-boundary facts; policy decides whether they are retryable. */
+interface LlmFailure {
+  /** Human-readable provider or transport failure. */
+  readonly message: string
+  /** Stable provider-neutral machine-routing code. */
+  readonly code: string
+  /** HTTP status observed at the provider boundary, when available. */
+  readonly status?: number
+  /** Provider-requested delay in milliseconds, when valid and available. */
+  readonly providerRetryAfterMs?: number
+  /** Opaque provider-issued request identifier for diagnostics. */
+  readonly requestId?: ProviderRequestId
+}
+```
+
+## 适配器契约
+
+每个适配器必须遵守以下规则，每个消费方可以依赖它们：
+
+- **`usage` 在 `finish` 之前，`finish` 之后不再有任何分片。** 将两者都推迟到提供方的流结束标记，这样尾部的 usage-only 分片就不会违反顺序。
+- **工具调用的 `arguments` 全程保持原始 JSON 字符串。** 部分片段通过 `argumentsDelta` 流式传输；如果提供方返回的是已解析的对象，适配器在 `block-end` 时重新序列化为字符串。
+- **两条受支持的错误路径，一种事实形状。** 失败可以从 `stream()` 抛出（传输/协议错误），**或者**以 `finish {kind:'error'|'aborted', failure}` 结束流（无法在流中途抛异常的适配器用它表示提供方带内错误）。`LlmError.failure` 携带同一个 `LlmFailure`。最终适配器边界保留被抛出的确切 `Error` 对象，并将不可变事实关联到该调用；agent loop（智能体循环）关闭失败的步骤，再把错误、事实与不可变的先前已重试事实提供给 `agent/request-error`。若未恢复，结构化失败会成为轮次错误，并且该次尝试不会提交正常 assistant 消息或工具副作用。
+- **一次适配器调用就是一次提供方尝试。** 适配器禁用库重试。agent 层恢复会打开另一个持久、带编号的步骤；直接调用 `ctx.llm.stream()` 的调用方仍然只尝试一次。
+- **提供方停顿在传输层受到时限约束。** 两个已交付的远程适配器都暴露正数且有限的 `streamIdleTimeoutMs`，默认五分钟。watchdog 只在 iterator `next()` 尚未完成时启动，整个请求使用同一个稳定 signal，把自身到期映射为 `TIMEOUT`，并把更早发生的调用方中止保留为 `ABORTED`。
+- **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
+- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
+- **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。除非 `agent/step-result` listener 改写了内容，否则循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
+
+该契约由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（手写 fetch/SSE（Server-Sent Events））和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
+
+## `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)。
+
+```ts type-equiv
+/**
+ * Static public application identity sent to LLM providers.
+ *
+ * Every field is a public product fact, safe on every request: no secrets,
+ * local paths, session ids, prompt text, or per-user identifiers belong here,
+ * and nothing per-request may influence the values.
+ */
+interface AppIdentity {
+  /** `User-Agent` product token (lowercase, hyphenated). */
+  product: string
+  /** Product version; sourced from package metadata, never hand-copied. */
+  version: string
+  /** Public home URL of the app, used as the `User-Agent` comment. */
+  url: string
+}
+```
+
+## `TokenUsage`
+
+逐调用 token 记账。各计数**互不重叠**：`inputTokens` 只包含未缓存输入；缓存输入单独报告，计费输入是三者之和。若提供方把缓存命中折入单一提示词总数（如 DeepSeek 的 `prompt_tokens`），适配器会再将其扣除。`reasoningTokens` 存在时只是信息性细节，已经包含在 `outputTokens` 中；汇总时不得重复相加。
+
+```ts type-equiv
+/**
+ * Token accounting for one model call (cache fields are optional).
+ *
+ * Counts are DISJOINT: `inputTokens` is uncached input only; cached input is
+ * reported separately as `cacheReadTokens`/`cacheWriteTokens` (billed input =
+ * sum of the three). Adapters whose providers fold cache hits into a total
+ * prompt count (DeepSeek's `prompt_tokens`) subtract them out.
+ */
+interface TokenUsage {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens?: number
+  cacheWriteTokens?: number
+  reasoningTokens?: number
+}
+```
+
+## `BlockAssembler`
+
+`BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同其提供方/模型 provenance 一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。
+
+```ts public-api
+/**
+ * Incrementally assembles raw {@link StreamChunk}s into complete
+ * {@link ContentBlock}s and a final assistant {@link Message}.
+ *
+ * The agent loop feeds it while logging raw chunks for replay fidelity, then
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+ *
+ * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
+ * an index already closed by `block-end` are ignored (malformed stream) so a
+ * misbehaving adapter cannot grow memory or corrupt a completed block.
+ */
+declare class BlockAssembler {
+  /**
+   * Feed one chunk into the assembly state.
+   * @param chunk - the next raw chunk, in stream order.
+   */
+  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).
+   */
+  blocks(): ContentBlock[];
+  /** Usage from the `usage` chunk; undefined until one arrives. */
+  get usage(): TokenUsage | undefined;
+  /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
+  get finish(): FinishReason;
+  /** Adapter-private replay state from the terminal finish chunk, if any. */
+  get replayState(): unknown;
+  /**
+   * The assembled assistant message.
+   * @returns an assistant-role message over `blocks()` (same open-block assembly rules).
+   */
+  message(): Message;
+}
+```
+
+## seam
+
+`LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerInfo()` 与异步 `listModels()` 方法为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单独的 `resolveModelContext()` 查询会暴露确切路由上对正确性敏感的容量信息，但不会让目录成员关系具有权威性；缺失表示元数据未知，而不是路由无效。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#content-blocks-and-streaming-dsh-llm)。
+
+```ts public-api
+/**
+ * Provider-wire adapter for the harness message and stream vocabulary. Register implementations
+ * with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
+ * `attributionHeaders()`; prove that at the wire or library header-hook boundary. The hand-rolled
+ * DeepSeek and pi-ai adapters intentionally exercise this contract through different internals.
+ */
+declare abstract class LlmAdapter {
+  /**
+   * Describe one provider route owned by this adapter.
+   * @param provider - a route passed to `registerAdapter()` for this instance.
+   * @returns detached display metadata whose id must equal `provider`.
+   */
+  providerInfo(provider: string): LlmProviderInfo;
+  /**
+   * List models this adapter can currently advertise for one owned provider.
+   * The result is advisory: an adapter may accept unlisted model ids, and
+   * consumers must not turn absence into request rejection.
+   * @param _provider - one provider route owned by this adapter.
+   * @returns discoverable models in adapter-preferred order.
+   */
+  listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+  /**
+   * Resolve context capacity for one model accepted by this adapter. Absence
+   * means the adapter does not know the capacity, not that routing is invalid.
+   * @param _provider - one provider route owned by this adapter.
+   * @param _model - exact model id passed to {@link GenerateOptions.model}.
+   * @returns provider-owned context metadata, or `undefined` when unavailable.
+   */
+  resolveModelContext(
+    _provider: string,
+    _model: string,
+  ): Promise<LlmModelContext | undefined>;
+  /**
+   * Stream one model call as raw chunks. The only required method.
+   * @param options - the fully-assembled request; implementations must honor `options.signal`.
+   * @returns the chunk stream, obeying the adapter contract documented on `StreamChunk`.
+   */
+  abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+```
+
+`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)。
diff --git a/docs/core-data-structures/persistence.i18n.yaml b/docs/core-data-structures/persistence.i18n.yaml
new file mode 100644
index 0000000000..b7d8fda4e8
--- /dev/null
+++ b/docs/core-data-structures/persistence.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
+persistence.md: dc497fd85f44660c0a981579351b5cfbe0040a4d
+persistence.zh.md: 5236f4fe2ba8ad1be7e74bffafebfea19014d7aa
diff --git a/docs/core-data-structures/persistence.md b/docs/core-data-structures/persistence.md
index aa789a6ee7..dc497fd85f 100644
--- a/docs/core-data-structures/persistence.md
+++ b/docs/core-data-structures/persistence.md
@@ -1,17 +1,23 @@
 # Session Persistence
 
+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/load/list over the existing `SessionEvent` — **no parallel persisted type** — and two interchangeable backends that pass the same `runPersistenceContract` suite. 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-persistence/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, crash-repairing load, non-mutating inspect, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted type** — and two interchangeable backends that pass the same `runPersistenceContract` suite. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
 
 ## The flush checkpoint
 
-`session/event` is a *synchronous* notification; persistence plugins buffer it (write-behind) until `session/flush`. The loop awaits an ordinary turn's checkpoint before claiming the next queue item; synchronous idle `inject()` schedules its checkpoint without blocking `send()`, and disposal still drains it. A successful flush durably commits the closed turn as one unit; a rejecting flush is reported through `agent/error` and the logger — never as a session event past the closed turn — while the backend keeps its buffered events for the next flush.
+`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.
 
 ## Crash recovery preserves an interrupted turn
 
 A backend that reloads a log crashed mid-turn finds an open `turn/start` with no `turn/end`. It does **not** truncate — a single turn can be huge in a long-horizon task (many steps, large tool output), and those events were durably appended before the crash. Instead it closes the orphaned turn with a synthetic `turn/end { reason: { kind: 'interrupted' } }`, keeping the log balanced and the turn-enclosure invariant intact. `interrupted` is the one `TurnEndReason` no loop emits (see [session.md](session.md#why-a-turn-ended-turnendreasonmap)).
 
+Repair applies only to cold sessions. For a live id, `SessionPersistence.load(id)` snapshots the in-memory log, waits until that snapshot is durable, and returns it with the stored header only when balanced; an open live turn rejects rather than receiving synthetic interruption boundaries. A coordinator-backed cold load reserves the id across backend reads and repair writes, so concurrent publication of a same-id live session rejects and rolls back. HMR also adopts a live prefix without closing its active turn.
+
+`SessionPersistence.inspect(id)` is the observer counterpart to recovery: it returns a detached valid stored prefix without truncating a torn record, adding interruption closers, or publishing write state. Same-id serialization keeps it coherent with backend writes. Derived read models use `inspect`, never `load`, so observing a checkpointed open turn cannot mutate the log if live ownership begins concurrently.
+
 ## `SessionLocation` — optional per-session artifact target
 
 `SessionPersistence.locate(meta)` synchronously resolves a backend-owned independent artifact without reading, creating, or flushing it. JSONL returns its absolute target path; SQLite returns `undefined` because sessions share one database. A returned path can therefore name a file that does not yet exist or lacks the current unflushed turn; it is a location hint, not authorization or a freshness guarantee.
@@ -49,7 +55,7 @@ interface SessionHeader {
   readonly version: number
   /** The session's id (mirrors the {@link Session}'s id). */
   readonly id: SessionId
-  /** Unix epoch milliseconds when the session was created. */
+  /** Non-negative safe-integer Unix epoch milliseconds when the session was created. */
   readonly createdAt: number
   /** Absolute working directory the session was created in (if any). */
   readonly cwd?: string
@@ -98,11 +104,31 @@ interface CreateSessionOptions {
 
 Replay/fork is therefore `ctx.sessions.create(id, { seed: seedEvents })`; resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
 
+## Lightweight source revisions
+
+Consumers of derived state compare a cheap opaque revision before loading a full event log. The persistence backend owns its representation and changes it transactionally with append or mutating load repair; callers compare it only for equality.
+
+```ts type-equiv
+/**
+ * Backend-owned token that identifies both one storage source and one revision
+ * of a persisted session log.
+ */
+type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
+```
+
+```ts type-equiv
+/** Lightweight immutable source identity returned without loading a full log. */
+interface SessionPersistenceSnapshot {
+  /** Detached metadata for one materialized session. */
+  header: SessionHeader
+  /** Opaque source-qualified token that changes whenever this stored log changes. */
+  revision: SessionPersistenceRevision
+}
+```
+
 ## The backends
 
-Both implement the same abstract `SessionPersistence` (locate/create/append/load/list over `SessionEvent`) and pass `runPersistenceContract`, proving the seam is genuinely backend-agnostic:
+Both implement the same abstract `SessionPersistence` (locate/create/append/load/inspect/list/listSnapshots over `SessionEvent`) 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.
-
-Multiple backends sharing one on-disk session coordinate writes through the [shared persistence write-coordinator](../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md).
diff --git a/docs/core-data-structures/persistence.zh.md b/docs/core-data-structures/persistence.zh.md
new file mode 100644
index 0000000000..5236f4fe2b
--- /dev/null
+++ b/docs/core-data-structures/persistence.zh.md
@@ -0,0 +1,134 @@
+# 会话持久化
+
+[English](persistence.md) | 中文
+
+事件日志的**持久性 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、会执行崩溃修复的 load、不会修改数据的 inspect，以及轻量的 list/snapshot 观察——**没有平行的持久化类型**——以及两个可互换、通过同一套 `runPersistenceContract` 的后端。见 [session-persistence Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+
+## flush 检查点
+
+`session/event` 是一个*同步*通知；持久化插件会将事件复制到逐会话控制器，并立即启动写入而不阻塞生产方。并发事件会加入当前批次；在该批次写入期间接纳的事件会触发后续批次。`session/flush` 会等待当前与待处理批次全部清空，因此循环仍将其用作在领取下一个普通轮次之前的顺序与错误观察检查点。立即写入被拒绝时会保留对应事件；显式 flush 会重试这些事件，并通过 `agent/error` 和 logger 报告失败，绝不会把失败记录成已关闭轮次之后的会话事件。dispose（资源释放）会执行同样的最终排空。
+
+## 崩溃恢复保留被中断的轮次
+
+后端重新加载一个在轮次中途崩溃的日志时，会发现一个已打开的 `turn/start` 却没有 `turn/end`。它**不会**截断日志：在长周期任务中，单个轮次可能非常庞大（许多步骤、大量工具输出），而这些事件在崩溃前已被持久追加。后端改为用一个合成的 `turn/end { reason: { kind: 'interrupted' } }` 关闭这个遗留轮次，保持日志平衡与轮次闭合不变式。`interrupted` 是唯一一个不由循环发出的 `TurnEndReason`（见 [session.md](session.md#why-a-turn-ended-turnendreasonmap)）。
+
+修复仅适用于冷会话。对于活跃 id，`SessionPersistence.load(id)` 会对内存日志拍摄快照，等待该快照完成持久化，并且只在日志平衡时连同已存储的 header 返回；若活跃轮次仍未闭合，则拒绝操作，而不是添加合成的中断边界。由协调器管理的冷加载会在后端读取和修复写入期间占用该 id，因此并发发布同 id 的活跃会话会被拒绝并回滚。HMR 也会接管活跃前缀，而不会关闭其中正在进行的轮次。
+
+`SessionPersistence.inspect(id)` 是恢复机制面向观察方的对等操作：它返回已存储有效前缀的独立副本，不截断不完整记录、不添加中断结束事件，也不发布写入状态。同 id 串行化确保它与后端写入保持一致。派生读取模型使用 `inspect`，绝不使用 `load`，因此即使活跃所有权并发建立，观察已落检查点但仍未闭合的轮次也不会修改日志。
+
+## `SessionLocation`——可选的逐会话产物目标
+
+`SessionPersistence.locate(meta)` 会同步解析一个归后端所有的独立产物，而不会读取、创建或 flush 它。JSONL 返回其绝对目标路径；SQLite 因各会话共享一个数据库而返回 `undefined`。因此，返回的路径可能指向尚不存在、或还不包含当前尚未 flush 的轮次；它是位置提示，不是授权或新鲜度保证。
+
+```ts type-equiv
+/**
+ * A backend-resolved, per-session local artifact location. The path is an
+ * absolute target path and can name an artifact that has not materialized yet.
+ * Consumers must treat it as a location hint, never as an authorization token.
+ */
+interface SessionLocation {
+  /** Backend-specific artifact kind, for example `jsonl`. */
+  readonly kind: string
+  /** Absolute path to this session's backend-owned artifact. */
+  readonly path: string
+}
+```
+
+## `SessionHeader`：日志旁的元数据
+
+每个会话的元数据与事件日志**分开**存储：格式版本、cwd、血统与 seed 边界是存储层关注点而非对话事件，因此不进入 `SessionEventMap`，也不会到达 `deriveMessages()`。header 通过 `session.header` 附加到 `Session` 上。
+
+源码：[`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
+
+```ts type-equiv
+/**
+ * Immutable validated storage metadata, kept outside the conversation event log.
+ */
+interface SessionHeader {
+  /**
+   * On-disk format version, stamped from {@link SESSION_FORMAT_VERSION} when the
+   * session is created. A persistence backend rejects any other version on load
+   * (no migration — see the constant).
+   */
+  readonly version: number
+  /** The session's id (mirrors the {@link Session}'s id). */
+  readonly id: SessionId
+  /** Non-negative safe-integer Unix epoch milliseconds when the session was created. */
+  readonly createdAt: number
+  /** Absolute working directory the session was created in (if any). */
+  readonly cwd?: string
+  /** The session this one was forked from (seed lineage), if any. */
+  readonly parentSession?: SessionId
+  /**
+   * How many leading events were inherited through a seed. Persisting this
+   * boundary lets resume and replay distinguish parent history from child work.
+   */
+  readonly seedLength?: number
+  /**
+   * Delegation depth: absent (zero) for a top-level session, parent depth + 1
+   * for a subagent child. Persisted so a recursion budget survives restart and
+   * resume — a runtime-only depth would reset a resumed child to top-level.
+   */
+  readonly delegationDepth?: number
+}
+```
+
+## `CreateSessionOptions`：seed 与元数据
+
+通过 store 创建 `Session` 时会接收 `seed`（回放/fork 现有事件日志）与 `meta`（store 折叠进 `SessionHeader` 的存储层字段）。store 填充 `version`/`id` 并为 `createdAt` 提供默认值；调用方提供已校验的绝对 `cwd`、`parentSession` 谱系、`seedLength` 种子边界、`delegationDepth`，以及——仅在重建已持久化会话时——需要保留的原始 `createdAt`。
+
+```ts type-equiv
+/**
+ * Options for creating a {@link Session} via the store. `seed` replays/forks
+ * an existing event log; `meta` carries the caller-supplied storage fields the
+ * store folds into a {@link SessionHeader}.
+ */
+interface CreateSessionOptions {
+  /** Events to seed the new session with (replay/fork). */
+  readonly seed?: readonly SessionEvent[]
+  /**
+   * Storage metadata read once before publication. `seedLength` is explicit
+   * because a resumed seed contains the full stored log, not only its inherited prefix.
+   */
+  readonly meta?: {
+    readonly cwd?: string
+    readonly parentSession?: SessionId
+    readonly createdAt?: number
+    readonly seedLength?: number
+    readonly delegationDepth?: number
+  }
+}
+```
+
+因此，回放/fork 的调用方式为 `ctx.sessions.create(id, { seed: seedEvents })`；将一个*持久化*会话恢复为活跃 agent 的调用方式为 `ctx.agents.resume({ resumeSessionId })`。
+
+## 轻量源修订号
+
+派生状态的消费方会在加载完整事件日志之前比较一个低开销的不透明修订号。其表示由持久化后端拥有，并随 append 或会修改数据的 load 修复以事务方式改变；调用方仅比较修订号是否相等。
+
+```ts type-equiv
+/**
+ * Backend-owned token that identifies both one storage source and one revision
+ * of a persisted session log.
+ */
+type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
+```
+
+```ts type-equiv
+/** Lightweight immutable source identity returned without loading a full log. */
+interface SessionPersistenceSnapshot {
+  /** Detached metadata for one materialized session. */
+  header: SessionHeader
+  /** Opaque source-qualified token that changes whenever this stored log changes. */
+  revision: SessionPersistenceRevision
+}
+```
+
+## 后端
+
+两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/load/inspect/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。
diff --git a/docs/core-data-structures/pty.md b/docs/core-data-structures/pty.md
index c8dfa49460..b205ec64c9 100644
--- a/docs/core-data-structures/pty.md
+++ b/docs/core-data-structures/pty.md
@@ -22,14 +22,14 @@ type PtySessionStatus =
 
 ## Backend and live session
 
-A backend owns how one registered type starts and detects readiness. `PtyService` publishes the returned session only after setup succeeds, then owns id authorization and cleanup. A backend session owns terminal state and captured-resource quiescence.
+A backend owns how one registered type starts and detects readiness. `PtyService` publishes the returned session only after setup succeeds, then owns id authorization and cleanup. A backend that cannot clean partial startup resources rejects with `PtyBackendCleanupError`, allowing disposal to retain the cleanup failure without replacing the caller's cancellation reason. A backend session owns terminal state and captured-resource quiescence.
 
 ```ts type-equiv
 /** Replaceable provider for one PTY session type. */
 interface PtyBackend {
   /** Stable type selected by {@link PtySpawnRequest.type}. */
   readonly type: string
-  /** Create an unpublished session or reject after cleaning partial resources. */
+  /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link PtyBackendCleanupError}. */
   spawn(spec: PtyBackendSpawnSpec): Promise<PtyBackendSession>
 }
 ```
diff --git a/docs/core-data-structures/sandbox.i18n.yaml b/docs/core-data-structures/sandbox.i18n.yaml
new file mode 100644
index 0000000000..f8189f4e15
--- /dev/null
+++ b/docs/core-data-structures/sandbox.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
+sandbox.md: 9bc05fa06f22fdc9ac9e8aacd482c1e7c2f2edec
+sandbox.zh.md: 9a52f126758fe0e7988715c7824e963bd6e6ea84
diff --git a/docs/core-data-structures/sandbox.md b/docs/core-data-structures/sandbox.md
index bdc86287fb..9bc05fa06f 100644
--- a/docs/core-data-structures/sandbox.md
+++ b/docs/core-data-structures/sandbox.md
@@ -1,5 +1,7 @@
 # Process Sandbox
 
+English | [中文](sandbox.zh.md)
+
 The process-sandbox seam of [dsh-sandbox](../../packages/sandbox/sandbox) wraps a same-world subprocess argv in a file-effect policy without coupling consumers to a platform runner. [dsh-sandbox-local](../../packages/sandbox/sandbox-local) supplies the Linux bwrap/Landlock and macOS Seatbelt backends; [dsh-bash-sandbox](../../packages/bash/bash-sandbox) is the first consumer. Containers, microVMs, and remote execution are sibling implementations of whole capability seams, not providers of `ctx.sandbox`.
 
 Source: [`packages/sandbox/sandbox/src/index.ts`](../../packages/sandbox/sandbox/src/index.ts)
diff --git a/docs/core-data-structures/sandbox.zh.md b/docs/core-data-structures/sandbox.zh.md
new file mode 100644
index 0000000000..9a52f12675
--- /dev/null
+++ b/docs/core-data-structures/sandbox.zh.md
@@ -0,0 +1,127 @@
+# 进程沙箱
+
+[English](sandbox.md) | 中文
+
+[dsh-sandbox](../../packages/sandbox/sandbox) 的进程沙箱 seam 将与宿主共享文件系统和内核的子进程 argv 包装在文件效果策略中，而不将消费方耦合到特定平台运行器。[dsh-sandbox-local](../../packages/sandbox/sandbox-local) 提供 Linux bwrap/Landlock 与 macOS Seatbelt 后端；[dsh-bash-sandbox](../../packages/bash/bash-sandbox) 是第一个消费方。容器、microVM 和远程执行是完整能力 seam 的兄弟实现，而非 `ctx.sandbox` 的提供方。
+
+源码：[`packages/sandbox/sandbox/src/index.ts`](../../packages/sandbox/sandbox/src/index.ts)
+
+## 模式与强制执行
+
+`SandboxMode` 仅管控文件系统效果。`read-only` 拒绝所有写入（必需的 `/dev/null` 接收器除外）；`workspace-write` 允许在工作区根目录及后端承诺的临时区域下写入；`danger-full-access` 绕过隔离。网络与进程可见性不在此处的定义范围内。
+
+```ts type-equiv
+/**
+ * File-effect policy for confined processes. `read-only` permits only required
+ * sinks such as `/dev/null`; `workspace-write` also permits the workspace and a
+ * backend-defined temp area; `danger-full-access` bypasses confinement. Network
+ * and process visibility are outside this vocabulary.
+ */
+type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
+```
+
+只有前两种模式可以发送给提供方。`danger-full-access` 的消费方直接 spawn 原始 argv，不调用 `ctx.sandbox`。
+
+```ts type-equiv
+/** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */
+type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>
+```
+
+强制执行程度是一个报告事实。`full` 表示后端管控了该模式承诺的所有文件效果；`partial` 表示活跃后端或较旧的内核 ABI 仅管控其中一个子集，因此要求绝对保证的消费方必须拒绝或向上暴露这一区别。
+
+```ts type-equiv
+/**
+ * Enforcement completeness for this host. `partial` means an active backend or
+ * older kernel ABI cannot govern every promised file effect; callers requiring
+ * an absolute boundary must not treat it as `full`.
+ */
+type SandboxEnforcement = 'full' | 'partial'
+```
+
+## 逐调用策略
+
+完整执行策略会按每次能力调用解析并携带。它包括 `danger-full-access`，因此消费方可以只解析一次策略，再决定是否绕过约束。普通工具调用从调用会话的不可变 cwd 派生 `workspaceRoot`；部署配置是没有 agent（智能体）时的回退值。root 会先按文件系统语义规范化，再做词法规范化，因此包含 `symlink/..` 的 cwd 会标识所生成进程实际运行的目录。
+
+```ts type-equiv
+/**
+ * The complete file-effect policy resolved for one capability call. The root
+ * is carried even under modes that do not consume it so callers can resolve
+ * policy once before choosing the enforcement path.
+ */
+interface SandboxExecutionPolicy {
+  /** The file-effect mode this execution runs under. */
+  mode: SandboxMode
+  /** Absolute root directory `workspace-write` may write under. */
+  workspaceRoot: string
+}
+```
+
+`ctx.sandboxPolicy.resolve()` 接收活跃会话；对于已批准的重试，还接收显式模式。该服务拥有优先级与 root 回退规则，使 bash 和 fs 不必重复实现。
+
+```ts type-equiv
+/** Inputs that select the sandbox policy for one capability call. */
+interface SandboxPolicyRequest {
+  /** Calling session; its immutable cwd becomes the workspace boundary. */
+  session?: Session
+  /** Explicit approved mode override, which outranks session policy. */
+  mode?: SandboxMode
+}
+```
+
+只有受约束的执行会到达 `ctx.sandbox`；其提供方策略在保留同一 root 的同时收窄模式。这使并发会话、消费方与一次性提权重试可以向同一提供方请求不同边界，而无需改变提供方状态。
+
+```ts type-equiv
+/**
+ * What one confined execution is allowed to touch — carried PER CALL, not
+ * fixed on the provider: two consumers may confine under different policies
+ * at the same instant (bash under `read-only` while a confined child agent
+ * needs its state directory writable), and an approved escalated retry is a
+ * new call with a wider policy. Defaulting/resolution is an explicit step at
+ * the consumer boundary; the provider treats the policy as fully specified.
+ */
+interface SandboxPolicy extends SandboxExecutionPolicy {
+  /** The file-effect mode this execution runs under. */
+  mode: ConfinedSandboxMode
+}
+```
+
+## 包装后的 argv 与分类方言
+
+`ConfinedArgv` 是消费方实际 spawn 的内容。除了替换后的 argv，它还携带后端的强制执行事实和两种正交的 stderr 方言。`denialSignatures` 用于识别沙箱正常工作时被隔离命令被阻止的情况。`runnerFailureSignatures` 用于识别沙箱运行器在执行命令之前拒绝或失败的情况；消费方应先检查后者，将其作为沙箱基础设施故障上报，而非普通任务失败。
+
+```ts type-equiv
+/**
+ * A {@link SandboxProvider.confine} result: the argv to spawn in place of
+ * the caller's own, plus the enforcement completeness the selected backend
+ * achieves for it.
+ */
+interface ConfinedArgv {
+  /** The wrapped argv (runner, profile, separator, then the caller's argv). */
+  argv: string[]
+  /** How completely the selected backend enforces the policy's file effects. */
+  enforcement: SandboxEnforcement
+  /**
+   * The selected backend's denial DIALECT: the case-insensitive stderr
+   * substrings a file effect denied by THIS backend produces (EROFS text
+   * under bwrap's read-only binds, EACCES under Landlock, EPERM under
+   * Seatbelt). A consumer that infers denials from a failed run's stderr
+   * matches against exactly these rather than a cross-backend union — the
+   * union claims denials a given backend never produces.
+   */
+  denialSignatures: readonly string[]
+  /**
+   * Case-insensitive signatures for runner failure before command execution.
+   * Consumers check these before denial signatures: runner failure means the
+   * command never ran, while denial means confinement worked and blocked it.
+   */
+  runnerFailureSignatures: readonly string[]
+}
+```
+
+运维人员配置的本地运行器必须为自身的 pre-exec 拒绝方言提供至少一条 `runnerFailureSignatures` 条目；提供方会自动添加外层 shell 的 missing 和 unexecutable 形式。这使得可执行的自定义运行器拒绝其 profile 的情况能够与被包装命令以相同状态码退出的情况区分开来。
+
+## 提供方与 fail-closed 错误
+
+`ctx.sandbox.confine(argv, policy)` 返回一个 `ConfinedArgv`，或在没有可用后端时抛出 `SandboxUnavailableError`（错误码 `SANDBOX_UNAVAILABLE`）。已选定的运行器也可能在执行时 fail-closed，此时其失败签名承载相同的基础设施含义。对于受限策略，静默的无隔离透传永远不合法。
+
+提供方探测在多个候选后端之间仲裁，结果在提供方生命周期内缓存。只有一个候选后端的平台可以直接选定它；执行时拒绝仍保留安全属性。本地提供方将 bwrap 和 Seatbelt 报告为 full，并保留 Landlock 启动器的 full/partial 内核裁定。
diff --git a/docs/core-data-structures/scope.i18n.yaml b/docs/core-data-structures/scope.i18n.yaml
new file mode 100644
index 0000000000..b565e11461
--- /dev/null
+++ b/docs/core-data-structures/scope.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
+scope.md: 73a697f2843293daffff85dabf4656346f7dcd04
+scope.zh.md: f3c591da2befdcff69d89ad0667653392111fb8e
diff --git a/docs/core-data-structures/scope.md b/docs/core-data-structures/scope.md
index e9869f3152..73a697f284 100644
--- a/docs/core-data-structures/scope.md
+++ b/docs/core-data-structures/scope.md
@@ -1,5 +1,7 @@
 # Scoped Registration
 
+English | [中文](scope.zh.md)
+
 The [scope package](../../packages/core/scope) supplies the identity, carrier, and scoped-layer vocabulary that makes one registration context mean both per-agent visibility and shared lifetime ownership. It is a library primitive rather than a Cordis service; the [agent-scope runtime-design Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#scope-routing-one-opaque-key-selects-one-layer) owns the lifecycle rationale, the [shared-storage Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md) owns the registry-layer decision, and the package [README](../../packages/core/scope/README.md) owns the callable API and filtering semantics.
 
 Sources: [`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index.ts) and [`packages/core/scope/src/store.ts`](../../packages/core/scope/src/store.ts).
diff --git a/docs/core-data-structures/scope.zh.md b/docs/core-data-structures/scope.zh.md
new file mode 100644
index 0000000000..f3c591da2b
--- /dev/null
+++ b/docs/core-data-structures/scope.zh.md
@@ -0,0 +1,59 @@
+# 作用域注册
+
+[English](scope.md) | 中文
+
+[scope 包（package）](../../packages/core/scope)提供 identity、carrier 与 scoped-layer 词汇，使同一个注册上下文同时代表逐 agent（智能体）可见性和共享生命周期所有权。它是库原语，而不是 Cordis 服务；生命周期设计理由由 [agent-scope 运行时设计 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#scope-routing-one-opaque-key-selects-one-layer)规定，注册表层决策由[共享存储 Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)规定，可调用 API 与过滤语义则由包 [README](../../packages/core/scope/README.md)规定。
+
+源码：[`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index.ts) 与 [`packages/core/scope/src/store.ts`](../../packages/core/scope/src/store.ts)。
+
+## 身份标识与分发载体
+
+`ScopeKey` 是一个不透明的对象身份标识。已交付的 agent loop（智能体循环）使用活跃的 `Agent` 对象作为自身的 key，但该原语从不检视该对象。
+
+```ts type-equiv
+/** An opaque, identity-compared scope key. */
+type ScopeKey = object
+```
+
+`Scoped<T>` 是编译期品牌标记，标注在 `scopeTarget(base, key)` 返回的不透明路由接收器上。作用域过滤的事件声明要求以此载体作为 `this` 类型，而真正的事件主体仍作为显式参数传入。
+
+```ts type-equiv
+/**
+ * A routing-only event receiver built by {@link scopeTarget}. The type
+ * parameter records the subject type for dispatch checking; the carrier does
+ * not expose the subject's properties. Event payloads carry the real subject.
+ */
+type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
+```
+
+## 拥有所有权的注册上下文
+
+`Scope` 将带标签的注册上下文与两个拆卸接口配对。`rawDispose` 保留有序复合 effect 所需的精确 Cordis disposer 身份；`dispose()` 是面向直接调用方和竞态调用方的公共停稳边界。
+
+```ts type-equiv
+/** A minted registration scope and its quiescent disposal boundaries. */
+interface Scope {
+  /** Context through which scope-owned registrations are made. */
+  ctx: Context
+  /** Exact Cordis disposer, used when nesting this scope in an ordered composite effect. */
+  rawDispose: () => Promise<void> | void
+  /** Dispose every scope-owned registration; racing calls await the same completion. */
+  dispose(): Promise<void>
+}
+```
+
+## 带作用域的注册表层
+
+`ScopeLayer` 表示一个注册表在全局或确切作用域层级的完整贡献。具体 layer 可以聚合多个具名与匿名 table；整个 layer 为空时，`ScopedLayers` 可以回收带作用域状态，而不会丢弃兄弟 table。
+
+```ts type-equiv
+/** One scope's aggregate contribution to a registry. */
+interface ScopeLayer {
+  /** Whether every table in this layer is empty. */
+  isEmpty(): boolean
+}
+```
+
+`ScopedLayers<L>` 拥有立即创建的全局 layer，以及惰性创建的确切作用域 layer。读取不会创建 layer：`peek(undefined)` 表示没有 overlay，而 `merge()` 会物化按插入顺序排列的全局具名 entry，随后是带作用域的 shadow。注册使用同一个上下文表示可见性与 Cordis effect 所有权，在可选通知前收集一个同步 undo，返回 Cordis 的确切 disposer，并且只在带作用域 layer 的完整 `ScopeLayer` 为空时回收它。
+
+`NamedEntries<V>` 提供按插入顺序的查找与 live iteration，重复错误由调用方所有。`AnonymousEntries<V>` 为每次 append 分配唯一标识，使相等的值仍相互独立。迭代在同一非空 table generation 内保持 live；排空 table 会让现有 iterator 与后续插入脱离。两者都返回幂等的确切 entry undo；共享的 `EntryValues` 实现接口不公开。
diff --git a/docs/core-data-structures/session-query.i18n.yaml b/docs/core-data-structures/session-query.i18n.yaml
new file mode 100644
index 0000000000..2cba0f9b42
--- /dev/null
+++ b/docs/core-data-structures/session-query.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
+session-query.md: c6dde8714a0875d46cf7b49cc181daab8f44afe0
+session-query.zh.md: 44be8b7f89e1576e54c8dc3cb60619d6728c6895
diff --git a/docs/core-data-structures/session-query.md b/docs/core-data-structures/session-query.md
index 8b37b0f5f2..c6dde8714a 100644
--- a/docs/core-data-structures/session-query.md
+++ b/docs/core-data-structures/session-query.md
@@ -1,6 +1,8 @@
 # Session Query
 
-Exact reads and relationship traces over the live-preferred logical session corpus. The [package contract](../../packages/session-query/session-query) owns source precedence, dynamic optional persistence, cloning, surface classification, bounded windows, tracing validation, and typed failures. Full-text search is a separate proposed SQLite package.
+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.
 
 Source: [`packages/session-query/session-query/src/types.ts`](../../packages/session-query/session-query/src/types.ts)
 
@@ -25,7 +27,17 @@ interface SessionRecord {
 }
 ```
 
-`SessionSurfaceSnapshot` is one exact-read observation rather than a retained subscription. Its raw-log boundary and folded events come from the same live-preferred load.
+`SessionLogSnapshot` is the complete detached, replay-validated raw log used by resume preflight. `SessionSurfaceSnapshot` is one exact-read surface observation rather than a retained subscription.
+
+```ts type-equiv
+/** One validated detached observation of a logical session's complete raw log. */
+interface SessionLogSnapshot {
+  /** Cloned session header selected from the same observation as `events`. */
+  session: SessionHeader
+  /** Cloned contiguous raw events after persistence repair and replay validation. */
+  events: SessionEvent[]
+}
+```
 
 ```ts type-equiv
 /** One atomic live-preferred observation of a session's current model surface. */
@@ -55,6 +67,113 @@ interface SessionEventRecord {
 }
 ```
 
+## Provider-independent filters and documents
+
+Session and event filter arrays are ANDed; values inside one list clause are ORed. Ranges are inclusive. The event `text` clause is a literal Unicode case-insensitive, whitespace-flexible regular-expression scan over extracted semantic text, independent of full-text providers.
+
+```ts type-equiv
+/**
+ * One logical-session predicate. A filter array is ANDed; `values` within a
+ * clause are ORed.
+ */
+type SessionResultFilter =
+  | { kind: 'id'; values: readonly SessionId[] }
+  | { kind: 'cwd'; values: readonly (string | null)[] }
+  | ({ kind: 'created-at' } & SessionResultRange)
+  | { kind: 'parent'; values: readonly (SessionId | null)[] }
+  | { kind: 'availability'; values: readonly SessionAvailability[] }
+```
+
+```ts type-equiv
+/**
+ * One event predicate. A filter array is ANDed; list-valued clauses are ORed.
+ * Text is a literal, case-insensitive, whitespace-flexible semantic-text scan.
+ */
+type SessionEventResultFilter =
+  | ({ kind: 'seq' } & SessionResultRange)
+  | ({ kind: 'time' } & SessionResultRange)
+  | { kind: 'type'; values: readonly SessionEventType[] }
+  | { kind: 'surface'; values: readonly SessionEventSurface[] }
+  | { kind: 'text'; text: string }
+```
+
+```ts type-equiv
+/** Searchable semantic document derived from one session event. */
+interface SessionEventSearchDocument extends SessionEventRecord {
+  /** First-party semantic text used by scan filters and full-text indexes. */
+  text: string
+}
+```
+
+`ctx.sessionQuery.filterSessions(filters)` applies `SessionResultFilter` to the complete logical corpus; `ctx.sessionQuery.filterEvents(sessionId, filters)` returns matching documents in ascending seq order. Messages, reasoning, tool calls/results, blocked prompts, todos, and failure/status detail contribute semantic text; structural events and stream chunks do not.
+
+## Full-text search pages
+
+The combined `ctx.sessionQuery` seam has two full-text scopes. `searchSessions()` groups the corpus by strongest matching event; `searchEvents()` searches one session. Requests bind an opaque cursor to the normalized query, metadata filters, and limit. The event text scan is intentionally absent from provider metadata filters.
+
+```ts type-equiv
+/** Provider-owned opaque continuation token returned by session search. */
+type SessionSearchCursor = Branded<'SessionSearchCursor'>
+```
+
+```ts type-equiv
+/** Cross-session full-text search request. */
+interface SessionSearchRequest {
+  /** Full-text query interpreted as data, never executable FTS syntax. */
+  query: string
+  /** Logical-session predicates applied before event ranking. */
+  sessionFilters?: readonly SessionResultFilter[]
+  /** Event predicates applied before event ranking. */
+  eventFilters?: readonly SessionEventMetadataFilter[]
+  /** Maximum sessions in this page. */
+  limit?: number
+  /** Opaque cursor returned for the identical normalized request. */
+  cursor?: SessionSearchCursor
+}
+```
+
+```ts type-equiv
+/** Within-session full-text search request. */
+interface SessionEventSearchRequest {
+  /** Session whose live-preferred logical log is searched. */
+  sessionId: SessionId
+  /** Full-text query interpreted as data, never executable FTS syntax. */
+  query: string
+  /** Event predicates applied before ranking. */
+  filters?: readonly SessionEventMetadataFilter[]
+  /** Maximum events in this page. */
+  limit?: number
+  /** Opaque cursor returned for the identical normalized request. */
+  cursor?: SessionSearchCursor
+}
+```
+
+```ts type-equiv
+/** One cursor-paginated result page. */
+interface SessionSearchPage<T> {
+  /** Results for this page in contract-defined order. */
+  items: readonly T[]
+  /** Opaque continuation cursor, absent on the final page. */
+  nextCursor?: SessionSearchCursor
+}
+```
+
+```ts type-equiv
+/** One event full-text search hit with a bounded plain-text excerpt. */
+interface SessionEventSearchHit extends SessionEventRecord {
+  /** Plain text excerpt selected around the match. */
+  snippet: string
+}
+```
+
+```ts type-equiv
+/** One grouped cross-session hit, ranked by its strongest matching event. */
+interface SessionSearchHit extends SessionRecord {
+  /** Strongest matching event for this session. */
+  bestMatch: SessionEventSearchHit
+}
+```
+
 ## Session lineage
 
 `SessionLineageTrace` carries known parents in immediate-to-outward order and a forest of recursively nested direct descendants. The completeness discriminant makes a known root and a missing parent mutually exclusive.
@@ -165,14 +284,21 @@ interface SessionEventTrace {
 The closed code union distinguishes request validation, missing targets, malformed surface logs, optional-backend failure, and contradictory source metadata.
 
 ```ts type-equiv
-/** Stable machine-routable failure taxonomy for exact session reads and traces. */
+/** Stable machine-routable failure taxonomy for session reads, traces, and search. */
 type SessionQueryErrorCode =
+  | 'SESSION_QUERY_ABORTED'
   | 'SESSION_QUERY_EVENT_NOT_FOUND'
+  | 'SESSION_QUERY_INDEX_FAILED'
   | 'SESSION_QUERY_INVALID_CONFIG'
+  | 'SESSION_QUERY_INVALID_CURSOR'
+  | 'SESSION_QUERY_INVALID_FILTER'
+  | 'SESSION_QUERY_INVALID_LIMIT'
+  | 'SESSION_QUERY_INVALID_QUERY'
   | 'SESSION_QUERY_INVALID_LINEAGE'
   | 'SESSION_QUERY_INVALID_SURFACE'
   | 'SESSION_QUERY_INVALID_WINDOW'
   | 'SESSION_QUERY_PERSISTENCE_FAILED'
   | 'SESSION_QUERY_SESSION_NOT_FOUND'
+  | 'SESSION_QUERY_STALE_CURSOR'
   | 'SESSION_QUERY_SOURCE_CONFLICT'
 ```
diff --git a/docs/core-data-structures/session-query.zh.md b/docs/core-data-structures/session-query.zh.md
new file mode 100644
index 0000000000..44be8b7f89
--- /dev/null
+++ b/docs/core-data-structures/session-query.zh.md
@@ -0,0 +1,304 @@
+# 会话查询
+
+[English](session-query.md) | 中文
+
+本文定义面向优先使用 live 数据的逻辑会话语料库的查询词汇。[接口包（package）](../../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)
+
+## 逻辑记录
+
+`SessionRecord` 由跨语料库列表返回。它独立于克隆后的实时优先 header 暴露源可用性。`SessionEventRecord` 是轻量的原始日志投影；分类使用与 model-history 推导相同的 `foldSurface()` 状态转换。
+
+```ts type-equiv
+/** Whether an event is current model context, replaced context, or raw-log-only. */
+type SessionEventSurface = 'current' | 'shadowed' | 'log-only'
+```
+
+```ts type-equiv
+/** Lightweight identity and source availability for one logical session. */
+interface SessionRecord {
+  /** Cloned session header selected from the live-preferred corpus. */
+  header: SessionHeader
+  /** Whether the id currently exists in `ctx.sessions`. */
+  live: boolean
+  /** Whether the active persistence backend currently materializes the id. */
+  persisted: boolean
+}
+```
+
+`SessionLogSnapshot` 是供恢复预检使用的完整原始日志：它脱离运行时，并经过回放验证。`SessionSurfaceSnapshot` 表示一次精确读取的 surface 观测结果，而不是持续保留的订阅。
+
+```ts type-equiv
+/** One validated detached observation of a logical session's complete raw log. */
+interface SessionLogSnapshot {
+  /** Cloned session header selected from the same observation as `events`. */
+  session: SessionHeader
+  /** Cloned contiguous raw events after persistence repair and replay validation. */
+  events: SessionEvent[]
+}
+```
+
+```ts type-equiv
+/** One atomic live-preferred observation of a session's current model surface. */
+interface SessionSurfaceSnapshot {
+  /** Cloned session header selected from the same corpus observation as `events`. */
+  session: SessionHeader
+  /** Highest raw-log seq included in the observation, or `null` for an empty log. */
+  capturedThroughSeq: number | null
+  /** Cloned current surface events in model-history order. */
+  events: SurfaceEvent[]
+}
+```
+
+```ts type-equiv
+/** Lightweight metadata for one event within a logical session. */
+interface SessionEventRecord {
+  /** Session that owns the event. */
+  sessionId: SessionId
+  /** Monotonic event seq within the session. */
+  seq: number
+  /** Discriminant of the session event. */
+  type: SessionEventType
+  /** Event timestamp in Unix epoch milliseconds. */
+  time: number
+  /** Event placement in the folded session surface. */
+  surface: SessionEventSurface
+}
+```
+
+## 与提供方无关的过滤器和文档
+
+会话和事件过滤器数组内的各项按逻辑与（AND）组合；单个列表子句中的各值按逻辑或（OR）组合。范围包含两端。事件的 `text` 子句会对提取出的语义文本执行正则表达式扫描：搜索文本按字面量处理，Unicode 字符不区分大小写，空白字符可灵活匹配；该过程与全文搜索提供方无关。
+
+```ts type-equiv
+/**
+ * One logical-session predicate. A filter array is ANDed; `values` within a
+ * clause are ORed.
+ */
+type SessionResultFilter =
+  | { kind: 'id'; values: readonly SessionId[] }
+  | { kind: 'cwd'; values: readonly (string | null)[] }
+  | ({ kind: 'created-at' } & SessionResultRange)
+  | { kind: 'parent'; values: readonly (SessionId | null)[] }
+  | { kind: 'availability'; values: readonly SessionAvailability[] }
+```
+
+```ts type-equiv
+/**
+ * One event predicate. A filter array is ANDed; list-valued clauses are ORed.
+ * Text is a literal, case-insensitive, whitespace-flexible semantic-text scan.
+ */
+type SessionEventResultFilter =
+  | ({ kind: 'seq' } & SessionResultRange)
+  | ({ kind: 'time' } & SessionResultRange)
+  | { kind: 'type'; values: readonly SessionEventType[] }
+  | { kind: 'surface'; values: readonly SessionEventSurface[] }
+  | { kind: 'text'; text: string }
+```
+
+```ts type-equiv
+/** Searchable semantic document derived from one session event. */
+interface SessionEventSearchDocument extends SessionEventRecord {
+  /** First-party semantic text used by scan filters and full-text indexes. */
+  text: string
+}
+```
+
+`ctx.sessionQuery.filterSessions(filters)` 会对完整的逻辑会话语料库应用 `SessionResultFilter`；`ctx.sessionQuery.filterEvents(sessionId, filters)` 按 seq 升序返回匹配的文档。消息、推理（reasoning）、工具调用和工具结果、被阻止的提示词、待办事项，以及失败和状态详情会纳入语义文本；结构事件和流分片则不会。
+
+## 全文搜索结果页
+
+整合后的 `ctx.sessionQuery` seam 提供两个全文搜索范围。`searchSessions()` 按匹配度最强的事件对语料库分组；`searchEvents()` 搜索单个会话。请求将不透明游标与规范化后的查询、元数据过滤器和结果数量上限绑定。提供方的元数据过滤器有意不包含事件文本扫描。
+
+```ts type-equiv
+/** Provider-owned opaque continuation token returned by session search. */
+type SessionSearchCursor = Branded<'SessionSearchCursor'>
+```
+
+```ts type-equiv
+/** Cross-session full-text search request. */
+interface SessionSearchRequest {
+  /** Full-text query interpreted as data, never executable FTS syntax. */
+  query: string
+  /** Logical-session predicates applied before event ranking. */
+  sessionFilters?: readonly SessionResultFilter[]
+  /** Event predicates applied before event ranking. */
+  eventFilters?: readonly SessionEventMetadataFilter[]
+  /** Maximum sessions in this page. */
+  limit?: number
+  /** Opaque cursor returned for the identical normalized request. */
+  cursor?: SessionSearchCursor
+}
+```
+
+```ts type-equiv
+/** Within-session full-text search request. */
+interface SessionEventSearchRequest {
+  /** Session whose live-preferred logical log is searched. */
+  sessionId: SessionId
+  /** Full-text query interpreted as data, never executable FTS syntax. */
+  query: string
+  /** Event predicates applied before ranking. */
+  filters?: readonly SessionEventMetadataFilter[]
+  /** Maximum events in this page. */
+  limit?: number
+  /** Opaque cursor returned for the identical normalized request. */
+  cursor?: SessionSearchCursor
+}
+```
+
+```ts type-equiv
+/** One cursor-paginated result page. */
+interface SessionSearchPage<T> {
+  /** Results for this page in contract-defined order. */
+  items: readonly T[]
+  /** Opaque continuation cursor, absent on the final page. */
+  nextCursor?: SessionSearchCursor
+}
+```
+
+```ts type-equiv
+/** One event full-text search hit with a bounded plain-text excerpt. */
+interface SessionEventSearchHit extends SessionEventRecord {
+  /** Plain text excerpt selected around the match. */
+  snippet: string
+}
+```
+
+```ts type-equiv
+/** One grouped cross-session hit, ranked by its strongest matching event. */
+interface SessionSearchHit extends SessionRecord {
+  /** Strongest matching event for this session. */
+  bestMatch: SessionEventSearchHit
+}
+```
+
+## 会话谱系
+
+`SessionLineageTrace` 按由近及远的顺序携带已知 parent，并携带一片由直接 descendant 递归嵌套而成的森林。完整性判别字段使已知 root 与缺失 parent 互斥。
+
+```ts type-equiv
+/** Recursive descendant node in a session-lineage trace. */
+interface SessionLineageNode {
+  /** Detached logical-corpus record for this descendant. */
+  session: SessionRecord
+  /** Direct children, each carrying its own recursive descendants. */
+  descendants: SessionLineageNode[]
+}
+```
+
+```ts type-equiv
+/** Known ancestry and descendants for one logical session. */
+type SessionLineageTrace = {
+  /** Detached record for the session that was traced. */
+  target: SessionRecord
+  /** Known parents from the immediate parent outward. */
+  ancestors: SessionRecord[]
+  /** Complete known descendant trees rooted at the target's direct children. */
+  descendants: SessionLineageNode[]
+} & (
+  | {
+    /** The complete parent chain is present in the logical corpus. */
+    complete: true
+    /** Detached record at the top of the complete lineage. */
+    root: SessionRecord
+  }
+  | {
+    /** The parent chain leaves the visible logical corpus. */
+    complete: false
+    /** First parent id that is not present in the logical corpus. */
+    unresolvedParentId: SessionId
+  }
+)
+```
+
+## 有界事件读取
+
+请求指定一个原始 seq 及可选的邻近数量。结果携带 `SessionHeader` 而非可用性标志，使已知的实时目标可以独立于持久化健康状态。
+
+```ts type-equiv
+/** Request for one event plus raw neighboring log context. */
+interface SessionEventReadRequest {
+  /** Session that owns the target event. */
+  sessionId: SessionId
+  /** Target event seq. */
+  seq: number
+  /** Number of preceding raw events to include. */
+  before?: number
+  /** Number of following raw events to include. */
+  after?: number
+}
+```
+
+```ts type-equiv
+/** Full target event and a bounded raw-log window. */
+interface SessionEventWindow {
+  /** Cloned header for the live-preferred source read. */
+  session: SessionHeader
+  /** Full cloned target event. */
+  target: SessionEvent
+  /** Full cloned events from `startSeq` through `endSeq`. */
+  events: SessionEvent[]
+  /** First seq included in `events`. */
+  startSeq: number
+  /** Last seq included in `events`. */
+  endSeq: number
+}
+```
+
+## 事件关系
+
+事件追踪会区分位置性的 surface 替换与已记录 provenance。除 `replacementChain` 外，每个 seq 列表都包含直接链接；该链从目标沿直接 replacer 追踪到最终的位置替换。
+
+```ts type-equiv
+/** Request for direct surface and provenance relationships around one event. */
+interface SessionEventTraceRequest {
+  /** Session that owns the target event. */
+  sessionId: SessionId
+  /** Target event seq. */
+  seq: number
+}
+```
+
+```ts type-equiv
+/** Direct surface and provenance relationships for one event. */
+interface SessionEventTrace {
+  /** Lightweight target record. */
+  target: SessionEventRecord
+  /** Immediate positional replacement event, when the target was shadowed. */
+  replacedBy?: number
+  /** Positional replacers from the immediate replacement to the final replacement. */
+  replacementChain: number[]
+  /** Surface nodes directly removed when the target itself performed a replacement. */
+  replacedEventSeqs: number[]
+  /** Direct logged provenance sources in their recorded order. */
+  sourceEventSeqs: number[]
+  /** Later events that directly name the target as a provenance source, in log order. */
+  derivedEventSeqs: number[]
+}
+```
+
+## 错误
+
+封闭的 code 联合类型区分请求校验、目标缺失、surface 日志格式错误、可选后端故障与矛盾的源元数据。
+
+```ts type-equiv
+/** Stable machine-routable failure taxonomy for session reads, traces, and search. */
+type SessionQueryErrorCode =
+  | 'SESSION_QUERY_ABORTED'
+  | 'SESSION_QUERY_EVENT_NOT_FOUND'
+  | 'SESSION_QUERY_INDEX_FAILED'
+  | 'SESSION_QUERY_INVALID_CONFIG'
+  | 'SESSION_QUERY_INVALID_CURSOR'
+  | 'SESSION_QUERY_INVALID_FILTER'
+  | 'SESSION_QUERY_INVALID_LIMIT'
+  | 'SESSION_QUERY_INVALID_QUERY'
+  | 'SESSION_QUERY_INVALID_LINEAGE'
+  | 'SESSION_QUERY_INVALID_SURFACE'
+  | 'SESSION_QUERY_INVALID_WINDOW'
+  | 'SESSION_QUERY_PERSISTENCE_FAILED'
+  | 'SESSION_QUERY_SESSION_NOT_FOUND'
+  | 'SESSION_QUERY_STALE_CURSOR'
+  | 'SESSION_QUERY_SOURCE_CONFLICT'
+```
diff --git a/docs/core-data-structures/session-reference.md b/docs/core-data-structures/session-reference.md
index dbe3c43d35..d9a73c08c6 100644
--- a/docs/core-data-structures/session-reference.md
+++ b/docs/core-data-structures/session-reference.md
@@ -36,7 +36,7 @@ interface SessionReferenceCandidate {
 
 ## Prepared messages
 
-Preparation preserves readable current-message content and returns at most one aggregated context. The host binds `contexts` to that exact `send()` or `steer()` call.
+Preparation preserves readable current-message content and returns at most one aggregated context. The host binds `contexts` to that exact `followup()` or `steer()` call.
 
 ```ts type-equiv
 /** Message payload and the zero-or-one durable snapshot contexts bound to it. */
diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/core-data-structures/session.i18n.yaml
new file mode 100644
index 0000000000..f215956acf
--- /dev/null
+++ b/docs/core-data-structures/session.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
+session.md: 7a9ae919fecef7db19f3ca67feb128bcba1db4f0
+session.zh.md: 9e1e9a4f39ed6919416ff5cebf345b43bbc450ea
diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md
index 7f61be2e73..7a9ae919fe 100644
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -1,5 +1,7 @@
 # Sessions
 
+English | [中文](session.zh.md)
+
 The in-memory, event-sourced model of [dsh-session](../../packages/core/session). A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth for an agent's whole interaction history. The LLM message history is *derived* from the log, never stored separately; replay is re-derivation from the same events. How the log is made **durable** (the persistence seam, backends, crash recovery) is the sibling concern on [persistence.md](persistence.md).
 
 Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
@@ -9,7 +11,13 @@ Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/t
 The append-only event types. Merge-extensible: a plugin declares extra event types via declaration merging — e.g. the [compaction seam](compaction.md) adds `compact/start` / `compact/summary` / `compact/end`, and `@deepseek-ai/dsh-hook-protocol` adds log-only `hook/invoked` / `hook/result` provenance for a hook bridge. Like `compact/*`, these are NOT `SurfaceEventType`s (no `surfaceOp`). The generated [persistence log event catalog](../persistence-catalog.md) enumerates every member — core and merged — with its payload, surface badge, and declaration site.
 
 ```ts type-equiv
-/** Shared payload for ordinary and steering prompt messages. */
+/**
+ * Shared payload for user, injected-context, and steering prompt messages. A
+ * direct human prompt, a synthetic `agent.inject()` context, and mid-turn
+ * steering all project into the model transcript as verbatim user-role content;
+ * they are told apart by `source` (a non-`user` kind marks injected context),
+ * not by event type. `meta` carries durable model-hidden producer state.
+ */
 interface PromptMessageData {
   /** Exact model-facing blocks, including any baked prompt-prefix contexts. */
   content: ContentBlock[]
@@ -17,6 +25,15 @@ interface PromptMessageData {
   source: MessageSource
   /** Present only when prompt-prefix contexts were baked into `content`. */
   envelope?: PromptMessageEnvelope
+  /**
+   * Opaque durable JSON state retained on the event but hidden from the model
+   * projection. It is the intended channel for a future framing directive (a
+   * producer declares the frame, a dedicated renderer applies it — see the
+   * deferred note in
+   * ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md),
+   * so the surface keeps projecting `content` verbatim rather than wrapping it.
+   */
+  meta?: JsonValue
 }
 ```
 
@@ -46,29 +63,21 @@ interface SessionEventMap {
   'step/start': { turn: number; step: number }
   /** Closes step `step` of turn `turn`. */
   'step/end': { turn: number; step: number }
-  /** A user-visible prompt (the queued message claimed for this turn). */
+  /**
+   * 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 admitted goal continuation round. All three
+   * project their `content` verbatim; `source` (with a non-`user` kind marking
+   * injected context) is the only channel that tells them apart. An idle
+   * injection wraps this event in a one-shot turn so the log stays turn-enclosed.
+   */
   'user/message': PromptMessageData
   /**
    * Durable record of a prompt veto and its reason. It is log-only: the blocked
    * prompt never enters the model-visible surface, and its turn runs zero steps.
    */
   'prompt/blocked': { content: ContentBlock[]; source: MessageSource; reason: string }
-  /**
-   * In-session context injection (file-change notices, subdir AGENTS.md,
-   * skill content, cron notifications, …). Rendered into the derived history
-   * as a synthetic user-role message carrying `content` verbatim — NOT a
-   * user prompt. `meta` is durable JSON state omitted from the model
-   * projection; it is also the intended channel for any future framing
-   * directive (a producer declares the frame, a dedicated renderer applies it —
-   * see the deferred note in
-   * ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md),
-   * so the surface keeps projecting `content` verbatim rather than wrapping it.
-   */
-  'context/message': {
-    content: ContentBlock[]
-    source: MessageSource
-    meta?: JsonValue
-  }
   /** Raw stream chunk — token-level replay fidelity. */
   'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
   /**
@@ -85,15 +94,25 @@ interface SessionEventMap {
    */
   'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
   /**
-   * A completed tool call's model-facing result, plus an optional tool-private
-   * `meta` presentation payload. `meta` is opaque to the core (`unknown` — the
-   * producing tool owns its shape and reads it back in `presentResult`) but MUST
-   * be JSON-serializable: `Session.append` runtime-validates all event data with
-   * `isJsonValue`, so a non-serializable `meta` is rejected at the source, and the
-   * durable log reproduces the identical card on replay. Absent unless the tool
-   * attaches one (e.g. `dsh-tool-fs` carries its result-time contextual diff here).
+   * 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; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
+  'tool/result': {
+    turn: number
+    step: number
+    callId: CallId
+    content: ContentBlock[]
+    isError: boolean
+    error?: { name: string; code: string }
+    meta?: JsonValue
+  }
   /** Steering content injected between steps of a running turn. */
   'steering/message': PromptMessageData & { turn: number }
   /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
@@ -189,7 +208,7 @@ A proper discriminated union over `type` (not independent `type`/`data` unions),
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
  * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`, `context/message`, `steering/message`).
+ * `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.
@@ -223,7 +242,7 @@ For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-emp
 
 ## Surface types
 
-The five message-producing types (`SurfaceEventType` — `user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`) carry surface metadata declaring how they join the ordered derived surface. See the [session surface Agent Note](../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md).
+The four message-producing types (`SurfaceEventType` — `user/message`, `assistant/message`, `tool/result`, `steering/message`) carry surface metadata declaring how they join the ordered derived surface. See the [session surface Agent Note](../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md).
 
 ### `SurfaceEventType` — the message-producing subset of event types
 
@@ -237,7 +256,6 @@ type SurfaceEventType =
   | 'user/message'
   | 'assistant/message'
   | 'tool/result'
-  | 'context/message'
   | 'steering/message'
 ```
 
@@ -248,7 +266,7 @@ type SurfaceEventType =
  * How a session event entered the ordered surface. Only valid on
  * {@link SurfaceEventType} events.
  *
- * - `'append'`: added to the tail — normal path for user/assistant/tool/context
+ * - `'append'`: added to the tail — normal path for user/assistant/tool/steering
  *   messages.
  * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
@@ -455,7 +473,7 @@ declare class Session {
 - `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.
 - `tool/result` → a user message carrying a `tool-result` block.
-- `context/message` → a user-role message carrying its `content` verbatim at its chronological position. Optional JSON `meta` remains in the event log and is never rendered.
+- `user/message` (injected context, i.e. non-`user` source) → a user-role message carrying its `content` verbatim at its chronological position. Optional JSON `meta` remains in the event log and is never rendered.
 - `steering/message` → a user-role message carrying exact `content` at its chronological position; an optional envelope remains log-only display metadata.
 
 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. An operational error's step number is on `turn/end.reason` for `kind: 'error'`, with normalized `LlmFailure` facts for a final model-request failure and message/code for other live errors. 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.
@@ -479,11 +497,12 @@ interface TurnTriggerMap {
   message: { kind: 'message'; source: MessageSource }
   /**
    * An out-of-band context injection (`agent.inject()`) made while the agent
-   * was idle. The loop wraps the injected `context/message` in a one-shot turn
-   * (`turn/start` → `context/message` → `turn/end`) so every event in the log
-   * stays turn-enclosed — the durability/replay boundary is the turn, and a
-   * bare event between turns would otherwise be indistinguishable from a crash
-   * tail on reload.
+   * was idle. The loop wraps the injected `user/message` (a non-`user` source,
+   * plugin by default) in a one-shot turn (`turn/start` → `user/message` →
+   * `turn/end`) so every event in the log stays turn-enclosed — the
+   * durability/replay boundary is the turn, and a bare event between turns would
+   * otherwise be indistinguishable from a crash tail on reload. The trigger's
+   * `source` mirrors that message's producer.
    */
   injection: { kind: 'injection'; source: MessageSource }
 }
@@ -532,13 +551,13 @@ interface TurnEndReasonMap {
 
 ## The turn-enclosure invariant
 
-Every session event lives **inside** a turn (between a `turn/start` and its `turn/end`). The loop appends queued `user/message` events *after* `turn/start`, an idle `agent.inject()` wraps its `context/message` in a one-shot `injection` turn, and `appendOutOfBand()` similarly wraps an eligible log-only event when no turn is open. This makes the turn the single durability/replay boundary: a backend can treat anything after the last `turn/end` as an interrupted-crash tail without risking the loss of legitimately-recorded between-turn context. The optional `dsh-session/invariant` companion enforces it in dev through `ctx.invariants` (a message event outside an open turn throws). See [the turn-enclosure invariant Agent Note](../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md).
+Every session event lives **inside** a turn (between a `turn/start` and its `turn/end`). The loop appends queued `user/message` events *after* `turn/start`, an idle `agent.inject()` wraps its `user/message` in a one-shot `injection` turn, and `appendOutOfBand()` similarly wraps an eligible log-only event when no turn is open. This makes the turn the single durability/replay boundary: a backend can treat anything after the last `turn/end` as an interrupted-crash tail without risking the loss of legitimately-recorded between-turn context. The optional `dsh-session/invariant` companion enforces it in dev through `ctx.invariants` (a message event outside an open turn throws). See [the turn-enclosure invariant Agent Note](../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md).
 
 ## 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), but, like every event, they must sit inside an open turn. 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).
 
-The hook bridges' `hook/invoked` / `hook/result` provenance pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. The mid-turn hook points (`PreToolUse`/`PostToolUse`/`UserPromptSubmit`/`Stop`) fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record — its injected `context/message` is the durable evidence — because it has no open turn to enclose one (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
+The hook bridges' `hook/invoked` / `hook/result` provenance pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. The mid-turn hook points (`PreToolUse`/`PostToolUse`/`UserPromptSubmit`/`Stop`) fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record — its injected `user/message` is the durable evidence — because it has no open turn to enclose one (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
 
 ## Durability contract
 
diff --git a/docs/core-data-structures/session.zh.md b/docs/core-data-structures/session.zh.md
new file mode 100644
index 0000000000..9e1e9a4f39
--- /dev/null
+++ b/docs/core-data-structures/session.zh.md
@@ -0,0 +1,570 @@
+# 会话
+
+[English](session.md) | 中文
+
+[dsh-session](../../packages/core/session) 的内存事件溯源模型。`Session` 是一份由类型化 `SessionEvent` 组成的**仅追加日志**，是 agent（智能体）完整交互历史的唯一真源。LLM（大语言模型）消息历史从日志*派生*而来，从不单独存储；回放即从同一组事件重新派生。日志如何实现**持久化**（持久化 seam、后端、崩溃恢复）是兄弟文档 [persistence.md](persistence.md) 的关注点。
+
+源码：[`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
+
+## `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 标记与声明位置。
+
+```ts type-equiv
+/**
+ * Shared payload for user, injected-context, and steering prompt messages. A
+ * direct human prompt, a synthetic `agent.inject()` context, and mid-turn
+ * steering all project into the model transcript as verbatim user-role content;
+ * they are told apart by `source` (a non-`user` kind marks injected context),
+ * not by event type. `meta` carries durable model-hidden producer state.
+ */
+interface PromptMessageData {
+  /** Exact model-facing blocks, including any baked prompt-prefix contexts. */
+  content: ContentBlock[]
+  /** Producer provenance for the direct prompt. */
+  source: MessageSource
+  /** Present only when prompt-prefix contexts were baked into `content`. */
+  envelope?: PromptMessageEnvelope
+  /**
+   * Opaque durable JSON state retained on the event but hidden from the model
+   * projection. It is the intended channel for a future framing directive (a
+   * producer declares the frame, a dedicated renderer applies it — see the
+   * deferred note in
+   * ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md),
+   * so the surface keeps projecting `content` verbatim rather than wrapping it.
+   */
+  meta?: JsonValue
+}
+```
+
+```ts type-equiv
+/**
+ * The merge-extensible, append-only source of truth for an agent interaction.
+ * Message history is derived from this log. Every event is lossless JSON and
+ * sequence numbers stay contiguous, including raw chunks, so persistence can
+ * store the canonical log verbatim.
+ */
+interface SessionEventMap {
+  /**
+   * Opens turn `turn`. `trigger` records what started it — one claimed queued
+   * message or an idle-time injection. The turn is the durability/replay
+   * boundary: every event sits between a `turn/start` and its matching
+   * `turn/end` (the turn-enclosure invariant).
+   */
+  'turn/start': { turn: number; trigger: TurnTrigger }
+  /**
+   * Closes turn `turn` with the {@link TurnEndReason} that ended it. The loop
+   * awaits `session/flush` after an ordinary turn ends before claiming the next
+   * queued item. Success commits the turn; rejection is reported live and does
+   * not prevent later work.
+   */
+  'turn/end': { turn: number; reason: TurnEndReason }
+  /** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */
+  'step/start': { turn: number; step: number }
+  /** Closes step `step` of turn `turn`. */
+  'step/end': { turn: number; step: number }
+  /**
+   * A user-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 admitted goal continuation round. All three
+   * project their `content` verbatim; `source` (with a non-`user` kind marking
+   * injected context) is the only channel that tells them apart. An idle
+   * injection wraps this event in a one-shot turn so the log stays turn-enclosed.
+   */
+  'user/message': PromptMessageData
+  /**
+   * Durable record of a prompt veto and its reason. It is log-only: the blocked
+   * prompt never enters the model-visible surface, and its turn runs zero steps.
+   */
+  'prompt/blocked': { content: ContentBlock[]; source: MessageSource; reason: string }
+  /** Raw stream chunk — token-level replay fidelity. */
+  'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
+  /**
+   * 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; content: ContentBlock[]; provenance: AssistantProvenance; usage?: TokenUsage }
+  /**
+   * The model requested one tool invocation: `name` with the raw `arguments`
+   * JSON string exactly as the model produced it (unparsed). `callId` pairs the
+   * call with its `tool/result`.
+   */
+  'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
+  /**
+   * A completed tool call's model-facing result, 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
+    callId: CallId
+    content: ContentBlock[]
+    isError: boolean
+    error?: { name: string; code: string }
+    meta?: JsonValue
+  }
+  /** Steering content injected between steps of a running turn. */
+  'steering/message': PromptMessageData & { turn: number }
+  /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
+  'todo/write': { todos: TodoItem[] }
+  /**
+   * 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 }
+}
+```
+
+`PromptMessageData.content` 始终是确切的模型可见内容。当附加上下文声明 `prompt-prefix` 放置方式时，AgentLoop 会依次把它的块、一个 `## My request:` 分隔符以及最终生效的直接提示词拼接进该数组。可选且对模型隐藏的 `envelope` 会保留 `displayContent`，以及按顺序排列的前缀上下文来源/元数据描述信息，使 transcript（文本记录）、标题与重新引用消费方无需改变可重建历史，就能呈现人类提示词。`displayPromptContent()` 负责该选择，并为普通事件和较早的事件回退到 `content`。
+
+### `OutOfBandSessionEventMap`：受限的带外追加显式准入
+
+仅属于 `SessionEventMap` 并不表示事件可以脱离 agent loop（智能体循环）的常规生命周期追加。事件所有方必须通过声明合并将同一键加入这个空标记映射，`ctx.sessions.appendOutOfBand()` 才会接受该事件；派生类型还会排除所有 surface 事件。被接受的更新会并入已打开的轮次；如果没有打开的轮次，系统则为它创建一个边界配平且已刷新完成的零步骤轮次。
+
+```ts type-equiv
+/**
+ * Marker map for plugin-owned log-only events accepted by
+ * `SessionStore.appendOutOfBand()`. A plugin extends this map with the same key
+ * it adds to {@link SessionEventMap}; surface and lifecycle events stay
+ * ineligible unless their owner explicitly opts them into this narrow seam.
+ */
+interface OutOfBandSessionEventMap {}
+```
+
+### `TodoItem`：一条待办项
+
+这是 `todo/write` 事件全量列表快照中的单元。它有意保持精简：一行 `content` 加一个三态 `status`（没有 id、优先级或 `activeForm`）；列表在每次写入时整体替换，因此条目无需稳定标识，而这三个状态值恰好对应 ACP 的 `PlanEntryStatus`，所以 UI 桥接层可以将待办列表一一映射为 ACP `plan`（并合成 ACP 额外要求的优先级）。见 [todo_write Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md)。
+
+```ts type-equiv
+/**
+ * One entry in an agent's todo list — the unit of the `todo/write`
+ * {@link SessionEventMap} event's whole-list snapshot.
+ *
+ * Deliberately minimal: a human-readable `content` line and a three-state
+ * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
+ * on every write (last-write-wins), so entries need no stable identity, and the
+ * status triple is exactly the ACP `PlanEntryStatus`, so a UI bridge can map a
+ * todo list onto an ACP `plan` 1:1 (synthesizing the priority ACP additionally
+ * requires).
+ */
+interface TodoItem {
+  /** What this task is — a short imperative line shown in the UI. */
+  content: string
+  /** Lifecycle state. `in_progress` marks the single task being worked now. */
+  status: 'pending' | 'in_progress' | 'completed'
+}
+```
+
+<a id="the-request-header-event-requestheader"></a>
+
+### 请求头事件：`request/header`
+
+请求信封（即 `EpochHeader`：调用配置 + 渲染后的系统提示词 + 已组装的工具 schema + 会话前缀）会作为会话状态写入日志，因此每个对话请求都是日志的纯函数（见可重建性 Agent Note）。带有 reason `'initial'` 或 `'resume'` 的完整 `request/header` 快照记录每个 agent loop 实例的边界；之后请求发生变化时，系统会以 reason `'change'` 记录另一份完整快照。`foldRequestHeader(events)` 通过选择最新快照重建请求头。该事件不是 `SurfaceEventType`，不产生 LLM 消息。
+
+```ts type-equiv
+/**
+ * Logged request state outside derived history: call config, system prompt,
+ * tools, and prefix. The latest full `request/header` snapshot reconstructs it;
+ * canonical empty optional fields are absent.
+ */
+interface EpochHeader {
+  /** The conversation's call configuration (provider, model, and sampling scalars). */
+  config: LlmCallConfig
+  /** Rendered system prompt text; absent for a system-less request. */
+  system?: string
+  /** Assembled tool schemas; absent for a tool-less request. */
+  tools?: ToolSchema[]
+  /**
+   * The session prefix: request-only messages sent BEFORE the entire derived
+   * history (the `agent/session-prefix` waterfall's product, composed once
+   * per loop instance and reused for every request it sends). Not session
+   * history — `deriveMessages()` never returns it — so the header is its
+   * only durable record; absent when the instance composed none.
+   */
+  messagePrefix?: Message[]
+}
+```
+
+规范形式：空系统提示词、空工具列表和空会话前缀都表示为字段缺失，与请求构建方式一致。`messagePrefix` 是 `agent/session-prefix` waterfall（瀑布式事件）产物的持久记录（请求 = `messagePrefix + derived history`）；每个 agent loop 实例只组合一次，并包含在该实例记录的每份完整快照中。包含已移除的 `request/header-delta` 事件或完整快照原因为 `fallback` 的旧版 v0 日志，会在 seed、append 和持久化加载边界被拒绝，而不会以不完整方式回放。
+
+## `SessionEvent<T>`：一条日志条目
+
+基于 `type` 的真正可辨识联合（而非独立的 `type`/`data` 联合），因此 `switch (event.type)` 能直接收窄 `event.data`，无需类型断言。`seq` 是日志中的单调递增位置（`seq = log.length`）；`time` 为 epoch 毫秒。
+
+```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]
+```
+
+`SessionEventType = keyof SessionEventMap`。由于 `SessionEventMap` 可通过合并扩展，对 `SessionEvent` 的 switch 语句禁止使用 `assertNever`：插件添加的变体是合法的未知值；处理已知 case 后在 `default` 中放行。
+
+对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；字段缺失则表示旧格式或其他未记录溯源信息的情况。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
+
+## Surface 类型
+
+四种产生消息的类型（`SurfaceEventType`：`user/message`、`assistant/message`、`tool/result`、`steering/message`）携带 surface 元数据，用来声明它们如何加入有序的派生 surface。见 [session surface Agent Note](../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md)。
+
+### `SurfaceEventType`：事件类型中产生消息的子集
+
+```ts type-equiv
+/**
+ * The subset of {@link SessionEventType} values whose events produce LLM
+ * messages and are eligible to appear on the ordered surface. Only these
+ * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
+ */
+type SurfaceEventType =
+  | 'user/message'
+  | 'assistant/message'
+  | 'tool/result'
+  | 'steering/message'
+```
+
+### `SurfaceOp`：事件如何进入 surface
+
+```ts type-equiv
+/**
+ * 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/steering
+ *   messages.
+ * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
+ *   (inclusive) through `end` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `start === end` replaces a single
+ *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
+ *   shadowed surface node. Used by compaction and possible other manipulations.
+ */
+type SurfaceOp =
+  | 'append'
+  | { op: 'replace'; start: number; end: number }
+```
+
+`'append'` 是常规的尾部追加路径。`replace` 会遮蔽从 `start` 到 `end`（含两端）的 surface 条目（两者都必须是有效的 surface seq；`start === end` 时仅替换单个条目），并在原位置插入新事件。
+
+### `SurfaceIntent`：`session.append()` 的参数
+
+```ts type-equiv
+/**
+ * Surface placement and provenance for {@link Session.append}. Required on
+ * message-producing events and forbidden on log-only events.
+ */
+interface SurfaceIntent {
+  surfaceOp: SurfaceOp
+  /**
+   * Complete known provenance source set. `assistant/message` may use a
+   * present empty array for a known empty provider stream; omission means its
+   * provenance was not recorded. Other surface events require a non-empty set
+   * when this field is present.
+   */
+  sourceEventSeqs?: number[]
+}
+```
+
+对 `SurfaceEventType` 事件必填：每个产生消息的事件都必须声明它如何加入 surface（派生历史的唯一来源）。非 surface 类型在编译期拒绝此参数。
+
+此处适用相同的溯源区分：只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；省略该字段并不表示其源流为空。
+
+### `SessionSurface`：实时只读 surface 投影
+
+`Session.surface` 返回会话稳定的 `SessionSurface` 视图。同一个增量管理器在提交前校验追加候选事件，并根据已提交事件推进该投影；调用方可以观察成员关系和替换代次，但不能调用校验。
+
+```ts type-equiv
+/** Readonly live projection of the message-producing session events. */
+interface SessionSurface {
+  /** Current surface event sequences in model-visible order. */
+  readonly nodes: readonly number[]
+  /** Monotonic count of committed positional replacements. */
+  readonly replaceGeneration: number
+}
+```
+
+### `SurfaceFoldReplacement` 与 `SurfaceFoldResult`：完整的 surface 回放
+
+`foldSurface(events)` 返回一份独立的当前事件 seq 列表，以及每个声明的替换范围实际遮蔽的 seq。实时管理器复用同一套状态转换，但不保留替换历史。每提交一次替换，其 `replaceGeneration` 就递增一次，使增量消费方能够区分纯尾部增长与重写。
+
+```ts type-equiv
+/** One replacement operation observed while folding a session surface. */
+interface SurfaceFoldReplacement {
+  /** Seq of the event that replaced the prior surface range. */
+  seq: number
+  /** Declared inclusive start seq of the replaced surface range. */
+  start: number
+  /** Declared inclusive end seq of the replaced surface range. */
+  end: number
+  /** Actual surface entries removed by the operation, in surface order. */
+  shadowedSeqs: number[]
+}
+```
+
+```ts type-equiv
+/** Complete result of replaying the surface operations in a session log. */
+interface SurfaceFoldResult {
+  /** Current surface event sequences in model-visible order. */
+  nodes: number[]
+  /** Replacement operations in event order. */
+  replacements: SurfaceFoldReplacement[]
+}
+```
+
+## `Session` public API
+
+去除方法体的声明与源码中的普通类保持同步，覆盖其公共构造函数、状态访问器、追加边界和历史投影。存储操作仍由生成的 [`ctx.sessions` 服务目录](../cordis-catalog/services.md#ctxsessions--sessionstore)记录。
+
+```ts public-api
+/**
+ * An event-sourced session: an append-only log of {@link SessionEvent}s.
+ *
+ * Plain class (not a Service) — create instances via `ctx.sessions.create()`.
+ * Seeding with an existing event log replays/forks a session.
+ */
+declare class Session {
+  /** The ordered surface over this session's event log. */
+  get surface(): SessionSurface;
+  /**
+   * Detached, deep-frozen creation metadata (format version, cwd, lineage,
+   * seed boundary). Supplied by the store via `ctx.sessions.create()`. When a
+   * `Session` is constructed bare (tests, ad-hoc replay), a minimal header is
+   * synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
+   * `session.header` is always present. Kept out of the event log — it is a
+   * storage concern, not replayable conversation state.
+   */
+  readonly header: SessionHeader;
+  /** The session identity, derived from its durable header's single copy. */
+  get id(): SessionId;
+  constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);
+  /**
+   * An immutable snapshot of the append-only event log. The snapshot is reused
+   * until the next append; a previously returned array does not grow later.
+   * Events and their nested data are deep-frozen at acceptance, so neither a
+   * cast nor ordinary JavaScript can rewrite durable history.
+   */
+  get events(): readonly SessionEvent[];
+  /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
+  get seq(): number;
+  /**
+   * Append one typed event to the log and synchronously notify observers via
+   * the store-owned, module-private publication hooks. The hot path never blocks
+   * on I/O — persistence plugins buffer asynchronously. Once the event enters
+   * the log, the append is committed: observer failures are logged and
+   * contained per listener, so they do not change the return value or prevent
+   * later listeners from observing the same accepted event.
+   *
+   * @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
+   *   {@link SurfaceEventType} events (every message-producing event must
+   *   declare how it joins the surface, the sole source of derived history) and
+   *   rejected by the compiler for non-surface types like `turn/start` or
+   *   `assistant/chunk`.
+   * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
+   *   `data` that entered the log, so reading `event.data` back sees the logged
+   *   value, never the caller's still-mutable input.
+   * @throws if `data` or surface metadata is not losslessly JSON-serializable
+   *   (BigInt, function, symbol, undefined, negative zero, non-finite number,
+   *   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
+   *   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
+   *   of truth, so a bad event fails at the append site rather than later during
+   *   a backend flush. A synchronous internal dispatch validation failure or an
+   *   append reentered while this acceptance/publication boundary is open also
+   *   rejects before the log changes.
+   */
+  append<T extends SessionEventType>(
+    type: T,
+    data: SessionEventMap[T],
+    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []
+  ): SessionEvent<T>;
+  /**
+   * The {@link EpochHeader} in force after the log's last header event — the
+   * header the NEXT request will be compared against — or undefined before
+   * the first `request/header` snapshot. The live, incrementally-maintained
+   * form of `foldRequestHeader(session.events)`: each header event is folded
+   * once, when first seen, so a per-step read costs O(new events).
+   * @returns the folded header, or undefined when no header event exists yet.
+   */
+  requestHeader(): EpochHeader | undefined;
+  /**
+   * Derive the LLM message history by walking the ordered sequences of
+   * message-producing events maintained by `surfaceOp` markers. The
+   * surface is the single source of derived history: every message-producing
+   * append records its `surfaceOp`, so a raw event with no marker (a chunk, a
+   * turn boundary) is correctly absent, and a compaction `replace` deletes the
+   * shadowed nodes from the derivation. The projection rules are
+   * {@link deriveEventMessage}, folded per node.
+   *
+   * CACHED: each surface node is projected exactly once, when first seen — a
+   * call costs O(new nodes), and a surface rewrite (a `replace`;
+   * {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
+   * a fresh snapshot per call (later appends never grow an array a caller
+   * already holds); the `Message` objects in it are SHARED and **deep-frozen**.
+   * Their content reuses the already frozen durable event data, so the cache
+   * needs no second deep clone and consumers still cannot mutate the log.
+   * @returns a fresh array of the shared, frozen derived history.
+   */
+  deriveMessages(): Message[];
+  /**
+   * Project a single event into the LLM message it derives to, or null when
+   * it produces none — a non-surface event (chunk, boundary, log-only record)
+   * or an empty-content assistant/message (which exists only to host usage).
+   * The per-node pure function {@link deriveMessages} folds over the surface;
+   * an external reconstructor (or the dev invariant) folds the same function
+   * over a log prefix's surface to rebuild the exact messages any request was
+   * built from (the reconstructability Agent Note). The returned message wrapper is
+   * fresh; its content reuses the logged event's already deep-frozen durable
+   * data, so changing the wrapper cannot rewrite the log and changing content
+   * throws.
+   * @param event - the event to project.
+   * @returns the derived message, or null when the event produces none.
+   */
+  deriveEventMessage(event: SessionEvent): Message | null;
+}
+```
+
+## 派生历史：`deriveMessages()` 与 `deriveEventMessage()`
+
+`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。
+- `tool/result` → 一条携带 `tool-result` 块的 user 消息。
+- `user/message`（注入上下文，即非 `user` 来源）→ 按时间顺序在相应位置生成一条 user-role 消息，并原样承载其 `content`。可选的 JSON `meta` 保留在事件日志中，绝不渲染。
+- `steering/message` → 按时间顺序在相应位置生成一条携带确切 `content` 的 user-role 消息；可选 envelope 仅作为日志中的展示元数据保留。
+
+其余所有事件（`turn/*`、`step/*`、插件所有的 `llm/retry`）均为结构信息，不会投影为消息。token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息，因此其用量分片是持久化的记账记录。操作错误的步骤号记录在 `turn/end.reason`（`kind: 'error'`）中；如果是最终模型请求失败，其中包含规范化的 `LlmFailure` 事实，其他实时错误则包含消息/代码。由于这一尚未发布的格式有意不提供兼容性承诺，seed/load 校验会拒绝缺少提供方和模型的请求头，以及缺少提供方/模型溯源信息的 assistant 消息，而不会猜测历史数据应走的提供方路由。
+
+## 活跃会话 fork API
+
+`ctx.sessions.create(id, { seed, meta })` 是底层的回放/fork 原语。对于普通的活跃会话 fork，`SessionStore` 暴露一个策略 API：
+
+- `fork(source, boundary?, childSessionId?)` 接受一个活跃的 `Session` 对象或活跃的 `SessionId`，选取到 `boundary` seq（含）为止的源事件（默认为当前最后一个事件），要求 boundary 事件必须是 `turn/end`，然后创建一个活跃的子会话，包含深克隆的种子事件和子会话元数据（`parentSession`、`seedLength` 及继承的 `cwd`）。
+
+显式 `boundary` 允许调用者从之前完成的轮次 fork，即使源会话有更新的事件或正在进行的轮次。API 拒绝非 `turn/end` 的 boundary，而不是静默截断。更广泛的轮次封闭性检查留在既有的 `dsh-invariants` 插件和持久化修复路径中，不在 `fork()` 中重复。`dsh-subagent-fork` 保留其已完成前缀截断逻辑，因为工具时委托通常在父轮次仍然打开时启动；普通的会话分支应显式指定请求的 boundary。
+
+## 轮次的触发原因：`TurnTriggerMap`
+
+```ts type-equiv
+/**
+ * What started a turn.
+ * Merge-extensible sum type (same pattern as MessageSourceMap).
+ */
+interface TurnTriggerMap {
+  message: { kind: 'message'; source: MessageSource }
+  /**
+   * An out-of-band context injection (`agent.inject()`) made while the agent
+   * was idle. The loop wraps the injected `user/message` (a non-`user` source,
+   * plugin by default) in a one-shot turn (`turn/start` → `user/message` →
+   * `turn/end`) so every event in the log stays turn-enclosed — the
+   * durability/replay boundary is the turn, and a bare event between turns would
+   * otherwise be indistinguishable from a crash tail on reload. The trigger's
+   * `source` mirrors that message's producer.
+   */
+  injection: { kind: 'injection'; source: MessageSource }
+}
+```
+
+<a id="why-a-turn-ended-turnendreasonmap"></a>
+
+## 轮次的结束原因：`TurnEndReasonMap`
+
+`aborted` 有意作为一种粗粒度的持久结果：它只记录取消中断了实时轮次，不记录是哪个运行时调用方发起取消。仅属于运行时的调用方词汇由 [`AgentCancelCause`](core.md#the-agent-handle) 定义；未来若有审计需求，应新增独立的控制请求事件，而非让终止结果承载这一信息。
+
+```ts type-equiv
+/**
+ * Why a turn ended. Merge-extensible sum type.
+ */
+interface TurnEndReasonMap {
+  completed: { kind: 'completed' }
+  /** A cancellation request interrupted the live turn. */
+  aborted: { kind: 'aborted' }
+  /**
+   * The turn failed: a step threw or the model reported a failure. `step` is the
+   * step number the failure occurred on (the operational error's location — the
+   * single durable record of an in-turn failure; live diagnostics also fire via
+   * `agent/error`). Final model-request failures retain their normalized facts
+   * as one `failure`; other turn failures retain their live Error message/code.
+   */
+  error: { kind: 'error'; step: number } & (
+    | { failure: LlmFailure; message?: never; code?: never }
+    | { message: string; code?: string; failure?: never }
+  )
+  disposed: { kind: 'disposed' }
+  /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */
+  'max-tokens': { kind: 'max-tokens' }
+  /**
+   * Policy blocked the turn's claimed prompt before the first step. The
+   * zero-step turn still records a balanced durable boundary and veto reason.
+   */
+  rejected: { kind: 'rejected'; reason: string }
+  /**
+   * A persistence backend closed a crash-orphaned turn on reload. The loop never
+   * emits this marker, and the events recorded before the crash remain intact.
+   */
+  interrupted: { kind: 'interrupted' }
+}
+```
+
+`max-tokens` 与模型调用中同名的 `FinishReason` 对应：只要轮次内有任何步骤以 `max-tokens` 结束，整个轮次就以 `max-tokens` 而不是 `completed` 结束（即使之后继续执行，截断事实仍优先），让消费方能够区分正常停止和截断停止；但它只优先于 `completed`，`disposed`/`aborted`/`error` 结果的优先级更高。`rejected` 表示一个零步骤轮次，其已认领的提示词被 `agent/prompt-submit` 钩子阻止（ACP（Agent Client Protocol）桥接层将其映射为 `cancelled`）。`interrupted` 是唯一不会由任何 loop 发出的原因：它由崩溃恢复合成（见 [persistence.md](persistence.md)）。两个 map 均可通过合并扩展。
+
+## 轮次封闭不变式
+
+每个会话事件都位于一个轮次**之内**（在 `turn/start` 和对应的 `turn/end` 之间）。loop 在 `turn/start` *之后*追加已排队的 `user/message` 事件；空闲时的 `agent.inject()` 会用一次性的 `injection` 轮次包住其 `user/message`；没有打开的轮次时，`appendOutOfBand()` 同样会用一个轮次包住符合条件的仅日志事件。这使轮次成为唯一的持久性/回放边界：后端可以将最后一个 `turn/end` 之后的任何内容视为崩溃中断尾部，而不会丢失合法记录在轮次之间的上下文。可选的 `dsh-session/invariant` 配套插件通过 `ctx.invariants` 在开发环境中强制此不变式（消息事件若位于打开的轮次之外便会抛出）。见[轮次封闭不变式 Agent Note](../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)。
+
+## 插件贡献的仅日志事件
+
+插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史），但与所有事件一样，必须位于一个打开的轮次内。完整的逐事件枚举（核心与插件贡献的，含 payload 与溯源信息）见生成的[持久化日志事件目录](../persistence-catalog.md)；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
+
+钩子桥接层的 `hook/invoked` / `hook/result` 溯源对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。轮次中间的钩子点（`PreToolUse`/`PostToolUse`/`UserPromptSubmit`/`Stop`）在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录：它注入的 `user/message` 已是持久证据，而且当时没有已打开的轮次可容纳该记录（见[钩子桥接 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` 始终与后端可持久化的内容一致。新增携带不可序列化数据的事件类型，或破坏会话不变式配套插件所检查的轮次/步骤嵌套，会构成磁盘格式的破坏性变更。
+
+消费此契约的后端见 [persistence.md](persistence.md)。
diff --git a/docs/core-data-structures/skills.i18n.yaml b/docs/core-data-structures/skills.i18n.yaml
new file mode 100644
index 0000000000..2f67387224
--- /dev/null
+++ b/docs/core-data-structures/skills.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
+skills.md: fc9599713dcfddec9719ed746b66ea0217b86cf5
+skills.zh.md: 0eb4c0aa69ed56117c7508358c0d47e3b3e95fcb
diff --git a/docs/core-data-structures/skills.md b/docs/core-data-structures/skills.md
index e367adf006..fc9599713d 100644
--- a/docs/core-data-structures/skills.md
+++ b/docs/core-data-structures/skills.md
@@ -1,5 +1,7 @@
 # Skills
 
+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 project/custom/user directories; the consumer ([dsh-tool-skill](../../packages/skill/tool-skill)) owns the session-prefix catalog and 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).
diff --git a/docs/core-data-structures/skills.zh.md b/docs/core-data-structures/skills.zh.md
new file mode 100644
index 0000000000..0eb4c0aa69
--- /dev/null
+++ b/docs/core-data-structures/skills.zh.md
@@ -0,0 +1,159 @@
+# Skills
+
+[English](skills.md) | 中文
+
+[skill（技能）能力族](../../packages/skill)拆分为三个包（package）：注册表（[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)。
+
+源码：[`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)。
+
+## 提供方注册表
+
+`ctx.skills` 组合本地、内嵌、远程或其他提供方。注册是同步的；远程初始化与发现属于 `list()` 的 await 阶段。提供方对象、选项与候选项以只读方式借用，语义字段会被校验。
+
+重名按 rank、提供方顺序、本地顺序依次解决；摘要按名称排序。`list()` 拒绝时记录日志并跳过，不缓存降级后的目录；格式错误的候选项快速失败。
+
+```ts type-equiv
+/** Provider interface for one source of skills, such as local directories or a remote registry. */
+interface SkillProvider {
+  /** Unique provider name in the `ctx.skills` registry. */
+  readonly name: string
+  /**
+   * List available skill candidates for the current lookup context. Provider
+   * plugins register synchronously during `apply()`; remote initialization,
+   * authentication, and discovery are awaited inside this method. Implementations
+   * should settle promptly when `options.signal` aborts.
+   * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+   * @returns provider candidates with precedence ranks and opaque locators.
+   */
+  readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[]>
+  /**
+   * Load a complete skill body for a previously listed candidate.
+   * @param candidate - the winning candidate originally returned by this provider.
+   * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+   * @returns the full skill body, or `undefined` if it is no longer loadable.
+   */
+  readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>
+}
+```
+
+## 本地发现优先级
+
+内置的本地提供方按 rank 顺序扫描各根目录：
+
+| Rank | Source | Root |
+|---|---|---|
+| 100 | `project-dsh` | `<projectRoot>/.dsh/skills` |
+| 200 | `project-agents` | `<projectRoot>/.agents/skills` |
+| 300 | `custom` | `Config.customSkillDirs` |
+| 400 | `user-dsh` | `<dshHome>/skills` |
+| 500 | `user-agents` | `<agentsHome>/skills` |
+
+项目根目录为包含 `.git` 的最近祖先目录；找不到时使用当前 cwd。当 `ctx.fs` 可用时，git-root 向上查找通过文件系统服务探测 `.git`，使远程或沙箱工作区不会回退到宿主文件系统边界。用户 DSH 根目录会跳过其 `.system` 子目录。本地提供方不附带内置系统 skill；部署方通过另一个提供方提供内置 skill。
+
+## Skill 身份
+
+skill 名称为 kebab-case（`^[a-z0-9]+(?:-[a-z0-9]+)*$`）。本地提供方接受目录包（`<name>/SKILL.md`）和扁平 Markdown 文件（`<name>.md`）。嵌套递归的 `**/SKILL.md` 发现有意不在 v1 范围内。
+
+```ts type-equiv
+/** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
+type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | (string & {})
+```
+
+## 摘要、候选项与完整定义
+
+`SkillSummary` 是注册表中可供模型调用的摘要形状。消费方自行选择渲染哪些字段；会话目录仅使用 `name` 和 `description`，从不使用 body 或绝对文件路径。`disableModelInvocation` 将 skill 从模型列表中隐藏，但允许受信代码按名称加载。
+
+```ts type-equiv
+/** Model-visible skill metadata returned by `ctx.skills.list()` and rendered into request guidance. */
+interface SkillSummary {
+  /** Kebab-case identifier used with the `skill` tool. */
+  readonly name: string
+  /** Short routing description shown to the model. */
+  readonly description: string
+  /** Optional extra routing guidance shown to the model. */
+  readonly whenToUse?: string
+  /** Whether the skill is hidden from model listings while remaining loadable by trusted callers. */
+  readonly disableModelInvocation?: boolean
+  /** Discovery source that produced this winning skill. */
+  readonly source: SkillSource
+  /** Provider that owns this skill body. */
+  readonly provider: string
+  /** Provider-specific base for relative resources. */
+  readonly resourceBase?: SkillResourceBase
+}
+```
+
+`SkillCandidate` 是提供方到注册表的形状。`locator` 是提供方的不透明状态；注册表只存储它并在调用获胜提供方的 `get()` 时传回。
+
+```ts type-equiv
+/** Provider catalog entry used by the registry to merge and later load skills. */
+interface SkillCandidate extends SkillSummary {
+  /** Lower ranks win duplicate skill names before provider registration order is considered. */
+  readonly rank: number
+  /** Opaque provider-owned handle passed back to `provider.get()`. */
+  readonly locator: unknown
+  /** Absolute file path when the provider has one. */
+  readonly path?: string
+  /** Parsed optional metadata object from provider-specific skill frontmatter. */
+  readonly metadata?: Readonly<Record<string, unknown>>
+}
+```
+
+`SkillDefinition` 是 `ctx.skills.get()` 返回的完整解析结果，供 `skill` 工具使用。`resourceBase` 告知工具如何为本地、URL 或提供方管理的 skill 渲染相对资源引导。
+
+```ts type-equiv
+/** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */
+type SkillResourceBase =
+  | { readonly kind: 'directory'; readonly path: string }
+  | { readonly kind: 'url'; readonly url: string }
+  | { readonly kind: 'opaque'; readonly description: string }
+```
+
+```ts type-equiv
+/** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */
+interface SkillDefinition extends SkillSummary {
+  /** Markdown instruction body after any provider-specific metadata removal. */
+  readonly content: string
+  /** Absolute file path when the skill came from disk. */
+  readonly path?: string
+  /** Parsed optional metadata object from frontmatter. */
+  readonly metadata?: Readonly<Record<string, unknown>>
+}
+```
+
+运行时 skill 使用相同的完整形状，参与相同的先到先得收集顺序。返回的 disposer 移除该贡献并使发现缓存失效。
+
+```ts type-equiv
+/** Runtime skill contribution accepted by `ctx.skills.register()`. */
+type SkillRegistration = Omit<SkillDefinition, 'provider'> & { readonly provider?: string }
+```
+
+## 查找与配置
+
+skill 查找对 cwd 敏感，因为提供方可能暴露工作区本地的 skill；可选的 signal 为调用方取消提供方的工作。提供方接收与缓存标识和加载相同的只读选项对象。取消在目录选择前后（包括缓存命中时）都会检查，并与发现和完整定义加载竞争。如果找不到 git root，本地提供方将所提供的 cwd 本身视为项目根目录。
+
+```ts type-equiv
+/** Caller context used for cwd-sensitive and abortable provider work. */
+interface SkillLookupOptions {
+  /** Workspace selector for the current lookup. */
+  readonly cwd?: string | undefined
+  /** Abort discovery or loading work for the current caller. */
+  readonly signal?: AbortSignal | undefined
+}
+```
+
+注册表只拥有其发现缓存上限。本地提供方拥有文件系统根目录（`dshHome`、`agentsHome` 与 `customSkillDirs`）。消费方拥有其目录描述上限。
+
+```ts type-equiv
+/** Skill registry configuration. */
+interface Config {
+  /** Maximum number of completed cwd/provider catalogs kept in memory. */
+  readonly collectCacheMaxEntries?: number
+}
+```
+
+## 会话目录与工具契约
+
+`dsh-tool-skill` 通过 `agent/session-prefix` 贡献一条 user-role `<system-reminder>`。目录只包含已排序的 skill `name` 和规范化、经 XML 转义的 `description`；不包含正文、路径、来源、提供方或路由提示。Prefix 发现通过 `SkillLookupOptions` 转发调用方的 abort signal。`catalogDescriptionMaxLength` 是消费方用于 description 上限的配置，默认值为 `500`，整数最小值为 `3`。其仅用于请求、记录在 header 中的生命周期由 [session-prefix Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-07-session-prefix.md)定义。
+
+面向模型的 `skill({ name })` 工具校验 kebab-case 名称，为调用方 agent 的 cwd 加载完整定义，将未解析的 skill 报告为 unknown 或 no longer available，拒绝 `disableModelInvocation` 的 skill，并返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 仅按需解析显式引用的脚本、参考资料和资产；加载结果不枚举 skill 目录。工具结果是模型获取完整指令的可见路径。
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml
new file mode 100644
index 0000000000..d8d6a493d7
--- /dev/null
+++ b/docs/core-data-structures/subagent.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
+subagent.md: 0335a3f0780ae17b57ae730f5a49a269261c8073
+subagent.zh.md: dac48b624f6e0cfc28737e3e1a2774ba2d97e85b
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index 1fe311fd52..0335a3f078 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -1,5 +1,7 @@
 # Subagent
 
+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`); the model-facing consumer is [dsh-tool-subagent](../../packages/subagent/tool-subagent). The proposal and rationale: [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md).
@@ -66,11 +68,11 @@ interface SubagentStartRequest {
   /** Per-child agent options (model and plugin-defined extension fields). */
   readonly agentOptions?: AgentOptions
   /**
-   * Object-rooted JSON Schema within `assertSupportedOutputSchema`'s enforced subset. Start rejects
+   * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
    * unsupported schemas or providers without the capability. Data must be plain host-realm JSON;
    * a successful child returns the matching value as {@link SubagentResult.structured}.
    */
-  readonly outputSchema?: StructuredOutputSchema
+  readonly outputSchema?: ObjectJsonSchema
   /**
    * Optional absolute delegation-depth cap for the child being started: its
    * computed depth must be less than or equal to this non-negative safe
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md
new file mode 100644
index 0000000000..dac48b624f
--- /dev/null
+++ b/docs/core-data-structures/subagent.zh.md
@@ -0,0 +1,248 @@
+# Subagent
+
+[English](subagent.md) | 中文
+
+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`；面向模型的消费方是 [dsh-tool-subagent](../../packages/subagent/tool-subagent)。提案与设计理由见 [subagent Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)。
+
+源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)
+
+## 两类能力，两种发现方式
+
+提供方通过一个静态描述符公布其**启动时**特性，服务在 run 存在之前即行检查；如果请求依赖提供方不具备的特性，会被大声拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。**运行时**特性（steering（中途引导）、恢复）则是 [`SubagentRun`](#a-live-run-subagentrun) 上的可选方法——方法的存在即为能力，TypeScript 的类型收窄即为发现机制。
+
+```ts type-equiv
+/**
+ * Which START-TIME features a provider supports. Checked by the service before delegating to
+ * {@link SubagentProvider.start}: a request that needs a capability the chosen provider lacks
+ * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent
+ * degradation" rule). These static flags cover features needed before a run exists; runtime
+ * capabilities such as steering and resume are optional {@link SubagentRun} methods whose presence
+ * is the capability.
+ */
+interface SubagentCapabilities {
+  /** Honor {@link SubagentStartRequest.outputSchema} (structured final output). */
+  readonly outputSchema: boolean
+  /** Enforce {@link SubagentStartRequest.maxDepth} (recursion cap). */
+  readonly depthLimit: boolean
+  /** Enforce {@link SubagentStartRequest.toolFilter} (child tool scoping). */
+  readonly toolFilter: boolean
+  /** Honor {@link SubagentStartRequest.persona} (a per-child persona). */
+  readonly persona: boolean
+}
+```
+
+## 启动请求
+
+工具层根据模型输入和自身配置构建此请求；服务在 `start` 之前针对指定提供方进行校验。必填的 `parent` 提供会话 cwd、谱系与委派深度。可选的 output schema、depth、工具过滤器和 persona 需要对应的能力 flag 匹配。不支持的 schema 在启动时即失败；进程内后端将 filter 和 persona 的作用域限定在子 agent 创建阶段，并通过强制 capture 工具实现所支持的 object-rooted schema。
+
+```ts type-equiv
+/**
+ * What a caller asks for when starting a subagent. The tool layer builds this
+ * from the model's `{ description, prompt }` plus its own config; the service
+ * validates {@link SubagentCapabilities} against the named provider, then
+ * passes it to {@link SubagentProvider.start}.
+ */
+interface SubagentStartRequest {
+  /** The task/prompt for the child agent (a user message in the child session). */
+  readonly prompt: ContentBlock[]
+  /**
+   * The spawning ("parent") agent — the one whose tool call started this
+   * subagent. REQUIRED: in-process backends read `parent.session.header` for
+   * the working directory, the `parentSession` lineage to stamp on the child,
+   * and the parent's delegation depth. The out-of-process backend (ACP) reads
+   * exactly one field — the session header's cwd, the child's workspace when
+   * no deployment `cwd` override is configured; nothing else crosses the
+   * process boundary.
+   */
+  readonly parent: Agent
+  /**
+   * Cancellation signal from the spawning context (the tool's `exec.signal`).
+   * This is the canonical cancellation channel both before and after startup:
+   * a provider rejects `start()` after cleaning partial resources when it
+   * fires before publication, and cancels a published child when it fires
+   * afterward.
+   */
+  readonly signal: AbortSignal
+  /** Per-child agent options (model and plugin-defined extension fields). */
+  readonly agentOptions?: AgentOptions
+  /**
+   * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
+   * unsupported schemas or providers without the capability. Data must be plain host-realm JSON;
+   * a successful child returns the matching value as {@link SubagentResult.structured}.
+   */
+  readonly outputSchema?: ObjectJsonSchema
+  /**
+   * Optional absolute delegation-depth cap for the child being started: its
+   * computed depth must be less than or equal to this non-negative safe
+   * integer. Requires {@link SubagentCapabilities.depthLimit}; rejected at
+   * start otherwise.
+   */
+  readonly maxDepth?: number
+  /**
+   * Optional child tool scoping. Requires {@link SubagentCapabilities.toolFilter};
+   * rejected at start otherwise. In-process backends apply it as a scoped
+   * `tools.restrict()` in the child's creation window: the named tools vanish
+   * from the child's prompt AND refuse to execute (one visibility), with loud
+   * unknown-name validation.
+   */
+  readonly toolFilter?: ToolRestriction
+  /**
+   * Optional per-child persona. Requires {@link SubagentCapabilities.persona};
+   * rejected at start otherwise. In-process backends register it as a scoped
+   * `deployment:persona` section on the child, SHADOWING the deployment's
+   * persona for this child alone — same template semantics as the deployment
+   * persona (strict `{{…}}` interpolation against the registered variables).
+   */
+  readonly persona?: string
+}
+```
+
+`signal` 是就绪前后唯一的取消通道。[subagent 组合控制 Agent Note](../../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)规定 persona、live 全局工具过滤、绝对深度以及「可见性而非权限」的设计理由。
+
+## 终态结果：`SubagentResult`
+
+一次 run 的最终产出，由 `SubagentRun.result` resolve。`structured` 仅在请求了 `outputSchema` 且成功满足时才存在；请求 schema 不保证一定能得到它，当子 agent 失败或结束时未产出有效 capture 时，提供方可能返回 `stopReason: 'error'`。非 `completed` 的 `stopReason` 意味着 `output` 可能不完整——消费方将其映射为 `isError` 的工具结果，而非将部分输出报告为成功。
+
+```ts type-equiv
+/**
+ * The terminal outcome of a subagent run, resolved by {@link SubagentRun.result}.
+ */
+interface SubagentResult {
+  /** The child's final assistant output (the last assistant message's content). */
+  readonly output: ContentBlock[]
+  /**
+   * The structured result after a requested `outputSchema` was successfully
+   * satisfied. Requesting a schema does not guarantee presence: a provider can
+   * end with `stopReason: 'error'` when the child fails or finishes without a
+   * valid capture. Shape is validated against the request schema by the
+   * provider; `unknown` here because the seam is schema-agnostic.
+   */
+  readonly structured?: unknown
+  /** Why the run ended. A non-`completed` reason means `output` may be partial. */
+  readonly stopReason: SubagentStopReason
+}
+```
+
+`SubagentStopReason` 是一个[可合并扩展的派生联合类型](core.md#the-map--derived-union-pattern)——后端可以添加变体，因此消费方应对已知 case 分支处理，将未知的终态原因视为失败：
+
+```ts type-equiv
+/**
+ * Why a subagent run ended. Merge-extensible (a backend may add variants);
+ * consumers branch on the known cases and fall through `default`. The known
+ * cases mirror the harness turn-end vocabulary so the tool layer can map a
+ * non-`completed` result to an `isError` tool result.
+ */
+interface SubagentStopReasonMap {
+  /** The child finished its turn normally. */
+  completed: 'completed'
+  /** The run was cancelled by its request signal or by disposal. */
+  aborted: 'aborted'
+  /** The child failed (model error, transport error). */
+  error: 'error'
+  /** The child hit its token ceiling before finishing. */
+  'max-tokens': 'max-tokens'
+  /** The child declined the task. */
+  refusal: 'refusal'
+}
+```
+
+<a id="a-live-run-subagentrun"></a>
+
+## 活跃 run：`SubagentRun`
+
+`SubagentRun` 是消费方持有的、指向一个就绪子 agent 的句柄。消费方 await `result` 并始终 dispose（资源释放）该 run，直至其完全停稳。子 agent 失败时以非 completed 的 stop reason resolve；只有不可表示的基础设施故障才会 reject。可选的 `sendMessage` 和 `resume` 方法通过自身的存在来公布运行时能力。
+
+```ts type-equiv
+/**
+ * Child handle returned only after readiness. Consumers await {@link result} and must always
+ * {@link dispose} to cancel remaining work and reach quiescence. Optional methods are runtime
+ * capability discovery; narrow their presence before calling.
+ */
+interface SubagentRun {
+  /**
+   * Parent-scoped run id. For a local run, this MUST equal the published child
+   * session id, whose `parentSession` records `request.parent.session.id`; a
+   * remote provider mints an id unique in the parent namespace.
+   */
+  readonly id: SessionId
+  /**
+   * The exact published in-process child, or `undefined` for a remote run.
+   * When present, its id is {@link id}; the provider retains no ownership
+   * implication beyond the run's ordinary {@link dispose} contract.
+   */
+  readonly localAgent: Agent | undefined
+  /**
+   * Resolves with the child's terminal {@link SubagentResult} when the run
+   * settles. Does NOT reject on a child-level failure — a model/transport
+   * failure resolves with `stopReason: 'error'` so the consumer maps it to an
+   * `isError` tool result. Rejects only on an infrastructure fault the seam
+   * cannot represent as a stop reason.
+   */
+  readonly result: Promise<SubagentResult>
+  /**
+   * Cancel remaining work, reach child quiescence, and release the run's
+   * resources (in-process: dispose the owned agent and remove its session;
+   * ACP: kill and reap the subprocess). Idempotent.
+   */
+  dispose(): Promise<void>
+  /**
+   * OPTIONAL (steering capability): send additional content to the running
+   * child between steps. Present only on providers that support live steering.
+   */
+  sendMessage?(content: ContentBlock[]): void
+  /**
+   * OPTIONAL (resume capability): send a follow-up task to a settled child,
+   * continuing its session, and return a fresh run for the continuation.
+   */
+  resume?(content: ContentBlock[]): Promise<SubagentRun>
+}
+```
+
+本地 run 必须在 `start()` fulfill 前发布一个普通子 agent/会话，将该子会话 id 作为 `SubagentRun.id` 返回，以 `localAgent` 暴露确切子 agent，并在子 agent 的 `parentSession` header 中记录 `request.parent.session.id`。运行时所有权可以把子 agent 放在 parent、提供方或 root 作用域下。远程提供方则返回 parent 作用域的生命周期 id 与 `localAgent: undefined`。
+
+## 提供方 seam：`SubagentProvider`
+
+每个提供方是一个具名的子 agent 传输层，多个提供方可以共存。服务在 `start()` 之前校验请求的启动时能力。`inheritsParentContext` 仅描述对话种子注入（`fork`：true；`spawn` 和 `acp`：false），使消费方能生成准确的面向模型的措辞，而不暗示继承了工具、服务或权限。
+
+```ts type-equiv
+/**
+ * A subagent backend: one transport for running a child agent (in-process
+ * spawn/fork, ACP to another process, …). Implementations register under a
+ * unique name via {@link SubagentService.registerProvider}; multiple providers
+ * coexist in one context (unlike the single-implementation bash seam). The
+ * Providers are trusted same-process implementations; callers treat their
+ * descriptors and returned values as borrowed immutable data.
+ */
+interface SubagentProvider {
+  /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */
+  readonly name: string
+  /** The start-time features this provider supports (see {@link SubagentCapabilities}). */
+  readonly capabilities: SubagentCapabilities
+  /**
+   * Whether the child sees the parent's completed-turn prefix. This is descriptive, not a
+   * service-validated start capability: the model-facing tool derives truthful wording from it.
+   * It says nothing about tool registration, injected services, or authority inheritance.
+   */
+  readonly inheritsParentContext: boolean
+  /**
+   * Establish a child and return its handle only after publication. The
+   * service has already validated that every requested start-time capability
+   * is supported, so an implementation may assume e.g. `request.maxDepth` is
+   * honorable when present. If setup fails or `request.signal` aborts before
+   * fulfillment, the provider owns and cleans all partial resources before this
+   * promise rejects. Ownership transfers to the caller only on fulfillment.
+   */
+  start(request: SubagentStartRequest): Promise<SubagentRun>
+}
+```
+
+`start()` 仅在 run 就绪时 fulfill。服务铸造唯一 `runId`，从提供方的确切 `localAgent` 快照 `local`，观察结果，emit `subagent/start`，并返回同一个 run；rejection 意味着提供方已清理，且不会 emit 生命周期事件对。配对的 `subagent/end` 携带相同标识与最终输出或基础设施失败。两个事件都仅用于观察，每个 listener 异常都会被独立隔离。
+
+## 进程内后端：深度与种子
+
+spawn 和 fork 后端通过 `parent.ctx` 创建一个普通 agent，将取消信号传入核心创建流程，并通过 `AgentHandle` 进行 dispose。移除提供方会阻止新的 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 })` 传递，与 `resume` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/support/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
diff --git a/docs/core-data-structures/system-prompt.i18n.yaml b/docs/core-data-structures/system-prompt.i18n.yaml
new file mode 100644
index 0000000000..e697ec6bcd
--- /dev/null
+++ b/docs/core-data-structures/system-prompt.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
+system-prompt.md: 63a750c74300b4353f132d3dae9da52a10631f23
+system-prompt.zh.md: 3f7ab9aee5743616f00e95e81fb9a3a4af2c6e8a
diff --git a/docs/core-data-structures/system-prompt.md b/docs/core-data-structures/system-prompt.md
index 85a974e6df..63a750c743 100644
--- a/docs/core-data-structures/system-prompt.md
+++ b/docs/core-data-structures/system-prompt.md
@@ -1,5 +1,7 @@
 # System Prompt Assembly
 
+English | [中文](system-prompt.zh.md)
+
 The [system-prompt package](../../packages/core/system-prompt) owns the data exchanged between prompt contributors and one assembly call. The package [README](../../packages/core/system-prompt/README.md) documents registration, ordering, scoping, and rendering behavior; this page pins the literal cross-package shapes that plugins implement or pass.
 
 Source: [`packages/core/system-prompt/src/index.ts`](../../packages/core/system-prompt/src/index.ts).
diff --git a/docs/core-data-structures/system-prompt.zh.md b/docs/core-data-structures/system-prompt.zh.md
new file mode 100644
index 0000000000..3f7ab9aee5
--- /dev/null
+++ b/docs/core-data-structures/system-prompt.zh.md
@@ -0,0 +1,62 @@
+# 系统提示词组装
+
+[English](system-prompt.md) | 中文
+
+[system-prompt 包（package）](../../packages/core/system-prompt)负责管理提示词贡献者与一次组装调用之间交换的数据。该包的 [README](../../packages/core/system-prompt/README.md) 记录了注册、排序、作用域与渲染行为；本页固定各插件实现或传递的跨包字面形状。
+
+源码：[`packages/core/system-prompt/src/index.ts`](../../packages/core/system-prompt/src/index.ts)。
+
+## 组装上下文
+
+`AssembleContext` 标识一次组装所解析的作用域 layer，并可携带该请求的显式控制 signal。它可合并扩展：`dsh-agent` 添加可选的 live `agent` 字段，`assembleContextFor(agent, signal)` 则一起设置这些显式字段。裸组装既没有 scope，也没有 signal。
+
+```ts type-equiv
+/** Merge-extensible context for one prompt assembly. */
+interface AssembleContext {
+  /**
+   * Scope whose providers and waterfall listeners participate. When absent,
+   * only global providers and subject-less listeners participate.
+   */
+  scope?: ScopeKey
+  /** Explicit control signal for the turn that requested this assembly, when any. */
+  signal?: AbortSignal
+}
+```
+
+## 工具提供方结果
+
+`ToolProviderResult.schemas` 是当前组装中对模型可见的工具集合。`knownNames` 是提供方在限制前的名称全集，用于区分「配置名拼写错误」与「已知工具在此作用域中被有意隐藏」。
+
+```ts type-equiv
+/** Tool schemas visible in one assembly and their pre-restriction name set. */
+interface ToolProviderResult {
+  /** The schemas this provider contributes to THIS assembly. */
+  readonly schemas: readonly ToolSchema[]
+  /** The pre-restriction name universe for config validation (defaults to `schemas`' names). */
+  readonly knownNames?: readonly string[]
+}
+```
+
+## 提示词段落
+
+`PromptSection` 是一份只读的同进程注册契约。其文本可以是静态的，也可以从当前组装上下文动态解析。
+
+```ts type-equiv
+/** One contributed section of the system prompt (registry input). */
+interface PromptSection {
+  /** Unique name — a duplicate registration throws (see {@link SystemPrompt.section}). */
+  readonly name: string
+  /**
+   * Sections are concatenated in ascending order. Convention: `-100` is the
+   * harness identity, `0` the deployment persona, tool guidance uses 100–199;
+   * other negative orders also render before the persona.
+   */
+  readonly order: number
+  /**
+   * Static text or a provider evaluated at each assembly with that assembly's
+   * {@link AssembleContext}. The text may reference `{{variable}}`s — they are
+   * interpolated later, by {@link renderPrompt}.
+   */
+  readonly text: string | ((context: AssembleContext) => string)
+}
+```
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 491f380166..2c7555b84d 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -34,6 +34,11 @@ interface TaskStart {
   kind: TaskKind
   /** One-line model-facing label (the command; the delegation description). */
   label: string
+  /**
+   * Optional UTF-8 byte cap for each complete model-facing completion notice or
+   * output read, including control-surface status metadata.
+   */
+  outputLimitBytes?: number
   /**
    * Owning live agent. Access is fenced by its session id, and agent disposal
    * cancels and awaits the task. The instance must be the one currently
@@ -104,6 +109,8 @@ interface TaskSnapshot {
   kind: TaskKind
   /** The producer-supplied one-line label. */
   label: string
+  /** Producer-owned cap for complete model-facing notices and output reads. */
+  outputLimitBytes?: number
   /**
    * Owner session id used for authorization and correlation; absent for
    * unowned tasks. Completion listeners receive the exact {@link Agent}
diff --git a/docs/core-data-structures/tools.i18n.yaml b/docs/core-data-structures/tools.i18n.yaml
new file mode 100644
index 0000000000..d22f80c910
--- /dev/null
+++ b/docs/core-data-structures/tools.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+tools.md: 43d91e72d83dce0bec99417ca90f9394f4c2169e
+tools.zh.md: b92f6d3d99fda7dc28d10556adcceee3946a9571
diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md
index a4f523fe61..43d91e72d8 100644
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -1,26 +1,55 @@
 # Tools
 
+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.
 
 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)
 
 ## `ToolDefinition` — a registered tool
 
-A `ToolSchema` (the model-facing fields) plus the `execute` function, host-only scheduler metadata, and optional UI presenters. The registry holds these; the loop dispatches calls through them. The registry's `schemas()` builds the model-facing `ToolSchema[]` by an explicit allowlist — `execute`/`timeoutMs`/`isConcurrencySafe`/`presentCall`/`presentResult` must never leak into a model request.
+A `ToolSchema` (the model-facing fields) plus a mandatory canonical output declaration, the `execute` function, host-only scheduler metadata, an optional final-content callback, and optional UI presenters. The registry holds these; the loop dispatches calls through them. The registry's `schemas()` builds the model-facing `ToolSchema[]` by an explicit allowlist — `output`/`execute`/`finalizeContent`/`timeoutMs`/`isConcurrencySafe`/`presentCall`/`presentResult` must never leak into a model request.
+
+```ts type-equiv
+/** Tool-owned canonical output contract used after the body returns a JSON value. */
+interface ToolOutputDefinition {
+  /** Raw supported JSON Schema enforced against every successful canonical value. */
+  readonly schema: JsonSchemaNode
+  /** Pure projection from validated arguments and value to Native/model content. */
+  render(args: unknown, value: JsonValue): ContentBlock[]
+  /** Pure replayable presentation projection, computed only for surface calls. */
+  presentationMeta?(args: unknown, value: JsonValue): JsonValue
+}
+```
 
 ```ts type-equiv
 /** A registered tool: its schema plus the execution function. */
 interface ToolDefinition extends ToolSchema {
+  /** Mandatory canonical output declaration. */
+  readonly output: ToolOutputDefinition
   /**
-   * Run one accepted call. Async work must observe or forward `exec.signal` and
-   * settle only after its owned work reaches quiescence. The registry preserves
-   * caller cancellation through around-dispatch signal replacement and does
-   * not abandon this promise, but it cannot hard-kill same-process code.
+   * Run one accepted call and return only its canonical lossless-JSON value.
+   * Async work must observe or forward `exec.signal` and settle only after its
+   * owned work reaches quiescence. The registry preserves caller cancellation
+   * through around-dispatch signal replacement and does not abandon this
+   * promise, but it cannot hard-kill same-process code.
    * @param args - losslessly snapshotted, frozen model arguments.
    * @param exec - execution identity, cancellation signal, and context deferral.
-   * @returns model-facing content plus optional private presentation metadata.
+   * @returns the canonical value declared by `output.schema`.
    */
-  execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>
+  execute(args: unknown, exec: ToolRunContext): Promise<unknown>
+  /**
+   * Synchronous last-mile transform for model-facing content. The registry
+   * snapshots this callback when execution starts and invokes it exactly once
+   * for every normalized outcome, including pipeline failures that bypass
+   * `tools/post-execute`, immediately before lossless materialization.
+   * Returning `undefined` preserves the content; every other result field
+   * remains registry-owned. The callback must be total and must not throw.
+   * @param exec - immutable execution identity and arguments.
+   * @param result - complete normalized outcome before materialization.
+   * @returns replacement content, or `undefined` to preserve it.
+   */
+  finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
   /**
    * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
    * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it
@@ -55,7 +84,7 @@ interface ToolDefinition extends ToolSchema {
   presentCall?(args: unknown): ToolCallView | undefined
   /**
    * Optional: how to present the COMPLETED state, given the same `args` and the
-   * `result` (`execute`'s content + whether it errored). Returns a
+   * durable result projection (`content`, failure state, and optional `meta`). Returns a
    * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
    * pending title and render the raw result content. Pure and side-effect-free
    * for the same replay reason.
@@ -64,69 +93,62 @@ interface ToolDefinition extends ToolSchema {
 }
 ```
 
-`execute` receives `args: unknown` — a raw `ToolDefinition` validates its own input. First-party tools don't write that by hand; they use `defineTool`, which validates and narrows for them.
+`execute` receives `args: unknown` — a raw `ToolDefinition` validates its own input. First-party tools don't write that by hand; they use `defineTool`, which validates and narrows the arguments, infers the body return from `output.schema`, and types both output projectors. `finalizeContent` deliberately receives the immutable execution instead of typed arguments because invalid-input and outer pipeline failures reach it too; it may enforce a tool-owned content bound while preserving `isError`, canonical value, structured error identity, deferred contexts, and presentation metadata.
 
-## The typed schema DSL
+## The unified JSON-value schema DSL
 
-Plugin authors write per-property specs with a boolean `required: true`, and a type-level helper maps the spec to the `execute` argument type — zero casts. The DSL is *machinery that types* `ToolDefinition`; it is intentionally a sub-page detail, not core.
+Plugin authors use one vocabulary for typed parameters and typed output values. `ValueSchemaSpec` supports `string`, `number`, `integer`, `boolean`, `null`, `array`, `object`, author-only `json`, and exact-one `oneOf`; scalar `enum` and `const` values must match their node type. An explicit object node always declares `additionalProperties: true | false`. Parameter definitions remain an implicit open object property map, with `required: true` attached to each required property.
 
 Source: [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts)
 
 ```ts type-equiv
-/** One schema-spec property entry. */
-interface SchemaProp {
-  type: SchemaType
-  /** Per-property required flag (NOT the JSON Schema top-level required array). */
-  required?: true
-  /** Human-readable description, surfaced in the JSON Schema as well. */
-  description?: string
-  /** Enum of allowed values (strings only). */
-  enum?: string[]
-  /**
-   * Model-visible JSON Schema default annotation. Validation does not apply it;
-   * dynamic tool mounts may supply it even though first-party definitions do not.
-   */
-  default?: unknown
-  /** Nested properties for type: 'object'. */
-  properties?: SchemaSpec
-  /** Items schema for type: 'array'. */
-  items?: SchemaProp
+/** One author-facing schema for any lossless JSON value root. */
+type ValueSchemaSpec =
+  | StringValueSchemaSpec
+  | NumberValueSchemaSpec
+  | IntegerValueSchemaSpec
+  | BooleanValueSchemaSpec
+  | NullValueSchemaSpec
+  | ArrayValueSchemaSpec
+  | ObjectValueSchemaSpec
+  | JsonValueSchemaSpec
+  | OneOfValueSchemaSpec
+```
+
+```ts type-equiv
+/** One implicit parameter-root property, optionally required. */
+type ParameterPropertySpec = ValueSchemaSpec & { required?: true }
+```
+
+```ts type-equiv
+/**
+ * Tool parameter schema. The map itself is an implicit open object root;
+ * requiredness remains a per-property `required: true` annotation.
+ */
+type ParameterSchemaSpec = {
+  [key: string]: ParameterPropertySpec
+  [key: symbol]: never
 }
 ```
 
-```ts type-equiv
-/**
- * The author-facing parameter schema: a shallow map of property name to
- * {@link SchemaProp}. Required-ness is a per-property boolean (`required:
- * true`), not a separate array.
- */
-type SchemaSpec = Record<string, SchemaProp>
-```
-
-`SchemaType` is the primitive union `'string' | 'number' | 'boolean' | 'object' | 'array'`. `InferArgs<S>` maps a `SchemaSpec` to the TS argument type — `required: true` props become required keys, everything else genuinely optional:
+`{ type: 'json' }` infers `JsonValue` and compiles to an annotation-only unconstrained raw schema. Output roots can be objects, arrays, scalars, or null. `InferValue<S>` honors literal constraints and object openness through 16 container levels, then falls back to `JsonValue` instead of exhausting TypeScript's type-instantiation stack. `InferArgs<P>` turns per-property requiredness into required and optional string keys:
 
 ```ts type-equiv
 /**
- * Infer the TS argument type for a complete {@link SchemaSpec}.
- *
- * Properties marked `required: true` are required keys; all others are
- * genuinely optional keys (`?`), so callers may omit them entirely.
- *
- * Example:
- * ```ts
- * type Args = InferArgs<{ path: { type: 'string'; required: true }; limit: { type: 'number' } }>
- * // → { path: string; limit?: number }
- * ```
+ * Infer the TypeScript value accepted by an author-facing value schema. Exact
+ * inference is bounded to 16 container levels, then falls back to `JsonValue`.
  */
-type InferArgs<S extends SchemaSpec> = Simplify<
-  & { [K in RequiredKeys<S>]: InferPropValue<S[K]> }
-  & { [K in Exclude<keyof S, RequiredKeys<S>>]?: InferPropValue<S[K]> }
->
+type InferValue<S> = InferValueAt<S, []>
 ```
 
-`defineTool({ name, description, parameters, execute, … })` ties it together: `parameters` is a `SchemaSpec`, `execute(args, exec)` gets `args: InferArgs<typeof parameters>`, and the helper converts the spec to JSON Schema (`schemaSpecToJsonSchema`) for the wire and validates model-generated args (`validateArgs`) before the typed body runs. A mismatch throws `ToolArgsError` (`code: 'INVALID_ARGS'`), which the registry turns into an `isError` result so the model can self-correct. Why a custom DSL and not schemastery: tool parameters need JSON Schema (the LLM wire format), not validation/transformation — the lightweight DSL gives the best authoring DX with the smallest surface.
+```ts type-equiv
+/** Infer the TypeScript argument object for an implicit parameter schema. */
+type InferArgs<S> = InferProperties<S, []>
+```
 
-Registration is a trusted same-process contract. The registry borrows the typed definition as readonly input and validates only semantic requirements such as a positive finite `timeoutMs`; `schemas()` materializes the explicit model-facing projection at the model boundary so execution and presentation share one resolved definition without leaking callbacks onto the wire.
+`defineTool({ name, description, parameters, output, execute, … })` ties parameter inference to `parameterSchemaSpecToJsonSchema()` and `validateArgs()`, and ties `execute`/`render`/`presentationMeta` to `InferValue<OutputSchema>`. Schema records contain only own enumerable string keys, and schema arrays are dense intrinsic arrays, so inference, compilation, and validation observe the same declaration. Inference stays exact through 16 container levels and then widens to `JsonValue`; runtime validation keeps walking the complete schema. `valueSchemaSpecToJsonSchema()` compiles output declarations through the same enforced raw subset. A parameter mismatch throws `ToolArgsError` (`INVALID_ARGS`); an invalid body or post-policy value throws `ToolOutputError` (`INVALID_TOOL_OUTPUT`). Both use the normal tool-error path. Raw JSON Schema remains open by default; unsupported keywords reject instead of being accepted without enforcement.
+
+Registration is a trusted same-process contract. The registry borrows the typed definition as readonly input, requires `output`, validates its raw schema, and checks semantic requirements such as a positive finite `timeoutMs`; `schemas()` materializes the explicit model-facing projection at the model boundary so execution and presentation share one resolved definition without leaking callbacks onto the wire.
 
 ## `ToolRestriction` — one scope's live global filter
 
@@ -147,7 +169,7 @@ interface ToolRestriction {
 
 ## Execution: extensible waterfalls plus monotonic policy
 
-`ctx.tools.execute()` accepts a caller-owned `ToolExecutionInput` with a required readonly `signal`, materializes its parsed JSON arguments once into a pipeline-owned `ToolExecution`, and runs that call through `tools/pre-execute` (the reorderable allow/deny/ask waterfall) → registered monotonic guards → `tools/execute` (around-dispatch wrappers) → `tools/post-execute` (inspect/replace the result) → `tools/result` (the immutable authoritative outcome). Only the `tools/execute` view may replace the required signal. The outcome is a `ToolExecutionResult`.
+`ctx.tools.execute()` accepts a caller-owned `ToolExecutionInput` with a required readonly `signal`, materializes its parsed JSON arguments once into a pipeline-owned `ToolExecution`, and runs that call through `tools/pre-execute` (the reorderable allow/deny/ask waterfall) → registered monotonic guards → `tools/execute` (around-dispatch wrappers) → `tools/post-execute` (inspect/replace the result) → optional definition-owned `finalizeContent` → `tools/result` (the immutable authoritative outcome). Only the `tools/execute` view may replace the required signal. The outcome is a `ToolExecutionResult`.
 
 ```ts type-equiv
 /** Opaque call identity that permits correlation without exposing mutable execution state. */
@@ -252,34 +274,50 @@ type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined
 ```
 
 ```ts type-equiv
-/** The outcome of one tool call. */
-interface ToolExecutionResult {
-  content: ContentBlock[]
-  isError: boolean
-  /**
-   * Set when the call failed with a {@link HarnessError}: machine-routable
-   * `{ name, code }` for retry/sandbox plugins and replay. The model-facing
-   * text in `content` is always present; this is extra structure for code.
-   */
-  error?: ToolErrorInfo
-  /**
-   * Model-facing context for the next request, separate from this tool result. The loop
-   * accepts it into the active-batch FIFO, then appends after recorded results even if interrupted.
-   */
-  additionalContexts?: HookContext[]
-  /**
-   * The tool-private presentation payload from a successful `execute` (the object
-   * return form). Threaded onto the `tool/result` session event and back into
-   * {@link ToolResult} for `presentResult`. Opaque (`unknown`); absent when the
-   * tool attached none or the call failed.
-   */
-  meta?: unknown
+/** Canonical failure detail; internal routing information remains optional. */
+interface ToolFailure {
+  /** Human-readable failure message without the Native `Error: ` envelope. */
+  message: string
+  /** Internal error class/code used by policy and durable diagnostics. */
+  info?: ToolErrorInfo
 }
 ```
 
-The result carries only the outcome. Call identity remains on the immutable `ToolExecution` that accompanies it through every hook and on the durable `tool/call` / `tool/result` session events, so wrappers cannot create a second, disagreeing identity.
+```ts type-equiv
+/** Successful canonical tool execution, including its Native/model projection. */
+interface ToolExecutionSuccess {
+  readonly isError: false
+  /** Execution-local canonical value; deliberately omitted from durable events. */
+  readonly value: JsonValue
+  readonly content: ContentBlock[]
+  readonly error?: never
+  readonly meta?: JsonValue
+  readonly additionalContexts?: HookContext[]
+}
+```
 
-The registry materializes and freezes the final accepted result immediately before `tools/result`. Its content, structured error, additional context, and presentation metadata must round-trip losslessly through JSON; an invalid outcome becomes a JSON-safe `isError` result, so the observed live outcome is safe for the later durable `tool/result` append.
+```ts type-equiv
+/** Failed canonical tool execution; failures never carry a successful value. */
+interface ToolExecutionFailure {
+  readonly isError: true
+  readonly error: ToolFailure
+  readonly value?: never
+  readonly content: ContentBlock[]
+  readonly meta?: JsonValue
+  readonly additionalContexts?: HookContext[]
+}
+```
+
+```ts type-equiv
+/** The discriminated, execution-local outcome of one tool call. */
+type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure
+```
+
+The result carries only the outcome. Call identity remains on the immutable `ToolExecution` that accompanies it through every hook and on the durable `tool/call` / `tool/result` session events, so wrappers cannot create a second, disagreeing identity. The canonical `value` is execution-local: the loop persists only `content`, `error`, and `meta`, while `tool/code-dispatch` stores a bounded summary. Replay reproduces presentation but cannot reconstruct intermediate values.
+
+On success the registry snapshots and validates the body value, freezes it, and invokes the pure renderer plus the optional direct-surface metadata projector. It separately materializes the durable presentation fields immediately before `tools/result`; an invalid value, renderer/projector failure, or non-JSON presentation becomes a JSON-safe `isError`. The final live observer therefore sees the exact execution-local value beside fields safe for the later durable append.
+
+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`:
 
@@ -298,67 +336,70 @@ type PreToolDecision =
 
 ```ts type-equiv
 /**
- * Post-dispatch decision: accept or replace content, attach context for the next
- * request, or block by turning corrective feedback into an error result.
+ * Post-dispatch decision: accept, replace one projection, attach context for the
+ * next request, or block by turning corrective feedback into an error result.
  */
 type PostToolDecision =
-  | { kind: 'accept'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
+  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: HookContext[] }
+  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: HookContext[] }
   | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: HookContext[] }
 ```
 
 Call `next()` for the default or return a decision to short-circuit. Pre-policy may deny or ask; only `allowed-once` proceeds, while a non-grant, missing approval channel or service, or agent-less request becomes a denial. Guards may still impose a final denial. Arguments cannot be rewritten because history, audit, UI, and execution must agree.
 
-Post-policy may replace content; a block becomes an `isError` result containing its corrective feedback. `tools/result` receives the frozen execution and result after normalization; observers cannot transform them, and observer failures are contained. Unknown and throwing tools both become structured errors (`ToolNotFoundError` maps to `UNKNOWN_TOOL`), so the call fails without ending the turn.
+Post-policy may replace either content or value, never both. Content replacement preserves the canonical value and existing metadata; value replacement is revalidated and recomputes content/metadata; a block removes the value and becomes an `isError` containing corrective feedback. Content replacement is presentation policy, not confidentiality policy: a listener that must hide the programmatic value blocks or replaces it. `tools/result` receives the frozen execution and result after normalization; observers cannot transform them, and observer failures are contained. Unknown and throwing tools both become structured errors (`ToolNotFoundError` maps to `UNKNOWN_TOOL`), so the call fails without ending the turn.
 
-## The structured-output schema subset
+## The enforced raw JSON Schema subset
 
-The vocabulary a caller uses to demand a machine-readable result from a subagent (`SubagentStartRequest.outputSchema`, [subagent.md](subagent.md#the-start-request)) or a workflow `agent()` call. It is deliberately NOT full JSON Schema: the schema travels verbatim to the model as a forced tool's `parameters`, and the produced value is validated client-side by `validateStructuredValue` — so every accepted keyword must be one the validator actually enforces, and `assertSupportedOutputSchema` rejects anything else loud (`OutputSchemaError`, listing every violation). Both walkers reason over own enumerable properties only (JSON carries nothing else) and reject non-plain objects (`Date`, `Map`) that would serialize lossily.
+Raw schemas from subagents, workflows, MCP, and dynamic registrations use the wire-level counterpart of the author DSL. `assertSupportedJsonSchema()` accepts any JSON root, `validateJsonSchemaValue()` enforces it, and `JsonSchemaError` reports every unsupported or malformed schema path. The empty annotation-only node means unconstrained lossless JSON. `oneOf` requires at least two branches and a value must match exactly one. Consumers that still require an object root call `assertObjectJsonSchema()` and carry `ObjectJsonSchema`; this is how subagent/workflow caller-defined structured output remains object-rooted without restricting the shared vocabulary.
 
 ```ts type-equiv
-/** The scalar values `enum`/`const` may carry (finite numbers only). */
-type StructuredScalar = string | number | boolean | null
+/** Scalar JSON values supported by `enum` and `const`. */
+type JsonSchemaScalar = string | number | boolean | null
 ```
 
 ```ts type-equiv
-/** The `type` keywords the subset accepts. */
-type StructuredSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+/** Single-type keywords accepted by the enforced subset. */
+type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
 ```
 
 ```ts type-equiv
 /**
- * One node of the structured-output schema subset. Recursive via `properties`
- * and `items`; see the module doc for the exact keyword semantics.
+ * One raw JSON Schema node in the enforced subset. The optional fields express
+ * the external wire shape; {@link assertSupportedJsonSchema} rejects invalid
+ * combinations before a caller treats the node as trusted.
  */
-interface StructuredSchemaNode {
-  type: StructuredSchemaType
+interface JsonSchemaNode {
+  /** Omit with no constraints for any JSON value, or use `oneOf`. */
+  type?: JsonSchemaType
+  /** Exactly one branch must validate; at least two branches are required. */
+  oneOf?: JsonSchemaNode[]
   /** Nested property schemas (`type: 'object'` only). */
-  properties?: Record<string, StructuredSchemaNode>
+  properties?: Record<string, JsonSchemaNode>
   /** Required property names; each must appear in `properties`. */
   required?: string[]
-  /** `false` rejects undeclared keys; absent/`true` allows them (JSON Schema default). */
+  /** `false` rejects undeclared keys; absent/`true` follows JSON Schema's open default. */
   additionalProperties?: boolean
-  /** Item schema (`type: 'array'` only); absent ⇒ any JSON items. */
-  items?: StructuredSchemaNode
-  /** Allowed values (scalar types only). */
-  enum?: StructuredScalar[]
-  /** The single allowed value (scalar types only). */
-  const?: StructuredScalar
+  /** Item schema (`type: 'array'` only); absent accepts any JSON item. */
+  items?: JsonSchemaNode
+  /** Allowed values for a scalar node. */
+  enum?: JsonSchemaScalar[]
+  /** The single allowed value for a scalar node. */
+  const?: JsonSchemaScalar
   /** Annotation, ignored for validation. */
   description?: string
   /** Annotation, ignored for validation. */
   title?: string
-  /** Annotation, ignored for validation (must still be JSON data). */
-  default?: unknown
-  /** Annotation, ignored for validation (must still be JSON data). */
-  examples?: unknown
+  /** Annotation, ignored for validation but required to be lossless JSON. */
+  default?: JsonValue
+  /** Annotation, ignored for validation but required to be lossless JSON. */
+  examples?: JsonValue
 }
 ```
 
-A schema is an object-rooted node (`enum`/`const` are scalar-only; `description`/`title`/`default`/`examples` are annotations, allowed and ignored but still required to be JSON data — they ride the wire):
-
 ```ts type-equiv
-/** A structured-output schema: an OBJECT-rooted {@link StructuredSchemaNode}. */
-type StructuredOutputSchema = StructuredSchemaNode & { type: 'object' }
+/** A consumer-constrained object-rooted schema. */
+type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 ```
 
 ## Tool-presentation UI vocabulary
diff --git a/docs/core-data-structures/tools.zh.md b/docs/core-data-structures/tools.zh.md
new file mode 100644
index 0000000000..b92f6d3d99
--- /dev/null
+++ b/docs/core-data-structures/tools.zh.md
@@ -0,0 +1,414 @@
+# 工具
+
+[English](tools.md) | 中文
+
+[dsh-tools](../../packages/core/tools) 的工具流水线。[core.md](core.md) 介绍了 `ToolDefinition`（唯一被提升到主干的流水线编写类型）和 `ToolSchema`（面向模型的协议格式（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)
+
+## `ToolDefinition` — 一个已注册的工具
+
+由一个 `ToolSchema`（面向模型的字段）、必需的规范输出声明、`execute` 函数、仅供宿主使用的调度器元数据、可选的最终内容回调和可选 UI 展示函数组成。注册表持有这些定义，循环通过它们分派调用。注册表的 `schemas()` 通过显式允许列表构建面向模型的 `ToolSchema[]`；`output`/`execute`/`finalizeContent`/`timeoutMs`/`isConcurrencySafe`/`presentCall`/`presentResult` 绝不能泄漏到模型请求中。
+
+```ts type-equiv
+/** Tool-owned canonical output contract used after the body returns a JSON value. */
+interface ToolOutputDefinition {
+  /** Raw supported JSON Schema enforced against every successful canonical value. */
+  readonly schema: JsonSchemaNode
+  /** Pure projection from validated arguments and value to Native/model content. */
+  render(args: unknown, value: JsonValue): ContentBlock[]
+  /** Pure replayable presentation projection, computed only for surface calls. */
+  presentationMeta?(args: unknown, value: JsonValue): JsonValue
+}
+```
+
+```ts type-equiv
+/** A registered tool: its schema plus the execution function. */
+interface ToolDefinition extends ToolSchema {
+  /** Mandatory canonical output declaration. */
+  readonly output: ToolOutputDefinition
+  /**
+   * Run one accepted call and return only its canonical lossless-JSON value.
+   * Async work must observe or forward `exec.signal` and settle only after its
+   * owned work reaches quiescence. The registry preserves caller cancellation
+   * through around-dispatch signal replacement and does not abandon this
+   * promise, but it cannot hard-kill same-process code.
+   * @param args - losslessly snapshotted, frozen model arguments.
+   * @param exec - execution identity, cancellation signal, and context deferral.
+   * @returns the canonical value declared by `output.schema`.
+   */
+  execute(args: unknown, exec: ToolRunContext): Promise<unknown>
+  /**
+   * Synchronous last-mile transform for model-facing content. The registry
+   * snapshots this callback when execution starts and invokes it exactly once
+   * for every normalized outcome, including pipeline failures that bypass
+   * `tools/post-execute`, immediately before lossless materialization.
+   * Returning `undefined` preserves the content; every other result field
+   * remains registry-owned. The callback must be total and must not throw.
+   * @param exec - immutable execution identity and arguments.
+   * @param result - complete normalized outcome before materialization.
+   * @returns replacement content, or `undefined` to preserve it.
+   */
+  finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
+  /**
+   * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
+   * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it
+   * is NEVER sent to the model — `schemas()` whitelists only name/description/
+   * parameters. Declaring it asserts this tool forwards `exec.signal` to a
+   * cooperative implementation that can reach quiescence when the signal aborts.
+   */
+  timeoutMs?: number
+  /**
+   * Pure synchronous classifier for overlap with sibling tool calls. Only
+   * `true` opts in; omission, exceptions, non-`true` returns, and invalid
+   * `defineTool` arguments are exclusive. This metadata is never model-visible.
+   *
+   * Opted-in executions must not mutate parent-owned state. Shared state must
+   * tolerate concurrent dispatch; recorder races are permitted only when they
+   * commute or fail closed. See the
+   * [parallel-tool-call Agent Note](../../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)
+   * for the full contract.
+   * @param args - parsed arguments; `defineTool` validates before calling.
+   * @returns Whether this call may join a parallel group.
+   */
+  isConcurrencySafe?(args: unknown): boolean
+  /**
+   * Optional: how to present the PENDING state of one call in a UI, derived from
+   * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows
+   * its own input). Returns a {@link ToolCallView} (a `card`-tagged render intent),
+   * or `undefined` (or omit the method) to fall back to a generic presentation
+   * (title = tool name, raw args as input). Pure and side-effect-free: a UI may
+   * call it during live streaming AND a session-log replay, so it must depend
+   * only on `args`.
+   */
+  presentCall?(args: unknown): ToolCallView | undefined
+  /**
+   * Optional: how to present the COMPLETED state, given the same `args` and the
+   * durable result projection (`content`, failure state, and optional `meta`). Returns a
+   * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
+   * pending title and render the raw result content. Pure and side-effect-free
+   * for the same replay reason.
+   */
+  presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined
+}
+```
+
+`execute` 接收 `args: unknown`——原始的 `ToolDefinition` 自行校验输入。第一方工具不需要手写校验；它们使用 `defineTool`，由后者代为校验并收窄参数类型、根据 `output.schema` 推导函数体返回类型，并为两个输出投影器提供类型约束。`finalizeContent` 特意接收不可变的执行对象而非类型化参数，因为无效输入和外层流水线失败也会到达该回调；它可以施加工具自有的内容限制，同时保留 `isError`、规范值、结构化错误身份、延迟上下文与展示元数据。
+
+## 统一的 JSON 值 schema DSL
+
+插件作者使用同一套词汇描述类型化参数和类型化输出值。`ValueSchemaSpec` 支持 `string`、`number`、`integer`、`boolean`、`null`、`array`、`object`、仅作者侧可用的 `json`，以及要求恰好命中一个分支的 `oneOf`；标量 `enum` 和 `const` 值必须与节点类型匹配。显式对象节点始终声明 `additionalProperties: true | false`。参数定义仍是隐式的开放对象属性映射，每个必填属性都附带 `required: true`。
+
+源码：[`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts)
+
+```ts type-equiv
+/** One author-facing schema for any lossless JSON value root. */
+type ValueSchemaSpec =
+  | StringValueSchemaSpec
+  | NumberValueSchemaSpec
+  | IntegerValueSchemaSpec
+  | BooleanValueSchemaSpec
+  | NullValueSchemaSpec
+  | ArrayValueSchemaSpec
+  | ObjectValueSchemaSpec
+  | JsonValueSchemaSpec
+  | OneOfValueSchemaSpec
+```
+
+```ts type-equiv
+/** One implicit parameter-root property, optionally required. */
+type ParameterPropertySpec = ValueSchemaSpec & { required?: true }
+```
+
+```ts type-equiv
+/**
+ * Tool parameter schema. The map itself is an implicit open object root;
+ * requiredness remains a per-property `required: true` annotation.
+ */
+type ParameterSchemaSpec = {
+  [key: string]: ParameterPropertySpec
+  [key: symbol]: never
+}
+```
+
+`{ type: 'json' }` 推导为 `JsonValue`，并编译成仅含注解、不施加约束的原始 schema。输出根可以是对象、数组、标量或 null。`InferValue<S>` 在 16 层容器内保留字面量约束与对象开放性，之后回退为 `JsonValue`，避免耗尽 TypeScript 的类型实例化栈。`InferArgs<P>` 依据逐属性的必填标记生成必填和可选的字符串键：
+
+```ts type-equiv
+/**
+ * Infer the TypeScript value accepted by an author-facing value schema. Exact
+ * inference is bounded to 16 container levels, then falls back to `JsonValue`.
+ */
+type InferValue<S> = InferValueAt<S, []>
+```
+
+```ts type-equiv
+/** Infer the TypeScript argument object for an implicit parameter schema. */
+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()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
+
+## `ToolRestriction` — 单个作用域的实时全局过滤器
+
+`ToolRestriction` 仅作用于实时的部署全局工具层。注册表将 readonly 名称编译为私有集合，对多个限制取交集，再叠加作用域本地工具。仅 deny 的过滤器允许后续未列出的全局工具通过，而 allow 列表则排除它们。
+
+```ts type-equiv
+/**
+ * Per-scope filter over global tools. Restrictions intersect and do not affect
+ * scoped registrations or the reserved Code Mode transport.
+ */
+interface ToolRestriction {
+  /** Global tool names that stay visible; everything else is removed. */
+  readonly allow?: readonly string[]
+  /** Global tool names removed from visibility. */
+  readonly deny?: readonly string[]
+}
+```
+
+## 执行：可扩展的 waterfall（瀑布式事件）加单调策略
+
+`ctx.tools.execute()` 接受由调用方拥有且包含必需 readonly `signal` 的 `ToolExecutionInput`，将其解析后的 JSON 参数一次性物化为流水线拥有的 `ToolExecution`，然后让调用依次经过 `tools/pre-execute`（可重排的 allow/deny/ask waterfall）→ 已注册的单调 guard → `tools/execute`（环绕分派包装层）→ `tools/post-execute`（检查/替换结果）→ 可选且由定义拥有的 `finalizeContent` → `tools/result`（不可变的权威结果）。只有 `tools/execute` 视图可以替换必需的 signal。最终产出为 `ToolExecutionResult`。
+
+```ts type-equiv
+/** Opaque call identity that permits correlation without exposing mutable execution state. */
+type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
+```
+
+```ts type-equiv
+/**
+ * Caller-supplied description of one tool call. {@link ToolRegistry.execute}
+ * adds the registry-owned token to form a pipeline {@link ToolExecution};
+ * callers do not choose that token.
+ */
+interface ToolExecutionInput {
+  readonly callId: CallId
+  readonly name: string
+  /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
+  readonly arguments: unknown
+  /** The agent on whose behalf the call runs (set by the agent loop). */
+  readonly agent?: Agent
+  /**
+   * Opaque token of the enclosing transport execution, when one exists. Code
+   * Mode sets this on SDK sub-dispatches so commit-style observers can wait for
+  * the outer `run_code` outcome without receiving its live mutable execution.
+  */
+  readonly parent?: ToolExecutionToken
+  /** Required caller-owned cancellation for this invocation. */
+  readonly signal: AbortSignal
+}
+```
+
+工具函数体接收运行时扩展。`deferContext()` 是组合工具的通道：它记录嵌套分派产生的上下文，而不会在外层调用尚未结束时注入这些上下文。
+
+```ts type-equiv
+/**
+ * Runtime context handed to a tool implementation after the registry has
+ * accepted a {@link ToolExecution}. A composite tool uses
+ * {@link deferContext} to ferry context produced by nested dispatches back to
+ * the outer result; the loop appends it only after the outer `tool/result`.
+ */
+interface ToolRunContext extends ToolExecution {
+  /**
+   * Defer one nested-dispatch context until this tool's final result reaches
+   * the agent loop. Contexts retain their individual source and metadata and
+   * are emitted in call order.
+   */
+  deferContext(context: HookContext): void
+}
+```
+
+agent loop（智能体循环）向注册表查询每个待处理调用的执行模式，并据此形成独占屏障和滚动池并行执行：
+
+```ts type-equiv
+/**
+ * Scheduling mode for one pending call. `parallel` may overlap with siblings;
+ * `exclusive` runs alone and forms an ordering barrier.
+ */
+type ToolExecutionMode =
+  | { kind: 'parallel' }
+  | { kind: 'exclusive' }
+```
+
+```ts type-equiv
+/**
+ * One pending tool call inside the registry pipeline. Parsed arguments cross
+ * one lossless-JSON materialization boundary before policy and are deep-frozen;
+ * call identity, the caller signal, and the registry-assigned {@link token} are
+ * readonly. The registry freezes the complete object before `tools/result`
+ * observers run.
+ */
+interface ToolExecution extends ToolExecutionInput {
+  /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
+  readonly token: ToolExecutionToken
+}
+```
+
+```ts type-equiv
+/**
+ * Around-dispatch view of a {@link ToolExecution}. A `tools/execute` wrapper
+ * may replace the signal for its delegated lifetime, but it cannot remove it.
+ * The registry fuses every replacement with the captured caller signal.
+ */
+interface ToolDispatchExecution extends Omit<ToolExecution, 'signal'> {
+  /** Cancellation signal visible to the next wrapper or tool body. */
+  signal: AbortSignal
+}
+```
+
+`ToolExecutionToken` 是不透明的运行时 `Symbol`，仅用于身份比较。策略执行前，`execute()` 会物化并冻结参数、拒绝非 JSON 输入并分配 token。身份字段、调用方必需的 signal 和可选的 parent token 均保持 readonly。`ToolDispatchExecution` 包装层可以替换 signal 但不能移除；注册表会在调用工具函数体前重新融合调用方的 signal。最终观察者接收冻结的执行身份。
+
+`ToolGuard` 是感知作用域的最终预分派策略。其形状有意不包含 allow 结果：`undefined` 保留 waterfall 的决策，而返回的 reason 只能缩减权限，因此后续监听器无法撤销它。
+
+```ts type-equiv
+/**
+ * A monotonic execution guard evaluated after every `tools/pre-execute`
+ * listener and before the tool body. Returning a reason denies the call;
+ * returning `undefined` leaves it unchanged. Because guards have no allow
+ * result, listener ordering cannot turn a denial back into permission.
+ * @param execution - the identity-protected call after extensible pre-execute policy completed.
+ * @returns a final denial reason, or `undefined` to leave the call allowed.
+ */
+type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined
+```
+
+```ts type-equiv
+/** Canonical failure detail; internal routing information remains optional. */
+interface ToolFailure {
+  /** Human-readable failure message without the Native `Error: ` envelope. */
+  message: string
+  /** Internal error class/code used by policy and durable diagnostics. */
+  info?: ToolErrorInfo
+}
+```
+
+```ts type-equiv
+/** Successful canonical tool execution, including its Native/model projection. */
+interface ToolExecutionSuccess {
+  readonly isError: false
+  /** Execution-local canonical value; deliberately omitted from durable events. */
+  readonly value: JsonValue
+  readonly content: ContentBlock[]
+  readonly error?: never
+  readonly meta?: JsonValue
+  readonly additionalContexts?: HookContext[]
+}
+```
+
+```ts type-equiv
+/** Failed canonical tool execution; failures never carry a successful value. */
+interface ToolExecutionFailure {
+  readonly isError: true
+  readonly error: ToolFailure
+  readonly value?: never
+  readonly content: ContentBlock[]
+  readonly meta?: JsonValue
+  readonly additionalContexts?: HookContext[]
+}
+```
+
+```ts type-equiv
+/** The discriminated, execution-local outcome of one tool call. */
+type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure
+```
+
+结果仅承载产出。调用身份保留在不可变的 `ToolExecution` 上，后者伴随结果经过每个钩子，并出现在持久化的 `tool/call` / `tool/result` 会话事件上，因此包装层无法创建第二个相互矛盾的身份。规范的 `value` 仅存在于执行期间：循环只持久化 `content`、`error` 和 `meta`，`tool/code-dispatch` 则存储有界摘要。回放可以重现展示，却无法重建中间值。
+
+成功时，注册表会快照并校验函数体返回值，将其冻结，然后调用纯渲染器；对于直接的外层调用，还会调用可选的元数据投影器。注册表会在 `tools/result` 之前另行物化持久展示字段；无效值、渲染器/投影器失败或非 JSON 展示都会转为 JSON 安全的 `isError`。因此，最终实时观察者能看到精确的执行期值，以及可安全用于后续持久追加的字段。
+
+在得到最终内容之前，注册表会物化候选结果；若内容、结构化错误、附加上下文或展示元数据无法物化，则会转为仍可到达 `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`：
+
+```ts type-equiv
+/**
+ * Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
+ * `ask` runs only after an approval service returns `allowed-once` and otherwise
+ * denies. Input rewriting is excluded because arguments are already logged and
+ * presented.
+ */
+type PreToolDecision =
+  | { kind: 'allow' }
+  | { kind: 'deny'; reason: string }
+  | { kind: 'ask'; reason?: string }
+```
+
+```ts type-equiv
+/**
+ * Post-dispatch decision: accept, replace one projection, attach context for the
+ * next request, or block by turning corrective feedback into an error result.
+ */
+type PostToolDecision =
+  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: HookContext[] }
+  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: HookContext[] }
+  | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: HookContext[] }
+```
+
+调用 `next()` 获取默认决策，或直接返回一个决策以短路。前置策略可以 deny 或 ask；只有 `allowed-once` 才继续执行，而未授权、缺少审批通道或服务、或无 agent 的请求都会变为拒绝。Guard 仍可施加最终拒绝。参数不可被改写，因为历史记录、审计、UI 和执行必须保持一致。
+
+后置策略可以替换内容或值，但不能同时替换两者。替换内容会保留规范值和现有元数据；替换值会重新校验并重新计算内容/元数据；阻止会移除值，并转为包含纠正反馈的 `isError`。内容替换是展示策略，而非保密策略；需要隐藏程序化值的监听器必须阻止或替换该值。`tools/result` 在归一化后接收冻结的执行和结果；观察者无法对其进行变换，观察者的失败也会被隔离。未知工具和抛出异常的工具都会变为结构化错误（`ToolNotFoundError` 映射为 `UNKNOWN_TOOL`），调用失败但不终止当前轮次。
+
+## 已强制执行的原始 JSON Schema 子集
+
+subagent、工作流、MCP 和动态注册提供的原始 schema 使用作者侧 DSL 在协议层的对应表示。`assertSupportedJsonSchema()` 接受任意 JSON 根，`validateJsonSchemaValue()` 强制执行该 schema，`JsonSchemaError` 则报告每条不受支持或格式错误的 schema 路径。仅含注解的空节点表示不受约束的无损 JSON。`oneOf` 至少要求两个分支，且一个值必须恰好匹配其中一个。仍要求对象根的消费方调用 `assertObjectJsonSchema()` 并携带 `ObjectJsonSchema`；这样，subagent/工作流中由调用方定义的结构化输出可以继续以对象为根，而不会限制共享词汇。
+
+```ts type-equiv
+/** Scalar JSON values supported by `enum` and `const`. */
+type JsonSchemaScalar = string | number | boolean | null
+```
+
+```ts type-equiv
+/** Single-type keywords accepted by the enforced subset. */
+type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+```
+
+```ts type-equiv
+/**
+ * One raw JSON Schema node in the enforced subset. The optional fields express
+ * the external wire shape; {@link assertSupportedJsonSchema} rejects invalid
+ * combinations before a caller treats the node as trusted.
+ */
+interface JsonSchemaNode {
+  /** Omit with no constraints for any JSON value, or use `oneOf`. */
+  type?: JsonSchemaType
+  /** Exactly one branch must validate; at least two branches are required. */
+  oneOf?: JsonSchemaNode[]
+  /** Nested property schemas (`type: 'object'` only). */
+  properties?: Record<string, JsonSchemaNode>
+  /** Required property names; each must appear in `properties`. */
+  required?: string[]
+  /** `false` rejects undeclared keys; absent/`true` follows JSON Schema's open default. */
+  additionalProperties?: boolean
+  /** Item schema (`type: 'array'` only); absent accepts any JSON item. */
+  items?: JsonSchemaNode
+  /** Allowed values for a scalar node. */
+  enum?: JsonSchemaScalar[]
+  /** The single allowed value for a scalar node. */
+  const?: JsonSchemaScalar
+  /** Annotation, ignored for validation. */
+  description?: string
+  /** Annotation, ignored for validation. */
+  title?: string
+  /** Annotation, ignored for validation but required to be lossless JSON. */
+  default?: JsonValue
+  /** Annotation, ignored for validation but required to be lossless JSON. */
+  examples?: JsonValue
+}
+```
+
+```ts type-equiv
+/** A consumer-constrained object-rooted schema. */
+type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
+```
+
+## 工具展示 UI 词汇
+
+工具希望其调用在 UI 中如何呈现（编辑器工具调用卡片、CLI（命令行界面）日志行），提供方无关，使工具在不依赖任何客户端协议的情况下描述自身。`presentCall`/`presentResult` 返回一个 **`card` 标签的渲染意图**——一个可辨识联合类型，UI 桥接层据此分发：
+
+- `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 获得桥接层从 `output` 派生的围栏 ` ```console ` 回退）、或 `{ card: 'diff', title?, diffs }`（已完成的文件变更→要展示的变更，通常是从变更前后内容计算出带上下文行的已应用 hunk，或在没有前像时的整文件 diff——例如文件创建。`tool_call_update` 的内容会替换调用的内容，因此变更工具即使与调用时的片段重复也要返回此卡片，以防结果文本覆盖 diff）。
+
+`ToolCallKind`（`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`）用于为通用卡片选择图标。`FileLocation`（`{ path, line? }`）与 `FileDiff`（`{ path, oldText, newText }`）是共享的文件卡片词汇。该设计由[渲染意图联合类型 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)固定；ACP（Agent Client Protocol）桥接层将 `diff` 卡片映射为 `{ type: 'diff' }` 内容块，将 `terminal` 卡片映射为 `_meta` 终端约定，并根据会话 cwd 将文件卡片标题转换为相对路径。
+
+完整的展示字段文档见 [`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/core-data-structures/user-interaction.i18n.yaml b/docs/core-data-structures/user-interaction.i18n.yaml
new file mode 100644
index 0000000000..126f18729e
--- /dev/null
+++ b/docs/core-data-structures/user-interaction.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
+user-interaction.md: 7ddc2f46bdbbe25f2a8979b029d0c6b958f85b09
+user-interaction.zh.md: 75b9b7795a36e0706672f0d17ba0b399c20cc644
diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md
index 1ec83b7827..7ddc2f46bd 100644
--- a/docs/core-data-structures/user-interaction.md
+++ b/docs/core-data-structures/user-interaction.md
@@ -1,5 +1,7 @@
 # User Interaction
 
+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`: `dsh-tui` uses keyboard-driven overlays, and `dsh-acp` maps questions to ACP form elicitations.
 
 Source: [`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)
@@ -58,14 +60,14 @@ interface AskUserQuestionRequest {
 
 ## Answer
 
-Providers return one answer per answered question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. When `custom` is present, `selected` is empty; custom text is an answer override, not a supplement to selected choices.
+Providers return one answer item per question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. When `custom` is present, `selected` is empty; custom text is an answer override, not a supplement to selected choices. A UI may also use an item with empty `selected` and no `custom` to preserve a skipped question in an otherwise completed batch.
 
 ```ts type-equiv
 /** Answer to one question. */
 interface AskUserQuestionAnswerItem {
   /** The answered question id. */
   id: string
-  /** Selected option labels. Empty when the answer is purely custom text. */
+  /** Selected option labels. Empty for custom or unanswered choices. */
   selected: string[]
   /** Optional free-text "Other" answer. */
   custom?: string
diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/core-data-structures/user-interaction.zh.md
new file mode 100644
index 0000000000..75b9b7795a
--- /dev/null
+++ b/docs/core-data-structures/user-interaction.zh.md
@@ -0,0 +1,108 @@
+# 用户交互
+
+[English](user-interaction.md) | 中文
+
+[dsh-user-interaction](../../packages/ui/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI surface 提供活跃的 `UserInteractionProvider`：`dsh-tui` 使用键盘驱动的 overlay，`dsh-acp` 则把问题映射为 ACP（Agent Client Protocol）表单 elicitation。
+
+源码：[`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)
+
+## 问题选项
+
+`AskUserQuestionOption` 是可选择项的形状。`label` 是面向用户的选项文字，同时也是面向模型的选中值；`description` 是可选的 UI 帮助文本。
+
+```ts type-equiv
+/** One selectable answer offered to the user. */
+interface AskUserQuestionOption {
+  /** User-facing label. */
+  label: string
+  /** Optional extra context rendered by capable UIs. */
+  description?: string
+}
+```
+
+## 问题条目
+
+`AskUserQuestionItem` 是请求中的一个问题。调用方提供稳定的 `id`，它会随答案原样返回，使批量问题仍可路由。可选的 `detail` 携带辅助文本；提供方会将其随问题渲染，但不会放入可选 option label。
+
+```ts type-equiv
+/** One question in a user-interaction request. */
+interface AskUserQuestionItem {
+  /** Stable caller-provided question id, echoed in the answer. */
+  id: string
+  /** The question to display. */
+  question: string
+  /** Optional supporting detail rendered with the question but kept out of option labels. */
+  detail?: string
+  /** Optional short heading/group label. */
+  header?: string
+  /** Optional choices the UI can render as a menu. */
+  options?: AskUserQuestionOption[]
+  /** Whether more than one option may be selected. Defaults to single-select. */
+  multiSelect?: boolean
+}
+```
+
+## 提问请求
+
+`AskUserQuestionRequest` 是跨包（package）的请求。`questions` 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。
+
+```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. */
+  agent?: Agent
+  /** Abort signal for the owning tool/step. */
+  signal?: AbortSignal
+}
+```
+
+## 回答
+
+提供方为每个问题 id 返回一个回答项。`selected` 包含选中的选项标签，`custom` 在用户输入自由文本时携带「其他」回答。当 `custom` 存在时，`selected` 为空；自定义文本是对选中项的覆盖，而非补充。UI 也可以使用 `selected` 为空且不含 `custom` 的回答项，在其余问题均已完成的批次中保留被跳过的问题。
+
+```ts type-equiv
+/** Answer to one question. */
+interface AskUserQuestionAnswerItem {
+  /** The answered question id. */
+  id: string
+  /** Selected option labels. Empty for custom or unanswered choices. */
+  selected: string[]
+  /** Optional free-text "Other" answer. */
+  custom?: string
+}
+```
+
+```ts type-equiv
+/** The human's answer. */
+interface AskUserQuestionAnswer {
+  /** Structured answers keyed by question id. */
+  answers: AskUserQuestionAnswerItem[]
+}
+```
+
+## 提供方
+
+同一上下文中只能有一个活跃的提供方。提供方注册绑定到 effect，因此 HMR（热模块替换）或 dispose（资源释放）会移除当前活跃的 UI。
+
+```ts type-equiv
+/** UI-side provider for user questions. */
+interface UserInteractionProvider {
+  ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+}
+```
+
+## 错误
+
+`UserInteractionError` 继承 `HarnessError`，因此 `ctx.tools.execute()` 会保留 `{ name, code }`，用于面向模型的工具失败，如 `EMPTY_QUESTIONS`、`NO_PROVIDER`、`ASK_ABORTED` 或 ACP 侧取消。
+
+```ts type-equiv
+/** Stable error taxonomy for user-interaction failures. */
+class UserInteractionError extends HarnessError {
+  constructor(message: string, code: string, options?: ErrorOptions) {
+    super(message, code, options)
+    this.name = 'UserInteractionError'
+  }
+}
+```
diff --git a/docs/core-data-structures/web.i18n.yaml b/docs/core-data-structures/web.i18n.yaml
new file mode 100644
index 0000000000..912c1decbe
--- /dev/null
+++ b/docs/core-data-structures/web.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
+web.md: 20d07240c9d9fea2f1f5abbac810f349a3e81f9b
+web.zh.md: 68ceed04bb0b80f32ed704118f1fc25f48a0da70
diff --git a/docs/core-data-structures/web.md b/docs/core-data-structures/web.md
index 22909b8dfb..20d07240c9 100644
--- a/docs/core-data-structures/web.md
+++ b/docs/core-data-structures/web.md
@@ -1,5 +1,7 @@
 # Web Access
 
+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.
 
 Source: [`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
diff --git a/docs/core-data-structures/web.zh.md b/docs/core-data-structures/web.zh.md
new file mode 100644
index 0000000000..68ceed04bb
--- /dev/null
+++ b/docs/core-data-structures/web.zh.md
@@ -0,0 +1,135 @@
+# Web 访问
+
+[English](web.md) | 中文
+
+Web 访问 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)，在同一个 `ctx.web` 服务上横跨**两项能力**（search 与 fetch），并拆分到多个包（package）：接口（[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 提供方不会改变模型请求 query 的方式，更换 fetch 实现也不会改变模型请求 URL 的方式。
+
+源码：[`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
+
+## 为什么两项能力合为一个 seam
+
+搜索与抓取既不共享请求 schema，也不共享业务逻辑，但它们被有意设计为同一个 `ctx.web` 中间层：一个提供方选择策略的所有者、一套 abort/error 词汇、一个面向产品的「此 harness 如何访问 Web」配置界面。代价是服务上并行的 `searchX`/`fetchX` 方法对；这种并行是有意为之，而非遗漏的提取。提供方注册的是**能力**（`WebSearchProvider` 或 `WebFetchProvider`），而非工具；面向模型的名称、schema、提示词引导与展示全部集中在唯一的消费方 `dsh-tool-web` 中。
+
+## 搜索请求与结果
+
+面向模型的工具参数仅为一个 `query`；`maxResults` 是消费方自有的上限（`dsh-tool-web` 的 `searchMaxResults` 配置，默认 `8`），通过 seam 传递并在返回时强制执行——如果提供方返回超量，seam 截断 `sources[]` 并设置 `truncated`。
+
+```ts type-equiv
+/**
+ * What one search-capable backend can return. The model-facing argument is just
+ * a query; `maxResults` is a `dsh-tool-web`-layer bound passed through unchanged
+ * and enforced on the way back by the seam (see {@link WebSearchResult}).
+ */
+interface WebSearchRequest {
+  readonly query: string
+  /**
+   * Upper bound on returned sources; the seam truncates to it. Omitted = no
+   * bound. `dsh-tool-web` always sets it. A provider whose API supports a
+   * result-count control (Exa's `numResults`) should apply it at the request
+   * layer as a cost/latency optimization; the seam enforces the bound
+   * regardless.
+   */
+  readonly maxResults?: number
+}
+```
+
+```ts type-equiv
+/**
+ * Normalized search outcome. `content` is optional provider-generated answer
+ * text or summary (Exa returns none; Perplexity returns a generated answer).
+ * `sources[]` is the portable citation surface. `truncated` is set by the seam
+ * when it cut `sources[]` down to `maxResults`.
+ */
+interface WebSearchResult {
+  /** Optional provider-generated answer text, search context, or summary. */
+  readonly content?: string
+  /** Citeable sources, already truncated to the request's `maxResults`. */
+  readonly sources: readonly WebSearchSource[]
+  /** True when the seam dropped sources to honor `maxResults`. */
+  readonly truncated: boolean
+}
+```
+
+`content` 是提供方可选生成的回答文本（Exa 和 DeepSeek 不返回；Perplexity 返回生成式回答）。`sources[]` 是一套可跨提供方使用的引用数据结构。一个 source 必有 `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
+ * `publishedAt` are optional because not every provider returns them — forcing
+ * adapters to invent them would make the seam lie (Perplexity citations may be
+ * URL-only). `dsh-tool-web` renders `title ?? hostname(url)` for display.
+ */
+interface WebSearchSource {
+  readonly url: string
+  readonly title?: string
+  readonly snippet?: string
+  /** Publication/crawl timestamp as a provider-supplied ISO-8601 string. */
+  readonly publishedAt?: string
+}
+```
+
+## 抓取请求与结果
+
+```ts type-equiv
+/**
+ * What one fetch-capable backend is asked to retrieve. The request deliberately
+ * omits timeout, format, prompt, and extraction controls: cancellation is a
+ * direct execution argument, while presentation and higher-level LLM concerns
+ * belong outside safe retrieval.
+ */
+interface WebFetchRequest {
+  readonly url: string
+}
+```
+
+HTTP 状态码是被抓取资源状态的一部分，不自动视为失败：成功的网络抓取返回 `404`/`500` 时，仍产出一个带状态码和有界解码 body 的 `WebFetchResult`。`url` 是经过允许的重定向后的最终 URL。`WebError` 仅用于无法安全获取或表示资源的情况。
+
+```ts type-equiv
+/**
+ * Normalized fetch outcome. A successful network fetch of a non-2xx response is
+ * a result, not an error: the status code is part of the fetched resource
+ * state. {@link WebError} is reserved for failures to safely retrieve or
+ * represent the resource.
+ */
+interface WebFetchResult {
+  /** The final URL after allowed redirects (the request URL is in the request). */
+  readonly url: string
+  /** HTTP status code of the fetched response. */
+  readonly statusCode: number
+  /** Decoded body, classified by content kind. */
+  readonly body: WebFetchBody
+  /** True when the provider capped the decoded body. */
+  readonly truncated: boolean
+}
+```
+
+`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
+ * `dsh-web`: the provider decodes the kind and `dsh-tool-web` renders it, so a
+ * new kind is a coordinated change across known packages, not a plugin
+ * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
+ * so adding a kind breaks compilation at every consumer until handled. Each arm
+ * stays its own object literal even where fields coincide today, leaving room
+ * for arm-specific fields later (a `pdf` body's `pageCount`).
+ */
+type WebFetchBody =
+  | { readonly kind: 'html'; readonly content: string }
+  | { readonly kind: 'text'; readonly content: string }
+```
+
+## 提供方可用性
+
+提供方的 `available(): boolean` 是一个廉价的本地检查（凭证是否存在、配置是否可解析），**禁止发起网络调用**。它是执行时选择的输入，而非健康检查系统：`search()`/`fetch()` 读取它以选出可用的提供方，选择失败以结构化的 `WebError` 呈现给调用方路由——其 code 和 message 携带可分支的细节（缺失的 id 或有歧义的候选集）。
+
+选择从不依赖注册顺序、配置顺序或 HMR（热模块替换）顺序：一项能力要么有显式的提供方 id（配置 `searchProvider`/`fetchProvider`，或填充同一字段的对应环境变量），要么在恰好只有一个可用提供方注册时自动选择；多个可用提供方且未配置 id 时为 `WEB_PROVIDER_AMBIGUOUS`，而非先注册先赢。
+
+## 错误
+
+`WebError extends HarnessError`（[core.md](core.md) 错误分类体系），带有 `code: string`（开放式，与其他 seam 的错误一致——`LlmError`、`SubagentError`），而非封闭联合类型：提供方可以在不修改 `dsh-web` 的情况下抛出自己的 code，消费方必须容忍未知 code。code 按所有者划分。seam 中立的 code 由 `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 暴露的兜底 code，包括网络/传输失败——DNS、连接被拒、TLS）。抓取传输层 code 由 `dsh-web-fetch-local` 实现拥有，不同的抓取后端无需抛出它们：`WEB_INVALID_URL`、`WEB_BLOCKED_URL`、`WEB_REDIRECT_BLOCKED`、`WEB_FETCH_TOO_LARGE`、`WEB_FETCH_TIMEOUT`、`WEB_UNSUPPORTED_CONTENT_TYPE`。
+
+## 服务
+
+`WebService` 注册搜索与抓取提供方，以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id，并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一跳同源重定向重新校验，并解码 body；展示由工具负责。私有网络阻断尚未实现，因此请勿在可触及敏感内部目标的环境中启用 `web_fetch`。
diff --git a/docs/core-data-structures/workflow.i18n.yaml b/docs/core-data-structures/workflow.i18n.yaml
new file mode 100644
index 0000000000..492a9bea08
--- /dev/null
+++ b/docs/core-data-structures/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
+workflow.md: 8d271b89e71de6f6bef548aa8da61402ef9ada6e
+workflow.zh.md: b8ed699eb52d9f0cef23c513f625de7e82c46c45
diff --git a/docs/core-data-structures/workflow.md b/docs/core-data-structures/workflow.md
index 8d8e47fc79..8d271b89e7 100644
--- a/docs/core-data-structures/workflow.md
+++ b/docs/core-data-structures/workflow.md
@@ -1,5 +1,7 @@
 # Workflow
 
+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).
diff --git a/docs/core-data-structures/workflow.zh.md b/docs/core-data-structures/workflow.zh.md
new file mode 100644
index 0000000000..b8ed699eb5
--- /dev/null
+++ b/docs/core-data-structures/workflow.zh.md
@@ -0,0 +1,132 @@
+# 工作流
+
+[English](workflow.md) | 中文
+
+工作流 seam：一个 agent（智能体）运行由模型编写的编排脚本（SCRIPT），扇出 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（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
+
+源码：[`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts)
+
+## 启动请求
+
+调用方启动 run 时提出的请求。普通工作流工具根据模型的 `{ script, meta, args }` 调用与发起调用的 agent 构建它；专用消费方还可以为该 run 选择一个引擎级 `subagentProvider` 并调低 `maxTotalAgents`，但脚本无法观察或替换这两项策略。`meta` 与 `args` 是普通 JSON 数据（引擎会对 `meta` 做形状校验，并在任何内容运行前大声拒绝——绝不会通过求值脚本文本来获取它）。`parent` 是必填字段——脚本生成的每个子 agent 都归属于它（cwd、谱系与深度通过 [subagent seam](subagent.md) 流转）。
+
+```ts type-equiv
+/**
+ * What a caller asks for when starting a workflow run. `meta` and `args` are
+ * plain JSON DATA by the seam contract (the tool builds both from the model's
+ * schema-validated call; the engine validates `meta`'s shape and rejects loud
+ * before anything runs) — an engine never evaluates script text to obtain
+ * them. `parent` is REQUIRED — every `agent()` the script spawns is
+ * attributed to it (cwd, lineage, depth flow through the subagent seam).
+ */
+interface WorkflowStartRequest {
+  /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
+  script: string
+  /** The workflow's identity block, as plain JSON data (shape-validated by the engine). */
+  meta: WorkflowMeta
+  /** Optional input exposed verbatim to the script as the `args` global. */
+  args?: unknown
+  /**
+   * Optional engine-wide child-provider override for this run. The workflow
+   * script cannot observe or replace it; omission uses the engine's configured
+   * provider.
+   */
+  subagentProvider?: string
+  /**
+   * Optional per-run total-child ceiling. Implementations reject values above
+   * their deployment ceiling before publishing the run.
+   */
+  maxTotalAgents?: number
+  /** The agent on whose behalf the run executes (parent of every child). */
+  parent: Agent
+  /** Cancels the run when aborted (the tool's `exec.signal`). */
+  signal?: AbortSignal
+}
+```
+
+## 工作流的身份标识：`WorkflowMeta`
+
+作为数据附在启动请求上的身份块（工具的 `meta` 参数；字段词汇与 Claude Code 动态工作流的 meta 块一致）。`phases` 仅用于进度展示：`phase()` 调用与标题匹配，供观察者使用；不暗示任何执行结构。
+
+```ts type-equiv
+/**
+ * The script's identity block, provided as plain JSON data alongside the
+ * script body (the model-facing tool carries it as its `meta` parameter) and
+ * validated by the engine before the body runs. `name`/`description` are
+ * required; the rest is optional annotation. The field vocabulary matches the
+ * Claude Code dynamic-workflows meta block.
+ */
+interface WorkflowMeta {
+  /** Short kebab-case workflow name (display + persistence key). */
+  name: string
+  /** One-line description of what the workflow does. */
+  description: string
+  /** Optional guidance on when this workflow applies (shown in listings). */
+  whenToUse?: string
+  /** Optional phase declarations matched by `phase()` calls. */
+  phases?: WorkflowPhase[]
+}
+```
+
+## 终态结果：`WorkflowResult`
+
+一次运行的结果，由 `WorkflowRun.result` resolve。`value` 是脚本的物化返回值——纯宿主域 JSON 数据（脚本无返回值时为 `null`）——仅在 `completed` 时有意义。`stopReason` 是封闭联合类型（引擎所有；消费方可穷举）：`completed` | `cancelled` | `error`。非 `completed` 的原因在 `error` 中携带失败信息，消费方将其映射为 `isError` 工具结果，而非把部分输出当作成功上报。
+
+```ts type-equiv
+/**
+ * The outcome of one run, resolved by {@link WorkflowRun.result}. `value` is
+ * the script's materialized return value (plain host-realm JSON data; `null`
+ * when the script returned `undefined`) — meaningful only for `completed`.
+ * A non-`completed` reason carries the failure in `error`; the consumer maps
+ * it to an `isError` tool result rather than reporting partial output.
+ */
+interface WorkflowResult {
+  /** The script's return value (host JSON data; `null` for no return). */
+  value: unknown
+  /** Why the run settled. */
+  stopReason: WorkflowStopReason
+  /** The failure message (present iff `stopReason` is not `completed`). */
+  error?: string
+  /**
+   * How many `agent()` calls the run accepted over its whole lifetime. On a
+   * graceful settlement this is the script-side count (calls still queued for
+   * a concurrency slot included); on a termination path (grace force-settle,
+   * worker death) it degrades to the host-observed count — calls queued
+   * inside a terminated script are unknowable then.
+   */
+  agentsStarted: number
+}
+```
+
+## 活跃运行：`WorkflowRun`
+
+脚本执行期间消费方持有的句柄。消费方 await `result`，可中途 `cancel`，且必须在每条路径上 `dispose`（资源释放）。`result` 不会 reject：脚本失败以 `stopReason: 'error'` resolve；一旦运行被取消，即使脚本本身永不 settle，它也会在引擎的有界宽限期内 settle（引擎强制以 `cancelled` settle；worker-thread 引擎随后终止脚本的 worker），因此消费方 await `result` 不会在取消后卡死。`dispose()` = cancel + 有界 settle + 等待子 agent 停稳；它不会因脚本卡死而挂起。
+
+```ts type-equiv
+/**
+ * Holder-owned live workflow. `result` never rejects and settles within the
+ * engine's cancellation grace; failures resolve through `stopReason`. Consumers
+ * may cancel and must call idempotent `dispose()` on every path to await bounded
+ * script settlement and child quiescence.
+ */
+interface WorkflowRun {
+  readonly id: WorkflowRunId
+  /** The validated meta block (available before the body runs). */
+  readonly meta: WorkflowMeta
+  readonly result: Promise<WorkflowResult>
+  /** Cancel the run: children abort, pending hooks reject, the script dies at its next await (or is force-settled at the grace). */
+  cancel(reason?: string): void
+  /** Cancel + bounded-grace settle; safe to call on every path (idempotent). */
+  dispose(): Promise<void>
+}
+```
+
+## 失败纪律：`WorkflowError.fatal`
+
+脚本内部的钩子误用：错误参数、未知或延迟的 `agent()` 选项、超出[结构化输出子集](../../packages/core/tools/README.md)的 schema、触发的上限、seam 启动失败、取消，都会抛出 `fatal: true` 的 `WorkflowError`。`parallel()`/`pipeline()` 组合器对 fatal 错误直接重新抛出，而非将该项映射为 `null`：一个拼写错误的选项必须让脚本大声失败，绝不能消融为看似普通子 agent 失败的结果。逐项的 `null` 保留给子运行失败（非 `completed` 的 stop reason）和阶段内的普通脚本错误。
+
+## 事件
+
+`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` 一致。
diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml
new file mode 100644
index 0000000000..96c938a74f
--- /dev/null
+++ b/docs/defensive-patterns.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
+defensive-patterns.md: c69094db461048f5dbca5f8bdd1fb5581b08a962
+defensive-patterns.zh.md: eb57f035ad0bd67e62e285d451502d41e4efc2bc
diff --git a/docs/defensive-patterns.md b/docs/defensive-patterns.md
index fe74a9d19f..c69094db46 100644
--- a/docs/defensive-patterns.md
+++ b/docs/defensive-patterns.md
@@ -1,5 +1,7 @@
 # Defensive patterns
 
+English | [中文](defensive-patterns.zh.md)
+
 Hard-won bug-class rules: each pattern below is a class of defect that actually shipped or nearly shipped here, stated as the rule that prevents its recurrence. Read this before writing lifecycle, concurrency, subprocess, or teardown code. Test-tier counterparts (real entry path, world-verification, resource ownership) are in [testing.md](testing.md).
 
 ## Report orthogonal outcomes independently
@@ -12,7 +14,7 @@ When an interface documents two valid ways to signal something — an adapter ma
 
 ## Async state is not synchronous state
 
-`agent.send()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) instead of treating status as a per-send result: several queued sends run as consecutive turns under one `running` interval, while cancellation or disposal can discard unstarted items. The guard cuts both ways: if the awaited transition can never occur (EOF with no work submitted → never `running`), the wait hangs — handle the "nothing to wait for" branch explicitly.
+`agent.followup()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) instead of treating status as a per-follow-up result: several queued follow-ups run as consecutive turns under one `running` interval, while cancellation or disposal can discard unstarted items. The guard cuts both ways: if the awaited transition can never occur (EOF with no work submitted → never `running`), the wait hangs — handle the "nothing to wait for" branch explicitly.
 
 ## Dispose must reach quiescence, not just request it
 
diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md
new file mode 100644
index 0000000000..eb57f035ad
--- /dev/null
+++ b/docs/defensive-patterns.zh.md
@@ -0,0 +1,29 @@
+# 防御性模式
+
+[English](defensive-patterns.md) | 中文
+
+来之不易的缺陷类别规则：下面每条模式都是本项目实际发布或差点发布的一类缺陷，以防止其复发的规则形式陈述。在编写生命周期、并发、子进程或清理代码之前请先阅读本文。测试层面的对应规则（真实入口路径、world 验证、资源归属）见 [testing.md](testing.md)。
+
+## 正交结果独立上报
+
+一个结果可以同时具有多重性质：进程可能既超时又以 exit 0 退出，因为它捕获了信号。每个独立事实（`timedOut`、`signal`、`exitCode`）都应独立暴露；切勿将某个 flag 的上报嵌套在另一个 flag 的分支内，否则调用方会把一次被截断的运行误读为正常成功。
+
+## 跨 seam 契约两侧都要遵守
+
+当一个接口文档记录了两种合法的信号方式时——例如适配器可以通过从 `stream()` 抛出异常来报告失败，也可以通过以 `finish {kind:'error'|'aborted'}` 分片结束流来报告——消费方必须同时处理两种路径，而不是只处理第一个实现恰好使用的那种。依赖库的适配器可能无法在流中途抛出异常，只能走带内路径；如果 agent loop（智能体循环）只捕获抛出的异常，就会把提供方的 401 错误变成一个正常完成的轮次。请在类型定义处记录契约；通过真实消费方测试每个分支。
+
+## 异步状态不是同步状态
+
+`agent.followup()` 不会在返回前翻转状态；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿基于一个刚刚请求的状态来控制流程——应以实际触发的事件/promise（`agent/status`、`task.done`）驱动生命周期，并观察状态转换（先看到 `running` 再看到 `idle`），而不是把状态当作逐次 `followup()` 的结果：多次排队的 `followup()` 会在同一个 `running` 区间内连续运行多个轮次，而取消或资源释放可能丢弃尚未启动的项。这条守则是双向的：如果等待的转换永远不会发生（EOF 时没有提交过任何工作 → 永远不会进入 `running`），等待就会挂起——请显式处理「无需等待」的分支。
+
+## Dispose 必须达到完全停稳，而不仅仅是请求停止
+
+一个清理流程如果发出 kill/abort 后就返回、而不等待工作实际停止，就会留下孤儿进程。请让清理逻辑异步化并 await 子进程退出（kill → await `done`），并在 kill 之前关闭监听器/通知注册表，使迟到的完成事件保持静默。测试应证明 dispose 确实等待了（`await fiber.dispose()` 之后 pid 已不存在），而不仅仅是进程最终会死。
+
+## 在边界处包容回调异常
+
+用户提供的监听器如果抛出异常，不得导致它所在的 promise 被 reject，也不得饿死排在它后面的监听器。请用 try/catch 包裹分发循环并记录日志；一个行为不当的订阅者绝不能破坏核心生命周期。
+
+## 绝不将环境变量或可预测路径暴露给不可信输出
+
+spawn 的命令应获得一份经过清洗的 env（去除 `*KEY*`/`*SECRET*`/`*TOKEN*`），使 harness 凭证无法泄漏到输出、`env` 或溢出文件中。临时/溢出文件应使用私有（0700）目录、随机文件名和排他的仅所有者可访问打开方式（`'wx'`、`0o600`）——可预测的全局可读路径会招致符号链接竞争和信息泄露。
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index a04e633377..b36d390f55 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -8,22 +8,24 @@ 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:353`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | [`tui`](../packages/ui/tui) |
-| `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:217`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:179`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:188`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:365`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), `runtime`, [`tui`](../packages/ui/tui) |
-| `agent/post-step` | `serial` | [`packages/core/agent/src/types.ts:315`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy) |
-| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:246`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`time-context`](../packages/context/time-context), [`user-approval`](../packages/ui/user-approval) |
-| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:262`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`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) |
-| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:207`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:276`](../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:330`](../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), [`plan-mode`](../packages/plan/plan-mode) |
-| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:291`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`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:197`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), [`goal-session`](../packages/goal/goal-session), `runtime`, [`tui`](../packages/ui/tui) |
-| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:303`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
-| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:341`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode) |
-| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:352`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tool-goal`](../packages/goal/tool-goal) |
+| `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:350`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:285`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:294`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:498`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), `runtime`, [`tui`](../packages/ui/tui) |
+| `agent/inbox/dequeue` | `emit` | [`packages/core/agent/src/types.ts:326`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent) |
+| `agent/inbox/discard` | `emit` | [`packages/core/agent/src/types.ts:340`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent) |
+| `agent/inbox/enqueue` | `emit` | [`packages/core/agent/src/types.ts:316`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
+| `agent/post-step` | `serial` | [`packages/core/agent/src/types.ts:448`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy) |
+| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:379`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`time-context`](../packages/context/time-context), [`user-approval`](../packages/ui/user-approval) |
+| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:395`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`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) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:409`](../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:463`](../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), [`plan-mode`](../packages/plan/plan-mode) |
+| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:424`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:363`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`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:303`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), [`goal-session`](../packages/goal/goal-session), `runtime`, [`tui`](../packages/ui/tui) |
+| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:436`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:474`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode) |
+| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:485`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tool-goal`](../packages/goal/tool-goal) |
 | `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/ui/acp) |
 | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:103`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`tui`](../packages/ui/tui) |
 | `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) |
@@ -41,11 +43,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:130`](../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`) | - |
-| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:123`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:93`](../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/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:105`](../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), [`workspace-context`](../packages/context/workspace-context) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:82`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:113`](../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:143`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `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) |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:125`](../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), [`workspace-context`](../packages/context/workspace-context) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:102`](../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:133`](../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) |
@@ -57,7 +59,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 
 | Event string | Dispatchers | Listeners |
 | --- | --- | --- |
-| `internal/dispatch` | - | [`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), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`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` | - | [`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), [`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` | - | `webserver` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
 | `slots/changed` | `runtime` (`emit`) | - |
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
new file mode 100644
index 0000000000..b63e41b87b
--- /dev/null
+++ b/docs/glossary.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
+glossary.md: 0270a2d0dba558483e8e458a932a27b0151f2c93
+glossary.zh.md: ed3009a054815f1c7165fc322e44cc9521527643
diff --git a/docs/glossary.md b/docs/glossary.md
index e290543d2c..0270a2d0db 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -1,5 +1,7 @@
 # Glossary
 
+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.
@@ -19,7 +21,7 @@ FIXME(glossary-completeness): Expand this glossary before the first release so i
 ## goal
 
 - **goal** — one durable completion objective attached to an existing session, with a revisioned `active` / `paused` / `blocked` / `complete` phase and a goal-round cap; `blocked` retains a policy code and explanation. A goal is state, not a scheduler or a separate conversation; the session log remains its source of truth.
-- **goal round** — one continuation cycle admitted for the current goal. The same-session driver materializes a goal round as one goal-sourced [turn](#turn), which can contain multiple steps; unrelated human turns in the same session do not consume the goal-round cap. <a id="goal-round"></a>
+- **goal round** — one continuation cycle admitted for the current goal. The same-session driver materializes a goal round as one goal-sourced [turn](#turn), which can contain zero or more steps; unrelated human turns in the same session do not consume the goal-round cap. <a id="goal-round"></a>
 - **goal activation** — process-local permission for a continuation consumer to admit another goal round. Activation is either `armed` or `disarmed`; it is deliberately absent from durable replay, so resume and fork require a later human-authorized resume mutation through `/goal` or the model tool before automatic work.
 
 ## human command
@@ -31,7 +33,7 @@ FIXME(glossary-completeness): Expand this glossary before the first release so i
 ## loop hierarchy
 
 - **turn** — one drain of admitted input in a session, ending after the model and its tools stop or a terminal policy intervenes. <a id="turn"></a>
-- **step** — one model request plus the tool executions caused by its response; a turn contains one or more steps. <a id="step"></a>
+- **step** — one model request plus the tool executions caused by its response; a turn contains zero or more steps. <a id="step"></a>
 - **round** — an outer policy iteration containing a turn, such as a [goal round](#goal-round) or one fresh-agent Ralph attempt. Round counters belong to that policy and do not count every turn in a session. <a id="round"></a>
 
 ## Ralph
diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md
new file mode 100644
index 0000000000..ed3009a054
--- /dev/null
+++ b/docs/glossary.zh.md
@@ -0,0 +1,43 @@
+# 术语表
+
+[English](glossary.md) | 中文
+
+DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。各术语通过标准 Markdown 锚点链接到相应条目；实现细节留在各包（package）的 README 与 Agent Note（agent 决策记录）中。
+
+FIXME(glossary-completeness): 首次发布前扩充本术语表，使其覆盖 SDK 的其他核心与能力子系统，而非仅限于 agent scope。
+
+## agent-scope
+
+- **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 过滤分发。注册表主体事件可以在各自的事件契约下保持故意不过滤。
+- **scope carrier**：scope 过滤分发所携带的 `thisArg`（由 `scopeTarget` 构建）；其过滤器放行无标签监听器加上主体自身的监听器。*无主体*的 carrier（没有 key）只放行无标签监听器。
+- **scoped dispatch**：规则是：关于某个 agent 活动的事件以该 agent 的 carrier 进行分发。关于注册表本身的事件（如「一个工具被添加了」）属于*注册表主体*事件，保持不过滤。
+- **shadowing**：最具体者胜出的名称解析：一个有范围的工具/片段/变量仅在该 scope 内替换同名的全局对应项。这是按 agent 定制 persona 和按 agent 定制工具变体的机制。
+- **restriction / scope-local 注册**：restriction（`tools.restrict`）为单个 scope 过滤全局工具表面（多个 restriction 取交集组合）；scope-local 注册在过滤之后合并。被过滤掉的全局工具既不出现在提示词中，也拒绝执行，与不存在的工具无法区分。
+- **setup window**：创建者组装 agent 有范围世界的创建时隙（`CreateAgentOptions.setup`）：在 scope 和 agent 对象已存在、但 agent 或会话尚未发布、`agent/session-start` 尚未触发、首次提示词尚未组装之前。setup 只做注册，从不驱动 agent。
+- **lineage**：以数据形式携带的父子关系事实（`parentSession`、持久的 `delegationDepth`、运行时 `subagentDepth`）；从不影响可见性。<a id="lineage"></a>
+
+## 目标
+
+- **目标**：附着在现有会话上的单个持久完成目标，带有按修订号演进的 `active` / `paused` / `blocked` / `complete` 阶段和 Goal Round 上限；`blocked` 保留策略代码与说明。目标是一种状态，不是调度器，也不是一段独立对话；会话日志仍是其真源。
+- **Goal Round**：为当前目标接纳的一次续行周期。同会话驱动器将 Goal Round 具体化为一个来源为目标的[轮次](#turn)，其中可包含零个或多个步骤；同一会话中无关的人类轮次不消耗 Goal Round 上限。<a id="goal-round"></a>
+- **目标激活**：续行消费方接纳下一个 Goal Round 的进程本地权限。激活态为 `armed` 或 `disarmed`；它有意不参与持久回放，因此恢复和 fork 后，必须由人类随后通过 `/goal` 或模型工具授权恢复变更，自动工作才可开始。
+
+## 人类命令
+
+- **人类命令**：以斜杠开头的指令，由面向人类的适配器通过 `ctx.commands` 解释并执行，不会成为模型消息。它既不同于面向模型的工具，也不同于通过 `ctx.bash` 执行 shell 命令。
+- **命令平面**：由 UI 适配器与命令插件拥有的发现、解析、分发、取消和结果渲染。除非处理器另行改变持久领域，否则命令输出属于 UI 状态。
+- **目标命令**：`/goal` 是由 `dsh-command-goal` 提供的人类命令；它直接观察或更改当前目标，而目标领域拥有每条持久且模型可见的记录。
+
+## 循环层级
+
+- **轮次**：会话中一次对已接纳输入的排空过程，在模型及其工具停止工作或终止策略介入后结束。<a id="turn"></a>
+- **步骤**：一次模型请求，以及由模型响应引发的工具执行；一个轮次包含零个或多个步骤。<a id="step"></a>
+- **Round**：承载一个轮次的外层策略迭代，例如一个 [Goal Round](#goal-round) 或一次使用全新 agent 的 Ralph 尝试。Round 计数器归该策略所有，并不统计会话中的每个轮次。<a id="round"></a>
+
+## Ralph
+
+- **Ralph 循环**：一次面向不可变目标的前台全新 agent 工作流运行。它是由工作流和 subagent 原语组合而成的面向模型的工具策略，不是同会话目标、agent loop（智能体循环）模式、调度器或通用工作流脚本功能。<a id="ralph-loop"></a>
+- **Ralph Round**：[Ralph 循环](#ralph-loop)中的一个全新子会话。子会话不接收父会话或此前子会话的对话种子；共享工作区和一份有界的 [Ralph 交接](#ralph-handoff)承载跨 Round 的状态。<a id="ralph-round"></a>
+- **Ralph 交接**：从一个仍需继续的 Ralph Round 传给下一个 Ralph Round 的规范化、有界结构化报告，包含状态、摘要、证据、后续步骤和阻塞说明。它补充共享工作区，而不取代工作区的权威地位。<a id="ralph-handoff"></a>
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index 2a72aaa53e..602699a178 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
-README.md: c4ddf44ad2497b4ff371918356ab1ec0698c7049
-README.zh.md: 4a31af4fdee4db2d0362cf9117a6eef4fea32393
+README.md: 77d7b3210216c7c12d7d06b1ed16396d02ef1d16
+README.zh.md: de15fc3b5f30c1280ce6b38c1afd2475be7f9671
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index c4ddf44ad2..77d7b32102 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -40,7 +40,7 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
 
 **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`, and `docs/module-graph.md` — generated files; their generators emit English only today, so a hand-written translation would go stale on every regeneration. The planned follow-up is to teach the generators to emit Chinese alongside English, at which point these leave the exclusion list.
+- `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; their generators emit English only today, so a hand-written translation would go stale on every regeneration. The planned follow-up is to teach the generators to emit Chinese alongside English, at which point these leave the exclusion list.
 - `docs/AGENTS.md` and `.agents/notes/**/AGENTS.md` — 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.
@@ -49,4 +49,4 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
 
 ## 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 canonical rules into either direction and strictly parses the three-field XML response, while `verify-translation-prompt` exercises both render directions, the checked-in example, and the CDATA split rule 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, 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`.
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 4a31af4fde..de15fc3b5f 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -2,12 +2,12 @@
 
 [English](README.md) | 中文
 
-本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此 README、Agent Note 与 docs 目录树以英文和简体中文双语维护。本页定义配对契约、强制门禁与推进策略；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
+本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此 README、Agent Note（agent 决策记录）与 docs 目录树以英文和简体中文双语维护。本页定义配对契约、强制门禁与推进策略；[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）永远不会只带一种语言而缺其余两个文件。
+- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。
+- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。
 - **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：
 
   ```yaml
@@ -15,38 +15,38 @@
   foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b
   ```
 
-  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。记录的 hash 还能还原任一侧上次确认时的确切文本（`git cat-file -p <hash>`），所以失去同步的配对是「把被改的一侧与其上次确认状态做 diff、再最小化地修补另一侧」——从不整篇重译。两侧对齐后，`pnpm run verify-translation-pairing --write` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审。
-- **语言切换行。**两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
-- **结构与另一侧一一对应。**标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
+  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。记录的 hash 还能还原任一侧上次确认时的确切文本（`git cat-file -p <hash>`），所以失去同步的配对是「把被改的一侧与其上次确认状态做 diff、再最小化地修补另一侧」，从不整篇重译。两侧对齐后，`pnpm run verify-translation-pairing --write` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审。
+- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
+- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
 
 ## 门禁：verify-translation-pairing
 
 `pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：
 
 1. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个文件都有完整配对。
-2. 任何已存在的配对——无论是否 required——都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致——标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
+2. 任何已存在的配对（无论是否 required）都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
 3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。
-4. 凡文件名符合 `yyyy-mm-dd-*.md` 且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，都必须有完整配对——新建的日期命名 Agent Note 从创建起便须配齐中英文。
+4. 凡文件名符合 `yyyy-mm-dd-*.md` 且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，都必须有完整配对；新建的日期命名 Agent Note 从创建起便须配齐中英文。
 
-`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态——missing、out-of-sync 或 ok——是翻译批次的工作清单。它从不失败；它只报告。
+`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok），是翻译批次的工作清单。它从不失败；它只报告。
 
-这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write`），与本仓库既有的代码/README doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。
+这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。
 
-把门禁的边界说白：**门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。**它检查 hash 和形状；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然——那是契约中评审者的那一半，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
+把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
 
 ## 范围、排除与推进
 
-**范围**：根 `README.md`，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部内容。package README（`packages/**`）在后续批次加入范围。
+**范围**：根 `README.md`，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部内容。包（package）README（`packages/**`）在后续批次加入范围。
 
 **排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：
 
-- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md` 与 `docs/module-graph.md`——生成文件；生成器目前只输出英文，手写译文在每次重新生成时必然陈旧。计划中的后续工作是让生成器同时输出中文，届时这些文件移出排除清单。
-- `docs/AGENTS.md` 与 `.agents/notes/**/AGENTS.md`——agent 指令，与根 `AGENTS.md` 一样只以英文维护。
-- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)——二者本身即为中英对照文档。
-- [translation-prompt.md](translation-prompt.md)——自动翻译流水线的 prompt 模板；正文逐字进入模型请求，配对翻译会改变流水线行为。
+- `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`：生成文件；生成器目前只输出英文，手写译文在每次重新生成时必然陈旧。计划中的后续工作是让生成器同时输出中文，届时这些文件移出排除清单。
+- `docs/AGENTS.md` 与 `.agents/notes/**/AGENTS.md`：agent 指令，与根 `AGENTS.md` 一样只以英文维护。
+- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。
+- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。
 
-**推进**：以日期命名的文档（`yyyy-mm-dd-*.md`，即 Agent Note），只要标注日期等于或晚于 manifest 的 `requiredSince` 分界日期，合入时就必须配齐双语文件。更早日期的文件属于 backlog（待翻清单），包括分界前夜创建的文件。Agent Note 文件名记录首次提出日期，因此倒填日期绕过分界属于评审可见的违规。manifest 中的 `required` 列表是当前执行红线，并非全量覆盖这一最终目标。翻译批次将路径加入 `required`，使门禁只向前收紧。未列入的文档仍可通过 `--list` 查看，而任何已存在的配对都受完整契约约束。后续修改必须同步更新两侧，因此 `required` 的扩展速度不能超过翻译评审的承载能力。
+**推进**：以日期命名的文档（`yyyy-mm-dd-*.md`，即 Agent Note），只要标注日期等于或晚于 manifest 的 `requiredSince` 分界日期，合并时就必须配齐双语文件。更早日期的文件属于 backlog（待翻清单），包括分界前夜创建的文件。Agent Note 文件名记录首次提出日期，因此倒填日期绕过分界属于评审可见的违规。manifest 中的 `required` 列表是当前执行红线，并非全量覆盖这一最终目标。翻译批次将路径加入 `required`，使门禁只向前收紧。未列入的文档仍可通过 `--list` 查看，而任何已存在的配对都受完整契约约束。后续修改必须同步更新两侧，因此 `required` 的扩展速度不能超过翻译评审的承载能力。
 
 ## 分工
 
-对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。prompt 契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把权威规则渲染到英译中或中译英的 prompt 中，并严格解析包含三个字段的 XML 响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向、仓库内示例与 CDATA 拆分规则。
+这里的对侧文件由运行 [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 dd970b7c12..b20b2a4c90 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -28,9 +28,9 @@
 
 **dispose（资源释放）必须等待所有任务完全停稳，不能仅下发终止指令就返回**：如果清理过程只发出终止或中断信号，却不等任务停止就返回，就会留下孤儿进程。清理应采用异步方式，等待所有子任务彻底退出（先发出终止信号，再等待退出）；发出信号前应先关闭监听器与通知注册表，使延迟到达的完成事件不再触发通知。测试要证明 dispose 的确等到清理完成：执行完 `await fiber.dispose()` 后进程 PID 立即消失，不能只检查进程最终会自行消亡。
 
-> **Async state is not synchronous state** — `agent.send()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) instead of treating status as a per-send result: several queued sends run as consecutive turns under one `running` interval, while cancellation or disposal can discard unstarted items.
+> **Async state is not synchronous state** — `agent.followup()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) instead of treating status as a per-follow-up result: several queued follow-ups run as consecutive turns under one `running` interval, while cancellation or disposal can discard unstarted items.
 
-**异步状态不等同于同步瞬时状态**：调用 `agent.send()` 不会在返回前同步更新状态；后台任务的完成时间与轮次边界存在竞态；`reader.close()` 既会在读到文件末尾时触发，也会在资源释放时触发。切勿把刚刚发起的状态变更当成已经生效，据此控制流程；生命周期逻辑应以实际触发的事件和已完成的 promise（`agent/status`、`task.done`）为准，并观察完整的状态变化（先 `running`，再 `idle`），不要把状态当作逐次 `send()` 的结果：多次排队的 `send()` 会作为连续轮次运行，但可能共用一个 `running` 区间；取消或资源释放还可能丢弃尚未启动的队列项。
+**异步状态不等同于同步瞬时状态**：调用 `agent.followup()` 不会在返回前同步更新状态；后台任务的完成时间与轮次边界存在竞态；`reader.close()` 既会在读到文件末尾时触发，也会在资源释放时触发。切勿把刚刚发起的状态变更当成已经生效，据此控制流程；生命周期逻辑应以实际触发的事件和已完成的 promise（`agent/status`、`task.done`）为准，并观察完整的状态变化（先 `running`，再 `idle`），不要把状态当作逐次 `followup()` 的结果：多次排队的 `followup()` 会作为连续轮次运行，但可能共用一个 `running` 区间；取消或资源释放还可能丢弃尚未启动的队列项。
 
 ## ③ 测试政策清单
 
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 74ce7ad969..ae28258b9b 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -52,6 +52,7 @@
 | loader | loader | | | |
 | manifest | manifest | manifest（元数据清单） | | |
 | monorepo | monorepo | | | |
+| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |
 | schema | schema | | | |
 | schema DSL | schema DSL | | | |
 | seam | seam | | | 与 `extension point` 是不同概念；根据具体语境，可译为`服务边界`或`可替换点` |
@@ -103,10 +104,12 @@
 | durability | 持久性 | | | |
 | feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |
 | enforcement frontier | 执行红线 | | 强制边界 | i18n 配对机制用语：manifest `required` 清单所划的门禁生效范围；与金标样例（style-samples ⑦）一致 |
+| ergonomics | 易用性 / 开发体验 | | 人体工学 | API 或面向模型的接口用「易用性」；工具链或开发者工作流用「开发体验」 |
 | event | 事件 | | | |
 | event log | 事件日志 | | | |
 | event stream | 事件流 | | | |
 | event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |
+| Executive summary | 摘要 | | | 事故复盘标题用语 |
 | executor | 执行器 | | | |
 | expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |
 | extension | 扩展 | | | |
@@ -131,11 +134,14 @@
 | mod | 模组 | | | |
 | model provider | 模型提供方 | | | |
 | module | 模块 | | | |
+| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |
 | npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
+| opt-out ratio | opt-out 比例 | | 退出检查比例 | |
 | orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |
 | orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
 | package | 包 | 包（package） | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |
 | pairing | 配对 | | | |
+| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |
 | peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |
 | permission | 权限 | | | |
 | persistence | 持久化 | | | |
@@ -145,12 +151,14 @@
 | provider | 提供方 | | | |
 | provider-neutral | 提供方无关 | | | |
 | quality gate | 质量门禁 | | | |
+| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |
 | reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |
 | reasoning_content | 思考内容 | | | |
 | registry | 注册表 | | | |
 | replay | 回放 | | | |
 | resume | 恢复 | | | |
 | runtime | 运行时 | | | |
+| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |
 | sandbox | 沙箱 | | | |
 | service | 服务 | | | |
 | serving surface | 对外服务接口 | | | |
@@ -167,6 +175,7 @@
 | stream | 流 | | | |
 | streaming | 流式输出 | | | |
 | structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |
+| Summary | 概述 | | | 事故复盘标题用语 |
 | system prompt | 系统提示词 | | | |
 | taxonomy | 分类体系 | | | |
 | token usage | token 用量 | | | |
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index e7943bedae..d0e17c87a9 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) 排除清单）。渲染时会把 [translation-rules.md](translation-rules.md) 全文填入 `{{translation_rules}}`，把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`，以免模板另存一份规则而日后失去同步。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题；术语表、忠实性和结构规则优先于样例，样例只在这些硬性约束内决定文体。修改本文件会改变翻译行为，需正常经过 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 评审。
 
 ## 占位符契约
 
@@ -10,18 +10,15 @@
 |---|---|---|
 | `{{source_lang}}` | 源语言名（`English` / `Chinese`） | 由改动侧文件推断：`.zh.md` 被改则为 `Chinese` |
 | `{{target_lang}}` | 目标语言名（`Chinese` / `English`） | 与 `{{source_lang}}` 相对 |
-| `{{translation_rules}}` | [translation-rules.md](translation-rules.md) 全文（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
 | `{{terminology}}` | [terminology.md](terminology.md) 的完整表格（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
-| `{{source_filename}}` | 源文档的 basename（如 `foo.md` 或 `foo.zh.md`） | 由流水线从待译文件路径取得 |
-| `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 英文源追加 `.zh`；中文源使用自身 basename |
 
-例如，英译中时若源文件是 `foo.md`，`{{source_filename}}` 填 `foo.md`，`{{source_filename_zh}}` 填 `foo.zh.md`；中译英时若源文件是 `foo.zh.md`，两个占位符都填 `foo.zh.md`。
+流水线只识别上表中的占位符，并且一次翻译整篇文档。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}`、`{{translation_rules}}` 或 `%%` 分段协议；输出采用模板正文规定的三段 XML，流水线解析取 `<final>` 段。
 
-流水线只识别上表中的占位符，并且一次翻译整篇文档。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 或 `%%` 分段协议。输出必须是一个以 `<dsh-translation-response>` 为根元素的 XML 文档；三个子元素中的 Markdown 内容都放在 CDATA 中。内容出现 `]]>` 时写成 `]]]]><![CDATA[>`，XML 解析后仍会还原为原文。
+语言切换行：已有配对的源文件自带切换行，模型按模板规则翻转即可。全新配对的源文件没有切换行，模型也无从得知文件名——此时由流水线在解析 `<final>` 后按目标文件名插入或校正切换行（机械后处理，配对门禁兜底校验）。
 
 ## Few-shot 金标
 
-流水线使用**整篇文档**的中英对照作为 few-shot，不是模板内嵌的句子级正误例。以下 5 组配对文档均经过人工评审，并以仓库当前版本为准，随仓库一同更新：
+流水线使用**整篇文档**的中英对照作为 few-shot，不是模板内嵌的句子级正误例。以下 5 组配对文档均经过人工评审，以仓库当前版本为准、随仓库更新：
 
 - `README.md` ↔ `README.zh.md`
 - `docs/development.md` ↔ `docs/development.zh.md`
@@ -29,58 +26,135 @@
 - `docs/i18n/translation-rules.md` ↔ `docs/i18n/translation-rules.zh.md`
 - `.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md` ↔ 对应 `.zh.md`
 
-注入时按当前翻译方向选择每组的源侧与目标侧：user 消息包含源文档全文，assistant 消息采用模板正文规定的 XML 协议；`translation` 与 `final` 都放入目标文档全文，`review` 填 `- [None] No corrections.`。CDATA 遵循上文的 `]]>` 拆分规则。上下文不足时，按上列顺序从后往前删减示例组数。这 5 组也是评审校准锚点；改动任何一组都会改变流水线行为。
+注入方式：在系统消息（本模板）之后、待译文档之前，每组作为一轮示例对话——user 消息为源文档全文，assistant 消息为定稿译文全文（裸文本，不带三段 XML 包装；只有真实请求要求三段输出）。上下文不足时按上列顺序从后往前删减组数。这 5 组也是评审校准锚点（见 [style-samples.md](style-samples.md)），改动任何一组即改变流水线行为。
 
 ## 模板正文
 
 ````text
 # Translation Prompt
 
-You are a senior technical translator specializing in LLM and agent development documentation. Translate the complete source document from {{source_lang}} to {{target_lang}} as natural, professional technical prose.
+You are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the given source document from {{source_lang}} to {{target_lang}}, producing natural, professional technical prose.
 
-## Binding Translation Rules
+## Quality Requirements
 
-The canonical repository rules below are injected verbatim. Apply every direction-appropriate requirement. In those rules, the authored document is the source for this request and the generated document is its counterpart.
+### Structure and Format Preservation
+- Output a complete translated document that maintains exactly the same structure as the source: heading hierarchy, list shape, table columns, link targets, and code blocks.
+- Fenced code blocks must be byte-identical to the source, including ALL comments inside them. Do NOT translate comments inside code blocks. This is a hard rule with no exceptions.
+- Inline code spans (commands, flags, paths, API names, version numbers) must be kept verbatim. Never translate or reformat them.
+- Every relative link must point to the same target as in the source. Link text is translated; link targets are not.
+- Language switcher line: when translating into Chinese, write `[English](source-filename.md) | 中文`. When translating into English, write `English | [中文](source-filename.zh.md)`. Do NOT copy the switcher line from the source file unchanged — you must flip the link direction.
+- After a closing bold marker `**`, insert a space before the next character when that character is a Latin letter, digit, or CJK ideograph. Never insert a space before any punctuation (full-width or half-width).
 
-{{translation_rules}}
+### Tone and Style
+- The translation must read as if originally written in the target language by a native speaker. If an expression sounds like a word-for-word rendering from the source language, rephrase it.
+- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.
+- Use polite imperative forms where the text instructs the reader to do something.
+- Keep the author's register: concise stays concise, detailed stays detailed.
 
-## Request-Specific Structure
+### Sentence Structure
+- Break long sentences with commas or semicolons. Avoid run-on sentences.
+- Prefer active voice. Convert passive constructions to active if it reads more naturally.
+- Translate meaning, not words. Restructure sentences where the target language grammar requires it.
+- Do not invent words or expressions that do not exist in natural technical writing of the target language.
 
-- The source basename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1.
-- Emit the switcher for a new pair and flip an existing switcher; never copy it unchanged.
+### Word Choice
+- Prefer precise, formal vocabulary over casual or colloquial alternatives.
+- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.
+- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.
+- Do not use the same word to translate two different source-language terms that carry distinct meanings.
+- Avoid repeating the same verb in close proximity; vary word choice for readability.
 
-## Binding Terminology
+#### When translating into Chinese
+- When a number modifies a noun, always include a Chinese classifier or measure word (量词). For example: "three-package seam" → "由三个包构成的 seam", not "三包 seam".
 
-Apply the current table below exactly as required by the injected translation rules.
+### Punctuation
+
+#### When translating into Chinese
+- Use full-width Chinese punctuation in prose: `，。：；？！（）「」`.
+- Strongly prefer replacing all em-dashes (——) with colons, periods, commas, or parentheses. Keep an em-dash only if no other punctuation works at all.
+- Use enumeration commas (、) between parallel items, not regular commas.
+- List item endings: use semicolons or no punctuation. Do not end list items with commas.
+- Put one half-width space between Chinese text and Latin words/numbers.
+- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以) and keep the SOURCE emphasis marker: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).
+
+#### When translating into English
+(To be added.)
+
+## Terminology
+
+A terminology table is provided below. Follow it strictly:
+- Render every listed term exactly as specified.
+- When the target language is Chinese, use the "中文" column. On first occurrence, write the "首次出现" value with its parenthetical gloss; on subsequent occurrences, write only the part before the parentheses.
+- When the target language is English, use the "English" column without a Chinese gloss; do not copy the "中文" or "首次出现" value into English prose.
+- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.
+- NEVER use translations listed in the "不要译作" column.
+- For technical terms not in the table, follow the target language: for a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source, or keep the source term and flag it as pending when no such precedent exists; for an English target, use the established English technical term, or preserve an ambiguous source term with a short English gloss and flag it as pending. Do not invent a translation. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.
 
 {{terminology}}
 
 ## Output Format
 
-Return exactly one well-formed XML document with this root and these three child elements. Do not wrap it in a Markdown code fence. Put all Markdown and review text inside CDATA. If any content contains the CDATA terminator, split it as `]]]]><![CDATA[>` so XML parsing reconstructs the original `]]>` sequence.
+Produce your output in three XML sections:
+
+The 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.
 
 ```xml
-<dsh-translation-response version="1">
-<translation><![CDATA[
-(Complete first-pass translation)
-]]></translation>
-<review><![CDATA[
-- [Tone] Replaced a literal rendering with the established target-language phrasing.
-- [Terminology] Applied the binding sidecar record term.
-]]></review>
-<final><![CDATA[
-(Complete corrected translation)
-]]></final>
-</dsh-translation-response>
+<translation>
+(Complete translation of the source document)
+</translation>
+
+<review>
+(Self-review notes, one correction per line with category tag, e.g.)
+- [Tone] "旁挂记录" → "伴随记录"（生造词）
+- [Sentence] 第 3 段补充逗号断句
+- [Punctuation] 两处破折号替换为冒号
+- 无修正
+</review>
+
+<final>
+(Final translation after corrections)
+</final>
 ```
 
 ## Self-Review Instructions
 
-After writing `<translation>`, re-read it in the target language without looking at the source. Then apply the injected translation rules as a clause-by-clause comparison against the source and record actual corrections in English inside `<review>`. Apply every recorded correction in `<final>`. If no correction is needed, write only `- [None] No corrections.` in `<review>` and copy `<translation>` unchanged into `<final>`.
+After writing `<translation>`, re-read it in the target language only, without looking at the source. Check by category:
+
+**Structure**
+- Is the heading hierarchy, list shape, and code block content identical to the source?
+- Are ALL comments inside code blocks left untranslated (byte-identical to source)?
+- Is the language switcher line correctly flipped (not copied from source)?
+- Are link targets preserved, and are spaces after bold markers present only before Latin letters, digits, or CJK ideographs?
+- Are wrapper-tag lines inside section bodies escaped with one additional backslash?
+
+**Tone & Style**
+- Does every sentence read as if originally written by a native speaker?
+- Is there any colloquial, casual, or overly informal phrasing?
+
+**Sentence Structure**
+- Are there run-on sentences that need breaking?
+- Are there stiff passive constructions that should be converted to active voice?
+
+**Word Choice**
+- Are there overly literal translations that sound unnatural?
+- Is the same target-language word used to translate two distinct source concepts?
+- Is any slang or internal jargon present?
+
+**Terminology**
+- For a Chinese target, are first-occurrence glosses correctly applied (not missing, not repeated)? For an English target, are Chinese glosses absent?
+- Are any "不要译作" forbidden translations present?
+- For unlisted terms, does a Chinese target use established Chinese precedent or retain the source term as pending, and does an English target use established English terminology or preserve only an ambiguous source term with a short English gloss?
+
+**Punctuation** (when target is Chinese)
+- Are there em-dashes that should be replaced with colons, periods, or commas?
+- Are list items ending with commas instead of semicolons?
+- Do RFC 2119 keywords preserve the source emphasis exactly?
+
+Record corrections in `<review>` with category tags. Then output the corrected version in `<final>`. If no corrections are needed, write "无修正" in `<review>` and copy the translation unchanged into `<final>`.
 
 ## Examples
 
-Follow the Good versions; these sentence-level examples illustrate error categories, not the assistant-message wire format.
+Below are representative examples of common problems and their corrections. Follow the "Good" versions.
 
 ### Colloquial verb → Professional verb
 - Source: `The repo pins pnpm@11.7.0 in package.json`
@@ -102,40 +176,40 @@ Follow the Good versions; these sentence-level examples illustrate error categor
 - Bad: `旁挂记录两侧 blob hash，使一致性可检查`
 - Good: `伴随记录保存两侧 blob hash，使一致性可检查`
 
+### Em-dash → Colon/period
+- 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.`
+- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`
+- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`
+
 ### Overly literal → Meaningful rendering
 - Source: `awkward phrasing is easier to hear without the source anchoring you`
 - Bad: `没有源文锚着，别扭的表述更容易被听出来`
 - Good: `不对照原文时，更容易察觉别扭的表达`
 
-### Terminology — keep the binding English form
+### Terminology — do not translate what should be kept in English
 - Source: `typed service seams, and explicit extension points`
 - Bad: `类型化的服务 seam（扩展点）与显式扩展点`
 - Good: `类型化的服务 seam 与显式扩展点`
 
-### Slang → Professional phrasing
+### Slang/jargon → Professional phrasing
 - Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`
 - Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`
 - Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`
 
-### Chinese → English — idiomatic subject and predicate
-- Source: `门禁绿并不代表译文内容正确。`
-- Bad: `The gate green does not represent that the translation content is correct.`
-- Good: `A green gate does not mean the translation is correct.`
+### "For humans" — translate the intent, not the word
+- Source: `For humans, start with the development guide`
+- Bad: `对于人工读者，请先从开发指南开始`（"人工读者"生硬）
+- Good: `面向开发者：请先阅读开发指南`（"开发者"自然，且中文里冒号在此处更自然）
 
-### Code block comments — never translate
+### Code block comments — NEVER translate
 - Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`
 - Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`
-- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (byte-identical)
+- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)
 
-### Language switcher — English to Chinese
-- Source: `English | [中文](README.zh.md)`
-- Bad: `English | [中文](README.zh.md)`
-- Good: `[English](README.md) | 中文`
-
-### Language switcher — Chinese to English
-- Source: `[English](README.md) | 中文`
-- Bad: `[English](README.md) | 中文`
-- Good: `English | [中文](README.zh.md)`
+### Language switcher — flip direction
+- Source file (English) has: `English | [中文](README.zh.md)`
+- Bad (copying source unchanged): `English | [中文](README.zh.md)`
+- Good (flipped for Chinese file): `[English](README.md) | 中文`
 
 ---
 
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 24fc34b890..212fd723a7 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -105,6 +105,7 @@ flowchart TD
   end
   subgraph group_session_query["packages/session-query"]
     pkg_session_query["session-query"]
+    pkg_session_query_sqlite["session-query-sqlite"]
   end
   subgraph group_session_title["packages/session-title"]
     pkg_session_title["session-title"]
@@ -132,11 +133,14 @@ flowchart TD
   end
   subgraph group_client["packages/client"]
     pkg_client_connection["client-connection"]
+    pkg_client_hmr["client-hmr"]
     pkg_client_i18n["client-i18n"]
+    pkg_client_modules["client-modules"]
     pkg_client_runtime["client-runtime"]
     pkg_client_ui_conversation["client-ui-conversation"]
     pkg_client_ui_layout["client-ui-layout"]
     pkg_client_ui_primitives["client-ui-primitives"]
+    pkg_client_ui_question["client-ui-question"]
     pkg_client_ui_sidebar["client-ui-sidebar"]
     pkg_client_ui_slots["client-ui-slots"]
     pkg_client_ui_theme["client-ui-theme"]
@@ -212,11 +216,10 @@ flowchart TD
   pkg_loader_smoke --> pkg_invariants
   pkg_client_connection --> pkg_invariants
   pkg_client_i18n --> pkg_invariants
+  pkg_client_modules --> pkg_invariants
   pkg_client_runtime --> pkg_invariants
-  pkg_client_ui_conversation --> pkg_invariants
-  pkg_client_ui_layout --> pkg_invariants
   pkg_client_ui_primitives --> pkg_invariants
-  pkg_client_ui_sidebar --> pkg_invariants
+  pkg_client_ui_question --> pkg_invariants
   pkg_client_ui_slots --> pkg_invariants
   pkg_client_ui_theme --> pkg_invariants
   pkg_client_ui_trajectory --> pkg_invariants
@@ -229,8 +232,19 @@ flowchart TD
   pkg_host_webserver --> pkg_invariants
   pkg_llm --> pkg_brand
   pkg_llm --> pkg_invariants
-  pkg_code_runtime_worker --> pkg_code_runtime
-  pkg_code_runtime_worker --> pkg_invariants
+  pkg_client_hmr --> pkg_client_modules
+  pkg_client_hmr --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_layout --> pkg_client_runtime
+  pkg_client_ui_layout --> pkg_client_ui_slots
+  pkg_client_ui_layout --> pkg_invariants
+  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_helper --> pkg_brand
   pkg_helper --> pkg_invariants
   pkg_telemetry --> pkg_brand
@@ -290,6 +304,7 @@ 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_title --> pkg_brand
@@ -302,6 +317,9 @@ flowchart TD
   pkg_app_boot --> pkg_invariants
   pkg_app_boot --> pkg_paths
   pkg_app_boot --> pkg_system_prompt
+  pkg_code_runtime_worker --> pkg_code_runtime
+  pkg_code_runtime_worker --> pkg_invariants
+  pkg_code_runtime_worker --> pkg_session
   pkg_lsp_local --> pkg_brand
   pkg_lsp_local --> pkg_invariants
   pkg_lsp_local --> pkg_llm
@@ -353,6 +371,7 @@ flowchart TD
   pkg_session_persistence_sqlite --> pkg_invariants
   pkg_session_persistence_sqlite --> pkg_session
   pkg_session_persistence_sqlite --> pkg_session_persistence
+  pkg_session_query --> pkg_brand
   pkg_session_query --> pkg_invariants
   pkg_session_query --> pkg_llm
   pkg_session_query --> pkg_session
@@ -420,6 +439,10 @@ flowchart TD
   pkg_fs_sandbox --> pkg_invariants
   pkg_fs_sandbox --> pkg_sandbox
   pkg_fs_sandbox --> pkg_sandbox_policy
+  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_session_title_all_messages_llm --> pkg_invariants
   pkg_session_title_all_messages_llm --> pkg_llm
   pkg_session_title_all_messages_llm --> pkg_session
@@ -443,10 +466,12 @@ flowchart TD
   pkg_session_reference --> pkg_retention
   pkg_session_reference --> pkg_session
   pkg_session_reference --> pkg_session_query
+  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_agent_loop --> pkg_agent
   pkg_agent_loop --> pkg_invariants
   pkg_agent_loop --> pkg_llm
@@ -578,11 +603,13 @@ flowchart TD
   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_tasks --> pkg_agent
   pkg_tool_tasks --> pkg_invariants
+  pkg_tool_tasks --> pkg_retention
   pkg_tool_tasks --> pkg_system_prompt
   pkg_tool_tasks --> pkg_tasks
   pkg_tool_tasks --> pkg_tools
@@ -647,11 +674,13 @@ flowchart TD
   pkg_tui --> pkg_agent
   pkg_tui --> pkg_agent_loop
   pkg_tui --> pkg_commands
+  pkg_tui --> pkg_goal
   pkg_tui --> pkg_invariants
   pkg_tui --> pkg_llm
   pkg_tui --> pkg_llm_retry
   pkg_tui --> pkg_session
   pkg_tui --> pkg_session_persistence
+  pkg_tui --> pkg_session_query
   pkg_tui --> pkg_session_reference
   pkg_tui --> pkg_session_title
   pkg_tui --> pkg_skill
@@ -712,6 +741,7 @@ flowchart TD
   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_session_reference
   pkg_acp_demo --> pkg_tools
   pkg_acp_demo --> pkg_user_interaction
@@ -738,6 +768,7 @@ flowchart TD
   pkg_tui_demo --> pkg_session_checkpoint_policy
   pkg_tui_demo --> pkg_session_persistence_jsonl
   pkg_tui_demo --> pkg_session_query
+  pkg_tui_demo --> pkg_session_query_sqlite
   pkg_tui_demo --> pkg_session_reference
   pkg_tui_demo --> pkg_tool_ask_user
   pkg_tui_demo --> pkg_tools
@@ -760,11 +791,10 @@ flowchart TD
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`invariants`](../packages/support/invariants) |
 | [`client-connection`](../packages/client/connection) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-i18n`](../packages/client/i18n) | `client` | [`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-ui-conversation`](../packages/client/ui-conversation) | `client` | [`invariants`](../packages/support/invariants) |
-| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | [`invariants`](../packages/support/invariants) |
-| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-question`](../packages/client/ui-question) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-ui-slots`](../packages/client/ui-slots) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`invariants`](../packages/support/invariants) |
@@ -776,7 +806,10 @@ flowchart TD
 | [`host-runtime`](../packages/host/runtime) | `host` | [`invariants`](../packages/support/invariants) |
 | [`host-webserver`](../packages/host/webserver) | `host` | [`invariants`](../packages/support/invariants) |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`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) |
+| [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`invariants`](../packages/support/invariants) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `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-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout) |
@@ -797,10 +830,11 @@ flowchart TD
 | [`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) |
 | [`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` | [`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) |
 | [`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) |
 | [`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) |
+| [`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) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
@@ -815,7 +849,7 @@ flowchart TD
 | [`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-query`](../packages/session-query/session-query) | `session-query` | [`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-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) |
 | [`commands`](../packages/ui/commands) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope) |
 | [`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) |
@@ -830,11 +864,12 @@ 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) |
+| [`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) |
 | [`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) |
 | [`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) |
 | [`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) |
-| [`pty-local`](../packages/pty/pty-local) | `pty` | [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
+| [`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) |
 | [`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) |
@@ -856,8 +891,8 @@ flowchart TD
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
 | [`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), [`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), [`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), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`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), [`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) |
 | [`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), [`subagent-subprocess`](../packages/subagent/subagent-subprocess) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -865,12 +900,12 @@ flowchart TD
 | [`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) |
 | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`user-interaction`](../packages/ui/user-interaction) |
 | [`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), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`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`](../packages/tasks/tasks), [`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) |
 | [`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-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) |
-| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/ui/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`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-reference`](../packages/context/session-reference), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
+| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/ui/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`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), [`session-reference`](../packages/context/session-reference), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction), [`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), [`app-boot`](../packages/ui/app-boot), [`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-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), [`app-boot`](../packages/ui/app-boot), [`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) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index b5a3c60463..973238d905 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -24,14 +24,13 @@ export type SurfaceEventType =
   | 'user/message'
   | 'assistant/message'
   | 'tool/result'
-  | 'context/message'
   | 'steering/message'
 
 /**
  * How a session event entered the ordered surface. Only valid on
  * {@link SurfaceEventType} events.
  *
- * - `'append'`: added to the tail — normal path for user/assistant/tool/context
+ * - `'append'`: added to the tail — normal path for user/assistant/tool/steering
  *   messages.
  * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
@@ -51,7 +50,7 @@ export type SurfaceOp =
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
  * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`, `context/message`, `steering/message`).
+ * `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.
@@ -79,7 +78,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-Sources: [`packages/core/session/src/types.ts:307`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:320`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:350`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:382`](../packages/core/session/src/types.ts)
+Sources: [`packages/core/session/src/types.ts:325`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:338`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:367`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:399`](../packages/core/session/src/types.ts)
 
 ## Events
 
@@ -151,7 +150,7 @@ Source: [`packages/ui/user-approval/src/index.ts:67`](../packages/ui/user-approv
 
 Types: [StreamChunk](core-data-structures/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:271`](../packages/core/session/src/types.ts)
 
 #### `assistant/message` — surface
 
@@ -167,7 +166,7 @@ Source: [`packages/core/session/src/types.ts:263`](../packages/core/session/src/
 
 Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:270`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:278`](../packages/core/session/src/types.ts)
 
 ### `compact/*`
 
@@ -221,33 +220,6 @@ Types: [ContentBlock](core-data-structures/core.md)
 
 Source: [`packages/compact/compact/src/types.ts:22`](../packages/compact/compact/src/types.ts)
 
-### `context/*`
-
-#### `context/message` — surface
-
-```ts persistence-catalog
-/**
- * In-session context injection (file-change notices, subdir AGENTS.md,
- * skill content, cron notifications, …). Rendered into the derived history
- * as a synthetic user-role message carrying `content` verbatim — NOT a
- * user prompt. `meta` is durable JSON state omitted from the model
- * projection; it is also the intended channel for any future framing
- * directive (a producer declares the frame, a dedicated renderer applies it —
- * see the deferred note in
- * ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md),
- * so the surface keeps projecting `content` verbatim rather than wrapping it.
- */
-'context/message': {
-  content: ContentBlock[]
-  source: MessageSource
-  meta?: JsonValue
-}
-```
-
-Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
-
-Source: [`packages/core/session/src/types.ts:257`](../packages/core/session/src/types.ts)
-
 ### `hook/*`
 
 #### `hook/invoked` — log-only
@@ -341,7 +313,7 @@ Source: [`packages/ui/permission/src/index.ts:36`](../packages/ui/permission/src
 'plan/mode': { active: boolean }
 ```
 
-Source: [`packages/plan/plan-mode/src/index.ts:40`](../packages/plan/plan-mode/src/index.ts)
+Source: [`packages/plan/plan-mode/src/index.ts:41`](../packages/plan/plan-mode/src/index.ts)
 
 ### `prompt/*`
 
@@ -357,7 +329,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:40`](../packages/plan/plan-mode/s
 
 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:269`](../packages/core/session/src/types.ts)
 
 ### `request/*`
 
@@ -371,7 +343,7 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/
 'request/header': { header: EpochHeader; reason: RequestHeaderReason }
 ```
 
-Source: [`packages/core/session/src/types.ts:295`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:313`](../packages/core/session/src/types.ts)
 
 ### `sandbox/*`
 
@@ -427,7 +399,7 @@ Source: [`packages/session-title/session-title-llm/src/index.ts:44`](../packages
 'steering/message': PromptMessageData & { turn: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:288`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:306`](../packages/core/session/src/types.ts)
 
 ### `step/*`
 
@@ -438,7 +410,7 @@ Source: [`packages/core/session/src/types.ts:288`](../packages/core/session/src/
 'step/end': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:254`](../packages/core/session/src/types.ts)
 
 #### `step/start` — log-only
 
@@ -447,7 +419,7 @@ Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/
 'step/start': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:236`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:252`](../packages/core/session/src/types.ts)
 
 ### `todo/*`
 
@@ -460,7 +432,7 @@ Source: [`packages/core/session/src/types.ts:236`](../packages/core/session/src/
 
 Types: [TodoItem](core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:290`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts)
 
 ### `tool/*`
 
@@ -477,7 +449,7 @@ Source: [`packages/core/session/src/types.ts:290`](../packages/core/session/src/
 
 Types: [CallId](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:276`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:284`](../packages/core/session/src/types.ts)
 
 #### `tool/code-dispatch` — log-only
 
@@ -508,20 +480,30 @@ Source: [`packages/core/tools/src/code-mode.ts:34`](../packages/core/tools/src/c
 
 ```ts persistence-catalog
 /**
- * A completed tool call's model-facing result, plus an optional tool-private
- * `meta` presentation payload. `meta` is opaque to the core (`unknown` — the
- * producing tool owns its shape and reads it back in `presentResult`) but MUST
- * be JSON-serializable: `Session.append` runtime-validates all event data with
- * `isJsonValue`, so a non-serializable `meta` is rejected at the source, and the
- * durable log reproduces the identical card on replay. Absent unless the tool
- * attaches one (e.g. `dsh-tool-fs` carries its result-time contextual diff here).
+ * 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; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
+'tool/result': {
+  turn: number
+  step: number
+  callId: CallId
+  content: ContentBlock[]
+  isError: boolean
+  error?: { name: string; code: string }
+  meta?: JsonValue
+}
 ```
 
 Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:286`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts)
 
 ### `turn/*`
 
@@ -539,7 +521,7 @@ Source: [`packages/core/session/src/types.ts:286`](../packages/core/session/src/
 
 Types: [TurnEndReason](core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:234`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:250`](../packages/core/session/src/types.ts)
 
 #### `turn/start` — log-only
 
@@ -555,15 +537,23 @@ Source: [`packages/core/session/src/types.ts:234`](../packages/core/session/src/
 
 Types: [TurnTrigger](core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:227`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:243`](../packages/core/session/src/types.ts)
 
 ### `user/*`
 
 #### `user/message` — surface
 
 ```ts persistence-catalog
-/** A user-visible prompt (the queued message claimed for this turn). */
+/**
+ * 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 admitted goal continuation round. All three
+ * project their `content` verbatim; `source` (with a non-`user` kind marking
+ * injected context) is the only channel that tells them apart. An idle
+ * injection wraps this event in a one-shot turn so the log stays turn-enclosed.
+ */
 'user/message': PromptMessageData
 ```
 
-Source: [`packages/core/session/src/types.ts:240`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:264`](../packages/core/session/src/types.ts)
diff --git a/docs/postmortem/0001-acp-default-export-drops-inject.i18n.yaml b/docs/postmortem/0001-acp-default-export-drops-inject.i18n.yaml
new file mode 100644
index 0000000000..d48af64198
--- /dev/null
+++ b/docs/postmortem/0001-acp-default-export-drops-inject.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
+0001-acp-default-export-drops-inject.md: ab3efc880cb5290dc149b6bacb276ccf581968c1
+0001-acp-default-export-drops-inject.zh.md: 763b2e6230cf42dcd6985df3d7e2da8766176fd5
diff --git a/docs/postmortem/0001-acp-default-export-drops-inject.md b/docs/postmortem/0001-acp-default-export-drops-inject.md
index 10e88c390c..ab3efc880c 100644
--- a/docs/postmortem/0001-acp-default-export-drops-inject.md
+++ b/docs/postmortem/0001-acp-default-export-drops-inject.md
@@ -1,5 +1,7 @@
 # Post-mortem 0001: ACP server crashed on connect — `export default` dropped the plugin's `inject`
 
+English | [中文](0001-acp-default-export-drops-inject.zh.md)
+
 Status: resolved (fix in PR #41 `feat/acp-2-bridge`)
 
 ## Executive summary
diff --git a/docs/postmortem/0001-acp-default-export-drops-inject.zh.md b/docs/postmortem/0001-acp-default-export-drops-inject.zh.md
new file mode 100644
index 0000000000..763b2e6230
--- /dev/null
+++ b/docs/postmortem/0001-acp-default-export-drops-inject.zh.md
@@ -0,0 +1,113 @@
+# 事故复盘（postmortem） 0001：ACP（Agent Client Protocol）服务器在连接时崩溃——`export default` 丢弃了插件的 `inject`
+
+[English](0001-acp-default-export-drops-inject.md) | 中文
+
+Status: resolved (fix in PR（Pull Request） #41 `feat/acp-2-bridge`)
+
+## 摘要
+
+两个集成错误在单元测试全覆盖的情况下仍然导致 ACP 崩溃：一个 default export 使 Loader 丢弃了 `inject`，一个经 traceable 代理的可选服务查找在 shadow 边界上失败。手动挂载的测试绕过了这两条路径。修复方案增加了无需 API key 的真实 Loader 覆盖率，并为插件导出和可选服务访问制定了包（package）级规则。
+
+## 概述
+
+ACP 服务器（`examples/acp-agent`、`@deepseek-ai/dsh-acp`）在真实编辑器（Zed）连接的瞬间崩溃：第一个 `session/new` 请求返回 `Internal error: cannot get property "agents" without inject`，`session/load` 对 `sessionPersistence` 返回同样的错误。尽管有 178 个绿色单元测试和 100% 行覆盖率，bridge 在生产环境中完全无法工作。两个独立的 bug 隐藏在同一个错误字符串背后，测试套件之所以两个都没捕获，原因也相同：所有测试都通过一条不会触及插件真实加载方式和服务真实解析方式的路径来挂载插件。
+
+## 影响
+
+ACP 服务器无法创建或加载任何一个会话——而这正是编辑器最先调用的两个 RPC。任何将 agent（智能体）接入 Zed 的人都会立即遭遇硬性失败。无数据丢失（崩溃前没有任何内容被持久化）；代价完全是「功能不可用」加上两次定位原因的调试时间。
+
+## 时间线
+
+- bridge（RFC 010）落地时附带完整的单元测试套件（codec、内存传输、基于属性的协议形状测试、失败路径、HMR（热模块替换））、一个需要 key 的真实 API e2e 测试，以及一个无需 key 的 stdout 纯净性 e2e 测试。全部绿色，100% 覆盖率。
+- 真实 Zed 会话在 `session/new` 上立即失败，报错 `cannot get property "agents" without inject`。
+- 调查最初追踪了一个 Cordis「traceable/shadow」理论（看似合理，且该机制确实存在——见 Bug #2），随后在 vendor 的 `reflect.ts` 中对实际 fiber 遍历做了插桩，并运行了真实子进程。trace 显示 throw 发生在 `apply()` 第 179 行、*插件加载时*，位于 ROOT fiber 且没有 shadow——推翻了 shadow 理论对 `session/new` 的解释。
+- 找到根因 #1：一行多余的 `export default apply`。删除后 `session/new` 修复。
+- 删除后暴露了 Bug #2：`session/load` 仍然在 `sessionPersistence` 上抛错——这是一个真正不同的机制（shadow 遍历），通过隔离修复并重新运行真实子进程得到确认。
+
+## 根因 #1——`export default apply` 丢弃了插件的 `inject`（导致 `session/new` 崩溃）
+
+`packages/ui/acp/src/index.ts` 是一个*命名空间插件*：它将 `name`、`inject`、`Config` 和 `apply` 作为独立的命名导出——与仓库中其他所有插件（`invariants`、`llm-deepseek`、`tool-bash`、`tui` 等）形状相同。但它*还*多了一行其他插件都没有的代码：
+
+```ts ignore-check
+export const name = 'acp'
+export const inject = ['agents', 'sessions', 'sessionPersistence']
+export function apply(ctx: Context, config: AcpConfig): void { /* … */ }
+// …
+export default apply   // ← the bug
+```
+
+当插件从 `cordis.yml` 加载时，Cordis Loader 通过 `Loader.unwrapExports`（`vendor/loader/src/index.ts`）对导入的模块进行规范化：
+
+```ts ignore-check
+unwrapExports(exports: any) {
+  if (isNullable(exports)) return exports
+  exports = exports.default ?? exports        // ← prefers `.default`
+  if (!exports.__esModule) return exports
+  return exports.default ?? exports
+}
+```
+
+存在 default export 时，`exports.default ?? exports` 解析为**裸 `apply` 函数**。裸函数没有 `inject`、没有 `name`、没有 `Config` 属性——这些作为*兄弟*命名导出存在于模块命名空间上，而 unwrap 到 `.default` 把整个命名空间丢弃了。Loader 随后基于空的 `inject` 构建了插件的 fiber。
+
+因此 `apply` 在一个**没有注入任何服务**的 fiber 中运行。第一行 `const agents = ctx.agents` 遍历 fiber 树（ROOT → Include → Loader → ROOT），在所有 fiber 的 store 中都找不到 `agents`，到达根 fiber（`runtime === null`）后抛出 `cannot get property "agents" without inject`。崩溃发生在*加载时*，而非后续的请求处理器中——请求只是恰好触发了加载。
+
+**修复：** 删除 `export default apply`。Loader 随后使用模块命名空间，正确识别 `inject`/`name`/`Config`，`apply` 在一个真正授予了声明服务的 fiber 中运行。
+
+## 根因 #2——可选服务读取通过 traceable shadow 触发 inject 守卫（导致 `session/load` 崩溃）
+
+修复 #1 后，`session/new` 正常工作，但 `session/load` 仍然抛出 `cannot get property "sessionPersistence" without inject`。这个问题*确实*是 Cordis 的 traceable/shadow 机制，值得精确理解。
+
+`session/load` 调用 `agents.resume(...)`，后者委托给 `AgentLoop.resume()`，其中读取了 `this.ctx.sessionPersistence`。`AgentLoop` 的 `static inject` 故意不包含 `sessionPersistence`——注入它会导致非持久化的演示永远挂起，等待一个永远不会加载的后端。该服务由一个独立的兄弟插件/fiber 提供，以机会性方式读取。
+
+Cordis 中的服务访问通过上下文代理（`vendor/cordis/src/reflect.ts`）进行。当通过从外部 fiber 获取的 *traceable 代理*调用服务方法时（此处：bridge fiber 调用 `ctx.agents.resume`，注册表返回 `this.factory`——即 `AgentLoop`——重新包装为绑定到调用方的新 traceable 代理），`createShadowMethod`（`vendor/cordis/src/utils.ts`）将 `this` 重新绑定到一个 *shadow* 对象，其 `ctx` 携带 `[symbols.shadow]` 指向 `AgentLoop` 自身的构造上下文。在 `resume` 内部，`this.ctx.sessionPersistence` 的解析从 shadow 的 fiber 开始遍历：
+
+```ts ignore-check
+// reflect.ts get handler
+let fiber = (ctx[symbols.shadow] as Context ?? ctx).fiber   // ← starts at AgentLoop's fiber
+while (true) {
+  const impl = fiber.store?.[prop]
+  if (impl) return getTraceable(ctx, impl.value)
+  if (prop in fiber.inject) { /* inactive-context error */ }
+  if (!fiber.runtime) throw error                            // ← reached root, throw
+  if (fiber.parent[symbols.isolate][prop] !== key) throw error
+  fiber = fiber.parent.fiber                                 // ← ancestor-only
+}
+```
+
+遍历**仅向祖先方向**进行。`sessionPersistence` 既不在 `AgentLoop` 的 fiber store 中（不在其 `static inject` 中），也不在通往 root 的任何祖先上（它位于一个*兄弟*分支），因此遍历到达根 fiber 后抛错。
+
+为什么内存中的 `AgentLoop` 恢复测试没有捕获这个问题？因为它们从测试代码直接调用 `ctx.agents.resume(...)`——*在任何插件 fiber 之外*。此时 `ctx.fiber.runtime` 为 `null`，代理处理器走了一条提前绕过的路径：
+
+```ts ignore-check
+if (!ctx.fiber.runtime) return ctx.reflect.get(prop, false)   // ← direct global-store lookup, no fiber walk
+```
+
+`ctx.reflect.get(name, false)` 是基于 isolate symbol 的全局服务 store 直接查找——完全忽略 fiber 拓扑，能找到服务。因此从顶层测试读取可以成功；而从真实插件 fiber 内部、经由 shadow 到达时则抛错。bridge 恰好是后者。
+
+**修复：** 使用 `ctx.get('sessionPersistence')` 读取可选服务，该方法使用全局 isolate-keyed store 同时保留活跃状态检查。对于插件声明注入集中的服务，直接属性读取仍然适用。
+
+## 为什么所有测试都没有捕获（真正的失败）
+
+两个 bug 共享同一个流程缺口：**没有任何测试通过插件的真实加载路径或真实调用拓扑来驱动它。**
+
+- 内存 harness 通过手动构建插件对象来挂载 bridge：`ctx.plugin({ name, inject, apply })`。这手动提供了 `inject`，因此永远无法复现 Bug #1——`unwrapExports` 只被 *Loader* 调用，`ctx.plugin` 从不调用它。即使 `ctx.plugin(NamespaceImport)` 也无法捕获。
+- 同一个 harness 将所有内容平铺挂载在一个根上下文上，因此从中触达的 `AgentLoop` 恢复要么运行在顶层（`!runtime` 绕过），要么通过一个 origin 仍然解析在 root 上的 shadow——掩盖了 Bug #2 的祖先遍历失败。
+- 唯一的无 key e2e 发送 `initialize` 并检查 stdout 纯净性。`initialize` 从不触达 factory，因此两个 bug 都安然通过。
+- 唯一驱动 `session/new`/`session/load` 的测试需要 key 才能运行，因此 CI（无 key）跳过了它——而本地它之所以「通过」，只是因为一个陈旧的已构建 `lib/`（包含旧代码）恰好满足了模块解析。
+
+100% 行覆盖率始终满足。覆盖率证明代码行*被执行过*；它不能说明功能是否*按交付方式正常工作*。
+
+## 新增的防护措施
+
+- **删除 `export default apply`**（`packages/ui/acp/src/index.ts`）——Bug #1 的修复。
+- **`AgentLoop.resume` 使用 `this.ctx.get('sessionPersistence')`**（`packages/core/agent-loop/src/index.ts`）——Bug #2 的修复，附注释说明 shadow 遍历陷阱。
+- **无需 key 的 `session/new` e2e，通过真实 stdio 运行**（`examples/acp-agent/tests/acp.e2e.ts`）：以子进程方式通过真实 Loader 启动示例，并断言 `session/new` 正常返回。无需 API key 即可在 Bug #1 上大声失败。已验证恢复 `export default apply` 时测试失败。
+- **e2e spawn 中设置 `TSX_TSCONFIG_PATH`**：子进程从临时 cwd 运行，tsx 无法通过向上搜索找到仓库根的 tsconfig `paths` 映射——因此 dsh-* 的 import 静默回退到已构建的 `lib/`。将 tsx 指向仓库 tsconfig 使解析不依赖 cwd，确保测试运行的是*源码*而非可能陈旧的构建产物。
+- **[docs/testing.md](../testing.md) 规则**：「测试真实入口路径」，行覆盖率不等于行为覆盖率——将这一教训编纂为所有未来插件的规则。
+
+## 经验教训
+
+- 命名空间插件与 default export 在 Cordis Loader 下互斥。选择命名空间形式（`name`/`inject`/`Config`/`apply`），不要添加 `export default`——`unwrapExports` 会丢弃命名空间。
+- 对于插件机会性读取但未在 `static inject` 中声明的服务，使用 `ctx.get(name)`，绝不使用 `ctx.<name>`。属性代理通过仅向祖先方向的 fiber 遍历解析，经由外部 shadow 时会失败；`ctx.get(name)` 是拓扑无关的查找（且默认严格——非活跃后端读取为 `undefined`，而非在 teardown 过程中被交出）。
+- 手动构建插件的测试无法验证插件的加载方式。至少一个测试必须端到端地驱动真实的 Loader/export 路径。当核心操作不调用模型时，该测试无需 API key——因此它属于 CI，而非 key 门控之后。
+- 相信 trace，不要相信理论。优雅的 shadow 解释是真实的，但它是*第二个* bug；*第一个*是一行导出错误，在数小时看似合理但实际错误的推理之后，一个 fiber 遍历的 `console.error` 在几分钟内就找到了它。
diff --git a/docs/postmortem/0002-js-expression-disabled-filesystem-tools.i18n.yaml b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.i18n.yaml
new file mode 100644
index 0000000000..2aad7141c5
--- /dev/null
+++ b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+0002-js-expression-disabled-filesystem-tools.md: 30ff9d920821a8d55c4bea5f120f1aeeca6634b3
+0002-js-expression-disabled-filesystem-tools.zh.md: b103ec6de5d6d6406ba48ec34f6ebb479e472352
diff --git a/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md
index ccdb725bfb..30ff9d9208 100644
--- a/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md
+++ b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md
@@ -1,5 +1,7 @@
 # Post-mortem 0002: Filesystem snapshot tools were permanently disabled
 
+English | [中文](0002-js-expression-disabled-filesystem-tools.zh.md)
+
 Status: resolved
 
 ## Executive summary
diff --git a/docs/postmortem/0002-js-expression-disabled-filesystem-tools.zh.md b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.zh.md
new file mode 100644
index 0000000000..b103ec6de5
--- /dev/null
+++ b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.zh.md
@@ -0,0 +1,47 @@
+# 事故复盘（postmortem） 0002：文件系统快照工具被永久禁用
+
+[English](0002-js-expression-disabled-filesystem-tools.md) | 中文
+
+Status: resolved
+
+## 摘要
+
+ACP（Agent Client Protocol）示例试图通过 `disabled: !!js ...` 有条件地启用文件系统插件，但 Cordis 仅在插件 `config` 内部对 JavaScript 表达式求值。原始的表达式对象为 truthy，因此文件系统栈始终处于禁用状态。快照刷新随后将 `UNKNOWN_TOOL` 结果接受为新的预期输出。修复方案改用显式的文件系统 overlay，并增加了静态配置守卫和快照结果守卫。
+
+## 概述
+
+默认的 ACP 组合有意只启用 bash，因为其沙箱无法约束进程内的文件系统提供方。文件系统快照场景仍然需要 `read`、`write` 和 `edit`，因此这些插件被放在默认的 `cordis.yml` 中，并附带一个 `disabled` 表达式，意图仅在全权限启动和快照模式下启用它们。
+
+Cordis Include 将每个 `!!js` 标量解析为一个表达式对象。Loader 递归地对插件的 `config` 进行插值，但直接消费 `disabled` 等入口元数据。因此每个文件系统入口看到的都是一个 truthy 对象，在所有模式下均保持禁用。
+
+## 影响
+
+七个文件系统场景和一个混合工作区编辑场景调用了注册表中不存在的工具。其结构化会话日志携带 `ToolNotFoundError`（code 为 `UNKNOWN_TOOL`），stdout 渲染出通用的失败工具卡片。快照套件通过了，因为结构化会话日志和 stdout 渲染出的通用失败工具卡片均与刷新后的 fixture（测试前置数据）匹配；它证明的是回归的确定性回放，而非文件系统行为的正确性。
+
+实际运行的受限默认模式并未获得意外的文件系统访问权限。一个简单的插值修复反而会制造该风险：权限预设在运行时更新 bash 沙箱和审批状态，但无法挂载、卸载或约束文件系统栈。
+
+## 时间线
+
+- PR（Pull Request） #261 整合了 ACP 组合并刷新了文件系统快照，同时引入了条件式文件系统入口。
+- 所有单元测试、覆盖率、快照、文档、构建和 hygiene 检查均通过。
+- 对刷新后的文件系统预期输出的评审发现了通用的失败卡片和结构化的 `UNKNOWN_TOOL` 结果。
+- 一次真实的 Loader 启动确认：每个 `disabled` 值仍为表达式对象，每个文件系统 fiber 均未创建。
+
+## 根因
+
+实现时假设 `!!js` 适用于整个 Loader 入口。其实际边界更窄：`Entry._resolveConfig()` 仅对 `entry.options.config` 进行插值；`Entry.disabled` 直接测试 `entry.options.disabled`，不经过插值。YAML 标签在语法上合法，因此加载过程不产生任何诊断信息。
+
+快照框架将任何确定性的 transcript（文本记录）视为有效行为。Header pin 验证了组合后的工具 schema，但文件系统场景共享来自默认组合的 pin，因此未独立证明其所需工具已注册。刷新在任何语义断言拒绝缺失工具之前，就已重写了预期的 stdout 和会话日志。
+
+## 已添加的防护措施
+
+- 文件系统场景启动 `fs.cordis.yml`：一个显式的固定全权限 overlay，配有对应的回放配置和独立的 request-header 类。
+- [`AGENTS.md`](../../AGENTS.md) 与 [Cordis 入门](../cordis-primer.md#loader-configuration)明确说明 `!!js` 仅在插件 `config` 内有效，条件式组合应使用 overlay。
+- `verify-cordis-config` 解析仓库中的 Cordis YAML，拒绝 Loader 入口元数据中的表达式节点（包括 include patch 和插入的入口）。
+- `dsh-acp-snapshot` 在新鲜运行和已提交的会话 fixture 中拒绝结构化的 `UNKNOWN_TOOL` 结果，防止其被提交为预期输出。
+
+## 教训
+
+- 语法上被接受的配置值不一定在该位置被求值；应记录并验证插值边界。
+- 快照刷新是 fixture 的生产过程，不是正确性审查。诸如已注册工具缺失这类语义上不可能的结果，需要独立于预期输出的断言。
+- 权限控制只应描述其实际管辖的能力。组合时的文件系统访问无法安全地跟随运行时的 bash-only 预设。
diff --git a/docs/postmortem/README.i18n.yaml b/docs/postmortem/README.i18n.yaml
new file mode 100644
index 0000000000..e68d3a1a07
--- /dev/null
+++ b/docs/postmortem/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
+README.md: df0e2fcb8540aeed005153dbecc451d781ca5ff1
+README.zh.md: 2ce6de475c705b02cd9dabfb2181929d81478e2c
diff --git a/docs/postmortem/README.md b/docs/postmortem/README.md
index 7114f65916..df0e2fcb85 100644
--- a/docs/postmortem/README.md
+++ b/docs/postmortem/README.md
@@ -1,5 +1,7 @@
 # Post-mortems
 
+English | [中文](README.zh.md)
+
 Incident write-ups: a bug reached a place it shouldn't have (a real user, a merged PR, a release), and the interesting part is *why our process let it through*, not just the one-line fix.
 
 A post-mortem is NOT an [Agent Note](../../.agents/notes/README.md) (which records a deliberate design decision and its rejected alternatives, or proposes future work). It is a backward-looking record of a failure: what broke, the mechanism, why every safety net missed it, and the concrete guardrails added so the same class of bug fails loudly next time.
diff --git a/docs/postmortem/README.zh.md b/docs/postmortem/README.zh.md
new file mode 100644
index 0000000000..2ce6de475c
--- /dev/null
+++ b/docs/postmortem/README.zh.md
@@ -0,0 +1,16 @@
+# 事故复盘（postmortem）
+
+[English](README.md) | 中文
+
+事故复盘：一个 bug 到达了它不该到达的地方（真实用户、已合并的 PR（Pull Request）、已发布的版本），值得关注的是*为什么我们的流程放过了它*，而不仅仅是那一行修复。
+
+事故复盘不是 [Agent Note（agent 决策记录）](../../.agents/notes/README.md)（Agent Note 记录一个经过深思熟虑的设计决策及其被否决的替代方案，或提出未来工作）。它是一份回顾性的失败记录：什么坏了、机制是什么、为什么每道安全网都没拦住、以及加了哪些具体的防护措施使同类 bug 下次能被显式暴露。
+
+当一个 bug 满足以下条件时，请撰写事故复盘：**隐蔽**（机制不显而易见，即使是细心的工程师也得费力重新推导）、**系统性**（逃逸的原因是测试/工具/约定的缺口，而非一次性的笔误）、**重新发现的代价高**（它消耗了真实的调试时间，且下次还会如此）。请链接该事故复盘所推动建立的防护措施（测试、AGENTS.md 规则、ADR）。
+
+每篇事故复盘以一段**摘要**开头：一个简短段落，让忙碌的读者在三十秒内吸收要点——什么坏了、用直白的话说根因是什么、为什么逃逸了、持久的教训是什么——然后才是后续的详细「概述 / 时间线 / 根因 / 防护措施」各节。
+
+| # | 标题 |
+|---|---|
+| [0001](0001-acp-default-export-drops-inject.md) | ACP（Agent Client Protocol）服务器在连接时崩溃：`export default` 丢失了插件的 `inject` |
+| [0002](0002-js-expression-disabled-filesystem-tools.md) | 文件系统快照工具被一个字面量 `!!js` 对象永久禁用 |
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
new file mode 100644
index 0000000000..8ebdff8c55
--- /dev/null
+++ b/docs/testing.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
+testing.md: fd38fb7b20d76ef48c81c86badcf501f7c0dbd4e
+testing.zh.md: 4584492350aefd5d72692093b08c0dcd4910a8af
diff --git a/docs/testing.md b/docs/testing.md
index 85798cee3e..fd38fb7b20 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -1,21 +1,23 @@
 # Testing policy
 
+English | [中文](testing.zh.md)
+
 How this repo tests, tier by tier, and the rules that keep a green suite meaningful. Commands live in root [AGENTS.md](../AGENTS.md); linked Agent Notes carry the rationale.
 
 ## Tiers
 
-- **Unit** (`pnpm run test`): vitest over `packages|examples/*/tests/**/*.spec.ts`, colocated with what they test. Every registry gets an HMR-safety test (dispose the contributing fiber, assert cleanup). Prefer edge cases, error paths, event ordering, concurrency races, and permanent contract regressions (see `packages/core/agent-loop/tests/contract-regressions.spec.ts`).
+- **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.
 - **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`): transport-specific keyless expected outputs cover external presentation. ACP suites boot the real example subprocess, replay a recorded session, and diff normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); the headless suite independently pins `stream-json` through its real one-shot subprocess. TUI completed journeys replay recorded primary/child JSONL through the real agent loop and tools before projecting ANSI into semantic terminal-state expected outputs; package-local snapshots retain transient renderer states, and a real PTY conversation covers the process boundary ([TUI snapshot Agent Note](../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)). Use `pnpm run test:snapshot:record` when a model transcript must change and `pnpm run test:snapshot:refresh` when committed replay input remains correct; review every JSONL and expected-output diff. System-prompt/tool-schema content is pinned by one ACP scenario (`text-turn`) and tokenized in every other fixture, so a prompt or schema edit churns one committed line ([pinned-header Agent Note](../.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **Snapshot** (`pnpm run test:snapshot`): keyless expected outputs cover external presentation. ACP boots the real 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. TUI journeys replay primary/child JSONL through the real loop and tools, then project ANSI into semantic terminal-state outputs; package snapshots retain transient states and a real PTY covers the process boundary ([TUI snapshot Agent Note](../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)). 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/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
 
 ## The with-key policy: inference is cheap here
 
-We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Write many: file-writing prompts, multi-turn conversations, tool use, cancellation mid-stream. Highest-value are **smoke tests** that boot the real example, send one real prompt, and check the world — they catch the "green unit tests, broken product" class that mocks structurally cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). The self-skip exists only so secretless CI and keyless contributors aren't blocked; it is not a cost signal. Every example ships both a keyless smoke and a with-key smoke ([examples/AGENTS.md](../examples/AGENTS.md)).
+We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Cover file-writing prompts, multi-turn conversations, tool use, and mid-stream cancellation. Highest-value are **smoke tests** that boot the real example, send one prompt, and check the world — they catch the "green unit tests, broken product" class that mocks cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). Self-skip keeps secretless CI and keyless contributors unblocked; it is not a cost signal. Every example ships keyless and with-key smokes ([examples/AGENTS.md](../examples/AGENTS.md)).
 
 ## Prefer the real implementation over a mock
 
-Mock only the genuinely expensive or non-deterministic boundary (the LLM adapter, the network, the clock); keep everything downstream real. A hand-rolled stand-in proves the bridge moves bytes, not that the shipping tool behaves as asserted — the two drift while the test stays green. Example: bridge tool-call tests run the scripted mock MODEL but the real tool + real executor (`makeBridgeHarness({ withBash: true })` plugs `dsh-bash-local` + `dsh-tool-bash` and runs an actual `echo`).
+Mock only the expensive or non-deterministic boundary (LLM adapter, network, clock); keep everything downstream real. A hand-rolled stand-in proves the bridge moves bytes, not that the shipping tool behaves as asserted. Bridge tool-call tests use the scripted mock model with the real tool and executor: `makeBridgeHarness({ withBash: true })` plugs in `dsh-bash-local` and `dsh-tool-bash`, then runs `echo`.
 
 Recovery tests separate pre/post-chunk failures by step and prove failed chunks derive no message or tool side effect. Cover exhaustion, cancellation, policy composition, persistence, status, wire counts, transport-closing idle timeouts, and shipping Loader composition.
 
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
new file mode 100644
index 0000000000..4584492350
--- /dev/null
+++ b/docs/testing.zh.md
@@ -0,0 +1,46 @@
+# 测试策略
+
+[English](testing.md) | 中文
+
+本文说明本仓库的分层测试方式，以及保持绿色测试套件有意义的规则。命令见根目录 [AGENTS.md](../AGENTS.md)；相关 Agent Note（agent 决策记录）承载设计动机。
+
+## 层级
+
+- **单元测试**（`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% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。
+- **真实 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`。TUI 旅程通过真实循环与工具回放主会话与子会话 JSONL，再将 ANSI 投影为语义化终端状态输出；包级快照保留瞬态状态，真实 PTY 覆盖进程边界（[TUI 快照 Agent Note](../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)）。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
+
+## 带密钥策略：推理在这里很便宜
+
+我们是 DeepSeek，不要吝惜真实 API 测试。无密钥测试只能证明底层通路；只有带密钥运行才能证明 agent（智能体）能对接真实模型正常工作。覆盖文件写入提示词、包含多个轮次的对话、工具使用和流中取消。价值最高的是**冒烟测试**：启动真实示例、发送一条提示词，并检查外部世界；它们能捕获「单元测试全绿、产品却坏了」这一类 mock 无法发现的问题（[事故复盘 0001](postmortem/0001-acp-default-export-drops-inject.md)）。自动跳过让无密钥 CI 和无密钥贡献者不受阻塞；它不是成本信号。每个示例都提供无密钥和带密钥冒烟测试（[examples/AGENTS.md](../examples/AGENTS.md)）。
+
+## 优先使用真实实现而非 mock
+
+只 mock 开销高或不确定的边界（LLM（大语言模型）适配器、网络、时钟）；下游一切保持真实。手写替身只能证明桥接层在搬运字节，不能证明交付的工具行为符合断言。桥接工具调用测试将脚本化 mock 模型与真实工具和执行器配合使用：`makeBridgeHarness({ withBash: true })` 接入 `dsh-bash-local` 与 `dsh-tool-bash`，然后运行 `echo`。
+
+恢复测试按步骤区分分片前与分片后的失败，并证明失败分片不会派生出消息或工具副作用。覆盖耗尽、取消、策略组合、持久化、状态、协议计数、会关闭传输的空闲超时，以及交付的 Loader 组合。
+
+## 验证外部世界，而非自我报告
+
+e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身输出做关键词探测会让作弊的 agent 通过。断言未修改的文件逐字节一致。e2e 测试自行管理资源：在测试中创建 harness，在 `afterEach` 中 dispose（即使失败/重试/超时也要释放）；共享 fixture 放在普通的 `tests/harness.ts` 中，绝不放在另一个 `*.e2e.ts` 中（导入一个 spec 会重新注册其 `describe`，导致真实 API 调用重复执行）。
+
+## 测试真实入口路径
+
+- 产品可见的插件必须有一个非单元的真实组合测试。手动构建的 `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`），并断言真正缺失的配置以非零状态退出。
+
+## 测试解析：仅限源码
+
+- 每个 vitest 配置都将 vite-tsconfig-paths 指向 `tsconfig.base.json`；工作区包的裸导入解析到 `src`（[布局](development.md#typescript-project-layout)），绝不会经由包的 `exports` 解析到构建后的 `lib/`，因为其中的陈旧产物会加载第二份模块单例。构建产物只在显式指定时使用：以 `lib` 模式运行的子进程，以及下文的构建产物冒烟测试。
+
+## 测试子进程启动模式
+
+- CI 与已有构建产物的测试通道通过共享双模式启动器，从构建后的 `lib/` 运行每个示例或 Cordis 配置子进程。不要为这些子进程手写 `--import tsx`。
+- 不加载 Cordis 的协议与操作系统 fixture 直接通过 Node 运行使用可擦除语法的 `.ts` 文件，不经过 tsx 或根路径映射。
+- 只有测试对象本身是源码路径解析时，才可以选择 `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` 拥有 `stream-json` 快照与回放 fixture。已完成的交互式终端旅程使用 `examples/tui-agent/tests/snapshots/` 下由 JSONL 驱动的场景；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 5c1bfbfdf3..c10b0c90a7 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -23,12 +23,12 @@ This table connects model-visible tool names to the plugin package and service s
 | `@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-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). 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`, `context/message goal snapshot 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. |
+| `@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`, `user/message goal snapshot 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. |
 | `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`, `ctx.lsp`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the 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`, `workflow and child session events during execution` | - | A fixed foreground workflow starts one fresh structured child per round; the model selects only the immutable objective and an optional round cap. |
 | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.skills` | `tool/call`, `tool/result` | - | - |
 | `@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 `examples/tui-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. |
-| `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `context/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-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 or ACP plan. |
 | `@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 and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. |
@@ -48,6 +48,7 @@ Ask the user a concise question when you need confirmation, a choice, or missing
       "description": "Questions to ask the user before continuing.",
       "items": {
         "type": "object",
+        "additionalProperties": true,
         "properties": {
           "id": {
             "type": "string",
@@ -66,6 +67,7 @@ Ask the user a concise question when you need confirmation, a choice, or missing
             "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",
@@ -229,7 +231,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor
 
 ### `cordis_mount`
 
-Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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.
 
 ```json
 {
@@ -896,6 +898,7 @@ Record and update a structured task list for the current work. Send the ENTIRE l
       "description": "The COMPLETE task list, replacing any previous list.",
       "items": {
         "type": "object",
+        "additionalProperties": true,
         "properties": {
           "content": {
             "type": "string",
@@ -937,7 +940,7 @@ Run a JavaScript workflow script that orchestrates subagents at scale. Use this
 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 — no oneOf/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.
+- `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.
@@ -957,6 +960,7 @@ Constraints: concurrency and total-agent caps apply; no filesystem, network, tim
     "meta": {
       "type": "object",
       "description": "The workflow identity block (plain JSON — never code).",
+      "additionalProperties": true,
       "properties": {
         "name": {
           "type": "string",
@@ -975,6 +979,7 @@ Constraints: concurrency and total-agent caps apply; no filesystem, network, tim
           "description": "Optional phase declarations matched by phase() calls.",
           "items": {
             "type": "object",
+            "additionalProperties": true,
             "properties": {
               "title": {
                 "type": "string",
@@ -1006,7 +1011,8 @@ Constraints: concurrency and total-agent caps apply; no filesystem, network, tim
     },
     "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\": [...]})."
+      "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": [
diff --git a/docs/tool-execution-pipeline.md b/docs/tool-execution-pipeline.md
index 5fc21db2f5..16a4461b6c 100644
--- a/docs/tool-execution-pipeline.md
+++ b/docs/tool-execution-pipeline.md
@@ -3,7 +3,7 @@
 
 # Tool Execution Pipeline
 
-This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering fit without changing the loop. The transformable extension points are the `tools/pre-execute`, `tools/execute`, and `tools/post-execute` waterfalls; monotonic guards and `tools/result` are the owner-enforced boundaries around them.
+This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering fit without changing the loop. The transformable extension points are the `tools/pre-execute`, `tools/execute`, and `tools/post-execute` waterfalls; monotonic guards, definition-owned `finalizeContent`, and `tools/result` are the owner-enforced boundaries around them.
 
 ```mermaid
 flowchart TD
@@ -19,8 +19,10 @@ flowchart TD
   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/>context/message after recorded tool results"]
+  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)"]
@@ -30,24 +32,31 @@ flowchart TD
   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
-  post --> final
+  around -.->|wrapper throws| normalized
+  post -.->|throw| normalized
+  post --> finalize
+  normalized --> finalize
+  finalize --> final
   final --> toolResult
   toolResult --> presentResult
   toolResult --> allResults
   allResults --> context
 ```
 
-Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`, while `tools/result` observes the immutable outcome after transforms, lossless-JSON validation, and outer error normalization. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
+Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
 
 Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.
diff --git a/docs/user/develop/basic/index.i18n.yaml b/docs/user/develop/basic/index.i18n.yaml
index 711715a5de..a6ab84c3e0 100644
--- a/docs/user/develop/basic/index.i18n.yaml
+++ b/docs/user/develop/basic/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
-index.md: d7d657ff7b8cb9001dd5e9c3af658a7a3c45b5b7
-index.zh.md: 7a134f7aaed470b87ee8ca8978dd39593de2651b
+index.md: 5a9f8dfb8f2d87dfbd2ba30b4d09d002ae9b635c
+index.zh.md: 08aca87cbc02d1b0dfbe6fe2d92b3f6e87075097
diff --git a/docs/user/develop/basic/index.md b/docs/user/develop/basic/index.md
index d7d657ff7b..5a9f8dfb8f 100644
--- a/docs/user/develop/basic/index.md
+++ b/docs/user/develop/basic/index.md
@@ -138,8 +138,12 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }
diff --git a/docs/user/develop/basic/index.zh.md b/docs/user/develop/basic/index.zh.md
index 7a134f7aae..08aca87cbc 100644
--- a/docs/user/develop/basic/index.zh.md
+++ b/docs/user/develop/basic/index.zh.md
@@ -138,8 +138,12 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }
diff --git a/docs/user/develop/basic/tool.i18n.yaml b/docs/user/develop/basic/tool.i18n.yaml
index d2f4343cf1..73970f99d8 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
-tool.md: 416733bcb584fa5303a8b3ba5e6e904302e7f992
-tool.zh.md: fce9a7d9b973853c8b4fb9ae2c034e749d8da999
+tool.md: 7b211cfef54306f7c316dc08da1df759dcbf1b06
+tool.zh.md: 214b35b28de0c647737bc8297b13b4997947b52e
diff --git a/docs/user/develop/basic/tool.md b/docs/user/develop/basic/tool.md
index 416733bcb5..7b211cfef5 100644
--- a/docs/user/develop/basic/tool.md
+++ b/docs/user/develop/basic/tool.md
@@ -20,9 +20,13 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true, description: 'The name to greet' },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       // args is inferred as { name: string }.
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }
@@ -37,10 +41,11 @@ export function apply(ctx: Context) {
 ```ts
 export const parameters = {
   path: { type: 'string', required: true },
-  limit: { type: 'number' },
+  limit: { type: 'integer' },
   recursive: { type: 'boolean' },
+  parent: { type: 'null' },
 }
-// Inferred type: { path: string; limit?: number; recursive?: boolean }
+// Inferred type: { path: string; limit?: number; recursive?: boolean; parent?: null }
 ```
 
 ### Enums
@@ -49,7 +54,7 @@ export const parameters = {
 export const parameters = {
   mode: { type: 'string', required: true, enum: ['read', 'write', 'append'] },
 }
-// Inferred type: { mode: string } (enum values are validated at runtime)
+// Inferred type: { mode: 'read' | 'write' | 'append' }
 ```
 
 ### Nested objects
@@ -58,13 +63,14 @@ export const parameters = {
 export const parameters = {
   options: {
     type: 'object',
+    additionalProperties: true,
     properties: {
       timeout: { type: 'number' },
       retries: { type: 'number' },
     },
   },
 }
-// Inferred type: { options?: { timeout?: number; retries?: number } }
+// The declared fields are inferred; additional JSON-valued keys are allowed.
 ```
 
 ### Arrays
@@ -83,12 +89,16 @@ export const parameters = {
 
 | Field | Type | Meaning |
 |------|------|------|
-| `type` | `'string' \| 'number' \| 'boolean' \| 'object' \| 'array'` | Value type |
+| `type` | `'string' \| 'number' \| 'integer' \| 'boolean' \| 'null' \| 'object' \| 'array' \| 'json'` | Value type; `json` accepts any lossless JSON value |
 | `required` | `true` | Marks the property required and affects inference |
 | `description` | `string` | Description sent to the model |
-| `enum` | `string[]` | Allowed string values |
-| `properties` | `SchemaSpec` | Nested properties for an object |
-| `items` | `SchemaProp` | Element schema for an array |
+| `enum` / `const` | matching scalar values | Allowed literal values, checked at author and runtime boundaries |
+| `properties` | `ParameterSchemaSpec` | Nested properties for an object |
+| `additionalProperties` | `true \| false` | Required on every explicit object node |
+| `items` | `ValueSchemaSpec` | Element schema for an array |
+| `oneOf` | at least two `ValueSchemaSpec` branches | Requires exactly one matching branch; used instead of `type` |
+
+The outer `parameters` map is an implicit open object. Explicit nested objects choose their openness; raw JSON Schema registered without `defineTool` keeps JSON Schema's open-by-default behavior.
 
 ## The execute function
 
@@ -101,33 +111,45 @@ export const tool = defineTool({
   name: 'example',
   description: 'Return an example result.',
   parameters: {},
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   async execute(args, exec) {
     // args: inferred from parameters
     // exec: ToolExecution context
 
-    // Return a ContentBlock array.
+    // Return the value declared by output.schema.
     void args
     void exec
-    return [{ type: 'text', text: 'result here' }]
+    return 'result here'
   },
 })
 ```
 
 ### Return value
 
-`execute` returns a `ContentBlock[]` that becomes the tool result visible to the model:
+`execute` returns the lossless JSON value declared by `output.schema`. `output.render(args, value)` separately turns that validated value into the Native/model-facing content:
 
 ```ts ignore-check
-// Text result
-return [{ type: 'text', text: 'file content here...' }]
-
-// Multiple blocks
-return [
-  { type: 'text', text: 'Found 3 matches:' },
-  { type: 'text', text: matchResults.join('\n') },
-]
+output: {
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      path: { type: 'string', required: true },
+      content: { type: 'string', required: true },
+    },
+  },
+  render: (_args, value) => [{ type: 'text', text: value.content }],
+},
+async execute(args) {
+  return { path: args.path, content: await readFile(args.path, 'utf8') }
+}
 ```
 
+The canonical value is available to execution-time programmatic callers and is not persisted in `tool/result`; the rendered content and optional `presentationMeta` are the replayable projections. A body value that does not satisfy the schema, or is not lossless JSON, becomes an `INVALID_TOOL_OUTPUT` failure.
+
 ### Argument validation
 
 Before calling `execute`, `defineTool` validates model-generated arguments. Invalid input raises `ToolArgsError`; the framework turns it into an `isError` result so the model can correct its call.
@@ -142,6 +164,10 @@ A tool can define UI presentation methods for terminal and ACP clients:
 defineTool({
   name: 'bash',
   // ...
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   presentCall(args) {
     return {
       card: 'terminal',
@@ -190,13 +216,24 @@ export function apply(ctx: Context) {
       path: { type: 'string', required: true, description: 'Directory path' },
       extension: { type: 'string', description: 'Filter by extension (e.g. ".ts")' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          count: { type: 'integer', required: true },
+          files: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Found ${value.count} files.` }],
+    },
     async execute(args) {
       const entries = await readdir(args.path, { withFileTypes: true })
       let files = entries.filter(e => e.isFile())
       if (args.extension) {
         files = files.filter(f => f.name.endsWith(args.extension!))
       }
-      return [{ type: 'text', text: `Found ${files.length} files.` }]
+      return { count: files.length, files: files.map(file => file.name) }
     },
   }))
 }
diff --git a/docs/user/develop/basic/tool.zh.md b/docs/user/develop/basic/tool.zh.md
index fce9a7d9b9..214b35b28d 100644
--- a/docs/user/develop/basic/tool.zh.md
+++ b/docs/user/develop/basic/tool.zh.md
@@ -20,9 +20,13 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true, description: 'The name to greet' },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       // args is inferred as { name: string }.
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }
@@ -37,10 +41,11 @@ export function apply(ctx: Context) {
 ```ts
 export const parameters = {
   path: { type: 'string', required: true },
-  limit: { type: 'number' },
+  limit: { type: 'integer' },
   recursive: { type: 'boolean' },
+  parent: { type: 'null' },
 }
-// Inferred type: { path: string; limit?: number; recursive?: boolean }
+// Inferred type: { path: string; limit?: number; recursive?: boolean; parent?: null }
 ```
 
 ### 枚举
@@ -49,7 +54,7 @@ export const parameters = {
 export const parameters = {
   mode: { type: 'string', required: true, enum: ['read', 'write', 'append'] },
 }
-// Inferred type: { mode: string } (enum values are validated at runtime)
+// Inferred type: { mode: 'read' | 'write' | 'append' }
 ```
 
 ### 嵌套对象
@@ -58,13 +63,14 @@ export const parameters = {
 export const parameters = {
   options: {
     type: 'object',
+    additionalProperties: true,
     properties: {
       timeout: { type: 'number' },
       retries: { type: 'number' },
     },
   },
 }
-// Inferred type: { options?: { timeout?: number; retries?: number } }
+// The declared fields are inferred; additional JSON-valued keys are allowed.
 ```
 
 ### 数组
@@ -83,12 +89,16 @@ export const parameters = {
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `type` | `'string' \| 'number' \| 'boolean' \| 'object' \| 'array'` | 值类型 |
+| `type` | `'string' \| 'number' \| 'integer' \| 'boolean' \| 'null' \| 'object' \| 'array' \| 'json'` | 值类型；`json` 接受任意无损 JSON 值 |
 | `required` | `true` | 标记为必填（影响类型推导） |
 | `description` | `string` | 发送给模型的描述 |
-| `enum` | `string[]` | 允许的枚举值 |
-| `properties` | `SchemaSpec` | 嵌套属性（type 为 object 时） |
-| `items` | `SchemaProp` | 数组元素 schema（type 为 array 时） |
+| `enum` / `const` | 匹配类型的标量值 | 允许的字面量值，在编写和运行时边界校验 |
+| `properties` | `ParameterSchemaSpec` | 对象的嵌套属性 |
+| `additionalProperties` | `true \| false` | 每个显式对象节点都必须声明 |
+| `items` | `ValueSchemaSpec` | 数组的元素 schema |
+| `oneOf` | 至少两个 `ValueSchemaSpec` 分支 | 要求恰好匹配一个分支；代替 `type` 使用 |
+
+外层 `parameters` 映射是一个隐式的开放对象。显式嵌套对象需自行选择是否开放；不通过 `defineTool` 注册的原始 JSON Schema 保持 JSON Schema 的默认开放语义。
 
 ## execute 函数
 
@@ -101,33 +111,45 @@ export const tool = defineTool({
   name: 'example',
   description: 'Return an example result.',
   parameters: {},
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   async execute(args, exec) {
     // args: inferred from parameters
     // exec: ToolExecution context
 
-    // Return a ContentBlock array.
+    // Return the value declared by output.schema.
     void args
     void exec
-    return [{ type: 'text', text: 'result here' }]
+    return 'result here'
   },
 })
 ```
 
 ### 返回值
 
-`execute` 必须返回一个 `ContentBlock[]`，告诉模型 tool 的执行结果：
+`execute` 返回由 `output.schema` 声明的无损 JSON 值。`output.render(args, value)` 会将经过校验的值另外转换为 Native／模型可见的内容：
 
 ```ts ignore-check
-// Text result
-return [{ type: 'text', text: 'file content here...' }]
-
-// Multiple blocks
-return [
-  { type: 'text', text: 'Found 3 matches:' },
-  { type: 'text', text: matchResults.join('\n') },
-]
+output: {
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      path: { type: 'string', required: true },
+      content: { type: 'string', required: true },
+    },
+  },
+  render: (_args, value) => [{ type: 'text', text: value.content }],
+},
+async execute(args) {
+  return { path: args.path, content: await readFile(args.path, 'utf8') }
+}
 ```
 
+执行期间的程序化调用方可以使用规范值，但 `tool/result` 不会持久化该值；渲染后的内容和可选的 `presentationMeta` 才是可回放的投影。工具主体返回的值若不满足 schema 或不是无损 JSON，就会变为 `INVALID_TOOL_OUTPUT` 失败。
+
 ### 参数校验
 
 `defineTool` 在调用 `execute` 之前会自动校验模型生成的参数。如果参数不合法，会抛出 `ToolArgsError`，框架将其转换为 `isError` 结果返回给模型，让模型自行修正。
@@ -142,6 +164,10 @@ Tool 可以定义 UI 渲染方法，用于在终端或 ACP 客户端中展示 to
 defineTool({
   name: 'bash',
   // ...
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   presentCall(args) {
     return {
       card: 'terminal',
@@ -190,13 +216,24 @@ export function apply(ctx: Context) {
       path: { type: 'string', required: true, description: 'Directory path' },
       extension: { type: 'string', description: 'Filter by extension (e.g. ".ts")' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          count: { type: 'integer', required: true },
+          files: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Found ${value.count} files.` }],
+    },
     async execute(args) {
       const entries = await readdir(args.path, { withFileTypes: true })
       let files = entries.filter(e => e.isFile())
       if (args.extension) {
         files = files.filter(f => f.name.endsWith(args.extension!))
       }
-      return [{ type: 'text', text: `Found ${files.length} files.` }]
+      return { count: files.length, files: files.map(file => file.name) }
     },
   }))
 }
diff --git a/docs/user/develop/practice/index.i18n.yaml b/docs/user/develop/practice/index.i18n.yaml
index d2478abf75..799dffc1c6 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
-index.md: 0261b49b071167f7c2a33f78bbc1959cc6f1879f
-index.zh.md: 5819344430fcbde31bf825e9815120983e44e3f6
+index.md: e197d499d7f5bd9911ea60bebf584251cd4ed915
+index.zh.md: 8b8d08f9d0c6d0ca8d95fbaa3281c98b7a600fe4
diff --git a/docs/user/develop/practice/index.md b/docs/user/develop/practice/index.md
index 0261b49b07..e197d499d7 100644
--- a/docs/user/develop/practice/index.md
+++ b/docs/user/develop/practice/index.md
@@ -132,9 +132,13 @@ export function apply(ctx: Context) {
     parameters: {
       input: { type: 'string', required: true },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       const result = await ctx.myCap.execute({ input: args.input })
-      return [{ type: 'text', text: result.output }]
+      return result.output
     },
   }))
 }
diff --git a/docs/user/develop/practice/index.zh.md b/docs/user/develop/practice/index.zh.md
index 5819344430..8b8d08f9d0 100644
--- a/docs/user/develop/practice/index.zh.md
+++ b/docs/user/develop/practice/index.zh.md
@@ -132,9 +132,13 @@ export function apply(ctx: Context) {
     parameters: {
       input: { type: 'string', required: true },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       const result = await ctx.myCap.execute({ input: args.input })
-      return [{ type: 'text', text: result.output }]
+      return result.output
     },
   }))
 }
diff --git a/eslint.config.mjs b/eslint.config.mjs
index eec63181df..ef03904390 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -12,6 +12,7 @@ export default tseslint.config(
       '**/.sessions/**',
       '.claude/**', // harness-local state (worktrees, skills) — other checkouts, not this one's sources
       '**/.doc-typecheck-*/**',
+      '**/.node-next-types-*/**',
       'website/.generated/**',
       'vendor/**', // vendored source keeps upstream style and idioms
       'native/**', // imported landlock-run subtree: self-contained workspace with its own gates (native/README.md)
diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml
index ffde5b0e3e..d0f9b43367 100644
--- a/examples/acp-agent/cordis.yml
+++ b/examples/acp-agent/cordis.yml
@@ -12,11 +12,10 @@
     baseURL: !!js process.env.DEEPSEEK_BASE_URL
     thinking: enabled
     reasoningEffort: max
+    defaultContextWindow: 256000
     models:
       - id: deepseek-v4-flash
-        contextWindow: 256000
       - id: deepseek-v4-pro
-        contextWindow: 256000
 
 # The default composition confines bash AND the filesystem tools to the
 # workspace and asks before a wider retry. Snapshot runs select
diff --git a/examples/acp-agent/pty.cordis.snapshot.yml b/examples/acp-agent/pty.cordis.snapshot.yml
index 9ef3ff6418..07e4605375 100644
--- a/examples/acp-agent/pty.cordis.snapshot.yml
+++ b/examples/acp-agent/pty.cordis.snapshot.yml
@@ -14,6 +14,8 @@
             name: './pty-snapshot-backend.mjs'
           - id: tool-pty
             name: '@deepseek-ai/dsh-tool-pty'
+            config:
+              maxResultBytes: 64
           - id: llm-replay
             name: '@deepseek-ai/dsh-llm-replay'
             config:
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index e35d47cea0..7d014991ed 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -140,11 +140,11 @@ const SCENARIOS: Scenario[] = [
   // Keyless, authored (like error-finish/cancel): deterministically forcing a
   // LIVE model to repeat one call three times is not a stable recording, so
   // the fixture scripts five identical todo_write calls and pins BOTH reminder
-  // tiers (gentle at 3, detailed at 5) as context/message in transcript and log.
+  // tiers (gentle at 3, detailed at 5) as injected user/message in transcript and log.
   { name: 'repeat-tool-guard', hasModelTurn: true, recorded: false },
   // Authored replay: a root AGENTS.md pins the session prefix, then a read in
   // nested/ discovers its narrower AGENTS.md as a raw, metadata-bearing
-  // context/message. Both AGENTS.md fixtures are symlinks to a sibling
+  // injected user/message. Both AGENTS.md fixtures are symlinks to a sibling
   // AGENTS.canonical.md, so this scenario also guards that discovery follows a
   // symlinked instruction file to its target's content. The scenario-specific
   // config keeps home/root discovery hermetic, and the resulting prefix needs
@@ -220,7 +220,7 @@ const SCENARIOS: Scenario[] = [
   // tool/code-dispatch events. Each overlay composes and pins its own header class.
   { name: 'code-mode-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'code', configPath: CODE_MODE_CONFIG },
   // A nested fs dispatch inside run_code discovers workspace instructions. The
-  // context/message must follow the outer result while retaining workspace
+  // injected user/message must follow the outer result while retaining workspace
   // provenance, which proves Code Mode carries deferred tool context end to end.
   {
     name: 'code-mode-workspace-context',
diff --git a/examples/acp-agent/tests/escalation.e2e.ts b/examples/acp-agent/tests/escalation.e2e.ts
index ae53252743..1bf0a5ac16 100644
--- a/examples/acp-agent/tests/escalation.e2e.ts
+++ b/examples/acp-agent/tests/escalation.e2e.ts
@@ -25,13 +25,11 @@ import { cleanupAcpExampleTest } from './cleanup.ts'
  * model nor a sandbox runner is ever exercised.
  *
  * With-key escalation flow (self-skips without DEEPSEEK_API_KEY or a usable
- * platform runner): a scripted ACP client plays the human. The prompt asserts
- * a prior denial (the organic denial→marker path lives on the sandbox e2e
- * legs and unit tiers), the real model escalates with `sandbox_permissions` +
- * `justification`, the bridge prompts THIS client over
- * `session/request_permission`, the client answers `allow-once`, and the
- * retried write must land ON DISK (world-verified) — under the granted mode,
- * a temp-dir session cwd is writable either way.
+ * platform runner): a scripted ACP client plays the human. The subprocess
+ * starts read-only, its first real bash write is denied, the model retries with
+ * `sandbox_permissions` + `justification`, and the bridge prompts THIS client
+ * over `session/request_permission`. An approved workspace-write retry must
+ * then land ON DISK (world-verified).
  */
 
 const AGENT: AgentUnderTest = {
@@ -58,14 +56,21 @@ interface Spawned extends LaunchedAcpTestAgent {
   permissionRequests: RequestPermissionRequest[]
 }
 
-/** Boot the example as an ACP subprocess; the scripted client answers every permission prompt with `answer`. */
-function launchExampleAcpAgent(cwd: string, answer: 'allow-once' | 'reject-once'): Spawned {
+/** Boot the example with an optional sandbox override; the scripted client answers every permission prompt with `answer`. */
+function launchExampleAcpAgent(
+  cwd: string,
+  answer: 'allow-once' | 'reject-once',
+  sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access',
+): Spawned {
   const permissionRequests: RequestPermissionRequest[] = []
   const launched = launchAcpTestAgent({
     agent: AGENT,
     cwd,
     // A dummy key lets the adapter boot keylessly; live tests carry the real key.
-    env: { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot' },
+    env: {
+      DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot',
+      DSH_PERMISSION_MODE: sandboxMode,
+    },
     requestPermission(params) {
       permissionRequests.push(params)
       const option = params.options.find(o => o.optionId === answer)
@@ -78,6 +83,17 @@ function launchExampleAcpAgent(cwd: string, answer: 'allow-once' | 'reject-once'
   return Object.assign(launched, { permissionRequests })
 }
 
+function escalationPrompt(path: string, content: string): string {
+  return `Create ${path} containing exactly ${JSON.stringify(content)} using bash, not filesystem tools. `
+    + 'First try the command without sandbox_permissions. If the sandbox denies it, retry that exact command once '
+    + 'with sandbox_permissions set to workspace-write and a one-sentence justification.'
+}
+
+function includesReadOnlyDenial(updates: LaunchedAcpTestAgent['updates']): boolean {
+  return updates.some(update => update.sessionUpdate === 'tool_call_update'
+    && JSON.stringify(update.content).includes('[sandbox: file access denied under read-only mode]'))
+}
+
 let spawned: Spawned | undefined
 let workdir: string | undefined
 
@@ -137,17 +153,20 @@ describe('default sandbox composition keyless smoke (real cordis.yml via the Loa
 describe.skipIf(!process.env.DEEPSEEK_API_KEY || !hasRunner)('default sandbox composition e2e: the live approval loop', () => {
   it('denial → model escalation → editor prompt → allow-once → the retried write lands on disk', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'sandbox-acp-e2e-'))
-    spawned = launchExampleAcpAgent(workdir, 'allow-once')
-    const { client, permissionRequests } = spawned
+    spawned = launchExampleAcpAgent(workdir, 'allow-once', 'read-only')
+    const { client, permissionRequests, updates } = spawned
 
     await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
     const { sessionId } = await client.newSession({ cwd: workdir, mcpServers: [] })
     const res = await client.prompt({
       sessionId,
-      prompt: [{ type: 'text', text: `The sandbox already denied writing ${workdir}/escalated.txt. Create it now containing exactly "ACP_ESCALATION_OK": `
-        + 'one single bash call with sandbox_permissions set to danger-full-access and a one-sentence justification, then stop.' }],
+      prompt: [{
+        type: 'text',
+        text: `${escalationPrompt(join(workdir, 'escalated.txt'), 'ACP_ESCALATION_OK')} Then stop.`,
+      }],
     })
     expect(['end_turn', 'max_tokens']).toContain(res.stopReason)
+    expect(includesReadOnlyDenial(updates)).toBe(true)
 
     // The WORLD: the approved escalated retry landed the write.
     const proof = await readFile(join(workdir, 'escalated.txt'), 'utf8')
@@ -166,17 +185,20 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || !hasRunner)('default sandbox co
 
   it('a rejected escalation stays denied: no write lands, the turn still ends', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'sandbox-acp-e2e-'))
-    spawned = launchExampleAcpAgent(workdir, 'reject-once')
-    const { client, permissionRequests } = spawned
+    spawned = launchExampleAcpAgent(workdir, 'reject-once', 'read-only')
+    const { client, permissionRequests, updates } = spawned
 
     await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
     const { sessionId } = await client.newSession({ cwd: workdir, mcpServers: [] })
     const res = await client.prompt({
       sessionId,
-      prompt: [{ type: 'text', text: `The sandbox already denied writing ${workdir}/refused.txt. Create it now containing "NO": `
-        + 'one single bash call with sandbox_permissions set to danger-full-access and a one-sentence justification. If that is rejected, stop and say so.' }],
+      prompt: [{
+        type: 'text',
+        text: `${escalationPrompt(join(workdir, 'refused.txt'), 'NO')} If approval is rejected, stop and say so.`,
+      }],
     })
     expect(['end_turn', 'max_tokens']).toContain(res.stopReason)
+    expect(includesReadOnlyDenial(updates)).toBe(true)
 
     // The WORLD: rejected means the file never appeared.
     await expect(readFile(join(workdir, 'refused.txt'), 'utf8')).rejects.toThrow()
diff --git a/examples/acp-agent/tests/fixtures/live-mode-switching-2026-07-07.session.jsonl b/examples/acp-agent/tests/fixtures/live-mode-switching-2026-07-07.session.jsonl
index 10ffb8c507..cb28e3c646 100644
--- a/examples/acp-agent/tests/fixtures/live-mode-switching-2026-07-07.session.jsonl
+++ b/examples/acp-agent/tests/fixtures/live-mode-switching-2026-07-07.session.jsonl
@@ -688,7 +688,7 @@
 {"type":"turn/start","seq":686,"time":1783421455801,"data":{"turn":4,"trigger":{"kind":"message","source":{"kind":"user"}}}}
 {"type":"approval/policy","seq":687,"time":1783421455801,"data":{"policy":"never"}}
 {"type":"user/message","seq":688,"time":1783421455801,"data":{"content":[{"type":"text","text":"帮我创建一个 c.md"}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"context/message","seq":689,"time":1783421455802,"data":{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"approval"}},"surfaceOp":"append"}
+{"type":"user/message","seq":689,"time":1783421455802,"data":{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"approval"}},"surfaceOp":"append"}
 {"type":"step/start","seq":690,"time":1783421455802,"data":{"turn":4,"step":1}}
 {"type":"request/header-delta","seq":691,"time":1783421455802,"data":{"system":{"keepStart":13,"keepEnd":0,"insert":["","Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation."]}}}
 {"type":"assistant/chunk","seq":692,"time":1783421456825,"data":{"turn":4,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
@@ -830,7 +830,7 @@
 {"type":"turn/start","seq":828,"time":1783421478599,"data":{"turn":5,"trigger":{"kind":"message","source":{"kind":"user"}}}}
 {"type":"bash/sandbox-mode","seq":829,"time":1783421478599,"data":{"mode":"workspace-write"}}
 {"type":"user/message","seq":830,"time":1783421478599,"data":{"content":[{"type":"text","text":"帮我创建一个 d.md"}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"context/message","seq":831,"time":1783421478600,"data":{"content":[{"type":"text","text":"The bash sandbox mode changed from \"read-only\" to \"workspace-write\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"tool-bash"}},"surfaceOp":"append"}
+{"type":"user/message","seq":831,"time":1783421478600,"data":{"content":[{"type":"text","text":"The bash sandbox mode changed from \"read-only\" to \"workspace-write\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"tool-bash"}},"surfaceOp":"append"}
 {"type":"step/start","seq":832,"time":1783421478600,"data":{"turn":5,"step":1}}
 {"type":"request/header-delta","seq":833,"time":1783421478600,"data":{"system":{"keepStart":12,"keepEnd":2,"insert":["Bash commands run under the \"workspace-write\" file sandbox."]}}}
 {"type":"assistant/chunk","seq":834,"time":1783421479489,"data":{"turn":5,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
@@ -1482,7 +1482,7 @@
 {"type":"turn/start","seq":1480,"time":1783421524030,"data":{"turn":7,"trigger":{"kind":"message","source":{"kind":"user"}}}}
 {"type":"approval/policy","seq":1481,"time":1783421524030,"data":{"policy":"ask"}}
 {"type":"user/message","seq":1482,"time":1783421524030,"data":{"content":[{"type":"text","text":"帮我在 ~ 创建一个 f.md"}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"context/message","seq":1483,"time":1783421524030,"data":{"content":[{"type":"text","text":"The approval policy changed from \"never\" to \"ask\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"approval"}},"surfaceOp":"append"}
+{"type":"user/message","seq":1483,"time":1783421524030,"data":{"content":[{"type":"text","text":"The approval policy changed from \"never\" to \"ask\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"approval"}},"surfaceOp":"append"}
 {"type":"step/start","seq":1484,"time":1783421524030,"data":{"turn":7,"step":1}}
 {"type":"request/header-delta","seq":1485,"time":1783421524030,"data":{"system":{"keepStart":13,"keepEnd":0,"insert":[]}}}
 {"type":"assistant/chunk","seq":1486,"time":1783421524940,"data":{"turn":7,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
@@ -1946,7 +1946,7 @@
 {"type":"turn/start","seq":1944,"time":1783421552564,"data":{"turn":9,"trigger":{"kind":"message","source":{"kind":"user"}}}}
 {"type":"bash/sandbox-mode","seq":1945,"time":1783421552564,"data":{"mode":"danger-full-access"}}
 {"type":"user/message","seq":1946,"time":1783421552564,"data":{"content":[{"type":"text","text":"创建一个 h.md"}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"context/message","seq":1947,"time":1783421552564,"data":{"content":[{"type":"text","text":"The bash sandbox mode changed from \"workspace-write\" to \"danger-full-access\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"tool-bash"}},"surfaceOp":"append"}
+{"type":"user/message","seq":1947,"time":1783421552564,"data":{"content":[{"type":"text","text":"The bash sandbox mode changed from \"workspace-write\" to \"danger-full-access\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"tool-bash"}},"surfaceOp":"append"}
 {"type":"step/start","seq":1948,"time":1783421552564,"data":{"turn":9,"step":1}}
 {"type":"request/header-delta","seq":1949,"time":1783421552564,"data":{"system":{"keepStart":12,"keepEnd":0,"insert":["Bash commands run under the \"danger-full-access\" file sandbox."]}}}
 {"type":"assistant/chunk","seq":1950,"time":1783421553289,"data":{"turn":9,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/examples/acp-agent/tests/goal-snapshots/goal-session/session.expected.jsonl b/examples/acp-agent/tests/goal-snapshots/goal-session/session.expected.jsonl
index 8954fd6bad..d598b34e37 100644
--- a/examples/acp-agent/tests/goal-snapshots/goal-session/session.expected.jsonl
+++ b/examples/acp-agent/tests/goal-snapshots/goal-session/session.expected.jsonl
@@ -12,7 +12,7 @@
 {"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_goal_create","name":"create_goal","arguments":"{\"objective\":\"Finish the ACP goal-session snapshot proof\",\"max_goal_rounds\":2}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":20,"outputTokens":8}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}
 {"type":"tool/call","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"call_goal_create","name":"create_goal","arguments":"{\"objective\":\"Finish the ACP goal-session snapshot proof\",\"max_goal_rounds\":2}"}}
 {"type":"tool/result","seq":12,"time":0,"data":{"turn":1,"step":1,"callId":"call_goal_create","content":[{"type":"text","text":"{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the ACP goal-session snapshot proof\",\"phase\":\"active\",\"roundsStarted\":0,\"maxGoalRounds\":2},\"activation\":\"armed\"}"}],"isError":false},"sourceEventSeqs":[11],"surfaceOp":"append"}
-{"type":"context/message","seq":13,"time":0,"data":{"content":[{"type":"text","text":"<goal_state>{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the ACP goal-session snapshot proof\",\"phase\":\"active\",\"maxGoalRounds\":2},\"roundsStarted\":0,\"createdAt\":0,\"updatedAt\":0}</goal_state>"}],"source":{"kind":"goal","goalId":"goal-{{sessionId}}","revision":1,"round":0},"meta":{"kind":"goal/change","version":1,"operation":"create","goal":{"id":"goal-{{sessionId}}","revision":1,"objective":"Finish the ACP goal-session snapshot proof","phase":"active","maxGoalRounds":2},"roundsStarted":0,"createdAt":0,"updatedAt":0}},"surfaceOp":"append"}
+{"type":"user/message","seq":13,"time":0,"data":{"content":[{"type":"text","text":"<goal_state>{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the ACP goal-session snapshot proof\",\"phase\":\"active\",\"maxGoalRounds\":2},\"roundsStarted\":0,\"createdAt\":0,\"updatedAt\":0}</goal_state>"}],"source":{"kind":"goal","goalId":"goal-{{sessionId}}","revision":1,"round":0},"meta":{"kind":"goal/change","version":1,"operation":"create","goal":{"id":"goal-{{sessionId}}","revision":1,"objective":"Finish the ACP goal-session snapshot proof","phase":"active","maxGoalRounds":2},"roundsStarted":0,"createdAt":0,"updatedAt":0}},"surfaceOp":"append"}
 {"type":"step/end","seq":14,"time":0,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":15,"time":0,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
@@ -49,6 +49,6 @@
 {"type":"step/start","seq":47,"time":0,"data":{"turn":3,"step":1}}
 {"type":"assistant/chunk","seq":48,"time":0,"data":{"turn":3,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":49,"time":0,"data":{"turn":3,"step":1,"chunk":{"type":"text-delta","index":0,"text":"partial"}}}
-{"type":"context/message","seq":50,"time":0,"data":{"content":[{"type":"text","text":"<goal_state>{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":2,\"objective\":\"Finish the ACP goal-session snapshot proof\",\"phase\":\"paused\",\"maxGoalRounds\":2},\"roundsStarted\":2,\"createdAt\":0,\"updatedAt\":0}</goal_state>"}],"source":{"kind":"goal","goalId":"goal-{{sessionId}}","revision":2,"round":0},"meta":{"kind":"goal/change","version":1,"operation":"pause","goal":{"id":"goal-{{sessionId}}","revision":2,"objective":"Finish the ACP goal-session snapshot proof","phase":"paused","maxGoalRounds":2},"roundsStarted":2,"createdAt":0,"updatedAt":0}},"surfaceOp":"append"}
+{"type":"user/message","seq":50,"time":0,"data":{"content":[{"type":"text","text":"<goal_state>{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":2,\"objective\":\"Finish the ACP goal-session snapshot proof\",\"phase\":\"paused\",\"maxGoalRounds\":2},\"roundsStarted\":2,\"createdAt\":0,\"updatedAt\":0}</goal_state>"}],"source":{"kind":"goal","goalId":"goal-{{sessionId}}","revision":2,"round":0},"meta":{"kind":"goal/change","version":1,"operation":"pause","goal":{"id":"goal-{{sessionId}}","revision":2,"objective":"Finish the ACP goal-session snapshot proof","phase":"paused","maxGoalRounds":2},"roundsStarted":2,"createdAt":0,"updatedAt":0}},"surfaceOp":"append"}
 {"type":"step/end","seq":51,"time":0,"data":{"turn":3,"step":1}}
 {"type":"turn/end","seq":52,"time":0,"data":{"turn":3,"reason":{"kind":"aborted"}}}
diff --git a/examples/acp-agent/tests/goal-snapshots/goal-session/stdout.expected.jsonl b/examples/acp-agent/tests/goal-snapshots/goal-session/stdout.expected.jsonl
index 747412d4f0..48965f6b4f 100644
--- a/examples/acp-agent/tests/goal-snapshots/goal-session/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/goal-snapshots/goal-session/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Create a durable two-round goal","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_goal_create","title":"Create goal","kind":"other","status":"in_progress","rawInput":"Finish the ACP goal-session snapshot proof"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_goal_create","status":"completed","content":[{"type":"content","content":{"type":"text","text":"{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the ACP goal-session snapshot proof\",\"phase\":\"active\",\"roundsStarted\":0,\"maxGoalRounds\":2},\"activation\":\"armed\"}"}}]}}}
diff --git a/examples/acp-agent/tests/goal.snapshot.ts b/examples/acp-agent/tests/goal.snapshot.ts
index 4bb01acd16..23359f9982 100644
--- a/examples/acp-agent/tests/goal.snapshot.ts
+++ b/examples/acp-agent/tests/goal.snapshot.ts
@@ -83,6 +83,7 @@ describe('ACP same-session goal snapshot', () => {
     const calls = events.filter(event => event.type === 'tool/call').map(event => event.data.name)
     expect(calls).toEqual(['create_goal', 'get_goal'])
     const rounds = events.flatMap(event => event.type === 'user/message' && event.data.source.kind === 'goal'
+      && event.data.source.round > 0
       ? [event.data.source.round]
       : [])
     expect(rounds).toEqual([1, 2])
diff --git a/examples/acp-agent/tests/semantic-checkpoint-snapshots/tool-outcome-unknown/stdout.expected.jsonl b/examples/acp-agent/tests/semantic-checkpoint-snapshots/tool-outcome-unknown/stdout.expected.jsonl
index 3075390cf5..96896d268a 100644
--- a/examples/acp-agent/tests/semantic-checkpoint-snapshots/tool-outcome-unknown/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/semantic-checkpoint-snapshots/tool-outcome-unknown/stdout.expected.jsonl
@@ -2,7 +2,7 @@
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"user_message_chunk","content":{"type":"text","text":"Perform one side-effecting remote mutation."}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"unknown-outcome-call","title":"write_remote","kind":"other","status":"in_progress","rawInput":{"value":1}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"unknown-outcome-call","status":"failed","content":[{"type":"content","content":{"type":"text","text":"The tool call was interrupted after it was recorded, but no result was durably recorded. Its outcome is unknown. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly."}}]}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":2,"result":{"modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Perform one side-effecting remote mutati","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"I will verify the external state before deciding whether to retry the side-effecting operation."}}}}
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
index 3b7a3a06f2..e754dd5639 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -22,7 +22,7 @@
 {"type":"assistant/message","seq":20,"time":1783957884490,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}
 {"type":"tool/call","seq":21,"time":1783957884490,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}
 {"type":"tool/code-dispatch","seq":22,"time":1783957884560,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"dynamic"},"isError":false,"resultSummary":"## dynamic\n- dyn-1: snapshot-marker [active]"}}
-{"type":"tool/result","seq":23,"time":1783957884561,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[21],"surfaceOp":"append"}
+{"type":"tool/result","seq":23,"time":1783957884561,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false},"sourceEventSeqs":[21],"surfaceOp":"append"}
 {"type":"step/end","seq":24,"time":1783957884561,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":25,"time":1783957884562,"data":{"turn":1,"step":3}}
 {"type":"assistant/chunk","seq":26,"time":1783950000026,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/advanced-toolchain/stdout.expected.jsonl
index 94914e7eda..7c0fe5cd9c 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Run this advanced flow exactly","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"advanced-mount","title":"Mount plugin into live cordis runtime","kind":"execute","status":"in_progress","rawInput":{"code":"return { name: 'snapshot-marker', apply() {} }"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"advanced-mount","status":"completed","content":[{"type":"content","content":{"type":"text","text":"mounted dyn-1 (plugin \"snapshot-marker\", state: active)"}}]}}}
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 2b46661722..73c31413bf 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
@@ -28,19 +28,21 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
 
 Pass `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:
 
-- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.
-- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.
+- 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.
+- 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.
 - Calls execute sequentially, even under `Promise.all`.
 - 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.
 
 The available tools:
 
 ```ts
-declare const tools: {
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+interface ToolArgsMap {
   /** 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. */
-  ask_user_question(args: {
+  ask_user_question: {
     /** Questions to ask the user before continuing. */
-    questions: {
+    questions: ({
       /** Stable id for this question; echoed in the answer. */
       id: string;
       /** The specific question to ask the user. */
@@ -48,18 +50,18 @@ declare const tools: {
       /** Optional short heading for the question, such as "Confirm" or "Choose Mode". */
       header?: string;
       /** Optional choices to show the user. If you recommend one, put it first and append "(Recommended)" to that label. */
-      options?: {
+      options?: ({
         /** Short user-facing option label. */
         label: string;
         /** One sentence explaining the tradeoff or impact. */
         description?: string;
-      }[];
+      } & Record<string, JsonValue>)[];
       /** Whether the user may select more than one option. Defaults to false. */
       multi_select?: boolean;
-    }[];
-  }): Promise<string>;
+    } & Record<string, JsonValue>)[];
+  } & Record<string, JsonValue>;
   /** 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. */
-  bash(args: {
+  bash: {
     /** The bash command to execute. */
     command: string;
     /** 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". */
@@ -74,33 +76,33 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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. */
-  cordis_inspect(args: {
+  cordis_inspect: {
     /** Limit the report to one section. Omit for all sections. */
     what?: "services" | "plugins" | "tools" | "dynamic" | "api" | "events";
     /** Exact service key or event name whose original JSDoc to include; valid only with what:"api" or what:"events". */
     name?: string;
-  }): Promise<string>;
-  /** Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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. */
-  cordis_mount(args: {
+  } & Record<string, JsonValue>;
+  /** Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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. */
+  cordis_mount: {
     /** Body of an async JS function; must `return` the plugin to mount. */
     code: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). */
-  cordis_unmount(args: {
+  cordis_unmount: {
     /** The dynamic mount id returned by cordis_mount (e.g. "dyn-1"). */
     id: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. */
-  create_goal(args: {
+  create_goal: {
     /** The concrete completion objective inferred from the direct human request. */
     objective: string;
     /** Optional positive safe-integer limit on automatic continuation rounds. */
     max_goal_rounds?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Edit an existing UTF-8 text file by replacing literal text. */
-  edit(args: {
+  edit: {
     /** Path to edit, resolved by the filesystem backend. */
     file_path: string;
     /** Literal text to replace. Must match exactly. */
@@ -113,83 +115,83 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again. */
-  exit_plan_mode(args: {
+  exit_plan_mode: {
     /** The complete plan, as markdown, starting with a # heading that names it. */
     plan: string;
-  }): Promise<string>;
+  } & 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(args: Record<string, unknown>): Promise<string>;
+  get_goal: 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(args: {
+  ralph: {
     /** The immutable completion objective for every fresh Ralph round. */
     objective: string;
     /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */
     maxRounds?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Read a UTF-8 text file and return line-numbered content. */
-  read(args: {
+  read: {
     /** Path to read, resolved by the filesystem backend. */
     file_path: string;
     /** 1-based first line to return. Defaults to 1. */
     offset?: number;
     /** Maximum number of lines to return. Defaults to 2000. */
     limit?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. */
-  skill(args: {
+  skill: {
     /** The exact skill name from the available skills list. */
     name: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */
-  subagent(args: {
+  subagent: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
     /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */
-  subagent_fork(args: {
+  subagent_fork: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
     /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
-  task_kill(args: {
+  task_kill: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
     /** Optional short reason, recorded in the log and forwarded to the task. */
     reason?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
-  task_list(args: Record<string, unknown>): Promise<string>;
+  task_list: Record<string, JsonValue>;
   /** 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. */
-  task_output(args: {
+  task_output: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
     /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */
     wait?: boolean;
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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). */
-  todo_write(args: {
+  todo_write: {
     /** The COMPLETE task list, replacing any previous list. */
     todos: ({
       /** What the task is — a short imperative line. */
       content: string;
       /** pending (not started) | in_progress (now) | completed (done). */
       status: "pending" | "in_progress" | "completed";
-    })[];
-  }): Promise<string>;
+    } & Record<string, JsonValue>)[];
+  } & Record<string, JsonValue>;
   /** 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. */
-  update_goal(args: {
+  update_goal: {
     /** Exact id returned by get_goal. */
     goal_id: string;
     /** Exact positive revision returned by get_goal. */
@@ -202,9 +204,9 @@ declare const tools: {
     max_goal_rounds?: number;
     /** Concrete blocking condition; required only with action blocked. */
     blocked_reason?: string;
-  }): Promise<string>;
-  /** 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 — no oneOf/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. */
-  workflow(args: {
+  } & Record<string, JsonValue>;
+  /** 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. */
+  workflow: {
     /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */
     script: string;
     /** The workflow identity block (plain JSON — never code). */
@@ -216,7 +218,7 @@ declare const tools: {
       /** Optional guidance on when this workflow applies. */
       whenToUse?: string;
       /** Optional phase declarations matched by phase() calls. */
-      phases?: {
+      phases?: ({
         /** The phase title phase() calls match by exact string. */
         title: string;
         /** Optional one-line description of the phase. */
@@ -225,13 +227,13 @@ declare const tools: {
         provider?: string;
         /** Optional model override this phase is expected to use. */
         model?: string;
-      }[];
-    };
+      } & Record<string, JsonValue>)[];
+    } & Record<string, JsonValue>;
     /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}). */
-    args?: Record<string, unknown>;
-  }): Promise<string>;
+    args?: Record<string, JsonValue>;
+  } & Record<string, JsonValue>;
   /** Create or fully replace a UTF-8 text file. */
-  write(args: {
+  write: {
     /** Path to write, resolved by the filesystem backend. */
     file_path: string;
     /** Full UTF-8 text content to write. */
@@ -240,6 +242,225 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
+}
+
+interface ToolOutputMap {
+  ask_user_question: {
+    answers: {
+      id: string;
+      selected: string[];
+      custom?: string;
+    }[];
+  };
+  bash: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    timeoutMs: number;
+    stdout: {
+      text: string;
+      truncated: boolean;
+      spillPath?: string;
+    };
+    stderr: {
+      text: string;
+      truncated: boolean;
+      spillPath?: string;
+    };
+    sandbox?: {
+      mode: string;
+      denied: boolean;
+      enforcement?: string;
+      runnerFailed?: boolean;
+    };
+  };
+  cordis_inspect: string;
+  cordis_mount: {
+    id: string;
+    pluginName: string;
+    state: "pending" | "loading" | "active" | "failed" | "disposed" | "unloading";
+    provides: string[];
+    waitingFor: string[];
+  };
+  cordis_unmount: {
+    id: string;
+    pluginName: string;
+  };
+  create_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  edit: {
+    path: string;
+    before: string;
+    after: string;
+  };
+  exit_plan_mode: {
+    approved: true;
+  };
+  get_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  ralph: {
+    runId: string;
+    agentsStarted: number;
+    result: JsonValue;
+  };
+  read: {
+    path: string;
+    offset: number;
+    lines: {
+      number: number;
+      text: string;
+    }[];
+    totalLines: number;
+  };
+  skill: {
+    name: string;
+    provider: string;
+    resourceBase?: {
+      kind: "directory";
+      path: string;
+    } | {
+      kind: "url";
+      url: string;
+    } | {
+      kind: "opaque";
+      description: string;
+    };
+    content: string;
+  };
+  subagent: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    runId: string;
+    output: JsonValue[];
+  };
+  subagent_fork: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    runId: string;
+    output: JsonValue[];
+  };
+  task_kill: {
+    outcome: "cancellation-requested" | "already-finished";
+    task: {
+      id: string;
+      kind: string;
+      label: string;
+      status: "running" | "stopping" | "completed" | "killed" | "failed";
+      detail?: string;
+      startedAt: number;
+      finishedAt?: number;
+    };
+  };
+  task_list: ({
+    id: string;
+    kind: string;
+    label: string;
+    status: "running" | "stopping" | "completed" | "killed" | "failed";
+    detail?: string;
+    startedAt: number;
+    finishedAt?: number;
+  })[];
+  task_output: {
+    text: string;
+    task: {
+      id: string;
+      kind: string;
+      label: string;
+      status: "running" | "stopping" | "completed" | "killed" | "failed";
+      detail?: string;
+      startedAt: number;
+      finishedAt?: number;
+    };
+  };
+  todo_write: {
+    todos: ({
+      content: string;
+      status: "pending" | "in_progress" | "completed";
+    })[];
+    counts: {
+      pending: number;
+      inProgress: number;
+      completed: number;
+    };
+  };
+  update_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  workflow: {
+    runId: string;
+    agentsStarted: number;
+    result: JsonValue;
+  };
+  write: {
+    path: string;
+    operation: "create" | "update";
+    before: string | null;
+    after: string;
+  };
+}
+
+type ToolName = keyof ToolOutputMap
+
+declare class ToolCallError extends Error {
+  readonly name: "ToolCallError";
+  readonly toolName: ToolName;
+}
+
+declare const tools: {
+  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;
 }
 ```
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 4b3868a31d..6b50a5d220 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
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -133,7 +135,7 @@
     },
     {
       "name": "cordis_mount",
-      "description": "Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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": {
@@ -438,6 +440,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -512,7 +515,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -523,6 +526,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -541,6 +545,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -572,7 +577,8 @@
           },
           "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\": [...]})."
+            "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": [
diff --git a/examples/acp-agent/tests/snapshots/bash-spill/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/bash-spill/stdout.expected.jsonl
index ca3eedb9cd..01a96948ba 100644
--- a/examples/acp-agent/tests/snapshots/bash-spill/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/bash-spill/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_spill","title":"node -e \"process.stdout.write('SPILL_START-' + 'x'.repeat(2000) + '-SPILL_END')\"","kind":"execute","status":"in_progress","rawInput":"node -e \"process.stdout.write('SPILL_START-' + 'x'.repeat(2000) + '-SPILL_END')\"","content":[{"type":"content","content":{"type":"text","text":"Print large deterministic output"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_spill","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\nSPILL_START-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-SPILL_END\n\n(Omitted 1417 bytes. Full formatted result stored at: {{spillLocator:bash.txt}}. Use read with offset/limit, or grep this path to search within it.)\n```"}}]}}}
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 358ea0c331..cbc7e2cd3a 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
@@ -77,18 +77,18 @@
 {"type":"assistant/chunk","seq":75,"time":1783611775407,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","argumentsDelta":"\\\""}}}
 {"type":"assistant/chunk","seq":76,"time":1783611775408,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","argumentsDelta":" });\\n"}}}
 {"type":"assistant/chunk","seq":77,"time":1783611775408,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","argumentsDelta":"return"}}}
-{"type":"assistant/chunk","seq":78,"time":1783611775436,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","argumentsDelta":" result"}}}
+{"type":"assistant/chunk","seq":78,"time":1783611775436,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","argumentsDelta":" result.stdout.text"}}}
 {"type":"assistant/chunk","seq":79,"time":1783611775437,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","argumentsDelta":";"}}}
 {"type":"assistant/chunk","seq":80,"time":1783611775437,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","argumentsDelta":"\""}}}
 {"type":"assistant/chunk","seq":81,"time":1783611775474,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","argumentsDelta":"}"}}}
 {"type":"assistant/chunk","seq":82,"time":1783611775497,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use the `run_code` tool to execute a program that calls `tools.bash` with the command `echo BOTH_OK` and returns its output."}}}}
-{"type":"assistant/chunk","seq":83,"time":1783611775498,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result;\"}"}}}}
+{"type":"assistant/chunk","seq":83,"time":1783611775498,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result.stdout.text;\"}"}}}}
 {"type":"assistant/chunk","seq":84,"time":1783611775498,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":5530,"outputTokens":108,"cacheReadTokens":0,"reasoningTokens":37}}}}
 {"type":"assistant/chunk","seq":85,"time":1783611775498,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":86,"time":1783611775503,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to use the `run_code` tool to execute a program that calls `tools.bash` with the command `echo BOTH_OK` and returns its output."},{"type":"tool-call","id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result;\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":5530,"outputTokens":108,"cacheReadTokens":0,"reasoningTokens":37}},"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],"surfaceOp":"append"}
-{"type":"tool/call","seq":87,"time":1783611775504,"data":{"turn":1,"step":1,"callId":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result;\"}"}}
+{"type":"assistant/message","seq":86,"time":1783611775503,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to use the `run_code` tool to execute a program that calls `tools.bash` with the command `echo BOTH_OK` and returns its output."},{"type":"tool-call","id":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result.stdout.text;\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":5530,"outputTokens":108,"cacheReadTokens":0,"reasoningTokens":37}},"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],"surfaceOp":"append"}
+{"type":"tool/call","seq":87,"time":1783611775504,"data":{"turn":1,"step":1,"callId":"call_00_AZFzvUwuC4vAUoICrfke5147","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result.stdout.text;\"}"}}
 {"type":"tool/code-dispatch","seq":88,"time":1783611775590,"data":{"parentCallId":"call_00_AZFzvUwuC4vAUoICrfke5147","subCallId":"call_00_AZFzvUwuC4vAUoICrfke5147:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Echo BOTH_OK"},"isError":false,"resultSummary":"BOTH_OK\n"}}
-{"type":"tool/result","seq":89,"time":1783611775592,"data":{"turn":1,"step":1,"callId":"call_00_AZFzvUwuC4vAUoICrfke5147","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[87],"surfaceOp":"append"}
+{"type":"tool/result","seq":89,"time":1783611775592,"data":{"turn":1,"step":1,"callId":"call_00_AZFzvUwuC4vAUoICrfke5147","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false},"sourceEventSeqs":[87],"surfaceOp":"append"}
 {"type":"step/end","seq":90,"time":1783611775592,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":91,"time":1783611775592,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":92,"time":1783611776183,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.expected.jsonl
index 99d2f0bd5b..2fb72d7f0b 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Call the run_code tool (NOT","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
@@ -39,7 +39,7 @@
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" its"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_AZFzvUwuC4vAUoICrfke5147","title":"const result = await tools.bash({ command: \"echo BOTH_OK\", description: \"Echo BOTH_OK\" });\nreturn result;","kind":"execute","status":"in_progress","rawInput":"const result = await tools.bash({ command: \"echo BOTH_OK\", description: \"Echo BOTH_OK\" });\nreturn result;"}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_AZFzvUwuC4vAUoICrfke5147","title":"const result = await tools.bash({ command: \"echo BOTH_OK\", description: \"Echo BOTH_OK\" });\nreturn result.stdout.text;","kind":"execute","status":"in_progress","rawInput":"const result = await tools.bash({ command: \"echo BOTH_OK\", description: \"Echo BOTH_OK\" });\nreturn result.stdout.text;"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_AZFzvUwuC4vAUoICrfke5147","status":"completed","content":[{"type":"content","content":{"type":"text","text":"BOTH_OK\n"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md
index 8868412707..8744029272 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md
@@ -28,19 +28,21 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
 
 Pass `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:
 
-- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.
-- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.
+- 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.
+- 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.
 - Calls execute sequentially, even under `Promise.all`.
 - 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.
 
 The available tools:
 
 ```ts
-declare const tools: {
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+interface ToolArgsMap {
   /** 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. */
-  ask_user_question(args: {
+  ask_user_question: {
     /** Questions to ask the user before continuing. */
-    questions: {
+    questions: ({
       /** Stable id for this question; echoed in the answer. */
       id: string;
       /** The specific question to ask the user. */
@@ -48,18 +50,18 @@ declare const tools: {
       /** Optional short heading for the question, such as "Confirm" or "Choose Mode". */
       header?: string;
       /** Optional choices to show the user. If you recommend one, put it first and append "(Recommended)" to that label. */
-      options?: {
+      options?: ({
         /** Short user-facing option label. */
         label: string;
         /** One sentence explaining the tradeoff or impact. */
         description?: string;
-      }[];
+      } & Record<string, JsonValue>)[];
       /** Whether the user may select more than one option. Defaults to false. */
       multi_select?: boolean;
-    }[];
-  }): Promise<string>;
+    } & Record<string, JsonValue>)[];
+  } & Record<string, JsonValue>;
   /** 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. */
-  bash(args: {
+  bash: {
     /** The bash command to execute. */
     command: string;
     /** 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". */
@@ -74,16 +76,16 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. */
-  create_goal(args: {
+  create_goal: {
     /** The concrete completion objective inferred from the direct human request. */
     objective: string;
     /** Optional positive safe-integer limit on automatic continuation rounds. */
     max_goal_rounds?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Edit an existing UTF-8 text file by replacing literal text. */
-  edit(args: {
+  edit: {
     /** Path to edit, resolved by the filesystem backend. */
     file_path: string;
     /** Literal text to replace. Must match exactly. */
@@ -96,83 +98,83 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again. */
-  exit_plan_mode(args: {
+  exit_plan_mode: {
     /** The complete plan, as markdown, starting with a # heading that names it. */
     plan: string;
-  }): Promise<string>;
+  } & 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(args: Record<string, unknown>): Promise<string>;
+  get_goal: 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(args: {
+  ralph: {
     /** The immutable completion objective for every fresh Ralph round. */
     objective: string;
     /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */
     maxRounds?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Read a UTF-8 text file and return line-numbered content. */
-  read(args: {
+  read: {
     /** Path to read, resolved by the filesystem backend. */
     file_path: string;
     /** 1-based first line to return. Defaults to 1. */
     offset?: number;
     /** Maximum number of lines to return. Defaults to 2000. */
     limit?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. */
-  skill(args: {
+  skill: {
     /** The exact skill name from the available skills list. */
     name: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */
-  subagent(args: {
+  subagent: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
     /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */
-  subagent_fork(args: {
+  subagent_fork: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
     /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
-  task_kill(args: {
+  task_kill: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
     /** Optional short reason, recorded in the log and forwarded to the task. */
     reason?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
-  task_list(args: Record<string, unknown>): Promise<string>;
+  task_list: Record<string, JsonValue>;
   /** 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. */
-  task_output(args: {
+  task_output: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
     /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */
     wait?: boolean;
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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). */
-  todo_write(args: {
+  todo_write: {
     /** The COMPLETE task list, replacing any previous list. */
     todos: ({
       /** What the task is — a short imperative line. */
       content: string;
       /** pending (not started) | in_progress (now) | completed (done). */
       status: "pending" | "in_progress" | "completed";
-    })[];
-  }): Promise<string>;
+    } & Record<string, JsonValue>)[];
+  } & Record<string, JsonValue>;
   /** 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. */
-  update_goal(args: {
+  update_goal: {
     /** Exact id returned by get_goal. */
     goal_id: string;
     /** Exact positive revision returned by get_goal. */
@@ -185,9 +187,9 @@ declare const tools: {
     max_goal_rounds?: number;
     /** Concrete blocking condition; required only with action blocked. */
     blocked_reason?: string;
-  }): Promise<string>;
-  /** 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 — no oneOf/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. */
-  workflow(args: {
+  } & Record<string, JsonValue>;
+  /** 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. */
+  workflow: {
     /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */
     script: string;
     /** The workflow identity block (plain JSON — never code). */
@@ -199,7 +201,7 @@ declare const tools: {
       /** Optional guidance on when this workflow applies. */
       whenToUse?: string;
       /** Optional phase declarations matched by phase() calls. */
-      phases?: {
+      phases?: ({
         /** The phase title phase() calls match by exact string. */
         title: string;
         /** Optional one-line description of the phase. */
@@ -208,13 +210,13 @@ declare const tools: {
         provider?: string;
         /** Optional model override this phase is expected to use. */
         model?: string;
-      }[];
-    };
+      } & Record<string, JsonValue>)[];
+    } & Record<string, JsonValue>;
     /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}). */
-    args?: Record<string, unknown>;
-  }): Promise<string>;
+    args?: Record<string, JsonValue>;
+  } & Record<string, JsonValue>;
   /** Create or fully replace a UTF-8 text file. */
-  write(args: {
+  write: {
     /** Path to write, resolved by the filesystem backend. */
     file_path: string;
     /** Full UTF-8 text content to write. */
@@ -223,6 +225,213 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
+}
+
+interface ToolOutputMap {
+  ask_user_question: {
+    answers: {
+      id: string;
+      selected: string[];
+      custom?: string;
+    }[];
+  };
+  bash: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    timeoutMs: number;
+    stdout: {
+      text: string;
+      truncated: boolean;
+      spillPath?: string;
+    };
+    stderr: {
+      text: string;
+      truncated: boolean;
+      spillPath?: string;
+    };
+    sandbox?: {
+      mode: string;
+      denied: boolean;
+      enforcement?: string;
+      runnerFailed?: boolean;
+    };
+  };
+  create_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  edit: {
+    path: string;
+    before: string;
+    after: string;
+  };
+  exit_plan_mode: {
+    approved: true;
+  };
+  get_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  ralph: {
+    runId: string;
+    agentsStarted: number;
+    result: JsonValue;
+  };
+  read: {
+    path: string;
+    offset: number;
+    lines: {
+      number: number;
+      text: string;
+    }[];
+    totalLines: number;
+  };
+  skill: {
+    name: string;
+    provider: string;
+    resourceBase?: {
+      kind: "directory";
+      path: string;
+    } | {
+      kind: "url";
+      url: string;
+    } | {
+      kind: "opaque";
+      description: string;
+    };
+    content: string;
+  };
+  subagent: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    runId: string;
+    output: JsonValue[];
+  };
+  subagent_fork: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    runId: string;
+    output: JsonValue[];
+  };
+  task_kill: {
+    outcome: "cancellation-requested" | "already-finished";
+    task: {
+      id: string;
+      kind: string;
+      label: string;
+      status: "running" | "stopping" | "completed" | "killed" | "failed";
+      detail?: string;
+      startedAt: number;
+      finishedAt?: number;
+    };
+  };
+  task_list: ({
+    id: string;
+    kind: string;
+    label: string;
+    status: "running" | "stopping" | "completed" | "killed" | "failed";
+    detail?: string;
+    startedAt: number;
+    finishedAt?: number;
+  })[];
+  task_output: {
+    text: string;
+    task: {
+      id: string;
+      kind: string;
+      label: string;
+      status: "running" | "stopping" | "completed" | "killed" | "failed";
+      detail?: string;
+      startedAt: number;
+      finishedAt?: number;
+    };
+  };
+  todo_write: {
+    todos: ({
+      content: string;
+      status: "pending" | "in_progress" | "completed";
+    })[];
+    counts: {
+      pending: number;
+      inProgress: number;
+      completed: number;
+    };
+  };
+  update_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  workflow: {
+    runId: string;
+    agentsStarted: number;
+    result: JsonValue;
+  };
+  write: {
+    path: string;
+    operation: "create" | "update";
+    before: string | null;
+    after: string;
+  };
+}
+
+type ToolName = keyof ToolOutputMap
+
+declare class ToolCallError extends Error {
+  readonly name: "ToolCallError";
+  readonly toolName: ToolName;
+}
+
+declare const tools: {
+  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;
 }
 ```
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 79cb046a40..7ceeec4042 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
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -381,6 +383,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -455,7 +458,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -466,6 +469,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -484,6 +488,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -515,7 +520,8 @@
           },
           "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\": [...]})."
+            "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": [
diff --git a/examples/acp-agent/tests/snapshots/cancel-tool-calls/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/cancel-tool-calls/stdout.expected.jsonl
index a2b46185d3..6258693575 100644
--- a/examples/acp-agent/tests/snapshots/cancel-tool-calls/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/cancel-tool-calls/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Run two shell commands: wait","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_wait","title":"node -e \"require('node:fs').writeFileSync('started.txt', 'started'); setInterval(() => {}, 1000)\"","kind":"execute","status":"in_progress","rawInput":"node -e \"require('node:fs').writeFileSync('started.txt', 'started'); setInterval(() => {}, 1000)\"","content":[{"type":"content","content":{"type":"text","text":"Wait until cancellation"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"stopReason":"cancelled"}}
diff --git a/examples/acp-agent/tests/snapshots/cancel/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/cancel/stdout.expected.jsonl
index 9cf7d7d4c4..c528122503 100644
--- a/examples/acp-agent/tests/snapshots/cancel/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/cancel/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Start a long task; this","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"partial"}}}}
 {"jsonrpc":"2.0","id":3,"result":{"stopReason":"cancelled"}}
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/input.json b/examples/acp-agent/tests/snapshots/code-mode-turn/input.json
index c6d4a1039e..03a3bca538 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/input.json
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/input.json
@@ -2,6 +2,6 @@
   "steps": [
     { "op": "initialize" },
     { "op": "newSession" },
-    { "op": "prompt", "text": "Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop." }
+    { "op": "prompt", "text": "Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO`. Inside that same program, console.log exactly `captured output`, then return the two outputs joined with a plus sign. Reply with that joined string only and stop." }
   ]
 }
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 88e4b7f75d..a7f4620a51 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl
@@ -1,151 +1,685 @@
-{"type":"session","version":0,"id":"94cd1ae4-e1d1-4ec8-9d27-50a1f849b6b3","createdAt":1783611771392,"cwd":"/var/folders/2c/psb0_fmx7hbgz558xjt_f0l00000gn/T/acp-snap-cwd-BteTVR","delegationDepth":0}
-{"type":"turn/start","seq":0,"time":1783611771394,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
-{"type":"user/message","seq":1,"time":1783611771394,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"session/title","seq":2,"time":1783611771394,"data":{"title":"Using ONE run_code program: call","messageSeqs":[1],"source":{"kind":"fallback"}}}
-{"type":"step/start","seq":3,"time":1783611771396,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":1783611771396,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
-{"type":"assistant/chunk","seq":5,"time":1783611771869,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"assistant/chunk","seq":6,"time":1783611771869,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
-{"type":"assistant/chunk","seq":7,"time":1783611771978,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
-{"type":"assistant/chunk","seq":8,"time":1783611772007,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
-{"type":"assistant/chunk","seq":9,"time":1783611772008,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
-{"type":"assistant/chunk","seq":10,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}}
-{"type":"assistant/chunk","seq":11,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}}
-{"type":"assistant/chunk","seq":12,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}}
-{"type":"assistant/chunk","seq":13,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}}
-{"type":"assistant/chunk","seq":14,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
-{"type":"assistant/chunk","seq":15,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" calls"}}}
-{"type":"assistant/chunk","seq":16,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
-{"type":"assistant/chunk","seq":17,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" twice"}}}
-{"type":"assistant/chunk","seq":18,"time":1783611772096,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}}
-{"type":"assistant/chunk","seq":19,"time":1783611772124,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}}
-{"type":"assistant/chunk","seq":20,"time":1783611772153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}}
-{"type":"assistant/chunk","seq":21,"time":1783611772183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
-{"type":"assistant/chunk","seq":22,"time":1783611772183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}}
-{"type":"assistant/chunk","seq":23,"time":1783611772211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}}
-{"type":"assistant/chunk","seq":24,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
-{"type":"assistant/chunk","seq":25,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
-{"type":"assistant/chunk","seq":26,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
-{"type":"assistant/chunk","seq":27,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}}
-{"type":"assistant/chunk","seq":28,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}}
-{"type":"assistant/chunk","seq":29,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
-{"type":"assistant/chunk","seq":30,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}}
-{"type":"assistant/chunk","seq":31,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
-{"type":"assistant/chunk","seq":32,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}}
-{"type":"assistant/chunk","seq":33,"time":1783611772270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" this"}}}
-{"type":"assistant/chunk","seq":34,"time":1783611772270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
-{"type":"assistant/chunk","seq":35,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":36,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":""}}}
-{"type":"assistant/chunk","seq":37,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"{"}}}
-{"type":"assistant/chunk","seq":38,"time":1783611772362,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
-{"type":"assistant/chunk","seq":39,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"code"}}}
-{"type":"assistant/chunk","seq":40,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
-{"type":"assistant/chunk","seq":41,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":": "}}}
-{"type":"assistant/chunk","seq":42,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
-{"type":"assistant/chunk","seq":43,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"const"}}}
-{"type":"assistant/chunk","seq":44,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
-{"type":"assistant/chunk","seq":45,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"1"}}}
-{"type":"assistant/chunk","seq":46,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" ="}}}
-{"type":"assistant/chunk","seq":47,"time":1783611772421,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" await"}}}
-{"type":"assistant/chunk","seq":48,"time":1783611772421,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" tools"}}}
-{"type":"assistant/chunk","seq":49,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".b"}}}
-{"type":"assistant/chunk","seq":50,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ash"}}}
-{"type":"assistant/chunk","seq":51,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"({"}}}
-{"type":"assistant/chunk","seq":52,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" command"}}}
-{"type":"assistant/chunk","seq":53,"time":1783611772478,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
-{"type":"assistant/chunk","seq":54,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
-{"type":"assistant/chunk","seq":55,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"echo"}}}
-{"type":"assistant/chunk","seq":56,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" CODE"}}}
-{"type":"assistant/chunk","seq":57,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"_"}}}
-{"type":"assistant/chunk","seq":58,"time":1783611772508,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ONE"}}}
-{"type":"assistant/chunk","seq":59,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\","}}}
-{"type":"assistant/chunk","seq":60,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" description"}}}
-{"type":"assistant/chunk","seq":61,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
-{"type":"assistant/chunk","seq":62,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
-{"type":"assistant/chunk","seq":63,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"First"}}}
-{"type":"assistant/chunk","seq":64,"time":1783611772538,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" echo"}}}
-{"type":"assistant/chunk","seq":65,"time":1783611772538,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
-{"type":"assistant/chunk","seq":66,"time":1783611772566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" });\\n"}}}
-{"type":"assistant/chunk","seq":67,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"const"}}}
-{"type":"assistant/chunk","seq":68,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
-{"type":"assistant/chunk","seq":69,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"2"}}}
-{"type":"assistant/chunk","seq":70,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" ="}}}
-{"type":"assistant/chunk","seq":71,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" await"}}}
-{"type":"assistant/chunk","seq":72,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" tools"}}}
-{"type":"assistant/chunk","seq":73,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".b"}}}
-{"type":"assistant/chunk","seq":74,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ash"}}}
-{"type":"assistant/chunk","seq":75,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"({"}}}
-{"type":"assistant/chunk","seq":76,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" command"}}}
-{"type":"assistant/chunk","seq":77,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
-{"type":"assistant/chunk","seq":78,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
-{"type":"assistant/chunk","seq":79,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"echo"}}}
-{"type":"assistant/chunk","seq":80,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" CODE"}}}
-{"type":"assistant/chunk","seq":81,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"_T"}}}
-{"type":"assistant/chunk","seq":82,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"WO"}}}
-{"type":"assistant/chunk","seq":83,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\","}}}
-{"type":"assistant/chunk","seq":84,"time":1783611772654,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" description"}}}
-{"type":"assistant/chunk","seq":85,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
-{"type":"assistant/chunk","seq":86,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
-{"type":"assistant/chunk","seq":87,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"Second"}}}
-{"type":"assistant/chunk","seq":88,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" echo"}}}
-{"type":"assistant/chunk","seq":89,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
-{"type":"assistant/chunk","seq":90,"time":1783611772684,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" });\\n"}}}
-{"type":"assistant/chunk","seq":91,"time":1783611772685,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"return"}}}
-{"type":"assistant/chunk","seq":92,"time":1783611772685,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
-{"type":"assistant/chunk","seq":93,"time":1783611772713,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"1"}}}
-{"type":"assistant/chunk","seq":94,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".trim"}}}
-{"type":"assistant/chunk","seq":95,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"()"}}}
-{"type":"assistant/chunk","seq":96,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" +"}}}
-{"type":"assistant/chunk","seq":97,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\"+"}}}
-{"type":"assistant/chunk","seq":98,"time":1783611772744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
-{"type":"assistant/chunk","seq":99,"time":1783611772744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" +"}}}
-{"type":"assistant/chunk","seq":100,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
-{"type":"assistant/chunk","seq":101,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"2"}}}
-{"type":"assistant/chunk","seq":102,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".trim"}}}
-{"type":"assistant/chunk","seq":103,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"();"}}}
-{"type":"assistant/chunk","seq":104,"time":1783611772772,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
-{"type":"assistant/chunk","seq":105,"time":1783611772773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"}"}}}
-{"type":"assistant/chunk","seq":106,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants a single run_code program that calls bash twice, then returns the two outputs joined with a plus sign. Let me write this."}}}}
-{"type":"assistant/chunk","seq":107,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}}
-{"type":"assistant/chunk","seq":108,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3009,"outputTokens":133,"cacheReadTokens":0,"reasoningTokens":29}}}}
-{"type":"assistant/chunk","seq":109,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":110,"time":1783611772840,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants a single run_code program that calls bash twice, then returns the two outputs joined with a plus sign. Let me write this."},{"type":"tool-call","id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3009,"outputTokens":133,"cacheReadTokens":0,"reasoningTokens":29}},"sourceEventSeqs":[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],"surfaceOp":"append"}
-{"type":"tool/call","seq":111,"time":1783611772840,"data":{"turn":1,"step":1,"callId":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}
-{"type":"tool/code-dispatch","seq":112,"time":1783611772933,"data":{"parentCallId":"call_00_DRxnM6R1TThfDwcudW0f2050","subCallId":"call_00_DRxnM6R1TThfDwcudW0f2050:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"First echo"},"isError":false,"resultSummary":"CODE_ONE\n"}}
-{"type":"tool/code-dispatch","seq":113,"time":1783611772936,"data":{"parentCallId":"call_00_DRxnM6R1TThfDwcudW0f2050","subCallId":"call_00_DRxnM6R1TThfDwcudW0f2050:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Second echo"},"isError":false,"resultSummary":"CODE_TWO\n"}}
-{"type":"tool/result","seq":114,"time":1783611772937,"data":{"turn":1,"step":1,"callId":"call_00_DRxnM6R1TThfDwcudW0f2050","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[111],"surfaceOp":"append"}
-{"type":"step/end","seq":115,"time":1783611772938,"data":{"turn":1,"step":1}}
-{"type":"step/start","seq":116,"time":1783611772938,"data":{"turn":1,"step":2}}
-{"type":"assistant/chunk","seq":117,"time":1783611773376,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"assistant/chunk","seq":118,"time":1783611773376,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
-{"type":"assistant/chunk","seq":119,"time":1783611773480,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
-{"type":"assistant/chunk","seq":120,"time":1783611773511,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}}
-{"type":"assistant/chunk","seq":121,"time":1783611773512,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
-{"type":"assistant/chunk","seq":122,"time":1783611773540,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}}
-{"type":"assistant/chunk","seq":123,"time":1783611773541,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
-{"type":"assistant/chunk","seq":124,"time":1783611773541,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
-{"type":"assistant/chunk","seq":125,"time":1783611773569,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" asked"}}}
-{"type":"assistant/chunk","seq":126,"time":1783611773570,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" for"}}}
-{"type":"assistant/chunk","seq":127,"time":1783611773570,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
-{"type":"assistant/chunk","seq":128,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
-{"type":"assistant/chunk","seq":129,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
-{"type":"assistant/chunk","seq":130,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
-{"type":"assistant/chunk","seq":131,"time":1783611773626,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}}
-{"type":"assistant/chunk","seq":132,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
-{"type":"assistant/chunk","seq":133,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
-{"type":"assistant/chunk","seq":134,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
-{"type":"assistant/chunk","seq":135,"time":1783611773654,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":136,"time":1783611773655,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
-{"type":"assistant/chunk","seq":137,"time":1783611773655,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}}
-{"type":"assistant/chunk","seq":138,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
-{"type":"assistant/chunk","seq":139,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}}
-{"type":"assistant/chunk","seq":140,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
-{"type":"assistant/chunk","seq":141,"time":1783611773657,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}}
-{"type":"assistant/chunk","seq":142,"time":1783611773685,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}}
-{"type":"assistant/chunk","seq":143,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is exactly what the user asked for: CODE_ONE+CODE_TWO"}}}}
-{"type":"assistant/chunk","seq":144,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}}
-{"type":"assistant/chunk","seq":145,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":89,"outputTokens":25,"cacheReadTokens":3072,"reasoningTokens":17}}}}
-{"type":"assistant/chunk","seq":146,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":147,"time":1783611773687,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is exactly what the user asked for: CODE_ONE+CODE_TWO"},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":89,"outputTokens":25,"cacheReadTokens":3072,"reasoningTokens":17}},"sourceEventSeqs":[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],"surfaceOp":"append"}
-{"type":"step/end","seq":148,"time":1783611773687,"data":{"turn":1,"step":2}}
-{"type":"turn/end","seq":149,"time":1783611773687,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session","version":0,"id":"bfa65aa9-f8f8-4b91-af4b-9653cee8fc19","createdAt":1784629671301,"cwd":"/var/folders/2c/psb0_fmx7hbgz558xjt_f0l00000gn/T/acp-snap-cwd-QAp4c9","delegationDepth":0}
+{"type":"turn/start","seq":0,"time":1784629671304,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1784629671305,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO`. Inside that same program, console.log exactly `captured output`, then return the two outputs joined with a plus sign. Reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"session/title","seq":2,"time":1784629671305,"data":{"title":"Using ONE run_code program: call","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"step/start","seq":3,"time":1784629671311,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":4,"time":1784629671312,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":5,"time":1784629671745,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":6,"time":1784629671746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}}
+{"type":"assistant/chunk","seq":7,"time":1784629671954,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":8,"time":1784629671983,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" carefully"}}}
+{"type":"assistant/chunk","seq":9,"time":1784629672017,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" read"}}}
+{"type":"assistant/chunk","seq":10,"time":1784629672017,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":11,"time":1784629672039,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" instructions"}}}
+{"type":"assistant/chunk","seq":12,"time":1784629672040,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":13,"time":1784629672040,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":14,"time":1784629672040,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}}
+{"type":"assistant/chunk","seq":15,"time":1784629672040,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":16,"time":1784629672040,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}}
+{"type":"assistant/chunk","seq":17,"time":1784629672068,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ONE"}}}
+{"type":"assistant/chunk","seq":18,"time":1784629672068,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}}
+{"type":"assistant/chunk","seq":19,"time":1784629672068,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}}
+{"type":"assistant/chunk","seq":20,"time":1784629672068,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}}
+{"type":"assistant/chunk","seq":21,"time":1784629672096,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
+{"type":"assistant/chunk","seq":22,"time":1784629672096,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n\n"}}}
+{"type":"assistant/chunk","seq":23,"time":1784629672096,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}}
+{"type":"assistant/chunk","seq":24,"time":1784629672096,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":25,"time":1784629672096,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}}
+{"type":"assistant/chunk","seq":26,"time":1784629672125,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
+{"type":"assistant/chunk","seq":27,"time":1784629672125,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":28,"time":1784629672125,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":29,"time":1784629672153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":30,"time":1784629672153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":31,"time":1784629672153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":32,"time":1784629672153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":33,"time":1784629672153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":34,"time":1784629672187,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" -"}}}
+{"type":"assistant/chunk","seq":35,"time":1784629672187,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}}
+{"type":"assistant/chunk","seq":36,"time":1784629672210,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":37,"time":1784629672237,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":38,"time":1784629672238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":39,"time":1784629672265,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":40,"time":1784629672294,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":41,"time":1784629672294,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":42,"time":1784629672294,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":43,"time":1784629672295,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\"\n"}}}
+{"type":"assistant/chunk","seq":44,"time":1784629672295,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}}
+{"type":"assistant/chunk","seq":45,"time":1784629672295,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":46,"time":1784629672327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}}
+{"type":"assistant/chunk","seq":47,"time":1784629672327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
+{"type":"assistant/chunk","seq":48,"time":1784629672327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":49,"time":1784629672327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":50,"time":1784629672327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":51,"time":1784629672327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":52,"time":1784629672351,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":53,"time":1784629672351,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":54,"time":1784629672351,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":55,"time":1784629672351,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" -"}}}
+{"type":"assistant/chunk","seq":56,"time":1784629672351,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}}
+{"type":"assistant/chunk","seq":57,"time":1784629672351,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":58,"time":1784629672382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":59,"time":1784629672382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":60,"time":1784629672382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":61,"time":1784629672383,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":62,"time":1784629672383,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":63,"time":1784629672383,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":64,"time":1784629672410,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\"\n"}}}
+{"type":"assistant/chunk","seq":65,"time":1784629672410,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}}
+{"type":"assistant/chunk","seq":66,"time":1784629672410,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":67,"time":1784629672411,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Inside"}}}
+{"type":"assistant/chunk","seq":68,"time":1784629672438,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
+{"type":"assistant/chunk","seq":69,"time":1784629672468,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" same"}}}
+{"type":"assistant/chunk","seq":70,"time":1784629672468,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}}
+{"type":"assistant/chunk","seq":71,"time":1784629672468,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}}
+{"type":"assistant/chunk","seq":72,"time":1784629672468,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" console"}}}
+{"type":"assistant/chunk","seq":73,"time":1784629672468,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".log"}}}
+{"type":"assistant/chunk","seq":74,"time":1784629672468,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":75,"time":1784629672495,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":76,"time":1784629672496,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"capt"}}}
+{"type":"assistant/chunk","seq":77,"time":1784629672496,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ured"}}}
+{"type":"assistant/chunk","seq":78,"time":1784629672496,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":79,"time":1784629672525,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}}
+{"type":"assistant/chunk","seq":80,"time":1784629672525,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"4"}}}
+{"type":"assistant/chunk","seq":81,"time":1784629672525,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":82,"time":1784629672525,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Return"}}}
+{"type":"assistant/chunk","seq":83,"time":1784629672552,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":84,"time":1784629672552,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}}
+{"type":"assistant/chunk","seq":85,"time":1784629672553,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}}
+{"type":"assistant/chunk","seq":86,"time":1784629672553,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
+{"type":"assistant/chunk","seq":87,"time":1784629672553,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":88,"time":1784629672553,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
+{"type":"assistant/chunk","seq":89,"time":1784629672581,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}}
+{"type":"assistant/chunk","seq":90,"time":1784629672581,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}}
+{"type":"assistant/chunk","seq":91,"time":1784629672581,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n\n"}}}
+{"type":"assistant/chunk","seq":92,"time":1784629672581,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}}
+{"type":"assistant/chunk","seq":93,"time":1784629672610,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":94,"time":1784629672610,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" look"}}}
+{"type":"assistant/chunk","seq":95,"time":1784629672610,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" at"}}}
+{"type":"assistant/chunk","seq":96,"time":1784629672610,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":97,"time":1784629672638,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
+{"type":"assistant/chunk","seq":98,"time":1784629672639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}}
+{"type":"assistant/chunk","seq":99,"time":1784629672639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" signature"}}}
+{"type":"assistant/chunk","seq":100,"time":1784629672668,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" carefully"}}}
+{"type":"assistant/chunk","seq":101,"time":1784629672668,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":102,"time":1784629672696,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}}
+{"type":"assistant/chunk","seq":103,"time":1784629672696,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":104,"time":1784629672726,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"command"}}}
+{"type":"assistant/chunk","seq":105,"time":1784629672726,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":106,"time":1784629672726,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" parameter"}}}
+{"type":"assistant/chunk","seq":107,"time":1784629672727,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}}
+{"type":"assistant/chunk","seq":108,"time":1784629672758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":109,"time":1784629672758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
+{"type":"assistant/chunk","seq":110,"time":1784629672786,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":111,"time":1784629672786,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":112,"time":1784629672814,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" execute"}}}
+{"type":"assistant/chunk","seq":113,"time":1784629672814,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":114,"time":1784629672814,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" So"}}}
+{"type":"assistant/chunk","seq":115,"time":1784629672843,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":116,"time":1784629672843,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"'d"}}}
+{"type":"assistant/chunk","seq":117,"time":1784629672871,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" pass"}}}
+{"type":"assistant/chunk","seq":118,"time":1784629672871,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":119,"time":1784629672900,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":120,"time":1784629672930,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":121,"time":1784629672931,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":122,"time":1784629672931,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":123,"time":1784629672931,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":124,"time":1784629672931,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" as"}}}
+{"type":"assistant/chunk","seq":125,"time":1784629672958,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":126,"time":1784629672958,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":127,"time":1784629672959,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\n\n"}}}
+{"type":"assistant/chunk","seq":128,"time":1784629672959,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"But"}}}
+{"type":"assistant/chunk","seq":129,"time":1784629672959,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wait"}}}
+{"type":"assistant/chunk","seq":130,"time":1784629672989,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" -"}}}
+{"type":"assistant/chunk","seq":131,"time":1784629672989,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":132,"time":1784629672989,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}}
+{"type":"assistant/chunk","seq":133,"time":1784629673016,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":134,"time":1784629673016,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" be"}}}
+{"type":"assistant/chunk","seq":135,"time":1784629673016,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" careful"}}}
+{"type":"assistant/chunk","seq":136,"time":1784629673044,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" about"}}}
+{"type":"assistant/chunk","seq":137,"time":1784629673044,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}}
+{"type":"assistant/chunk","seq":138,"time":1784629673044,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":139,"time":1784629673073,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":140,"time":1784629673073,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" looks"}}}
+{"type":"assistant/chunk","seq":141,"time":1784629673103,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" like"}}}
+{"type":"assistant/chunk","seq":142,"time":1784629673103,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":143,"time":1784629673103,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}}
+{"type":"assistant/chunk","seq":144,"time":1784629673103,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
+{"type":"assistant/chunk","seq":145,"time":1784629673130,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}}
+{"type":"assistant/chunk","seq":146,"time":1784629673130,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}}
+{"type":"assistant/chunk","seq":147,"time":1784629673159,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" stdout"}}}
+{"type":"assistant/chunk","seq":148,"time":1784629673159,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"/st"}}}
+{"type":"assistant/chunk","seq":149,"time":1784629673187,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"derr"}}}
+{"type":"assistant/chunk","seq":150,"time":1784629673187,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" objects"}}}
+{"type":"assistant/chunk","seq":151,"time":1784629673217,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":152,"time":1784629673218,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}}
+{"type":"assistant/chunk","seq":153,"time":1784629673218,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":154,"time":1784629673218,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" check"}}}
+{"type":"assistant/chunk","seq":155,"time":1784629673245,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":156,"time":1784629673245,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":157,"time":1784629673275,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" type"}}}
+{"type":"assistant/chunk","seq":158,"time":1784629673302,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n\n"}}}
+{"type":"assistant/chunk","seq":159,"time":1784629673302,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"```"}}}
+{"type":"assistant/chunk","seq":160,"time":1784629673302,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ts"}}}
+{"type":"assistant/chunk","seq":161,"time":1784629673303,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n"}}}
+{"type":"assistant/chunk","seq":162,"time":1784629673303,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"bash"}}}
+{"type":"assistant/chunk","seq":163,"time":1784629673335,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":164,"time":1784629673335,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" {\n"}}}
+{"type":"assistant/chunk","seq":165,"time":1784629673335,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"   "}}}
+{"type":"assistant/chunk","seq":166,"time":1784629673360,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" kind"}}}
+{"type":"assistant/chunk","seq":167,"time":1784629673360,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":168,"time":1784629673360,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":169,"time":1784629673388,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"fore"}}}
+{"type":"assistant/chunk","seq":170,"time":1784629673421,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ground"}}}
+{"type":"assistant/chunk","seq":171,"time":1784629673421,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":172,"time":1784629673421,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" |"}}}
+{"type":"assistant/chunk","seq":173,"time":1784629673422,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":174,"time":1784629673422,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"background"}}}
+{"type":"assistant/chunk","seq":175,"time":1784629673448,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\";\n"}}}
+{"type":"assistant/chunk","seq":176,"time":1784629673448,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"   "}}}
+{"type":"assistant/chunk","seq":177,"time":1784629673448,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" //"}}}
+{"type":"assistant/chunk","seq":178,"time":1784629673477,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" if"}}}
+{"type":"assistant/chunk","seq":179,"time":1784629673506,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" foreground"}}}
+{"type":"assistant/chunk","seq":180,"time":1784629673507,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n"}}}
+{"type":"assistant/chunk","seq":181,"time":1784629673507,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"   "}}}
+{"type":"assistant/chunk","seq":182,"time":1784629673534,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exit"}}}
+{"type":"assistant/chunk","seq":183,"time":1784629673534,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Code"}}}
+{"type":"assistant/chunk","seq":184,"time":1784629673534,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":185,"time":1784629673534,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" number"}}}
+{"type":"assistant/chunk","seq":186,"time":1784629673534,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" |"}}}
+{"type":"assistant/chunk","seq":187,"time":1784629673562,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" null"}}}
+{"type":"assistant/chunk","seq":188,"time":1784629673562,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":";\n"}}}
+{"type":"assistant/chunk","seq":189,"time":1784629673562,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"   "}}}
+{"type":"assistant/chunk","seq":190,"time":1784629673562,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" stdout"}}}
+{"type":"assistant/chunk","seq":191,"time":1784629673590,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":192,"time":1784629673590,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" {"}}}
+{"type":"assistant/chunk","seq":193,"time":1784629673618,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" text"}}}
+{"type":"assistant/chunk","seq":194,"time":1784629673619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":195,"time":1784629673619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}}
+{"type":"assistant/chunk","seq":196,"time":1784629673619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":";"}}}
+{"type":"assistant/chunk","seq":197,"time":1784629673619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" truncated"}}}
+{"type":"assistant/chunk","seq":198,"time":1784629673647,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":199,"time":1784629673647,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" boolean"}}}
+{"type":"assistant/chunk","seq":200,"time":1784629673647,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":";"}}}
+{"type":"assistant/chunk","seq":201,"time":1784629673647,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" spill"}}}
+{"type":"assistant/chunk","seq":202,"time":1784629673675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Path"}}}
+{"type":"assistant/chunk","seq":203,"time":1784629673676,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"?:"}}}
+{"type":"assistant/chunk","seq":204,"time":1784629673676,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}}
+{"type":"assistant/chunk","seq":205,"time":1784629673676,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":";"}}}
+{"type":"assistant/chunk","seq":206,"time":1784629673728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" };\n"}}}
+{"type":"assistant/chunk","seq":207,"time":1784629673728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"   "}}}
+{"type":"assistant/chunk","seq":208,"time":1784629673728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" st"}}}
+{"type":"assistant/chunk","seq":209,"time":1784629673728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"derr"}}}
+{"type":"assistant/chunk","seq":210,"time":1784629673728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":211,"time":1784629673728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" {"}}}
+{"type":"assistant/chunk","seq":212,"time":1784629673728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" text"}}}
+{"type":"assistant/chunk","seq":213,"time":1784629673732,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":214,"time":1784629673733,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}}
+{"type":"assistant/chunk","seq":215,"time":1784629673733,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":";"}}}
+{"type":"assistant/chunk","seq":216,"time":1784629673733,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ..."}}}
+{"type":"assistant/chunk","seq":217,"time":1784629673782,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" };\n"}}}
+{"type":"assistant/chunk","seq":218,"time":1784629673782,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"   "}}}
+{"type":"assistant/chunk","seq":219,"time":1784629673782,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ...\n"}}}
+{"type":"assistant/chunk","seq":220,"time":1784629673805,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"}\n"}}}
+{"type":"assistant/chunk","seq":221,"time":1784629673805,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"```\n\n"}}}
+{"type":"assistant/chunk","seq":222,"time":1784629673805,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"So"}}}
+{"type":"assistant/chunk","seq":223,"time":1784629673805,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":224,"time":1784629673805,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}}
+{"type":"assistant/chunk","seq":225,"time":1784629673838,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":226,"time":1784629673838,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" extract"}}}
+{"type":"assistant/chunk","seq":227,"time":1784629673838,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":228,"time":1784629673866,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"std"}}}
+{"type":"assistant/chunk","seq":229,"time":1784629673867,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"out"}}}
+{"type":"assistant/chunk","seq":230,"time":1784629673867,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".text"}}}
+{"type":"assistant/chunk","seq":231,"time":1784629673894,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":232,"time":1784629673894,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" from"}}}
+{"type":"assistant/chunk","seq":233,"time":1784629673894,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" each"}}}
+{"type":"assistant/chunk","seq":234,"time":1784629673894,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" call"}}}
+{"type":"assistant/chunk","seq":235,"time":1784629673983,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\n\n"}}}
+{"type":"assistant/chunk","seq":236,"time":1784629673983,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}}
+{"type":"assistant/chunk","seq":237,"time":1784629673983,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":238,"time":1784629673983,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" also"}}}
+{"type":"assistant/chunk","seq":239,"time":1784629673983,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" make"}}}
+{"type":"assistant/chunk","seq":240,"time":1784629673983,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sure"}}}
+{"type":"assistant/chunk","seq":241,"time":1784629673983,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" about"}}}
+{"type":"assistant/chunk","seq":242,"time":1784629674007,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":243,"time":1784629674007,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":244,"time":1784629674035,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"description"}}}
+{"type":"assistant/chunk","seq":245,"time":1784629674036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":246,"time":1784629674036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" parameter"}}}
+{"type":"assistant/chunk","seq":247,"time":1784629674064,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" -"}}}
+{"type":"assistant/chunk","seq":248,"time":1784629674064,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}}
+{"type":"assistant/chunk","seq":249,"time":1784629674064,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"'s"}}}
+{"type":"assistant/chunk","seq":250,"time":1784629674064,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" required"}}}
+{"type":"assistant/chunk","seq":251,"time":1784629674092,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":252,"time":1784629674124,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" should"}}}
+{"type":"assistant/chunk","seq":253,"time":1784629674153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" be"}}}
+{"type":"assistant/chunk","seq":254,"time":1784629674153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":255,"time":1784629674181,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"5"}}}
+{"type":"assistant/chunk","seq":256,"time":1784629674181,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"-"}}}
+{"type":"assistant/chunk","seq":257,"time":1784629674181,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"10"}}}
+{"type":"assistant/chunk","seq":258,"time":1784629674210,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" words"}}}
+{"type":"assistant/chunk","seq":259,"time":1784629674210,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":260,"time":1784629674239,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" describing"}}}
+{"type":"assistant/chunk","seq":261,"time":1784629674239,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":262,"time":1784629674270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":263,"time":1784629674270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\n\n"}}}
+{"type":"assistant/chunk","seq":264,"time":1784629674270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}}
+{"type":"assistant/chunk","seq":265,"time":1784629674270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":266,"time":1784629674270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}}
+{"type":"assistant/chunk","seq":267,"time":1784629674296,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":268,"time":1784629674296,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" code"}}}
+{"type":"assistant/chunk","seq":269,"time":1784629674327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n\n"}}}
+{"type":"assistant/chunk","seq":270,"time":1784629674327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"```"}}}
+{"type":"assistant/chunk","seq":271,"time":1784629674327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ts"}}}
+{"type":"assistant/chunk","seq":272,"time":1784629674327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n"}}}
+{"type":"assistant/chunk","seq":273,"time":1784629674327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"const"}}}
+{"type":"assistant/chunk","seq":274,"time":1784629674327,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" r"}}}
+{"type":"assistant/chunk","seq":275,"time":1784629674354,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}}
+{"type":"assistant/chunk","seq":276,"time":1784629674354,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ="}}}
+{"type":"assistant/chunk","seq":277,"time":1784629674354,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" await"}}}
+{"type":"assistant/chunk","seq":278,"time":1784629674354,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}}
+{"type":"assistant/chunk","seq":279,"time":1784629674354,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}}
+{"type":"assistant/chunk","seq":280,"time":1784629674354,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}}
+{"type":"assistant/chunk","seq":281,"time":1784629674382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"({"}}}
+{"type":"assistant/chunk","seq":282,"time":1784629674382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":283,"time":1784629674382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":284,"time":1784629674382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":285,"time":1784629674382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":286,"time":1784629674382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":287,"time":1784629674411,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":288,"time":1784629674411,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":289,"time":1784629674411,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\","}}}
+{"type":"assistant/chunk","seq":290,"time":1784629674411,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" description"}}}
+{"type":"assistant/chunk","seq":291,"time":1784629674411,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":292,"time":1784629674411,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":293,"time":1784629674440,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"E"}}}
+{"type":"assistant/chunk","seq":294,"time":1784629674440,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"cho"}}}
+{"type":"assistant/chunk","seq":295,"time":1784629674472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":296,"time":1784629674472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":297,"time":1784629674472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":298,"time":1784629674472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":299,"time":1784629674501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" stdout"}}}
+{"type":"assistant/chunk","seq":300,"time":1784629674501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":301,"time":1784629674501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" });\n"}}}
+{"type":"assistant/chunk","seq":302,"time":1784629674501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"const"}}}
+{"type":"assistant/chunk","seq":303,"time":1784629674501,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" r"}}}
+{"type":"assistant/chunk","seq":304,"time":1784629674529,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}}
+{"type":"assistant/chunk","seq":305,"time":1784629674529,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ="}}}
+{"type":"assistant/chunk","seq":306,"time":1784629674529,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" await"}}}
+{"type":"assistant/chunk","seq":307,"time":1784629674529,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}}
+{"type":"assistant/chunk","seq":308,"time":1784629674529,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}}
+{"type":"assistant/chunk","seq":309,"time":1784629674529,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}}
+{"type":"assistant/chunk","seq":310,"time":1784629674561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"({"}}}
+{"type":"assistant/chunk","seq":311,"time":1784629674561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}}
+{"type":"assistant/chunk","seq":312,"time":1784629674561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":313,"time":1784629674561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":314,"time":1784629674561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":315,"time":1784629674561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":316,"time":1784629674590,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":317,"time":1784629674590,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":318,"time":1784629674590,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\","}}}
+{"type":"assistant/chunk","seq":319,"time":1784629674590,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" description"}}}
+{"type":"assistant/chunk","seq":320,"time":1784629674590,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
+{"type":"assistant/chunk","seq":321,"time":1784629674591,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":322,"time":1784629674620,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"E"}}}
+{"type":"assistant/chunk","seq":323,"time":1784629674620,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"cho"}}}
+{"type":"assistant/chunk","seq":324,"time":1784629674620,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":325,"time":1784629674620,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":326,"time":1784629674620,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":327,"time":1784629674620,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":328,"time":1784629674650,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" stdout"}}}
+{"type":"assistant/chunk","seq":329,"time":1784629674651,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":330,"time":1784629674651,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" });\n"}}}
+{"type":"assistant/chunk","seq":331,"time":1784629674651,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"console"}}}
+{"type":"assistant/chunk","seq":332,"time":1784629674651,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".log"}}}
+{"type":"assistant/chunk","seq":333,"time":1784629674709,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"(\""}}}
+{"type":"assistant/chunk","seq":334,"time":1784629674709,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"capt"}}}
+{"type":"assistant/chunk","seq":335,"time":1784629674709,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ured"}}}
+{"type":"assistant/chunk","seq":336,"time":1784629674709,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":337,"time":1784629674709,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\");\n"}}}
+{"type":"assistant/chunk","seq":338,"time":1784629674709,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"return"}}}
+{"type":"assistant/chunk","seq":339,"time":1784629674712,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" r"}}}
+{"type":"assistant/chunk","seq":340,"time":1784629674741,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}}
+{"type":"assistant/chunk","seq":341,"time":1784629674741,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".stdout"}}}
+{"type":"assistant/chunk","seq":342,"time":1784629674741,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".text"}}}
+{"type":"assistant/chunk","seq":343,"time":1784629674770,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".trim"}}}
+{"type":"assistant/chunk","seq":344,"time":1784629674770,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"()"}}}
+{"type":"assistant/chunk","seq":345,"time":1784629674770,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" +"}}}
+{"type":"assistant/chunk","seq":346,"time":1784629674770,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \"+"}}}
+{"type":"assistant/chunk","seq":347,"time":1784629674798,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":348,"time":1784629674798,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" +"}}}
+{"type":"assistant/chunk","seq":349,"time":1784629674799,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" r"}}}
+{"type":"assistant/chunk","seq":350,"time":1784629674799,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}}
+{"type":"assistant/chunk","seq":351,"time":1784629674799,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".stdout"}}}
+{"type":"assistant/chunk","seq":352,"time":1784629674799,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".text"}}}
+{"type":"assistant/chunk","seq":353,"time":1784629674827,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".trim"}}}
+{"type":"assistant/chunk","seq":354,"time":1784629674827,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"();\n"}}}
+{"type":"assistant/chunk","seq":355,"time":1784629674827,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"```\n\n"}}}
+{"type":"assistant/chunk","seq":356,"time":1784629674827,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}}
+{"type":"assistant/chunk","seq":357,"time":1784629674827,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":358,"time":1784629674827,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" think"}}}
+{"type":"assistant/chunk","seq":359,"time":1784629674855,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" about"}}}
+{"type":"assistant/chunk","seq":360,"time":1784629674855,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":361,"time":1784629674883,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":362,"time":1784629674883,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" format"}}}
+{"type":"assistant/chunk","seq":363,"time":1784629674911,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":364,"time":1784629674911,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":365,"time":1784629674911,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":366,"time":1784629674940,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":367,"time":1784629674940,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":368,"time":1784629674940,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":369,"time":1784629674941,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":370,"time":1784629674941,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" will"}}}
+{"type":"assistant/chunk","seq":371,"time":1784629674969,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":372,"time":1784629674969,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":373,"time":1784629675000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":374,"time":1784629675000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":375,"time":1784629675000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":376,"time":1784629675000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\\n"}}}
+{"type":"assistant/chunk","seq":377,"time":1784629675000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`."}}}
+{"type":"assistant/chunk","seq":378,"time":1784629675025,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" So"}}}
+{"type":"assistant/chunk","seq":379,"time":1784629675055,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":380,"time":1784629675084,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"r"}}}
+{"type":"assistant/chunk","seq":381,"time":1784629675084,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}}
+{"type":"assistant/chunk","seq":382,"time":1784629675084,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".stdout"}}}
+{"type":"assistant/chunk","seq":383,"time":1784629675111,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".text"}}}
+{"type":"assistant/chunk","seq":384,"time":1784629675111,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":385,"time":1784629675145,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" would"}}}
+{"type":"assistant/chunk","seq":386,"time":1784629675145,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" be"}}}
+{"type":"assistant/chunk","seq":387,"time":1784629675145,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":388,"time":1784629675145,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":389,"time":1784629675171,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":390,"time":1784629675171,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":391,"time":1784629675171,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":392,"time":1784629675172,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\\n"}}}
+{"type":"assistant/chunk","seq":393,"time":1784629675172,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":394,"time":1784629675172,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":395,"time":1784629675199,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":396,"time":1784629675199,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" after"}}}
+{"type":"assistant/chunk","seq":397,"time":1784629675229,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" trim"}}}
+{"type":"assistant/chunk","seq":398,"time":1784629675257,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}}
+{"type":"assistant/chunk","seq":399,"time":1784629675257,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"'s"}}}
+{"type":"assistant/chunk","seq":400,"time":1784629675257,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":401,"time":1784629675285,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":402,"time":1784629675286,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":403,"time":1784629675286,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":404,"time":1784629675286,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":405,"time":1784629675286,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":406,"time":1784629675318,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`.\n\n"}}}
+{"type":"assistant/chunk","seq":407,"time":1784629675318,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"So"}}}
+{"type":"assistant/chunk","seq":408,"time":1784629675360,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":409,"time":1784629675361,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
+{"type":"assistant/chunk","seq":410,"time":1784629675361,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}}
+{"type":"assistant/chunk","seq":411,"time":1784629675370,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" would"}}}
+{"type":"assistant/chunk","seq":412,"time":1784629675371,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" be"}}}
+{"type":"assistant/chunk","seq":413,"time":1784629675371,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":414,"time":1784629675371,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":415,"time":1784629675399,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":416,"time":1784629675399,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":417,"time":1784629675399,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}}
+{"type":"assistant/chunk","seq":418,"time":1784629675399,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":419,"time":1784629675399,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":420,"time":1784629675427,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":421,"time":1784629675428,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`.\n\n"}}}
+{"type":"assistant/chunk","seq":422,"time":1784629675428,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"And"}}}
+{"type":"assistant/chunk","seq":423,"time":1784629675456,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" console"}}}
+{"type":"assistant/chunk","seq":424,"time":1784629675484,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".log"}}}
+{"type":"assistant/chunk","seq":425,"time":1784629675484,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"(\""}}}
+{"type":"assistant/chunk","seq":426,"time":1784629675515,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"capt"}}}
+{"type":"assistant/chunk","seq":427,"time":1784629675515,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ured"}}}
+{"type":"assistant/chunk","seq":428,"time":1784629675515,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":429,"time":1784629675515,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\")"}}}
+{"type":"assistant/chunk","seq":430,"time":1784629675515,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" prints"}}}
+{"type":"assistant/chunk","seq":431,"time":1784629675546,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":432,"time":1784629675579,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"capt"}}}
+{"type":"assistant/chunk","seq":433,"time":1784629675579,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ured"}}}
+{"type":"assistant/chunk","seq":434,"time":1784629675580,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":435,"time":1784629675580,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":436,"time":1784629675609,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":437,"time":1784629675609,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":438,"time":1784629675638,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" console"}}}
+{"type":"assistant/chunk","seq":439,"time":1784629675667,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\n\n"}}}
+{"type":"assistant/chunk","seq":440,"time":1784629675667,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":441,"time":1784629675667,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" response"}}}
+{"type":"assistant/chunk","seq":442,"time":1784629675695,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" comes"}}}
+{"type":"assistant/chunk","seq":443,"time":1784629675724,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" back"}}}
+{"type":"assistant/chunk","seq":444,"time":1784629675725,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" as"}}}
+{"type":"assistant/chunk","seq":445,"time":1784629675756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":446,"time":1784629675756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}}
+{"type":"assistant/chunk","seq":447,"time":1784629675786,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" result"}}}
+{"type":"assistant/chunk","seq":448,"time":1784629675786,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" which"}}}
+{"type":"assistant/chunk","seq":449,"time":1784629675814,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" includes"}}}
+{"type":"assistant/chunk","seq":450,"time":1784629675814,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" stdout"}}}
+{"type":"assistant/chunk","seq":451,"time":1784629675843,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":452,"time":1784629675873,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":453,"time":1784629675901,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" return"}}}
+{"type":"assistant/chunk","seq":454,"time":1784629675901,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" value"}}}
+{"type":"assistant/chunk","seq":455,"time":1784629675901,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":456,"time":1784629675932,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Since"}}}
+{"type":"assistant/chunk","seq":457,"time":1784629675932,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":458,"time":1784629675932,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" return"}}}
+{"type":"assistant/chunk","seq":459,"time":1784629675961,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" value"}}}
+{"type":"assistant/chunk","seq":460,"time":1784629675991,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}}
+{"type":"assistant/chunk","seq":461,"time":1784629675991,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}}
+{"type":"assistant/chunk","seq":462,"time":1784629676026,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" we"}}}
+{"type":"assistant/chunk","seq":463,"time":1784629676050,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" want"}}}
+{"type":"assistant/chunk","seq":464,"time":1784629676077,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}}
+{"type":"assistant/chunk","seq":465,"time":1784629676077,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":466,"time":1784629676108,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":467,"time":1784629676108,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"reply"}}}
+{"type":"assistant/chunk","seq":468,"time":1784629676136,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":469,"time":1784629676167,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
+{"type":"assistant/chunk","seq":470,"time":1784629676168,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
+{"type":"assistant/chunk","seq":471,"time":1784629676168,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}}
+{"type":"assistant/chunk","seq":472,"time":1784629676168,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}}
+{"type":"assistant/chunk","seq":473,"time":1784629676198,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":474,"time":1784629676198,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}}
+{"type":"assistant/chunk","seq":475,"time":1784629676198,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}}
+{"type":"assistant/chunk","seq":476,"time":1784629676227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" -"}}}
+{"type":"assistant/chunk","seq":477,"time":1784629676227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":478,"time":1784629676258,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" think"}}}
+{"type":"assistant/chunk","seq":479,"time":1784629676258,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":480,"time":1784629676286,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" return"}}}
+{"type":"assistant/chunk","seq":481,"time":1784629676287,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" value"}}}
+{"type":"assistant/chunk","seq":482,"time":1784629676287,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" of"}}}
+{"type":"assistant/chunk","seq":483,"time":1784629676315,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":484,"time":1784629676315,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}}
+{"type":"assistant/chunk","seq":485,"time":1784629676344,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}}
+{"type":"assistant/chunk","seq":486,"time":1784629676344,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" function"}}}
+{"type":"assistant/chunk","seq":487,"time":1784629676344,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}}
+{"type":"assistant/chunk","seq":488,"time":1784629676344,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}}
+{"type":"assistant/chunk","seq":489,"time":1784629676372,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" matters"}}}
+{"type":"assistant/chunk","seq":490,"time":1784629676372,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":491,"time":1784629676400,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" But"}}}
+{"type":"assistant/chunk","seq":492,"time":1784629676401,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" console"}}}
+{"type":"assistant/chunk","seq":493,"time":1784629676430,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".log"}}}
+{"type":"assistant/chunk","seq":494,"time":1784629676431,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":495,"time":1784629676459,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" also"}}}
+{"type":"assistant/chunk","seq":496,"time":1784629676486,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" comes"}}}
+{"type":"assistant/chunk","seq":497,"time":1784629676514,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" back"}}}
+{"type":"assistant/chunk","seq":498,"time":1784629676514,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\n\n"}}}
+{"type":"assistant/chunk","seq":499,"time":1784629676514,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}}
+{"type":"assistant/chunk","seq":500,"time":1784629676543,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":501,"time":1784629676543,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}}
+{"type":"assistant/chunk","seq":502,"time":1784629676571,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}}
+{"type":"assistant/chunk","seq":503,"time":1784629676599,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}}
+{"type":"assistant/chunk","seq":504,"time":1784629676600,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":505,"time":1784629676600,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" see"}}}
+{"type":"assistant/chunk","seq":506,"time":1784629676630,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":507,"time":1784629676713,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":508,"time":1784629676713,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":""}}}
+{"type":"assistant/chunk","seq":509,"time":1784629676742,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"{"}}}
+{"type":"assistant/chunk","seq":510,"time":1784629676742,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":511,"time":1784629676742,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"code"}}}
+{"type":"assistant/chunk","seq":512,"time":1784629676742,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":513,"time":1784629676742,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":": "}}}
+{"type":"assistant/chunk","seq":514,"time":1784629676770,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":515,"time":1784629676770,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\\n"}}}
+{"type":"assistant/chunk","seq":516,"time":1784629676770,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":517,"time":1784629676770,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" r"}}}
+{"type":"assistant/chunk","seq":518,"time":1784629676770,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"1"}}}
+{"type":"assistant/chunk","seq":519,"time":1784629676770,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":520,"time":1784629676799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" await"}}}
+{"type":"assistant/chunk","seq":521,"time":1784629676799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" tools"}}}
+{"type":"assistant/chunk","seq":522,"time":1784629676799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".b"}}}
+{"type":"assistant/chunk","seq":523,"time":1784629676799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"ash"}}}
+{"type":"assistant/chunk","seq":524,"time":1784629676799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"({"}}}
+{"type":"assistant/chunk","seq":525,"time":1784629676827,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" command"}}}
+{"type":"assistant/chunk","seq":526,"time":1784629676828,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":527,"time":1784629676828,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":528,"time":1784629676828,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"echo"}}}
+{"type":"assistant/chunk","seq":529,"time":1784629676828,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" CODE"}}}
+{"type":"assistant/chunk","seq":530,"time":1784629676855,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"_"}}}
+{"type":"assistant/chunk","seq":531,"time":1784629676856,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"ONE"}}}
+{"type":"assistant/chunk","seq":532,"time":1784629676856,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\\\","}}}
+{"type":"assistant/chunk","seq":533,"time":1784629676856,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" description"}}}
+{"type":"assistant/chunk","seq":534,"time":1784629676856,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":535,"time":1784629676856,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":536,"time":1784629676883,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"E"}}}
+{"type":"assistant/chunk","seq":537,"time":1784629676884,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"cho"}}}
+{"type":"assistant/chunk","seq":538,"time":1784629676884,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" CODE"}}}
+{"type":"assistant/chunk","seq":539,"time":1784629676884,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"_"}}}
+{"type":"assistant/chunk","seq":540,"time":1784629676884,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"ONE"}}}
+{"type":"assistant/chunk","seq":541,"time":1784629676884,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" to"}}}
+{"type":"assistant/chunk","seq":542,"time":1784629676912,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" stdout"}}}
+{"type":"assistant/chunk","seq":543,"time":1784629676912,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":544,"time":1784629676912,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" });\\n"}}}
+{"type":"assistant/chunk","seq":545,"time":1784629676912,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":546,"time":1784629676912,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" r"}}}
+{"type":"assistant/chunk","seq":547,"time":1784629676912,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"2"}}}
+{"type":"assistant/chunk","seq":548,"time":1784629676941,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":549,"time":1784629676941,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" await"}}}
+{"type":"assistant/chunk","seq":550,"time":1784629676941,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" tools"}}}
+{"type":"assistant/chunk","seq":551,"time":1784629676941,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".b"}}}
+{"type":"assistant/chunk","seq":552,"time":1784629676941,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"ash"}}}
+{"type":"assistant/chunk","seq":553,"time":1784629676941,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"({"}}}
+{"type":"assistant/chunk","seq":554,"time":1784629676972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" command"}}}
+{"type":"assistant/chunk","seq":555,"time":1784629676972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":556,"time":1784629676972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":557,"time":1784629676972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"echo"}}}
+{"type":"assistant/chunk","seq":558,"time":1784629676972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" CODE"}}}
+{"type":"assistant/chunk","seq":559,"time":1784629676972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"_T"}}}
+{"type":"assistant/chunk","seq":560,"time":1784629677001,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"WO"}}}
+{"type":"assistant/chunk","seq":561,"time":1784629677001,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\\\","}}}
+{"type":"assistant/chunk","seq":562,"time":1784629677001,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" description"}}}
+{"type":"assistant/chunk","seq":563,"time":1784629677001,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":564,"time":1784629677001,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":565,"time":1784629677002,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"E"}}}
+{"type":"assistant/chunk","seq":566,"time":1784629677029,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"cho"}}}
+{"type":"assistant/chunk","seq":567,"time":1784629677029,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" CODE"}}}
+{"type":"assistant/chunk","seq":568,"time":1784629677029,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"_T"}}}
+{"type":"assistant/chunk","seq":569,"time":1784629677029,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"WO"}}}
+{"type":"assistant/chunk","seq":570,"time":1784629677029,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" to"}}}
+{"type":"assistant/chunk","seq":571,"time":1784629677029,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" stdout"}}}
+{"type":"assistant/chunk","seq":572,"time":1784629677058,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":573,"time":1784629677058,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" });\\n"}}}
+{"type":"assistant/chunk","seq":574,"time":1784629677058,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"console"}}}
+{"type":"assistant/chunk","seq":575,"time":1784629677058,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".log"}}}
+{"type":"assistant/chunk","seq":576,"time":1784629677058,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"(\\\""}}}
+{"type":"assistant/chunk","seq":577,"time":1784629677058,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"capt"}}}
+{"type":"assistant/chunk","seq":578,"time":1784629677086,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"ured"}}}
+{"type":"assistant/chunk","seq":579,"time":1784629677086,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" output"}}}
+{"type":"assistant/chunk","seq":580,"time":1784629677086,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\\\");\\n"}}}
+{"type":"assistant/chunk","seq":581,"time":1784629677086,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"return"}}}
+{"type":"assistant/chunk","seq":582,"time":1784629677086,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" r"}}}
+{"type":"assistant/chunk","seq":583,"time":1784629677086,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"1"}}}
+{"type":"assistant/chunk","seq":584,"time":1784629677114,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".stdout"}}}
+{"type":"assistant/chunk","seq":585,"time":1784629677115,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".text"}}}
+{"type":"assistant/chunk","seq":586,"time":1784629677143,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".trim"}}}
+{"type":"assistant/chunk","seq":587,"time":1784629677143,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"()"}}}
+{"type":"assistant/chunk","seq":588,"time":1784629677143,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" +"}}}
+{"type":"assistant/chunk","seq":589,"time":1784629677143,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" \\\"+"}}}
+{"type":"assistant/chunk","seq":590,"time":1784629677172,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":591,"time":1784629677172,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" +"}}}
+{"type":"assistant/chunk","seq":592,"time":1784629677172,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":" r"}}}
+{"type":"assistant/chunk","seq":593,"time":1784629677172,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"2"}}}
+{"type":"assistant/chunk","seq":594,"time":1784629677172,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".stdout"}}}
+{"type":"assistant/chunk","seq":595,"time":1784629677172,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".text"}}}
+{"type":"assistant/chunk","seq":596,"time":1784629677200,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":".trim"}}}
+{"type":"assistant/chunk","seq":597,"time":1784629677200,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"();\\n"}}}
+{"type":"assistant/chunk","seq":598,"time":1784629677200,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":599,"time":1784629677231,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","argumentsDelta":"}"}}}
+{"type":"assistant/chunk","seq":600,"time":1784629677261,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Let me carefully read the instructions. I need to write ONE run_code program that:\n\n1. Calls bash with `echo CODE_ONE` - just the command \"echo CODE_ONE\"\n2. Calls bash with `echo CODE_TWO` - just the command \"echo CODE_TWO\"\n3. Inside that same program, console.log exactly `captured output`\n4. Return the two outputs joined with a plus sign\n\nLet me look at the bash tool signature carefully. The `command` parameter is the bash command to execute. So I'd pass `echo CODE_ONE` as the command.\n\nBut wait - I need to be careful about what the output looks like. The bash tool returns stdout/stderr objects. Let me check the output type:\n\n```ts\nbash: {\n    kind: \"foreground\" | \"background\";\n    // if foreground:\n    exitCode: number | null;\n    stdout: { text: string; truncated: boolean; spillPath?: string; };\n    stderr: { text: string; ... };\n    ...\n}\n```\n\nSo I need to extract `stdout.text` from each call.\n\nLet me also make sure about the `description` parameter - it's required and should be \"5-10 words\" describing the command.\n\nLet me write the code:\n\n```ts\nconst r1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE to stdout\" });\nconst r2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO to stdout\" });\nconsole.log(\"captured output\");\nreturn r1.stdout.text.trim() + \"+\" + r2.stdout.text.trim();\n```\n\nLet me think about the output format. `echo CODE_ONE` will output `CODE_ONE\\n`. So `r1.stdout.text` would be `\"CODE_ONE\\n\"` and after trim it's `\"CODE_ONE\"`.\n\nSo the joined string would be `CODE_ONE+CODE_TWO`.\n\nAnd console.log(\"captured output\") prints \"captured output\" to the console.\n\nThe response comes back as the tool result which includes stdout and the return value. Since the return value is what we want, and `reply with that joined string only and stop` - I think the return value of the run_code function is what matters. But console.log output also comes back.\n\nLet me just write it and see."}}}}
+{"type":"assistant/chunk","seq":601,"time":1784629677261,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","arguments":"{\"code\": \"\\nconst r1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE to stdout\\\" });\\nconst r2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO to stdout\\\" });\\nconsole.log(\\\"captured output\\\");\\nreturn r1.stdout.text.trim() + \\\"+\\\" + r2.stdout.text.trim();\\n\"}"}}}}
+{"type":"assistant/chunk","seq":602,"time":1784629677261,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":6005,"outputTokens":626,"cacheReadTokens":0,"reasoningTokens":501}}}}
+{"type":"assistant/chunk","seq":603,"time":1784629677261,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":604,"time":1784629677264,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"Let me carefully read the instructions. I need to write ONE run_code program that:\n\n1. Calls bash with `echo CODE_ONE` - just the command \"echo CODE_ONE\"\n2. Calls bash with `echo CODE_TWO` - just the command \"echo CODE_TWO\"\n3. Inside that same program, console.log exactly `captured output`\n4. Return the two outputs joined with a plus sign\n\nLet me look at the bash tool signature carefully. The `command` parameter is the bash command to execute. So I'd pass `echo CODE_ONE` as the command.\n\nBut wait - I need to be careful about what the output looks like. The bash tool returns stdout/stderr objects. Let me check the output type:\n\n```ts\nbash: {\n    kind: \"foreground\" | \"background\";\n    // if foreground:\n    exitCode: number | null;\n    stdout: { text: string; truncated: boolean; spillPath?: string; };\n    stderr: { text: string; ... };\n    ...\n}\n```\n\nSo I need to extract `stdout.text` from each call.\n\nLet me also make sure about the `description` parameter - it's required and should be \"5-10 words\" describing the command.\n\nLet me write the code:\n\n```ts\nconst r1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE to stdout\" });\nconst r2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO to stdout\" });\nconsole.log(\"captured output\");\nreturn r1.stdout.text.trim() + \"+\" + r2.stdout.text.trim();\n```\n\nLet me think about the output format. `echo CODE_ONE` will output `CODE_ONE\\n`. So `r1.stdout.text` would be `\"CODE_ONE\\n\"` and after trim it's `\"CODE_ONE\"`.\n\nSo the joined string would be `CODE_ONE+CODE_TWO`.\n\nAnd console.log(\"captured output\") prints \"captured output\" to the console.\n\nThe response comes back as the tool result which includes stdout and the return value. Since the return value is what we want, and `reply with that joined string only and stop` - I think the return value of the run_code function is what matters. But console.log output also comes back.\n\nLet me just write it and see."},{"type":"tool-call","id":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","arguments":"{\"code\": \"\\nconst r1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE to stdout\\\" });\\nconst r2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO to stdout\\\" });\\nconsole.log(\\\"captured output\\\");\\nreturn r1.stdout.text.trim() + \\\"+\\\" + r2.stdout.text.trim();\\n\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":6005,"outputTokens":626,"cacheReadTokens":0,"reasoningTokens":501}},"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,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284,285,286,287,288,289,290,291,292,293,294,295,296,297,298,299,300,301,302,303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325,326,327,328,329,330,331,332,333,334,335,336,337,338,339,340,341,342,343,344,345,346,347,348,349,350,351,352,353,354,355,356,357,358,359,360,361,362,363,364,365,366,367,368,369,370,371,372,373,374,375,376,377,378,379,380,381,382,383,384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399,400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,418,419,420,421,422,423,424,425,426,427,428,429,430,431,432,433,434,435,436,437,438,439,440,441,442,443,444,445,446,447,448,449,450,451,452,453,454,455,456,457,458,459,460,461,462,463,464,465,466,467,468,469,470,471,472,473,474,475,476,477,478,479,480,481,482,483,484,485,486,487,488,489,490,491,492,493,494,495,496,497,498,499,500,501,502,503,504,505,506,507,508,509,510,511,512,513,514,515,516,517,518,519,520,521,522,523,524,525,526,527,528,529,530,531,532,533,534,535,536,537,538,539,540,541,542,543,544,545,546,547,548,549,550,551,552,553,554,555,556,557,558,559,560,561,562,563,564,565,566,567,568,569,570,571,572,573,574,575,576,577,578,579,580,581,582,583,584,585,586,587,588,589,590,591,592,593,594,595,596,597,598,599,600,601,602,603],"surfaceOp":"append"}
+{"type":"tool/call","seq":605,"time":1784629677264,"data":{"turn":1,"step":1,"callId":"call_00_9r18203KAw8KCXThwJ7k3704","name":"run_code","arguments":"{\"code\": \"\\nconst r1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE to stdout\\\" });\\nconst r2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO to stdout\\\" });\\nconsole.log(\\\"captured output\\\");\\nreturn r1.stdout.text.trim() + \\\"+\\\" + r2.stdout.text.trim();\\n\"}"}}
+{"type":"tool/code-dispatch","seq":606,"time":1784629677359,"data":{"parentCallId":"call_00_9r18203KAw8KCXThwJ7k3704","subCallId":"call_00_9r18203KAw8KCXThwJ7k3704:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Echo CODE_ONE to stdout"},"isError":false,"resultSummary":"CODE_ONE\n"}}
+{"type":"tool/code-dispatch","seq":607,"time":1784629677361,"data":{"parentCallId":"call_00_9r18203KAw8KCXThwJ7k3704","subCallId":"call_00_9r18203KAw8KCXThwJ7k3704:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Echo CODE_TWO to stdout"},"isError":false,"resultSummary":"CODE_TWO\n"}}
+{"type":"tool/result","seq":608,"time":1784629677363,"data":{"turn":1,"step":1,"callId":"call_00_9r18203KAw8KCXThwJ7k3704","content":[{"type":"text","text":"captured output\nCODE_ONE+CODE_TWO"}],"isError":false},"sourceEventSeqs":[605],"surfaceOp":"append"}
+{"type":"step/end","seq":609,"time":1784629677365,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":610,"time":1784629677366,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":611,"time":1784629677997,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":612,"time":1784629677997,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":613,"time":1784629678140,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":614,"time":1784629678165,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" shows"}}}
+{"type":"assistant/chunk","seq":615,"time":1784629678193,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":\n"}}}
+{"type":"assistant/chunk","seq":616,"time":1784629678193,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"-"}}}
+{"type":"assistant/chunk","seq":617,"time":1784629678221,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":618,"time":1784629678221,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"capt"}}}
+{"type":"assistant/chunk","seq":619,"time":1784629678222,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ured"}}}
+{"type":"assistant/chunk","seq":620,"time":1784629678222,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":621,"time":1784629678249,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":622,"time":1784629678249,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" ("}}}
+{"type":"assistant/chunk","seq":623,"time":1784629678250,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"from"}}}
+{"type":"assistant/chunk","seq":624,"time":1784629678278,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" console"}}}
+{"type":"assistant/chunk","seq":625,"time":1784629678278,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":".log"}}}
+{"type":"assistant/chunk","seq":626,"time":1784629678278,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":")\n"}}}
+{"type":"assistant/chunk","seq":627,"time":1784629678279,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"-"}}}
+{"type":"assistant/chunk","seq":628,"time":1784629678279,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":629,"time":1784629678306,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":630,"time":1784629678306,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":631,"time":1784629678306,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":632,"time":1784629678306,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}}
+{"type":"assistant/chunk","seq":633,"time":1784629678306,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":634,"time":1784629678306,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":635,"time":1784629678334,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":636,"time":1784629678334,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":637,"time":1784629678334,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" ("}}}
+{"type":"assistant/chunk","seq":638,"time":1784629678334,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"the"}}}
+{"type":"assistant/chunk","seq":639,"time":1784629678361,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" return"}}}
+{"type":"assistant/chunk","seq":640,"time":1784629678362,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" value"}}}
+{"type":"assistant/chunk","seq":641,"time":1784629678362,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":")\n\n"}}}
+{"type":"assistant/chunk","seq":642,"time":1784629678362,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":643,"time":1784629678362,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" instructions"}}}
+{"type":"assistant/chunk","seq":644,"time":1784629678390,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" say"}}}
+{"type":"assistant/chunk","seq":645,"time":1784629678391,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":646,"time":1784629678391,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"Reply"}}}
+{"type":"assistant/chunk","seq":647,"time":1784629678417,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":648,"time":1784629678417,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
+{"type":"assistant/chunk","seq":649,"time":1784629678417,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
+{"type":"assistant/chunk","seq":650,"time":1784629678418,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}}
+{"type":"assistant/chunk","seq":651,"time":1784629678445,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}}
+{"type":"assistant/chunk","seq":652,"time":1784629678446,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":653,"time":1784629678446,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}}
+{"type":"assistant/chunk","seq":654,"time":1784629678473,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":".\""}}}
+{"type":"assistant/chunk","seq":655,"time":1784629678474,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" So"}}}
+{"type":"assistant/chunk","seq":656,"time":1784629678474,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}}
+{"type":"assistant/chunk","seq":657,"time":1784629678474,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" should"}}}
+{"type":"assistant/chunk","seq":658,"time":1784629678501,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":659,"time":1784629678501,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":660,"time":1784629678502,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":661,"time":1784629678529,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":662,"time":1784629678529,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":663,"time":1784629678529,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":664,"time":1784629678529,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}}
+{"type":"assistant/chunk","seq":665,"time":1784629678529,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":666,"time":1784629678530,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":667,"time":1784629678557,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":668,"time":1784629678558,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}}
+{"type":"assistant/chunk","seq":669,"time":1784629678558,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":670,"time":1784629678558,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":671,"time":1784629678558,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}}
+{"type":"assistant/chunk","seq":672,"time":1784629678558,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":673,"time":1784629678587,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}}
+{"type":"assistant/chunk","seq":674,"time":1784629678587,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":675,"time":1784629678587,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}}
+{"type":"assistant/chunk","seq":676,"time":1784629678587,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}}
+{"type":"assistant/chunk","seq":677,"time":1784629678587,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output shows:\n- \"captured output\" (from console.log)\n- \"CODE_ONE+CODE_TWO\" (the return value)\n\nThe instructions say \"Reply with that joined string only and stop.\" So I should reply with \"CODE_ONE+CODE_TWO\"."}}}}
+{"type":"assistant/chunk","seq":678,"time":1784629678587,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}}
+{"type":"assistant/chunk","seq":679,"time":1784629678587,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":766,"outputTokens":65,"cacheReadTokens":5888,"reasoningTokens":57}}}}
+{"type":"assistant/chunk","seq":680,"time":1784629678587,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":681,"time":1784629678588,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output shows:\n- \"captured output\" (from console.log)\n- \"CODE_ONE+CODE_TWO\" (the return value)\n\nThe instructions say \"Reply with that joined string only and stop.\" So I should reply with \"CODE_ONE+CODE_TWO\"."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":766,"outputTokens":65,"cacheReadTokens":5888,"reasoningTokens":57}},"sourceEventSeqs":[611,612,613,614,615,616,617,618,619,620,621,622,623,624,625,626,627,628,629,630,631,632,633,634,635,636,637,638,639,640,641,642,643,644,645,646,647,648,649,650,651,652,653,654,655,656,657,658,659,660,661,662,663,664,665,666,667,668,669,670,671,672,673,674,675,676,677,678,679,680],"surfaceOp":"append"}
+{"type":"step/end","seq":682,"time":1784629678588,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":683,"time":1784629678588,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.expected.jsonl
index 5e366ec1a3..85866dd6dc 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.expected.jsonl
@@ -1,22 +1,84 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Using ONE run_code program: call","updatedAt":"{{updatedAt}}"}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" carefully"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" read"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" instructions"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ONE"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" calls"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" twice"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" -"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" just"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" -"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" just"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Inside"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" same"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" then"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returns"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" console"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".log"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"capt"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ured"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"4"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Return"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" two"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" outputs"}}}}
@@ -25,31 +87,481 @@
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" plus"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sign"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" look"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" at"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" signature"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" carefully"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" The"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"command"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" parameter"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" execute"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" So"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'d"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" pass"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" as"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"But"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wait"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" -"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" be"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" careful"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" about"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" what"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" looks"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" like"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" The"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returns"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stdout"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"/st"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"derr"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" objects"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" this"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_DRxnM6R1TThfDwcudW0f2050","title":"const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"First echo\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Second echo\" });\nreturn out1.trim() + \"+\" + out2.trim();","kind":"execute","status":"in_progress","rawInput":"const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"First echo\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Second echo\" });\nreturn out1.trim() + \"+\" + out2.trim();"}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_DRxnM6R1TThfDwcudW0f2050","status":"completed","content":[{"type":"content","content":{"type":"text","text":"CODE_ONE+CODE_TWO"}}]}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" what"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" check"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" asked"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" for"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" type"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"```"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ts"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"bash"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" {\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"   "}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" kind"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"fore"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ground"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" |"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"background"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\";\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"   "}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" //"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" if"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" foreground"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"   "}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exit"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Code"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" number"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" |"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" null"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":";\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"   "}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stdout"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" {"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" text"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":";"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" truncated"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" boolean"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":";"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" spill"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Path"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"?:"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":";"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" };\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"   "}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" st"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"derr"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" {"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" text"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":";"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ..."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" };\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"   "}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ...\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"}\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"```\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"So"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" extract"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"std"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"out"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".text"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" from"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" each"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" call"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" also"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" make"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sure"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" about"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"description"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" parameter"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" -"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'s"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" required"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" should"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" be"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"5"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"-"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"10"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" words"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" describing"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" code"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"```"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ts"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"const"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" r"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ="}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" await"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".b"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ash"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"({"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\","}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" description"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"E"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"cho"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stdout"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" });\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"const"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" r"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ="}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" await"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".b"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ash"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"({"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\","}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" description"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"E"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"cho"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stdout"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" });\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"console"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".log"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"(\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"capt"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ured"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\");\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"return"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" r"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".stdout"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".text"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".trim"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"()"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" +"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \"+"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" +"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" r"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".stdout"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".text"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".trim"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"();\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"```\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" think"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" about"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" format"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" will"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" So"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"r"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".stdout"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".text"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" would"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" be"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" after"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" trim"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'s"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`.\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"So"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" would"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" be"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"+"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`.\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"And"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" console"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".log"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"(\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"capt"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ured"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\")"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" prints"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"capt"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ured"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" console"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" response"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" comes"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" back"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" as"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" result"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" which"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" includes"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stdout"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" return"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" value"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Since"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" return"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" value"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" what"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" we"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" want"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"reply"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" only"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" -"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" think"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" return"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" value"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" of"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" function"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" what"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" matters"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" But"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" console"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".log"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" also"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" comes"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" back"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" just"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" see"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_9r18203KAw8KCXThwJ7k3704","title":"\nconst r1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE to stdout\" });\nconst r2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO to stdout\" });\nconsole.log(\"captured output\");\nreturn r1.stdout.text.trim() + \"+\" + r2.stdout.text.trim();\n","kind":"execute","status":"in_progress","rawInput":"\nconst r1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE to stdout\" });\nconst r2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO to stdout\" });\nconsole.log(\"captured output\");\nreturn r1.stdout.text.trim() + \"+\" + r2.stdout.text.trim();\n"}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_9r18203KAw8KCXThwJ7k3704","status":"completed","content":[{"type":"content","content":{"type":"text","text":"captured output\nCODE_ONE+CODE_TWO"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" shows"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"-"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"capt"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ured"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ("}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"from"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" console"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".log"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":")\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"-"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"+"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ("}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" return"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" value"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":")\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" instructions"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" say"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Reply"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" only"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" So"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" should"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"+"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"."}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"CODE"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"_"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}}
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 8868412707..8744029272 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
@@ -28,19 +28,21 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
 
 Pass `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:
 
-- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.
-- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.
+- 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.
+- 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.
 - Calls execute sequentially, even under `Promise.all`.
 - 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.
 
 The available tools:
 
 ```ts
-declare const tools: {
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+interface ToolArgsMap {
   /** 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. */
-  ask_user_question(args: {
+  ask_user_question: {
     /** Questions to ask the user before continuing. */
-    questions: {
+    questions: ({
       /** Stable id for this question; echoed in the answer. */
       id: string;
       /** The specific question to ask the user. */
@@ -48,18 +50,18 @@ declare const tools: {
       /** Optional short heading for the question, such as "Confirm" or "Choose Mode". */
       header?: string;
       /** Optional choices to show the user. If you recommend one, put it first and append "(Recommended)" to that label. */
-      options?: {
+      options?: ({
         /** Short user-facing option label. */
         label: string;
         /** One sentence explaining the tradeoff or impact. */
         description?: string;
-      }[];
+      } & Record<string, JsonValue>)[];
       /** Whether the user may select more than one option. Defaults to false. */
       multi_select?: boolean;
-    }[];
-  }): Promise<string>;
+    } & Record<string, JsonValue>)[];
+  } & Record<string, JsonValue>;
   /** 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. */
-  bash(args: {
+  bash: {
     /** The bash command to execute. */
     command: string;
     /** 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". */
@@ -74,16 +76,16 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. */
-  create_goal(args: {
+  create_goal: {
     /** The concrete completion objective inferred from the direct human request. */
     objective: string;
     /** Optional positive safe-integer limit on automatic continuation rounds. */
     max_goal_rounds?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Edit an existing UTF-8 text file by replacing literal text. */
-  edit(args: {
+  edit: {
     /** Path to edit, resolved by the filesystem backend. */
     file_path: string;
     /** Literal text to replace. Must match exactly. */
@@ -96,83 +98,83 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again. */
-  exit_plan_mode(args: {
+  exit_plan_mode: {
     /** The complete plan, as markdown, starting with a # heading that names it. */
     plan: string;
-  }): Promise<string>;
+  } & 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(args: Record<string, unknown>): Promise<string>;
+  get_goal: 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(args: {
+  ralph: {
     /** The immutable completion objective for every fresh Ralph round. */
     objective: string;
     /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */
     maxRounds?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Read a UTF-8 text file and return line-numbered content. */
-  read(args: {
+  read: {
     /** Path to read, resolved by the filesystem backend. */
     file_path: string;
     /** 1-based first line to return. Defaults to 1. */
     offset?: number;
     /** Maximum number of lines to return. Defaults to 2000. */
     limit?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. */
-  skill(args: {
+  skill: {
     /** The exact skill name from the available skills list. */
     name: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */
-  subagent(args: {
+  subagent: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
     /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */
-  subagent_fork(args: {
+  subagent_fork: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
     /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
-  task_kill(args: {
+  task_kill: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
     /** Optional short reason, recorded in the log and forwarded to the task. */
     reason?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
-  task_list(args: Record<string, unknown>): Promise<string>;
+  task_list: Record<string, JsonValue>;
   /** 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. */
-  task_output(args: {
+  task_output: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
     /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */
     wait?: boolean;
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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). */
-  todo_write(args: {
+  todo_write: {
     /** The COMPLETE task list, replacing any previous list. */
     todos: ({
       /** What the task is — a short imperative line. */
       content: string;
       /** pending (not started) | in_progress (now) | completed (done). */
       status: "pending" | "in_progress" | "completed";
-    })[];
-  }): Promise<string>;
+    } & Record<string, JsonValue>)[];
+  } & Record<string, JsonValue>;
   /** 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. */
-  update_goal(args: {
+  update_goal: {
     /** Exact id returned by get_goal. */
     goal_id: string;
     /** Exact positive revision returned by get_goal. */
@@ -185,9 +187,9 @@ declare const tools: {
     max_goal_rounds?: number;
     /** Concrete blocking condition; required only with action blocked. */
     blocked_reason?: string;
-  }): Promise<string>;
-  /** 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 — no oneOf/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. */
-  workflow(args: {
+  } & Record<string, JsonValue>;
+  /** 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. */
+  workflow: {
     /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */
     script: string;
     /** The workflow identity block (plain JSON — never code). */
@@ -199,7 +201,7 @@ declare const tools: {
       /** Optional guidance on when this workflow applies. */
       whenToUse?: string;
       /** Optional phase declarations matched by phase() calls. */
-      phases?: {
+      phases?: ({
         /** The phase title phase() calls match by exact string. */
         title: string;
         /** Optional one-line description of the phase. */
@@ -208,13 +210,13 @@ declare const tools: {
         provider?: string;
         /** Optional model override this phase is expected to use. */
         model?: string;
-      }[];
-    };
+      } & Record<string, JsonValue>)[];
+    } & Record<string, JsonValue>;
     /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}). */
-    args?: Record<string, unknown>;
-  }): Promise<string>;
+    args?: Record<string, JsonValue>;
+  } & Record<string, JsonValue>;
   /** Create or fully replace a UTF-8 text file. */
-  write(args: {
+  write: {
     /** Path to write, resolved by the filesystem backend. */
     file_path: string;
     /** Full UTF-8 text content to write. */
@@ -223,6 +225,213 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
+}
+
+interface ToolOutputMap {
+  ask_user_question: {
+    answers: {
+      id: string;
+      selected: string[];
+      custom?: string;
+    }[];
+  };
+  bash: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    timeoutMs: number;
+    stdout: {
+      text: string;
+      truncated: boolean;
+      spillPath?: string;
+    };
+    stderr: {
+      text: string;
+      truncated: boolean;
+      spillPath?: string;
+    };
+    sandbox?: {
+      mode: string;
+      denied: boolean;
+      enforcement?: string;
+      runnerFailed?: boolean;
+    };
+  };
+  create_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  edit: {
+    path: string;
+    before: string;
+    after: string;
+  };
+  exit_plan_mode: {
+    approved: true;
+  };
+  get_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  ralph: {
+    runId: string;
+    agentsStarted: number;
+    result: JsonValue;
+  };
+  read: {
+    path: string;
+    offset: number;
+    lines: {
+      number: number;
+      text: string;
+    }[];
+    totalLines: number;
+  };
+  skill: {
+    name: string;
+    provider: string;
+    resourceBase?: {
+      kind: "directory";
+      path: string;
+    } | {
+      kind: "url";
+      url: string;
+    } | {
+      kind: "opaque";
+      description: string;
+    };
+    content: string;
+  };
+  subagent: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    runId: string;
+    output: JsonValue[];
+  };
+  subagent_fork: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    runId: string;
+    output: JsonValue[];
+  };
+  task_kill: {
+    outcome: "cancellation-requested" | "already-finished";
+    task: {
+      id: string;
+      kind: string;
+      label: string;
+      status: "running" | "stopping" | "completed" | "killed" | "failed";
+      detail?: string;
+      startedAt: number;
+      finishedAt?: number;
+    };
+  };
+  task_list: ({
+    id: string;
+    kind: string;
+    label: string;
+    status: "running" | "stopping" | "completed" | "killed" | "failed";
+    detail?: string;
+    startedAt: number;
+    finishedAt?: number;
+  })[];
+  task_output: {
+    text: string;
+    task: {
+      id: string;
+      kind: string;
+      label: string;
+      status: "running" | "stopping" | "completed" | "killed" | "failed";
+      detail?: string;
+      startedAt: number;
+      finishedAt?: number;
+    };
+  };
+  todo_write: {
+    todos: ({
+      content: string;
+      status: "pending" | "in_progress" | "completed";
+    })[];
+    counts: {
+      pending: number;
+      inProgress: number;
+      completed: number;
+    };
+  };
+  update_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  workflow: {
+    runId: string;
+    agentsStarted: number;
+    result: JsonValue;
+  };
+  write: {
+    path: string;
+    operation: "create" | "update";
+    before: string | null;
+    after: string;
+  };
+}
+
+type ToolName = keyof ToolOutputMap
+
+declare class ToolCallError extends Error {
+  readonly name: "ToolCallError";
+  readonly toolName: ToolName;
+}
+
+declare const tools: {
+  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;
 }
 ```
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 281970523c..3f664e8e09 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
@@ -75,19 +75,19 @@
 {"type":"assistant/chunk","seq":73,"time":1783921767068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","argumentsDelta":"\\\""}}}
 {"type":"assistant/chunk","seq":74,"time":1783921767068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","argumentsDelta":" });\\n"}}}
 {"type":"assistant/chunk","seq":75,"time":1783921767068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","argumentsDelta":"return"}}}
-{"type":"assistant/chunk","seq":76,"time":1783921767095,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","argumentsDelta":" content"}}}
+{"type":"assistant/chunk","seq":76,"time":1783921767095,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","argumentsDelta":" content.lines.map(line => line.text).join(String.fromCharCode(10))"}}}
 {"type":"assistant/chunk","seq":77,"time":1783921767095,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","argumentsDelta":";"}}}
 {"type":"assistant/chunk","seq":78,"time":1783921767095,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","argumentsDelta":"\""}}}
 {"type":"assistant/chunk","seq":79,"time":1783921767121,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","argumentsDelta":"}"}}}
 {"type":"assistant/chunk","seq":80,"time":1783921767205,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to write a single run_code program that reads a file called nested/task.txt and then answer the handshake question based on what's in that file. Let me start by reading the file."}}}}
-{"type":"assistant/chunk","seq":81,"time":1783921767205,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","arguments":"{\"code\": \"const content = await tools.read({ file_path: \\\"nested/task.txt\\\" });\\nreturn content;\"}"}}}}
+{"type":"assistant/chunk","seq":81,"time":1783921767205,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","arguments":"{\"code\": \"const content = await tools.read({ file_path: \\\"nested/task.txt\\\" });\\nreturn content.lines.map(line => line.text).join(String.fromCharCode(10));\"}"}}}}
 {"type":"assistant/chunk","seq":82,"time":1783921767205,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3195,"outputTokens":106,"cacheReadTokens":0,"reasoningTokens":43}}}}
 {"type":"assistant/chunk","seq":83,"time":1783921767205,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":84,"time":1783921767208,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that reads a file called nested/task.txt and then answer the handshake question based on what's in that file. Let me start by reading the file."},{"type":"tool-call","id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","arguments":"{\"code\": \"const content = await tools.read({ file_path: \\\"nested/task.txt\\\" });\\nreturn content;\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3195,"outputTokens":106,"cacheReadTokens":0,"reasoningTokens":43}},"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],"surfaceOp":"append"}
-{"type":"tool/call","seq":85,"time":1783921767208,"data":{"turn":1,"step":1,"callId":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","arguments":"{\"code\": \"const content = await tools.read({ file_path: \\\"nested/task.txt\\\" });\\nreturn content;\"}"}}
+{"type":"assistant/message","seq":84,"time":1783921767208,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that reads a file called nested/task.txt and then answer the handshake question based on what's in that file. Let me start by reading the file."},{"type":"tool-call","id":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","arguments":"{\"code\": \"const content = await tools.read({ file_path: \\\"nested/task.txt\\\" });\\nreturn content.lines.map(line => line.text).join(String.fromCharCode(10));\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3195,"outputTokens":106,"cacheReadTokens":0,"reasoningTokens":43}},"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],"surfaceOp":"append"}
+{"type":"tool/call","seq":85,"time":1783921767208,"data":{"turn":1,"step":1,"callId":"call_00_6APApmaKLRDlXKMdIcWL5139","name":"run_code","arguments":"{\"code\": \"const content = await tools.read({ file_path: \\\"nested/task.txt\\\" });\\nreturn content.lines.map(line => line.text).join(String.fromCharCode(10));\"}"}}
 {"type":"tool/code-dispatch","seq":86,"time":1783921767270,"data":{"parentCallId":"call_00_6APApmaKLRDlXKMdIcWL5139","subCallId":"call_00_6APApmaKLRDlXKMdIcWL5139:code:1","name":"read","arguments":{"file_path":"nested/task.txt"},"isError":false,"resultSummary":"<path>./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":87,"time":1783921767271,"data":{"turn":1,"step":1,"callId":"call_00_6APApmaKLRDlXKMdIcWL5139","content":[{"type":"text","text":"<path>/var/folders/_g/59jgff8x2gqd39f5vy1wnbfc0000gn/T/acp-snap-cwd-uorU26/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>"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[85],"surfaceOp":"append"}
-{"type":"context/message","seq":88,"time":1783921767272,"data":{"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":"plugin","plugin":"workspace-context"},"meta":{"kind":"workspace-instructions","version":1,"changes":[{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"ae22936ed26dc76b7107005ed6d5e2482a88668a"}]}},"surfaceOp":"append"}
+{"type":"tool/result","seq":87,"time":1783921767271,"data":{"turn":1,"step":1,"callId":"call_00_6APApmaKLRDlXKMdIcWL5139","content":[{"type":"text","text":"Touch this file to discover the nested workspace instruction."}],"isError":false},"sourceEventSeqs":[85],"surfaceOp":"append"}
+{"type":"user/message","seq":88,"time":1784811336862,"data":{"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":"plugin","plugin":"workspace-context"},"meta":{"kind":"workspace-instructions","version":1,"changes":[{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"ae22936ed26dc76b7107005ed6d5e2482a88668a"}]}},"surfaceOp":"append"}
 {"type":"step/end","seq":89,"time":1783921767272,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":90,"time":1783921767272,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":91,"time":1783921768339,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/stdout.expected.jsonl
index 5bdacf3b5c..c881517f8b 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Using ONE run_code program, call","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
@@ -45,8 +45,8 @@
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_6APApmaKLRDlXKMdIcWL5139","title":"const content = await tools.read({ file_path: \"nested/task.txt\" });\nreturn content;","kind":"execute","status":"in_progress","rawInput":"const content = await tools.read({ file_path: \"nested/task.txt\" });\nreturn content;"}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_6APApmaKLRDlXKMdIcWL5139","status":"completed","content":[{"type":"content","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>"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_6APApmaKLRDlXKMdIcWL5139","title":"const content = await tools.read({ file_path: \"nested/task.txt\" });\nreturn content.lines.map(line => line.text).join(String.fromCharCode(10));","kind":"execute","status":"in_progress","rawInput":"const content = await tools.read({ file_path: \"nested/task.txt\" });\nreturn content.lines.map(line => line.text).join(String.fromCharCode(10));"}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_6APApmaKLRDlXKMdIcWL5139","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Touch this file to discover the nested workspace instruction."}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" nested"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"/t"}}}}
diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md
index 8868412707..8744029272 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md
@@ -28,19 +28,21 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
 
 Pass `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:
 
-- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.
-- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.
+- 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.
+- 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.
 - Calls execute sequentially, even under `Promise.all`.
 - 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.
 
 The available tools:
 
 ```ts
-declare const tools: {
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+interface ToolArgsMap {
   /** 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. */
-  ask_user_question(args: {
+  ask_user_question: {
     /** Questions to ask the user before continuing. */
-    questions: {
+    questions: ({
       /** Stable id for this question; echoed in the answer. */
       id: string;
       /** The specific question to ask the user. */
@@ -48,18 +50,18 @@ declare const tools: {
       /** Optional short heading for the question, such as "Confirm" or "Choose Mode". */
       header?: string;
       /** Optional choices to show the user. If you recommend one, put it first and append "(Recommended)" to that label. */
-      options?: {
+      options?: ({
         /** Short user-facing option label. */
         label: string;
         /** One sentence explaining the tradeoff or impact. */
         description?: string;
-      }[];
+      } & Record<string, JsonValue>)[];
       /** Whether the user may select more than one option. Defaults to false. */
       multi_select?: boolean;
-    }[];
-  }): Promise<string>;
+    } & Record<string, JsonValue>)[];
+  } & Record<string, JsonValue>;
   /** 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. */
-  bash(args: {
+  bash: {
     /** The bash command to execute. */
     command: string;
     /** 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". */
@@ -74,16 +76,16 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. */
-  create_goal(args: {
+  create_goal: {
     /** The concrete completion objective inferred from the direct human request. */
     objective: string;
     /** Optional positive safe-integer limit on automatic continuation rounds. */
     max_goal_rounds?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Edit an existing UTF-8 text file by replacing literal text. */
-  edit(args: {
+  edit: {
     /** Path to edit, resolved by the filesystem backend. */
     file_path: string;
     /** Literal text to replace. Must match exactly. */
@@ -96,83 +98,83 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again. */
-  exit_plan_mode(args: {
+  exit_plan_mode: {
     /** The complete plan, as markdown, starting with a # heading that names it. */
     plan: string;
-  }): Promise<string>;
+  } & 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(args: Record<string, unknown>): Promise<string>;
+  get_goal: 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(args: {
+  ralph: {
     /** The immutable completion objective for every fresh Ralph round. */
     objective: string;
     /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */
     maxRounds?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Read a UTF-8 text file and return line-numbered content. */
-  read(args: {
+  read: {
     /** Path to read, resolved by the filesystem backend. */
     file_path: string;
     /** 1-based first line to return. Defaults to 1. */
     offset?: number;
     /** Maximum number of lines to return. Defaults to 2000. */
     limit?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. */
-  skill(args: {
+  skill: {
     /** The exact skill name from the available skills list. */
     name: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */
-  subagent(args: {
+  subagent: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
     /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */
-  subagent_fork(args: {
+  subagent_fork: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
     /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
-  task_kill(args: {
+  task_kill: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
     /** Optional short reason, recorded in the log and forwarded to the task. */
     reason?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
-  task_list(args: Record<string, unknown>): Promise<string>;
+  task_list: Record<string, JsonValue>;
   /** 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. */
-  task_output(args: {
+  task_output: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
     /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */
     wait?: boolean;
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
   /** 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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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). */
-  todo_write(args: {
+  todo_write: {
     /** The COMPLETE task list, replacing any previous list. */
     todos: ({
       /** What the task is — a short imperative line. */
       content: string;
       /** pending (not started) | in_progress (now) | completed (done). */
       status: "pending" | "in_progress" | "completed";
-    })[];
-  }): Promise<string>;
+    } & Record<string, JsonValue>)[];
+  } & Record<string, JsonValue>;
   /** 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. */
-  update_goal(args: {
+  update_goal: {
     /** Exact id returned by get_goal. */
     goal_id: string;
     /** Exact positive revision returned by get_goal. */
@@ -185,9 +187,9 @@ declare const tools: {
     max_goal_rounds?: number;
     /** Concrete blocking condition; required only with action blocked. */
     blocked_reason?: string;
-  }): Promise<string>;
-  /** 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 — no oneOf/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. */
-  workflow(args: {
+  } & Record<string, JsonValue>;
+  /** 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. */
+  workflow: {
     /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */
     script: string;
     /** The workflow identity block (plain JSON — never code). */
@@ -199,7 +201,7 @@ declare const tools: {
       /** Optional guidance on when this workflow applies. */
       whenToUse?: string;
       /** Optional phase declarations matched by phase() calls. */
-      phases?: {
+      phases?: ({
         /** The phase title phase() calls match by exact string. */
         title: string;
         /** Optional one-line description of the phase. */
@@ -208,13 +210,13 @@ declare const tools: {
         provider?: string;
         /** Optional model override this phase is expected to use. */
         model?: string;
-      }[];
-    };
+      } & Record<string, JsonValue>)[];
+    } & Record<string, JsonValue>;
     /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}). */
-    args?: Record<string, unknown>;
-  }): Promise<string>;
+    args?: Record<string, JsonValue>;
+  } & Record<string, JsonValue>;
   /** Create or fully replace a UTF-8 text file. */
-  write(args: {
+  write: {
     /** Path to write, resolved by the filesystem backend. */
     file_path: string;
     /** Full UTF-8 text content to write. */
@@ -223,6 +225,213 @@ declare const tools: {
     sandbox_permissions?: "workspace-write" | "danger-full-access";
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. */
     justification?: string;
-  }): Promise<string>;
+  } & Record<string, JsonValue>;
+}
+
+interface ToolOutputMap {
+  ask_user_question: {
+    answers: {
+      id: string;
+      selected: string[];
+      custom?: string;
+    }[];
+  };
+  bash: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    timeoutMs: number;
+    stdout: {
+      text: string;
+      truncated: boolean;
+      spillPath?: string;
+    };
+    stderr: {
+      text: string;
+      truncated: boolean;
+      spillPath?: string;
+    };
+    sandbox?: {
+      mode: string;
+      denied: boolean;
+      enforcement?: string;
+      runnerFailed?: boolean;
+    };
+  };
+  create_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  edit: {
+    path: string;
+    before: string;
+    after: string;
+  };
+  exit_plan_mode: {
+    approved: true;
+  };
+  get_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  ralph: {
+    runId: string;
+    agentsStarted: number;
+    result: JsonValue;
+  };
+  read: {
+    path: string;
+    offset: number;
+    lines: {
+      number: number;
+      text: string;
+    }[];
+    totalLines: number;
+  };
+  skill: {
+    name: string;
+    provider: string;
+    resourceBase?: {
+      kind: "directory";
+      path: string;
+    } | {
+      kind: "url";
+      url: string;
+    } | {
+      kind: "opaque";
+      description: string;
+    };
+    content: string;
+  };
+  subagent: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    runId: string;
+    output: JsonValue[];
+  };
+  subagent_fork: {
+    kind: "background";
+    taskId: string;
+  } | {
+    kind: "foreground";
+    runId: string;
+    output: JsonValue[];
+  };
+  task_kill: {
+    outcome: "cancellation-requested" | "already-finished";
+    task: {
+      id: string;
+      kind: string;
+      label: string;
+      status: "running" | "stopping" | "completed" | "killed" | "failed";
+      detail?: string;
+      startedAt: number;
+      finishedAt?: number;
+    };
+  };
+  task_list: ({
+    id: string;
+    kind: string;
+    label: string;
+    status: "running" | "stopping" | "completed" | "killed" | "failed";
+    detail?: string;
+    startedAt: number;
+    finishedAt?: number;
+  })[];
+  task_output: {
+    text: string;
+    task: {
+      id: string;
+      kind: string;
+      label: string;
+      status: "running" | "stopping" | "completed" | "killed" | "failed";
+      detail?: string;
+      startedAt: number;
+      finishedAt?: number;
+    };
+  };
+  todo_write: {
+    todos: ({
+      content: string;
+      status: "pending" | "in_progress" | "completed";
+    })[];
+    counts: {
+      pending: number;
+      inProgress: number;
+      completed: number;
+    };
+  };
+  update_goal: {
+    goal: null;
+  } | {
+    goal: {
+      id: string;
+      revision: number;
+      objective: string;
+      phase: "active" | "paused" | "blocked" | "complete";
+      roundsStarted: number;
+      maxGoalRounds: number;
+      blockedReason?: {
+        code: string;
+        message: string;
+      };
+    };
+    activation: "armed" | "disarmed";
+  };
+  workflow: {
+    runId: string;
+    agentsStarted: number;
+    result: JsonValue;
+  };
+  write: {
+    path: string;
+    operation: "create" | "update";
+    before: string | null;
+    after: string;
+  };
+}
+
+type ToolName = keyof ToolOutputMap
+
+declare class ToolCallError extends Error {
+  readonly name: "ToolCallError";
+  readonly toolName: ToolName;
+}
+
+declare const tools: {
+  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;
 }
 ```
diff --git a/examples/acp-agent/tests/snapshots/config-options/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/config-options/stdout.expected.jsonl
index 54063e3477..53ad812adb 100644
--- a/examples/acp-agent/tests/snapshots/config-options/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/config-options/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","id":4,"result":{"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","id":5,"error":{"code":-32602,"message":"Invalid params: unknown permission value \"plan\""}}
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 bd13d3b146..487f0517b1 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -11,7 +11,7 @@
 {"type":"assistant/chunk","seq":9,"time":1783951000009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":10,"time":1784449176722,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}
 {"type":"tool/call","seq":11,"time":1784449176722,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}}
-{"type":"tool/result","seq":12,"time":1784449176732,"data":{"turn":1,"step":1,"callId":"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 - the tool schema, execution, and optional presentation functions.\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, and final\n     * notification. Tool and listener failures resolve as materialized error\n     * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is\n     * the same lossless, frozen 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 status: AgentStatus;\n        readonly ctx: Context;\n        send(content: ContentBlock[], options?: SendOptions): void;\n        steer(content: ContentBlock[], options?: SendOptions): void;\n        inject(content: ContentBlock[], options?: InjectOptions): void;\n        cancel(cause?: AgentCancelCause): void;\n        whenIdle(): Promise<void>;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n    }\n    export type AgentStatus = 'idle' | 'running' | 'disposed';\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\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 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 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 interface HookContext {\n        content: ContentBlock[];\n        source: MessageSource;\n        placement?: 'separate' | 'prompt-prefix';\n        meta?: JsonValue;\n    }\n    export interface InjectOptions extends Omit<SendOptions, 'contexts'> {\n        meta?: JsonValue;\n    }\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\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        };\n    }\n    export type ScopeKey = object;\n    export interface SendOptions {\n        source?: MessageSource;\n        contexts?: HookContext[];\n    }\n    export type SessionId = Branded<'SessionId'>;\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 type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>;\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 type ToolExecuteReturn = ContentBlock[] | {\n        content: ContentBlock[];\n        meta?: unknown;\n    };\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\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 interface ToolExecutionResult {\n        content: ContentBlock[];\n        isError: boolean;\n        error?: ToolErrorInfo;\n        additionalContexts?: HookContext[];\n        meta?: unknown;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\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?: unknown;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: HookContext): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }"}],"isError":false},"sourceEventSeqs":[11],"surfaceOp":"append"}
+{"type":"tool/result","seq":12,"time":1784449176732,"data":{"turn":1,"step":1,"callId":"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 status: AgentStatus;\n        readonly ctx: Context;\n        followup(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n        queue(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n        steer(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n        inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId;\n        send(input: ResolvedAgentInput): AgentMessageId;\n        cancel(cause?: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise<void>;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    };\n    export type AgentMessageId = Branded<'AgentMessageId'>;\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n    }\n    export type AgentStatus = 'idle' | 'running' | 'disposed';\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;\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 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        system?: string;\n        tools?: ToolSchema[];\n        messagePrefix?: Message[];\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 interface HookContext {\n        content: ContentBlock[];\n        source: MessageSource;\n        placement?: 'separate' | 'prompt-prefix';\n        meta?: JsonValue;\n    }\n    export interface InjectOptions {\n        source?: MessageSource;\n        meta?: JsonValue;\n    }\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        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\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        role: 'system' | 'user' | 'assistant';\n        content: ContentBlock[];\n        provenance?: AssistantProvenance;\n    }\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        };\n    }\n    export interface PromptMessageData {\n        content: ContentBlock[];\n        source: MessageSource;\n        envelope?: PromptMessageEnvelope;\n        meta?: JsonValue;\n    }\n    export interface PromptMessageEnvelope {\n        displayContent: ContentBlock[];\n        prefixContexts: PromptPrefixContext[];\n    }\n    export interface PromptPrefixContext {\n        source: MessageSource;\n        meta?: JsonValue;\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ResolvedAgentInput = {\n        content: ContentBlock[];\n        source: MessageSource;\n        meta: JsonValue | undefined;\n    } & ({\n        target: 'next-turn';\n        wakeup: boolean;\n        contexts: HookContext[];\n    } | {\n        target: 'next-step';\n        wakeup: true;\n        contexts: HookContext[];\n    } | {\n        target: 'next-step';\n        wakeup: false;\n        contexts: [\n        ];\n    });\n    export type ScopeKey = object;\n    export interface SendOptions {\n        source?: MessageSource;\n        contexts?: HookContext[];\n        meta?: JsonValue;\n    }\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\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        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            trigger: TurnTrigger;\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': PromptMessageData;\n        'prompt/blocked': {\n            content: ContentBlock[];\n            source: MessageSource;\n            reason: string;\n        };\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            content: ContentBlock[];\n            provenance: AssistantProvenance;\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            callId: CallId;\n            content: ContentBlock[];\n            isError: boolean;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'steering/message': PromptMessageData & {\n            turn: number;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\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 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' | 'steering/message';\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?: HookContext[];\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?: HookContext[];\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 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 type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: HookContext): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n        };\n        error: {\n            kind: 'error';\n            step: number;\n        } & ({\n            failure: LlmFailure;\n            message?: never;\n            code?: never;\n        } | {\n            message: string;\n            code?: string;\n            failure?: never;\n        });\n        disposed: {\n            kind: 'disposed';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        rejected: {\n            kind: 'rejected';\n            reason: string;\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n    export interface TurnTriggerMap {\n        message: {\n            kind: 'message';\n            source: MessageSource;\n        };\n        injection: {\n            kind: 'injection';\n            source: MessageSource;\n        };\n    }"}],"isError":false},"sourceEventSeqs":[11],"surfaceOp":"append"}
 {"type":"step/end","seq":13,"time":1784449176732,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":14,"time":1784449176733,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":15,"time":1783951000015,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
index 6a78b05a65..56cc640977 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
@@ -1,9 +1,9 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Inspect the exact tools service","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"inspect-tools-api","title":"Inspect cordis runtime: api: tools","kind":"read","status":"in_progress"}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"inspect-tools-api","status":"completed","content":[{"type":"content","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 - the tool schema, execution, and optional presentation functions.\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, and final\n     * notification. Tool and listener failures resolve as materialized error\n     * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is\n     * the same lossless, frozen 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 status: AgentStatus;\n        readonly ctx: Context;\n        send(content: ContentBlock[], options?: SendOptions): void;\n        steer(content: ContentBlock[], options?: SendOptions): void;\n        inject(content: ContentBlock[], options?: InjectOptions): void;\n        cancel(cause?: AgentCancelCause): void;\n        whenIdle(): Promise<void>;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n    }\n    export type AgentStatus = 'idle' | 'running' | 'disposed';\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\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 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 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 interface HookContext {\n        content: ContentBlock[];\n        source: MessageSource;\n        placement?: 'separate' | 'prompt-prefix';\n        meta?: JsonValue;\n    }\n    export interface InjectOptions extends Omit<SendOptions, 'contexts'> {\n        meta?: JsonValue;\n    }\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\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        };\n    }\n    export type ScopeKey = object;\n    export interface SendOptions {\n        source?: MessageSource;\n        contexts?: HookContext[];\n    }\n    export type SessionId = Branded<'SessionId'>;\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 type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>;\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 type ToolExecuteReturn = ContentBlock[] | {\n        content: ContentBlock[];\n        meta?: unknown;\n    };\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\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 interface ToolExecutionResult {\n        content: ContentBlock[];\n        isError: boolean;\n        error?: ToolErrorInfo;\n        additionalContexts?: HookContext[];\n        meta?: unknown;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\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?: unknown;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: HookContext): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"inspect-tools-api","status":"completed","content":[{"type":"content","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 status: AgentStatus;\n        readonly ctx: Context;\n        followup(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n        queue(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n        steer(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n        inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId;\n        send(input: ResolvedAgentInput): AgentMessageId;\n        cancel(cause?: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise<void>;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    };\n    export type AgentMessageId = Branded<'AgentMessageId'>;\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n    }\n    export type AgentStatus = 'idle' | 'running' | 'disposed';\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;\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 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        system?: string;\n        tools?: ToolSchema[];\n        messagePrefix?: Message[];\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 interface HookContext {\n        content: ContentBlock[];\n        source: MessageSource;\n        placement?: 'separate' | 'prompt-prefix';\n        meta?: JsonValue;\n    }\n    export interface InjectOptions {\n        source?: MessageSource;\n        meta?: JsonValue;\n    }\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        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\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        role: 'system' | 'user' | 'assistant';\n        content: ContentBlock[];\n        provenance?: AssistantProvenance;\n    }\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        };\n    }\n    export interface PromptMessageData {\n        content: ContentBlock[];\n        source: MessageSource;\n        envelope?: PromptMessageEnvelope;\n        meta?: JsonValue;\n    }\n    export interface PromptMessageEnvelope {\n        displayContent: ContentBlock[];\n        prefixContexts: PromptPrefixContext[];\n    }\n    export interface PromptPrefixContext {\n        source: MessageSource;\n        meta?: JsonValue;\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ResolvedAgentInput = {\n        content: ContentBlock[];\n        source: MessageSource;\n        meta: JsonValue | undefined;\n    } & ({\n        target: 'next-turn';\n        wakeup: boolean;\n        contexts: HookContext[];\n    } | {\n        target: 'next-step';\n        wakeup: true;\n        contexts: HookContext[];\n    } | {\n        target: 'next-step';\n        wakeup: false;\n        contexts: [\n        ];\n    });\n    export type ScopeKey = object;\n    export interface SendOptions {\n        source?: MessageSource;\n        contexts?: HookContext[];\n        meta?: JsonValue;\n    }\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\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        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            trigger: TurnTrigger;\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': PromptMessageData;\n        'prompt/blocked': {\n            content: ContentBlock[];\n            source: MessageSource;\n            reason: string;\n        };\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            content: ContentBlock[];\n            provenance: AssistantProvenance;\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            callId: CallId;\n            content: ContentBlock[];\n            isError: boolean;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'steering/message': PromptMessageData & {\n            turn: number;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\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 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' | 'steering/message';\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?: HookContext[];\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?: HookContext[];\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 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 type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: HookContext): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n        };\n        error: {\n            kind: 'error';\n            step: number;\n        } & ({\n            failure: LlmFailure;\n            message?: never;\n            code?: never;\n        } | {\n            message: string;\n            code?: string;\n            failure?: never;\n        });\n        disposed: {\n            kind: 'disposed';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        rejected: {\n            kind: 'rejected';\n            reason: string;\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n    export interface TurnTriggerMap {\n        message: {\n            kind: 'message';\n            source: MessageSource;\n        };\n        injection: {\n            kind: 'injection';\n            source: MessageSource;\n        };\n    }"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"inspect-tools-event","title":"Inspect cordis runtime: events: tools/pre-execute","kind":"read","status":"in_progress"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"inspect-tools-event","status":"completed","content":[{"type":"content","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."}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}}}}
diff --git a/examples/acp-agent/tests/snapshots/error-finish/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/error-finish/stdout.expected.jsonl
index b07d78c68b..ecef64b941 100644
--- a/examples/acp-agent/tests/snapshots/error-finish/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/error-finish/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"This prompt triggers a recorded","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"\n\n[Model attempt failed; any partial output above is discarded: simulated provider error (HTTP 401)]\n\n"}}}}
 {"jsonrpc":"2.0","id":3,"error":{"code":-32603,"message":"Internal error: turn failed: simulated provider error (HTTP 401)"}}
diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/escalation-approved/stdout.expected.jsonl
index 445da921d3..f928a513ba 100644
--- a/examples/acp-agent/tests/snapshots/escalation-approved/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/escalation-approved/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"The sandbox already denied writing","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
diff --git a/examples/acp-agent/tests/snapshots/escalation-rejected/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/escalation-rejected/stdout.expected.jsonl
index a634adb5db..409bbb57a1 100644
--- a/examples/acp-agent/tests/snapshots/escalation-rejected/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/escalation-rejected/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"The sandbox already denied writing","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-edit/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-edit/stdout.expected.jsonl
index 6a9e22ca4f..b589e427d0 100644
--- a/examples/acp-agent/tests/snapshots/fs-edit/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-edit/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"First use the read tool","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl b/examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl
index 424aeb1aa3..918b3ab4d5 100644
--- a/examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl
@@ -92,7 +92,7 @@
 {"type":"tool/call","seq":90,"time":1784045703780,"data":{"turn":1,"step":1,"callId":"call_00_Fnymmavpr4klMDy4Fdej3227","name":"write","arguments":"{\"file_path\": \"escalated.md\", \"content\": \"escalated\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to escalate this write\"}"}}
 {"type":"approval/asked","seq":91,"time":1784045703782,"data":{"id":"d7250dff-fc08-4163-9b51-f43f08d6f36f","toolName":"write","callId":"call_00_Fnymmavpr4klMDy4Fdej3227","reason":"escalate sandbox to danger-full-access: the user asked to escalate this write"}}
 {"type":"approval/decided","seq":92,"time":1784045703786,"data":{"id":"d7250dff-fc08-4163-9b51-f43f08d6f36f","outcome":"allowed-once"}}
-{"type":"tool/result","seq":93,"time":1784045703798,"data":{"turn":1,"step":1,"callId":"call_00_Fnymmavpr4klMDy4Fdej3227","content":[{"type":"text","text":"<path>/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-vmEGzd/escalated.md</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false},"sourceEventSeqs":[90],"surfaceOp":"append"}
+{"type":"tool/result","seq":93,"time":1784045703798,"data":{"turn":1,"step":1,"callId":"call_00_Fnymmavpr4klMDy4Fdej3227","content":[{"type":"text","text":"<path>/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-vmEGzd/escalated.md</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false,"meta":{"diffs":[]}},"sourceEventSeqs":[90],"surfaceOp":"append"}
 {"type":"step/end","seq":94,"time":1784045703798,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":95,"time":1784045703799,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":96,"time":1784045704512,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-escalation-approved/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-escalation-approved/stdout.expected.jsonl
index 1870ad0e74..6f5783b6ad 100644
--- a/examples/acp-agent/tests/snapshots/fs-escalation-approved/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-escalation-approved/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the write tool (NOT","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-policy-reject/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-policy-reject/stdout.expected.jsonl
index 2392596350..49a6f6db55 100644
--- a/examples/acp-agent/tests/snapshots/fs-policy-reject/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-policy-reject/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Do NOT use the read","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-read-window/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-read-window/stdout.expected.jsonl
index 9fb6651a32..0a32a44362 100644
--- a/examples/acp-agent/tests/snapshots/fs-read-window/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-read-window/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the read tool (NOT","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-read/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-read/stdout.expected.jsonl
index d07b3280e6..aabd8fe4dc 100644
--- a/examples/acp-agent/tests/snapshots/fs-read/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-read/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the read tool (NOT","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-terminal-card/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-terminal-card/stdout.expected.jsonl
index 86458277ad..0b2343793b 100644
--- a/examples/acp-agent/tests/snapshots/fs-terminal-card/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-terminal-card/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-write-overwrite/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-write-overwrite/stdout.expected.jsonl
index 002f1b0da0..c1e57a0315 100644
--- a/examples/acp-agent/tests/snapshots/fs-write-overwrite/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-write-overwrite/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"First use the read tool","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-write/session.jsonl b/examples/acp-agent/tests/snapshots/fs-write/session.jsonl
index fe2c0b5b6b..dbaaf8a8b6 100644
--- a/examples/acp-agent/tests/snapshots/fs-write/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-write/session.jsonl
@@ -63,7 +63,7 @@
 {"type":"assistant/chunk","seq":61,"time":1783352079886,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":62,"time":1783352079888,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to create a file named notes.txt with the content \"hello world\" using the write tool, then reply with \"DONE\"."},{"type":"tool-call","id":"call_00_APMUCJJm9lrTSlVbg6dB0185","name":"write","arguments":"{\"file_path\": \"notes.txt\", \"content\": \"hello world\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":2891,"outputTokens":92,"cacheReadTokens":0,"reasoningTokens":30}},"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],"surfaceOp":"append"}
 {"type":"tool/call","seq":63,"time":1783352079888,"data":{"turn":1,"step":1,"callId":"call_00_APMUCJJm9lrTSlVbg6dB0185","name":"write","arguments":"{\"file_path\": \"notes.txt\", \"content\": \"hello world\"}"}}
-{"type":"tool/result","seq":64,"time":1783352079897,"data":{"turn":1,"step":1,"callId":"call_00_APMUCJJm9lrTSlVbg6dB0185","content":[{"type":"text","text":"<path>/tmp/acp-snap-cwd-sNvn5N/notes.txt</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false},"sourceEventSeqs":[63],"surfaceOp":"append"}
+{"type":"tool/result","seq":64,"time":1783352079897,"data":{"turn":1,"step":1,"callId":"call_00_APMUCJJm9lrTSlVbg6dB0185","content":[{"type":"text","text":"<path>/tmp/acp-snap-cwd-sNvn5N/notes.txt</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false,"meta":{"diffs":[]}},"sourceEventSeqs":[63],"surfaceOp":"append"}
 {"type":"step/end","seq":65,"time":1783352079898,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":66,"time":1783352079899,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":67,"time":1783352080825,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-write/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-write/stdout.expected.jsonl
index 955deb74df..16f2d39a8d 100644
--- a/examples/acp-agent/tests/snapshots/fs-write/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-write/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the write tool (NOT","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/goal-command-status/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/goal-command-status/stdout.expected.jsonl
index 12146e50c0..64ef74a717 100644
--- a/examples/acp-agent/tests/snapshots/goal-command-status/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/goal-command-status/stdout.expected.jsonl
@@ -1,5 +1,5 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"No goal is currently set.\nUsage: /goal [<objective>|clear|edit <objective>|pause|resume]"}}}}
 {"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
diff --git a/examples/acp-agent/tests/snapshots/handshake/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/handshake/stdout.expected.jsonl
index f80709f106..42747846b2 100644
--- a/examples/acp-agent/tests/snapshots/handshake/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/handshake/stdout.expected.jsonl
@@ -1,3 +1,3 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/stdout.expected.jsonl
index 08adb8f230..3295477ce5 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Call the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl
index c638389319..910bdfca68 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl
@@ -63,7 +63,7 @@
 {"type":"hook/invoked","seq":61,"time":1783352197968,"data":{"turn":1,"point":"PostToolUse","dialect":"claude","handlerId":"claude:PostToolUse:1","matcher":"bash"}}
 {"type":"hook/result","seq":62,"time":1783352197976,"data":{"turn":1,"point":"PostToolUse","handlerId":"claude:PostToolUse:1","decision":"pass","exitCode":0,"durationMs":7.404540999999881}}
 {"type":"tool/result","seq":63,"time":1783352197976,"data":{"turn":1,"step":1,"callId":"call_00_HbCMzTslWBZTSphWN0z97382","content":[{"type":"text","text":"HELLO\n"}],"isError":false},"sourceEventSeqs":[60],"surfaceOp":"append"}
-{"type":"context/message","seq":64,"time":1783352197976,"data":{"content":[{"type":"text","text":"Note: command output has been verified against the audit log."}],"source":{"kind":"plugin","plugin":"hooks-claude"}},"surfaceOp":"append"}
+{"type":"user/message","seq":64,"time":1783352197976,"data":{"content":[{"type":"text","text":"Note: command output has been verified against the audit log."}],"source":{"kind":"plugin","plugin":"hooks-claude"}},"surfaceOp":"append"}
 {"type":"step/end","seq":65,"time":1783352197977,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":66,"time":1783352197977,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":67,"time":1783352198981,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/stdout.expected.jsonl
index e9284e2893..9e19a80897 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/stdout.expected.jsonl
index ad13ccf938..a14e4cafb6 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/stdout.expected.jsonl
index 54e62a3a6d..59c21ed411 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-block/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-block/stdout.expected.jsonl
index dc5fb9671c..6a1310e749 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-block/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-block/stdout.expected.jsonl
@@ -1,4 +1,4 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"stopReason":"cancelled"}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl
index 46561a4760..921bc270d9 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl
@@ -3,7 +3,7 @@
 {"type":"hook/invoked","seq":1,"time":1783352160546,"data":{"turn":1,"point":"UserPromptSubmit","dialect":"claude","handlerId":"claude:UserPromptSubmit:1"}}
 {"type":"hook/result","seq":2,"time":1783352160564,"data":{"turn":1,"point":"UserPromptSubmit","handlerId":"claude:UserPromptSubmit:1","decision":"pass","exitCode":0,"durationMs":17.45639600000004}}
 {"type":"user/message","seq":3,"time":1783352160564,"data":{"content":[{"type":"text","text":"What is my favorite color? Reply with just the color and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"context/message","seq":4,"time":1783352160564,"data":{"content":[{"type":"text","text":"The user has previously stated their favorite color is teal."}],"source":{"kind":"plugin","plugin":"hooks-claude"}},"surfaceOp":"append"}
+{"type":"user/message","seq":4,"time":1783352160564,"data":{"content":[{"type":"text","text":"The user has previously stated their favorite color is teal."}],"source":{"kind":"plugin","plugin":"hooks-claude"}},"surfaceOp":"append"}
 {"type":"session/title","seq":5,"time":1783352160564,"data":{"title":"What is my favorite color?","messageSeqs":[3],"source":{"kind":"fallback"}}}
 {"type":"step/start","seq":6,"time":1783352160565,"data":{"turn":1,"step":1}}
 {"type":"request/header","seq":7,"time":1783352160566,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/stdout.expected.jsonl
index b5fa736957..c700da5011 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"What is my favorite color?","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/stdout.expected.jsonl
index 0ec240ce55..cb8001573f 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Reply with the single word","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/stdout.expected.jsonl
index edf46eb31e..02ddcc549b 100644
--- a/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Call the bash tool exactly","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl
index 9b58a769c5..deab3ab423 100644
--- a/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl
@@ -63,7 +63,7 @@
 {"type":"hook/invoked","seq":61,"time":1783352229622,"data":{"turn":1,"point":"PostToolUse","dialect":"codex","handlerId":"codex:PostToolUse:1","matcher":"bash"}}
 {"type":"hook/result","seq":62,"time":1783352229632,"data":{"turn":1,"point":"PostToolUse","handlerId":"codex:PostToolUse:1","decision":"pass","exitCode":0,"durationMs":9.27664199999981}}
 {"type":"tool/result","seq":63,"time":1783352229632,"data":{"turn":1,"step":1,"callId":"call_00_Q6wHtakaip2QNfIXaVJY5458","content":[{"type":"text","text":"HELLO\n"}],"isError":false},"sourceEventSeqs":[60],"surfaceOp":"append"}
-{"type":"context/message","seq":64,"time":1783352229633,"data":{"content":[{"type":"text","text":"Note: command output has been verified against the audit log."}],"source":{"kind":"plugin","plugin":"hooks-codex"}},"surfaceOp":"append"}
+{"type":"user/message","seq":64,"time":1783352229633,"data":{"content":[{"type":"text","text":"Note: command output has been verified against the audit log."}],"source":{"kind":"plugin","plugin":"hooks-codex"}},"surfaceOp":"append"}
 {"type":"step/end","seq":65,"time":1783352229633,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":66,"time":1783352229633,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":67,"time":1783352230757,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/stdout.expected.jsonl
index 9656372c47..18ef664117 100644
--- a/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/stdout.expected.jsonl
index 7a8e32a434..749e68ec30 100644
--- a/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-block/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-block/stdout.expected.jsonl
index dc5fb9671c..6a1310e749 100644
--- a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-block/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-block/stdout.expected.jsonl
@@ -1,4 +1,4 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"stopReason":"cancelled"}}
diff --git a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl
index c1f23a6b5e..ac319964f3 100644
--- a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl
@@ -3,7 +3,7 @@
 {"type":"hook/invoked","seq":1,"time":1783352209687,"data":{"turn":1,"point":"UserPromptSubmit","dialect":"codex","handlerId":"codex:UserPromptSubmit:1"}}
 {"type":"hook/result","seq":2,"time":1783352209706,"data":{"turn":1,"point":"UserPromptSubmit","handlerId":"codex:UserPromptSubmit:1","decision":"pass","exitCode":0,"durationMs":19.49695100000008}}
 {"type":"user/message","seq":3,"time":1783352209707,"data":{"content":[{"type":"text","text":"What is my favorite color? Reply with just the color and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"context/message","seq":4,"time":1783352209707,"data":{"content":[{"type":"text","text":"The user has previously stated their favorite color is teal."}],"source":{"kind":"plugin","plugin":"hooks-codex"}},"surfaceOp":"append"}
+{"type":"user/message","seq":4,"time":1783352209707,"data":{"content":[{"type":"text","text":"The user has previously stated their favorite color is teal."}],"source":{"kind":"plugin","plugin":"hooks-codex"}},"surfaceOp":"append"}
 {"type":"session/title","seq":5,"time":1783352209707,"data":{"title":"What is my favorite color?","messageSeqs":[3],"source":{"kind":"fallback"}}}
 {"type":"step/start","seq":6,"time":1783352209709,"data":{"turn":1,"step":1}}
 {"type":"request/header","seq":7,"time":1783352209710,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/stdout.expected.jsonl
index bd8177b30a..2a47058980 100644
--- a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"What is my favorite color?","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/stdout.expected.jsonl
index d2fb6a6df9..e7b1d906e9 100644
--- a/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Reply with the single word","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/lsp-definition/stdout.expected.jsonl
index c58fa5004c..ea9960c652 100644
--- a/examples/acp-agent/tests/snapshots/lsp-definition/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/lsp-definition/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the lsp tool exactly","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_lsp_definition","title":"LSP goToDefinition subject.ts:1:7","kind":"search","status":"in_progress","locations":[{"path":"subject.ts","line":1}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_lsp_definition","status":"completed","content":[{"type":"content","content":{"type":"text","text":"subject.ts:1:7\n… 1 more location omitted (limit 1)."}}]}}}
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 9839668511..b42a434388 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
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -402,6 +404,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -476,7 +479,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -487,6 +490,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -505,6 +509,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -536,7 +541,8 @@
           },
           "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\": [...]})."
+            "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": [
diff --git a/examples/acp-agent/tests/snapshots/model-switching/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/model-switching/stdout.expected.jsonl
index d44158e357..85bb5a7137 100644
--- a/examples/acp-agent/tests/snapshots/model-switching/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/model-switching/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Without using tools, reply with","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/model-switching/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/model-switching/tool-schemas.expected.json
index 85acdd1ee1..ef40784fa5 100644
--- a/examples/acp-agent/tests/snapshots/model-switching/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/model-switching/tool-schemas.expected.json
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -365,6 +367,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -439,7 +442,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -450,6 +453,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -468,6 +472,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -499,7 +504,8 @@
           },
           "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\": [...]})."
+            "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": [
@@ -555,6 +561,7 @@
               "description": "Questions to ask the user before continuing.",
               "items": {
                 "type": "object",
+                "additionalProperties": true,
                 "properties": {
                   "id": {
                     "type": "string",
@@ -573,6 +580,7 @@
                     "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",
@@ -909,6 +917,7 @@
               "description": "The COMPLETE task list, replacing any previous list.",
               "items": {
                 "type": "object",
+                "additionalProperties": true,
                 "properties": {
                   "content": {
                     "type": "string",
@@ -983,7 +992,7 @@
       },
       {
         "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 — no oneOf/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.",
+        "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": {
@@ -994,6 +1003,7 @@
             "meta": {
               "type": "object",
               "description": "The workflow identity block (plain JSON — never code).",
+              "additionalProperties": true,
               "properties": {
                 "name": {
                   "type": "string",
@@ -1012,6 +1022,7 @@
                   "description": "Optional phase declarations matched by phase() calls.",
                   "items": {
                     "type": "object",
+                    "additionalProperties": true,
                     "properties": {
                       "title": {
                         "type": "string",
@@ -1043,7 +1054,8 @@
             },
             "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\": [...]})."
+              "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": [
diff --git a/examples/acp-agent/tests/snapshots/modes-advertise/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/modes-advertise/stdout.expected.jsonl
index 86aec432ae..f7cc8fe1df 100644
--- a/examples/acp-agent/tests/snapshots/modes-advertise/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/modes-advertise/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"current_mode_update","currentModeId":"plan"}}}
 {"jsonrpc":"2.0","id":3,"result":{}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"current_mode_update","currentModeId":"default"}}}
diff --git a/examples/acp-agent/tests/snapshots/multi-turn/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/multi-turn/stdout.expected.jsonl
index 9d4ccf1046..ea06457e19 100644
--- a/examples/acp-agent/tests/snapshots/multi-turn/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/multi-turn/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Reply with exactly the word:","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/packed-chunks/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/packed-chunks/stdout.expected.jsonl
index 54e62a3a6d..59c21ed411 100644
--- a/examples/acp-agent/tests/snapshots/packed-chunks/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/packed-chunks/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/parallel-tool-calls/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/parallel-tool-calls/stdout.expected.jsonl
index a3595f8f4f..43066629e4 100644
--- a/examples/acp-agent/tests/snapshots/parallel-tool-calls/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/parallel-tool-calls/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the read tool twice","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_read_a","title":"Read a.txt","kind":"read","status":"in_progress","locations":[{"path":"a.txt","line":1}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_read_b","title":"Read b.txt","kind":"read","status":"in_progress","locations":[{"path":"b.txt","line":1}]}}}
diff --git a/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl b/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
index cbb52c1b08..381458957c 100644
--- a/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
@@ -106,7 +106,7 @@
 {"type":"sandbox/mode","seq":104,"time":1784518115842,"data":{"mode":"danger-full-access"}}
 {"type":"approval/policy","seq":105,"time":1783962244624,"data":{"policy":"never"}}
 {"type":"user/message","seq":106,"time":1783962244624,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: cat out.txt. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"context/message","seq":107,"time":1783962244624,"data":{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"}},"surfaceOp":"append"}
+{"type":"user/message","seq":107,"time":1783962244624,"data":{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"}},"surfaceOp":"append"}
 {"type":"step/start","seq":108,"time":1783962244624,"data":{"turn":2,"step":1}}
 {"type":"request/header","seq":109,"time":1784000791271,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"change"}}
 {"type":"assistant/chunk","seq":110,"time":1783860671025,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/examples/acp-agent/tests/snapshots/permission-switching/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/permission-switching/stdout.expected.jsonl
index a53224e202..7e51129a1d 100644
--- a/examples/acp-agent/tests/snapshots/permission-switching/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/permission-switching/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
diff --git a/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.expected.json
index 85acdd1ee1..ef40784fa5 100644
--- a/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.expected.json
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -365,6 +367,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -439,7 +442,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -450,6 +453,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -468,6 +472,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -499,7 +504,8 @@
           },
           "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\": [...]})."
+            "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": [
@@ -555,6 +561,7 @@
               "description": "Questions to ask the user before continuing.",
               "items": {
                 "type": "object",
+                "additionalProperties": true,
                 "properties": {
                   "id": {
                     "type": "string",
@@ -573,6 +580,7 @@
                     "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",
@@ -909,6 +917,7 @@
               "description": "The COMPLETE task list, replacing any previous list.",
               "items": {
                 "type": "object",
+                "additionalProperties": true,
                 "properties": {
                   "content": {
                     "type": "string",
@@ -983,7 +992,7 @@
       },
       {
         "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 — no oneOf/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.",
+        "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": {
@@ -994,6 +1003,7 @@
             "meta": {
               "type": "object",
               "description": "The workflow identity block (plain JSON — never code).",
+              "additionalProperties": true,
               "properties": {
                 "name": {
                   "type": "string",
@@ -1012,6 +1022,7 @@
                   "description": "Optional phase declarations matched by phase() calls.",
                   "items": {
                     "type": "object",
+                    "additionalProperties": true,
                     "properties": {
                       "title": {
                         "type": "string",
@@ -1043,7 +1054,8 @@
             },
             "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\": [...]})."
+              "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": [
diff --git a/examples/acp-agent/tests/snapshots/plan-mode-reject/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/plan-mode-reject/stdout.expected.jsonl
index 1fade38776..976bfd36e5 100644
--- a/examples/acp-agent/tests/snapshots/plan-mode-reject/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/plan-mode-reject/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"current_mode_update","currentModeId":"plan"}}}
 {"jsonrpc":"2.0","id":3,"result":{}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Read the file notes.txt (use","updatedAt":"{{updatedAt}}"}}}
diff --git a/examples/acp-agent/tests/snapshots/plan-mode/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/plan-mode/stdout.expected.jsonl
index 9d67e0f2eb..0976b68317 100644
--- a/examples/acp-agent/tests/snapshots/plan-mode/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/plan-mode/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"current_mode_update","currentModeId":"plan"}}}
 {"jsonrpc":"2.0","id":3,"result":{}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"The typo is on line","updatedAt":"{{updatedAt}}"}}}
diff --git a/examples/acp-agent/tests/snapshots/plan-mode/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/plan-mode/tool-schemas.expected.json
index 85acdd1ee1..ef40784fa5 100644
--- a/examples/acp-agent/tests/snapshots/plan-mode/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/plan-mode/tool-schemas.expected.json
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -365,6 +367,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -439,7 +442,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -450,6 +453,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -468,6 +472,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -499,7 +504,8 @@
           },
           "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\": [...]})."
+            "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": [
@@ -555,6 +561,7 @@
               "description": "Questions to ask the user before continuing.",
               "items": {
                 "type": "object",
+                "additionalProperties": true,
                 "properties": {
                   "id": {
                     "type": "string",
@@ -573,6 +580,7 @@
                     "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",
@@ -909,6 +917,7 @@
               "description": "The COMPLETE task list, replacing any previous list.",
               "items": {
                 "type": "object",
+                "additionalProperties": true,
                 "properties": {
                   "content": {
                     "type": "string",
@@ -983,7 +992,7 @@
       },
       {
         "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 — no oneOf/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.",
+        "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": {
@@ -994,6 +1003,7 @@
             "meta": {
               "type": "object",
               "description": "The workflow identity block (plain JSON — never code).",
+              "additionalProperties": true,
               "properties": {
                 "name": {
                   "type": "string",
@@ -1012,6 +1022,7 @@
                   "description": "Optional phase declarations matched by phase() calls.",
                   "items": {
                     "type": "object",
+                    "additionalProperties": true,
                     "properties": {
                       "title": {
                         "type": "string",
@@ -1043,7 +1054,8 @@
             },
             "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\": [...]})."
+              "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": [
diff --git a/examples/acp-agent/tests/snapshots/pty-tools/session.jsonl b/examples/acp-agent/tests/snapshots/pty-tools/session.jsonl
index f3157d811b..5694ae4343 100644
--- a/examples/acp-agent/tests/snapshots/pty-tools/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/pty-tools/session.jsonl
@@ -21,7 +21,7 @@
 {"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":20,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"pty-send","name":"terminal_send","arguments":"{\"sessionId\":\"pty-1\",\"text\":\"printf 'PTY_OK\\\\n'\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-pro"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}
 {"type":"tool/call","seq":21,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","name":"terminal_send","arguments":"{\"sessionId\":\"pty-1\",\"text\":\"printf 'PTY_OK\\\\n'\"}"}}
-{"type":"tool/result","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","content":[{"type":"text","text":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> \n[wait: stdin_read]\n[session: running]"}],"isError":false,"meta":{"viewport":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> ","waitReason":"stdin_read","sessionStatus":{"kind":"running"},"truncated":false}},"sourceEventSeqs":[21],"surfaceOp":"append"}
+{"type":"tool/result","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","content":[{"type":"text","text":"K\ndsh> \n[wait: stdin_read]\n[session: running]\n[output truncated]"}],"isError":false,"meta":{"viewport":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> ","waitReason":"stdin_read","sessionStatus":{"kind":"running"},"truncated":false}},"sourceEventSeqs":[21],"surfaceOp":"append"}
 {"type":"step/end","seq":23,"time":0,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":24,"time":0,"data":{"turn":1,"step":3}}
 {"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
diff --git a/examples/acp-agent/tests/snapshots/pty-tools/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/pty-tools/stdout.expected.jsonl
index 0158e55d12..b6ff0e64a1 100644
--- a/examples/acp-agent/tests/snapshots/pty-tools/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/pty-tools/stdout.expected.jsonl
@@ -1,11 +1,11 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-pro\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Exercise the six PTY tools","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"pty-spawn","title":"Open terminal main","kind":"execute","status":"in_progress"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"pty-spawn","status":"completed","content":[{"type":"content","content":{"type":"text","text":"started terminal session pty-1 (main) [type: shell]\ndsh> "}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"pty-send","title":"printf 'PTY_OK\\n'","kind":"execute","status":"in_progress","rawInput":"printf 'PTY_OK\\n'","content":[{"type":"content","content":{"type":"text","text":"Terminal pty-1"}},{"type":"terminal","terminalId":"pty-send"}],"_meta":{"terminal_info":{"terminal_id":"pty-send","cwd":"{{cwd}}"}}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"pty-send","status":"completed","_meta":{"terminal_output":{"terminal_id":"pty-send","data":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> \n[wait: stdin_read]\n[session: running]"}}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"pty-send","status":"completed","_meta":{"terminal_output":{"terminal_id":"pty-send","data":"K\ndsh> \n[wait: stdin_read]\n[session: running]\n[output truncated]"}}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"pty-read","title":"Read terminal pty-1","kind":"read","status":"in_progress","rawInput":{"sessionId":"pty-1","offset":0,"count":20}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"pty-read","status":"completed","content":[{"type":"content","content":{"type":"text","text":"dsh> printf 'PTY_OK\\n'\nPTY_OK\ndsh> \n[lines: 0-3 of 3]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"pty-signal","title":"Signal terminal pty-missing","kind":"execute","status":"in_progress","rawInput":{"sessionId":"pty-missing","signal":"SIGINT"}}}}
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 d466996ed1..529b1419da 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
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -494,6 +496,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -568,7 +571,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -579,6 +582,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -597,6 +601,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -628,7 +633,8 @@
           },
           "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\": [...]})."
+            "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": [
diff --git a/examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl b/examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl
index a277f2e997..1f7345dc80 100644
--- a/examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl
@@ -35,7 +35,7 @@
 {"type":"tool/call","seq":33,"time":0,"data":{"turn":1,"step":3,"callId":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
 {"type":"todo/write","seq":34,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
 {"type":"tool/result","seq":35,"time":0,"data":{"turn":1,"step":3,"callId":"call_3","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[33],"surfaceOp":"append"}
-{"type":"context/message","seq":36,"time":0,"data":{"content":[{"type":"text","text":"You are repeating the exact same tool call with identical arguments. Carefully analyze the previous result before calling again: if the task is not complete, try a different approach or different arguments instead of repeating the call."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"}
+{"type":"user/message","seq":36,"time":0,"data":{"content":[{"type":"text","text":"You are repeating the exact same tool call with identical arguments. Carefully analyze the previous result before calling again: if the task is not complete, try a different approach or different arguments instead of repeating the call."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"}
 {"type":"step/end","seq":37,"time":0,"data":{"turn":1,"step":3}}
 {"type":"step/start","seq":38,"time":0,"data":{"turn":1,"step":4}}
 {"type":"assistant/chunk","seq":39,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
@@ -58,7 +58,7 @@
 {"type":"tool/call","seq":56,"time":0,"data":{"turn":1,"step":5,"callId":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
 {"type":"todo/write","seq":57,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
 {"type":"tool/result","seq":58,"time":0,"data":{"turn":1,"step":5,"callId":"call_5","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[56],"surfaceOp":"append"}
-{"type":"context/message","seq":59,"time":0,"data":{"content":[{"type":"text","text":"Repeated tool call detected:\n- tool: todo_write\n- consecutive_calls: 5\n- arguments: {\"todos\":[{\"content\":\"watch the kettle boil\",\"status\":\"in_progress\"}]}\nThe repeated calls are not making progress. Do not call this tool with these exact arguments again. Inspect the latest result and choose a different action, different arguments, or finish the task if enough evidence has been gathered."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"}
+{"type":"user/message","seq":59,"time":0,"data":{"content":[{"type":"text","text":"Repeated tool call detected:\n- tool: todo_write\n- consecutive_calls: 5\n- arguments: {\"todos\":[{\"content\":\"watch the kettle boil\",\"status\":\"in_progress\"}]}\nThe repeated calls are not making progress. Do not call this tool with these exact arguments again. Inspect the latest result and choose a different action, different arguments, or finish the task if enough evidence has been gathered."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"}
 {"type":"step/end","seq":60,"time":0,"data":{"turn":1,"step":5}}
 {"type":"step/start","seq":61,"time":0,"data":{"turn":1,"step":6}}
 {"type":"assistant/chunk","seq":62,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
diff --git a/examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.expected.jsonl
index a9ed1f9e72..e2bc1c699a 100644
--- a/examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Write the todo list 'watch","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_1","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
diff --git a/examples/acp-agent/tests/snapshots/session-sandbox-root/session.jsonl b/examples/acp-agent/tests/snapshots/session-sandbox-root/session.jsonl
index 1abfd3ba7d..e92adbafb9 100644
--- a/examples/acp-agent/tests/snapshots/session-sandbox-root/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/session-sandbox-root/session.jsonl
@@ -14,7 +14,7 @@
 {"type":"assistant/chunk","seq":12,"time":1784567324143,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":13,"time":1784567324144,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_session_root","name":"write","arguments":"{\"file_path\":\"session-root.txt\",\"content\":\"session root\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}
 {"type":"tool/call","seq":14,"time":1784567324145,"data":{"turn":1,"step":1,"callId":"call_session_root","name":"write","arguments":"{\"file_path\":\"session-root.txt\",\"content\":\"session root\"}"}}
-{"type":"tool/result","seq":15,"time":1784567324155,"data":{"turn":1,"step":1,"callId":"call_session_root","content":[{"type":"text","text":"<path>/Users/cty/acp-snap-cwd-MABAjO/session-root.txt</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"tool/result","seq":15,"time":1784567324155,"data":{"turn":1,"step":1,"callId":"call_session_root","content":[{"type":"text","text":"<path>/Users/cty/acp-snap-cwd-MABAjO/session-root.txt</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false,"meta":{"diffs":[]}},"sourceEventSeqs":[14],"surfaceOp":"append"}
 {"type":"step/end","seq":16,"time":1784567324157,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":17,"time":1784567324157,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":18,"time":1784567324157,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
diff --git a/examples/acp-agent/tests/snapshots/session-sandbox-root/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/session-sandbox-root/stdout.expected.jsonl
index cd845049a6..6ba40a0980 100644
--- a/examples/acp-agent/tests/snapshots/session-sandbox-root/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/session-sandbox-root/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","id":3,"result":{"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"workspace-write","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the write tool (NOT","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_session_root","title":"Write session-root.txt","kind":"edit","status":"in_progress","locations":[{"path":"session-root.txt"}],"content":[{"type":"diff","path":"session-root.txt","oldText":null,"newText":"session root"}]}}}
diff --git a/examples/acp-agent/tests/snapshots/skill-load/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/skill-load/stdout.expected.jsonl
index 44e245ef46..3f6f1dd3fe 100644
--- a/examples/acp-agent/tests/snapshots/skill-load/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/skill-load/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Load the snapshot-skill skill with","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Load the requested skill."}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_skill_load","title":"Load skill snapshot-skill","kind":"read","status":"in_progress","rawInput":"snapshot-skill"}}}
diff --git a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json
index 61d317e2f8..b01e7683d1 100644
--- a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -365,6 +367,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -439,7 +442,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -450,6 +453,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -468,6 +472,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -499,7 +504,8 @@
           },
           "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\": [...]})."
+            "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": [
diff --git a/examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/stdout.expected.jsonl
index 3483f9490b..4e9be47961 100644
--- a/examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Delegate through two child generations.","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_root_child","title":"subagent","kind":"other","status":"in_progress","rawInput":{"description":"Start depth one","prompt":"Call subagent once. Ask that child to attempt one further subagent call, then report the result."}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_root_child","status":"completed","content":[{"type":"content","content":{"type":"text","text":"DEPTH_ONE_DONE"}}]}}}
diff --git a/examples/acp-agent/tests/snapshots/subagent-fork/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/subagent-fork/stdout.expected.jsonl
index d1184f6b12..931b77892e 100644
--- a/examples/acp-agent/tests/snapshots/subagent-fork/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/subagent-fork/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Remember this fact for later:","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/subagent-mixed/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/subagent-mixed/stdout.expected.jsonl
index 571f65d806..24eb9856a0 100644
--- a/examples/acp-agent/tests/snapshots/subagent-mixed/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/subagent-mixed/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Remember this fact for later:","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/subagent-multi/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/subagent-multi/stdout.expected.jsonl
index fa42c3b416..9693ed051a 100644
--- a/examples/acp-agent/tests/snapshots/subagent-multi/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/subagent-multi/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the subagent tool TWICE,","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/subagent-spawn/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/subagent-spawn/stdout.expected.jsonl
index 57176c4439..37af99ca19 100644
--- a/examples/acp-agent/tests/snapshots/subagent-spawn/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/subagent-spawn/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the subagent tool exactly","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/text-turn/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/text-turn/stdout.expected.jsonl
index e83383eec3..6bbcf7d91d 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/text-turn/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Reply with exactly the word:","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
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 61d317e2f8..b01e7683d1 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
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -365,6 +367,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -439,7 +442,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -450,6 +453,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -468,6 +472,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -499,7 +504,8 @@
           },
           "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\": [...]})."
+            "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": [
diff --git a/examples/acp-agent/tests/snapshots/todo-plan/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/todo-plan/stdout.expected.jsonl
index 73589a0aae..d699c3de1c 100644
--- a/examples/acp-agent/tests/snapshots/todo-plan/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/todo-plan/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the todo_write tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/tool-call-turn/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/tool-call-turn/stdout.expected.jsonl
index f730b1a24e..a72dbc43ed 100644
--- a/examples/acp-agent/tests/snapshots/tool-call-turn/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/tool-call-turn/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the bash tool to","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/workflow-run/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/workflow-run/stdout.expected.jsonl
index 05f86e858a..aa0cac2140 100644
--- a/examples/acp-agent/tests/snapshots/workflow-run/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/workflow-run/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Use the workflow tool exactly","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl b/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
index 8293ea3abf..883e685a6d 100644
--- a/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
@@ -12,7 +12,7 @@
 {"type":"assistant/message","seq":10,"time":1783778297070,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}
 {"type":"tool/call","seq":11,"time":1783778297070,"data":{"turn":1,"step":1,"callId":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}}
 {"type":"tool/result","seq":12,"time":1783778297072,"data":{"turn":1,"step":1,"callId":"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},"sourceEventSeqs":[11],"surfaceOp":"append"}
-{"type":"context/message","seq":13,"time":1783778297072,"data":{"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\nNested snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"plugin","plugin":"workspace-context"},"meta":{"kind":"workspace-instructions","version":1,"changes":[{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"c446df9a85c7e73a3055f394a4822a19ac9ead5a"}]}},"surfaceOp":"append"}
+{"type":"user/message","seq":13,"time":1783778297072,"data":{"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\nNested snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"plugin","plugin":"workspace-context"},"meta":{"kind":"workspace-instructions","version":1,"changes":[{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"c446df9a85c7e73a3055f394a4822a19ac9ead5a"}]}},"surfaceOp":"append"}
 {"type":"step/end","seq":14,"time":1783778297072,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":15,"time":1783778297072,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":16,"time":1783778297073,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
diff --git a/examples/acp-agent/tests/snapshots/workspace-context/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/workspace-context/stdout.expected.jsonl
index 39d2d8c5b0..b19fa5bbac 100644
--- a/examples/acp-agent/tests/snapshots/workspace-context/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-context/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"Read nested/task.txt with the read","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_workspace_read","title":"Read nested/task.txt","kind":"read","status":"in_progress","locations":[{"path":"nested/task.txt","line":1}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_workspace_read","status":"completed","content":[{"type":"content","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>"}}]}}}
diff --git a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json
index 61d317e2f8..b01e7683d1 100644
--- a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json
@@ -11,6 +11,7 @@
             "description": "Questions to ask the user before continuing.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "id": {
                   "type": "string",
@@ -29,6 +30,7 @@
                   "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",
@@ -365,6 +367,7 @@
             "description": "The COMPLETE task list, replacing any previous list.",
             "items": {
               "type": "object",
+              "additionalProperties": true,
               "properties": {
                 "content": {
                   "type": "string",
@@ -439,7 +442,7 @@
     },
     {
       "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 — no oneOf/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.",
+      "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": {
@@ -450,6 +453,7 @@
           "meta": {
             "type": "object",
             "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
             "properties": {
               "name": {
                 "type": "string",
@@ -468,6 +472,7 @@
                 "description": "Optional phase declarations matched by phase() calls.",
                 "items": {
                   "type": "object",
+                  "additionalProperties": true,
                   "properties": {
                     "title": {
                       "type": "string",
@@ -499,7 +504,8 @@
           },
           "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\": [...]})."
+            "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": [
diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.jsonl
index a5deb50252..1b2c49322e 100644
--- a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"sessionCapabilities":{"list":{}},"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"A file named greeting.txt in","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
index 50c4c4209e..97f673b81f 100644
--- a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
@@ -1,6 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","modes":{"availableModes":[{"id":"default","name":"default"},{"id":"plan","name":"plan"}],"currentModeId":"default"},"configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter plan mode","input":{"hint":"[message]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}},{"name":"plan","description":"Enter or leave plan mode","input":{"hint":"[off|message]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"A file named greeting.txt in","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
diff --git a/examples/cordis-agent/cordis.yml b/examples/cordis-agent/cordis.yml
index 5947e42456..6144d3ae4d 100644
--- a/examples/cordis-agent/cordis.yml
+++ b/examples/cordis-agent/cordis.yml
@@ -7,7 +7,7 @@
 # such as `ctx.bash`. Grant this toolset like bash access. See
 # ../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
 
-# Hot-module reload for the dev/demo loop (needs `node --expose-internals`).
+# Development-only hot reload; production assemblies omit it.
 - id: hmr
   name: '@cordisjs/plugin-hmr'
   config:
@@ -56,7 +56,7 @@
   config:
     provider: deepseek
     model: deepseek-v4-pro
-    resumeSessionId: !!js process.env.RESUME_SESSION_ID
+    resumeSessionId: !!js "typeof resumeSessionId === 'string' ? resumeSessionId : undefined"
     persistenceRoot: './.sessions'
     workspaceContext:
       maxBytes: 65536
diff --git a/examples/cordis-agent/tests/cordis-tools.e2e.ts b/examples/cordis-agent/tests/cordis-tools.e2e.ts
index ae3651fdaf..b5f8e27564 100644
--- a/examples/cordis-agent/tests/cordis-tools.e2e.ts
+++ b/examples/cordis-agent/tests/cordis-tools.e2e.ts
@@ -42,7 +42,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('cordis tools: a real model modif
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
     const agent = ctx.agentLoop.create(SessionId('cordis-e2e-listener'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{
+    agent.followup([{
       type: 'text',
       text: 'Use cordis_mount to mount a plugin that listens to the \'agent/status\' '
         + 'cordis event and logs every change with console.log. Reply "mounted" once done.',
@@ -58,7 +58,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('cordis tools: a real model modif
     })
     expect(resultText(mid)).toContain('dyn-')
 
-    agent.send([{ type: 'text', text: 'Now unmount the plugin you just mounted.' }])
+    agent.followup([{ type: 'text', text: 'Now unmount the plugin you just mounted.' }])
     await waitForIdle(ctx, agent)
 
     const after = await ctx.tools.execute({
@@ -72,7 +72,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('cordis tools: a real model modif
     ctx = await cordisHarness()
     const agent = ctx.agentLoop.create(SessionId('cordis-e2e-selftool'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{
+    agent.followup([{
       type: 'text',
       text: 'Give yourself a new tool: use cordis_mount to mount a plugin with '
         + 'inject ["tools"] that calls harness.registerTool(ctx, harness.defineTool({...})) '
@@ -119,7 +119,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('cordis tools: a real model modif
     ctx = await cordisHarness()
     const agent = ctx.agentLoop.create(SessionId('cordis-e2e-compose'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{
+    agent.followup([{
       type: 'text',
       text: 'Mount TWO separate plugins with cordis_mount. First a provider: apply calls '
         + 'ctx.provide(\'shouter\', { shout: (s) => s.toUpperCase() }). Second a consumer with '
@@ -144,7 +144,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('cordis tools: a real model modif
       .flatMap(event => event.data.content.filter(block => block.type === 'text').map(block => block.text))
     expect(shoutResults.some(text => text.includes('QUIET'))).toBe(true)
 
-    agent.send([{ type: 'text', text: 'Now unmount ONLY the provider plugin (the one that provided shouter).' }])
+    agent.followup([{ type: 'text', text: 'Now unmount ONLY the provider plugin (the one that provided shouter).' }])
     await waitForIdle(ctx, agent)
 
     // The consumer must have been parked by cordis itself: service gone,
diff --git a/examples/headless-agent/pty.cordis.snapshot.yml b/examples/headless-agent/pty.cordis.snapshot.yml
index f7fcea389a..0de292a8f9 100644
--- a/examples/headless-agent/pty.cordis.snapshot.yml
+++ b/examples/headless-agent/pty.cordis.snapshot.yml
@@ -14,5 +14,7 @@
             name: '../acp-agent/pty-snapshot-backend.mjs'
           - id: tool-pty
             name: '@deepseek-ai/dsh-tool-pty'
+            config:
+              maxResultBytes: 64
           - id: llm-replay
             name: '@deepseek-ai/dsh-llm-replay'
diff --git a/examples/headless-agent/tests/code-mode.e2e.ts b/examples/headless-agent/tests/code-mode.e2e.ts
index c7f5d48562..86c1559b83 100644
--- a/examples/headless-agent/tests/code-mode.e2e.ts
+++ b/examples/headless-agent/tests/code-mode.e2e.ts
@@ -3,11 +3,12 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import LlmService from '@deepseek-ai/dsh-llm'
+import LlmService, { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { RUN_CODE_NAME } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { RUN_CODE_NAME, defineTool } from '@deepseek-ai/dsh-tools'
+import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -18,6 +19,9 @@ import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as WorkspaceContext from '@deepseek-ai/dsh-workspace-context'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
+import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 
 /**
  * With-key Code Mode proof: a real model receives only `run_code`, composes two
@@ -73,6 +77,223 @@ async function workspaceCodeModeHarness(): Promise<Context> {
   return harness
 }
 
+let keylessCall = 0
+const testToolSignal = new AbortController().signal
+
+/** Execute one outer Code Mode call through the real registry and worker. */
+function runCode(harness: Context, code: string, signal: AbortSignal = testToolSignal): Promise<ToolExecutionResult> {
+  return harness.tools.execute({
+    callId: CallId(`keyless-code-${++keylessCall}`),
+    name: RUN_CODE_NAME,
+    arguments: { code },
+    signal,
+  })
+}
+
+/** Read the optional completion from a successful canonical `run_code` value. */
+function completion(result: ToolExecutionResult): unknown {
+  if (result.isError) {
+    throw new Error(result.content.filter(block => block.type === 'text').map(block => block.text).join('\n'))
+  }
+  const value = result.value
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('invalid run_code result')
+  return value.result
+}
+
+/** Keyless real-worker harness for direct typed-binding acceptance tests. */
+async function typedCodeModeHarness(): Promise<Context> {
+  const harness = new Context()
+  await harness.plugin(SystemPrompt)
+  await harness.plugin(ToolRegistry, { mode: 'code' })
+  await harness.plugin(WorkerCodeRuntime, {})
+  return harness
+}
+
+/** Keyless real-worker harness with the task-owned bash lifecycle. */
+async function backgroundCodeModeHarness(cwd: string): Promise<Context> {
+  const harness = await typedCodeModeHarness()
+  await harness.plugin(TaskService)
+  await harness.plugin(ToolTasks, {})
+  await harness.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
+  await harness.plugin(ToolBash)
+  return harness
+}
+
+describe('Code Mode typed values: keyless real-worker contracts', () => {
+  it('crosses a large intermediate value intact and exposes only typed tool failure fields', async () => {
+    ctx = await typedCodeModeHarness()
+    ctx.tools.register(defineTool({
+      name: 'large_value',
+      description: 'Return a large canonical string.',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
+      execute: () => Promise.resolve('x'.repeat(100_000)),
+    }))
+    ctx.tools.register(defineTool({
+      name: 'always_fail',
+      description: 'Fail for ToolCallError coverage.',
+      parameters: {},
+      output: { schema: { type: 'null' }, render: () => [] },
+      execute: () => Promise.reject(new HarnessError('expected failure', 'EXPECTED_INTERNAL_CODE')),
+    }))
+
+    const value = completion(await runCode(ctx, `
+      const large = await tools.large_value({});
+      let failure;
+      try {
+        await tools.always_fail({});
+      } catch (error) {
+        failure = {
+          typed: error instanceof ToolCallError,
+          name: error.name,
+          toolName: error.toolName,
+          message: error.message,
+          exposesCode: 'code' in error,
+          exposesContent: 'content' in error,
+          exposesInfo: 'info' in error,
+        };
+      }
+      return { length: large.length, failure };
+    `))
+
+    expect(value).toEqual({
+      length: 100_000,
+      failure: {
+        typed: true,
+        name: 'ToolCallError',
+        toolName: 'always_fail',
+        message: 'expected failure',
+        exposesCode: false,
+        exposesContent: false,
+        exposesInfo: false,
+      },
+    })
+  })
+
+  it('returns a background task id, settles the outer run, and polls that id to completion', async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'dsh-code-mode-background-'))
+    ctx = await backgroundCodeModeHarness(workdir)
+
+    const taskId = completion(await runCode(ctx, `
+      const started = await tools.bash({
+        command: "sleep 0.2; printf 'background-complete\\n'",
+        description: 'Run completion marker in background',
+        run_in_background: true,
+      });
+      return started.taskId;
+    `))
+    expect(taskId).toBe('bash-1')
+
+    const polled = completion(await runCode(ctx, `
+      return await tools.task_output({ task_id: ${JSON.stringify(taskId)}, wait: true, timeout_ms: 5000 });
+    `))
+    if (typeof polled !== 'object' || polled === null || Array.isArray(polled)) throw new Error('invalid task_output completion')
+    const taskOutput = polled as Record<string, unknown>
+    expect(taskOutput.text).toContain('background-complete')
+    expect(taskOutput.task).toMatchObject({ id: taskId, kind: 'bash', status: 'completed' })
+  }, 15_000)
+
+  it('pre-abort spawns nothing; post-publication abort leaves task_kill as the cancellation owner', async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'dsh-code-mode-task-cancel-'))
+    ctx = await backgroundCodeModeHarness(workdir)
+
+    const pre = new AbortController()
+    pre.abort('pre-aborted')
+    const preResult = await runCode(ctx, `
+      return await tools.bash({ command: 'sleep 10', description: 'Must never start', run_in_background: true });
+    `, pre.signal)
+    expect(preResult.isError).toBe(true)
+    expect(ctx.tasks.list()).toEqual([])
+
+    const afterPublication = new AbortController()
+    const running = runCode(ctx, `
+      const started = await tools.bash({ command: 'sleep 10', description: 'Wait for explicit task kill', run_in_background: true });
+      console.log(started.taskId);
+      await new Promise(() => {});
+    `, afterPublication.signal)
+    for (let attempt = 0; attempt < 100 && ctx.tasks.list().length === 0; attempt++) {
+      await new Promise(resolve => setTimeout(resolve, 10))
+    }
+    const task = ctx.tasks.list()[0]
+    expect(task).toMatchObject({ id: 'bash-1', status: 'running' })
+    afterPublication.abort('outer-call-cancelled')
+    expect((await running).isError).toBe(true)
+    expect(ctx.tasks.list()[0]).toMatchObject({ id: task!.id, status: 'running' })
+
+    const killed = completion(await runCode(ctx, `
+      return await tools.task_kill({ task_id: ${JSON.stringify(task!.id)}, reason: 'test owns cancellation' });
+    `))
+    expect(killed).toMatchObject({ outcome: 'cancellation-requested', task: { id: task!.id } })
+    const settled = completion(await runCode(ctx, `
+      return await tools.task_output({ task_id: ${JSON.stringify(task!.id)}, wait: true, timeout_ms: 5000 });
+    `))
+    expect(settled).toMatchObject({ task: { id: task!.id, status: 'killed' } })
+  }, 15_000)
+
+  it('keeps foreground bash coupled to the outer signal', async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'dsh-code-mode-foreground-cancel-'))
+    ctx = await backgroundCodeModeHarness(workdir)
+    const controller = new AbortController()
+    const startedAt = Date.now()
+    const pending = runCode(ctx, `
+      return await tools.bash({ command: 'sleep 10', description: 'Run cancellable foreground command' });
+    `, controller.signal)
+    setTimeout(() => { controller.abort('stop-foreground') }, 200)
+    const result = await pending
+    expect(result.isError).toBe(true)
+    expect(Date.now() - startedAt).toBeLessThan(5_000)
+    expect(ctx.tasks.list()).toEqual([])
+  }, 15_000)
+
+  it('uses cordis_mount DTO ids directly for active and pending mounts, then confirms removal', async () => {
+    ctx = await typedCodeModeHarness()
+    await ctx.plugin(ToolCordis)
+
+    const value = completion(await runCode(ctx, `
+      const active = await tools.cordis_mount({
+        code: "return { name: 'active-code-mode-plugin', apply(ctx) {} }",
+      });
+      const pending = await tools.cordis_mount({
+        code: "return { name: 'pending-code-mode-plugin', inject: ['missing-code-mode-service'], apply(ctx) {} }",
+      });
+      const before = await tools.cordis_inspect({ what: 'dynamic' });
+      const unmounted = await tools.cordis_unmount({ id: active.id });
+      const after = await tools.cordis_inspect({ what: 'dynamic' });
+      await tools.cordis_unmount({ id: pending.id });
+      return {
+        active,
+        pending,
+        unmounted,
+        beforeContainsId: before.includes(active.id),
+        afterContainsId: after.includes(active.id),
+      };
+    `))
+
+    expect(value).toEqual({
+      active: {
+        id: 'dyn-1',
+        pluginName: 'active-code-mode-plugin',
+        state: 'active',
+        provides: [],
+        waitingFor: [],
+      },
+      pending: {
+        id: 'dyn-2',
+        pluginName: 'pending-code-mode-plugin',
+        state: 'pending',
+        provides: [],
+        waitingFor: ['missing-code-mode-service'],
+      },
+      unmounted: { id: 'dyn-1', pluginName: 'active-code-mode-plugin' },
+      beforeContainsId: true,
+      afterContainsId: false,
+    })
+  })
+})
+
 function waitForIdle(harness: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = harness.on('agent/status', (subject, status) => {
@@ -90,7 +311,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('Code Mode: real model writes a p
     ctx = await codeModeHarness(workdir)
     const agent = ctx.agentLoop.create(SessionId('e2e-code-mode'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{
+    agent.followup([{
       type: 'text',
       text: 'Using one run_code program: run `echo alpha-7` with the bash tool, run `echo beta-9` with the bash tool, '
         + 'then write both outputs joined by a plus sign into combined.txt (bash heredoc or redirect), '
@@ -142,7 +363,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('Code Mode: real model writes a p
       agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
     })
 
-    handle.agent.send([{
+    handle.agent.followup([{
       type: 'text',
       text: 'Use one run_code program to call tools.read on pkg/deep/task.txt. After it finishes, answer: Code Mode workspace handshake?',
     }])
@@ -151,7 +372,8 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('Code Mode: real model writes a p
     const events: SessionEvent[] = [...handle.agent.session.events]
     const dispatch = events.find(event => event.type === 'tool/code-dispatch' && event.data.name === 'read')
     const outerResult = events.find(event => event.type === 'tool/result')
-    const workspaceContext = events.find(event => event.type === 'context/message'
+    const workspaceContext = events.find(event => event.type === 'user/message'
+      && event.data.source.kind === 'plugin'
       && typeof event.data.meta === 'object'
       && event.data.meta !== null
       && !Array.isArray(event.data.meta)
diff --git a/examples/headless-agent/tests/coding-task.e2e.ts b/examples/headless-agent/tests/coding-task.e2e.ts
index a5f525e5c3..4a827858bb 100644
--- a/examples/headless-agent/tests/coding-task.e2e.ts
+++ b/examples/headless-agent/tests/coding-task.e2e.ts
@@ -56,7 +56,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('coding task: fix a failing test
     ctx = await codingHarness(workdir, { persona: SYSTEM_PROMPT })
     const agent = ctx.agentLoop.create(SessionId('e2e-task'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{
+    agent.followup([{
       type: 'text',
       text: 'In the current directory, `node add.test.js` fails because add.js has a bug. '
         + 'Fix add.js so the test passes, run `node add.test.js` to verify, and report the result. '
diff --git a/examples/headless-agent/tests/compaction.e2e.ts b/examples/headless-agent/tests/compaction.e2e.ts
index fcebddb863..a96b7f3611 100644
--- a/examples/headless-agent/tests/compaction.e2e.ts
+++ b/examples/headless-agent/tests/compaction.e2e.ts
@@ -46,7 +46,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
     })
     const agent = ctx.agentLoop.create(SessionId('e2e-compaction'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{
+    agent.followup([{
       type: 'text',
       text: 'Read file1.txt, file2.txt, file3.txt, and file4.txt one at a '
         + 'time using cat (a separate bash command for each). After reading all four, tell me how '
diff --git a/examples/headless-agent/tests/full-loop.e2e.ts b/examples/headless-agent/tests/full-loop.e2e.ts
index db2eec63fc..4f61ec3fa3 100644
--- a/examples/headless-agent/tests/full-loop.e2e.ts
+++ b/examples/headless-agent/tests/full-loop.e2e.ts
@@ -30,7 +30,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('full loop: real model + real bas
     ctx = await codingHarness(workdir, { persona: SYSTEM_PROMPT })
     const agent = ctx.agentLoop.create(SessionId('e2e-loop'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{ type: 'text', text: 'Run `echo e2e-ok` with the bash tool and tell me its exact output.' }])
+    agent.followup([{ type: 'text', text: 'Run `echo e2e-ok` with the bash tool and tell me its exact output.' }])
     await waitForIdle(ctx, agent)
 
     const events = [...agent.session.events]
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 1626489bf5..6852fed20b 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -222,9 +222,14 @@ describe('headless stream-json snapshots', () => {
         const records = parseJsonl(logs[0]?.content ?? '')
         const calls = records.filter(record => record.type === 'tool/call')
           .map(record => (record.data as JsonObject | undefined)?.name)
-        expect(calls).toEqual(['create_goal', 'get_goal'])
+        expect(calls).toEqual(['update_goal', 'create_goal', 'get_goal'])
+        const probeResult = records.find(record => record.type === 'tool/result'
+          && (record.data as JsonObject | undefined)?.callId === 'call_goal_probe')
+        const probeData = probeResult?.data as JsonObject | undefined
+        expect(probeData?.isError).toBe(true)
+        expect((probeData?.error as JsonObject | undefined)?.code).toBe('GOAL_NOT_FOUND')
         const goalChanges = records.filter((record) => {
-          if (record.type !== 'context/message') return false
+          if (record.type !== 'user/message') return false
           const data = record.data as JsonObject | undefined
           const meta = data?.meta as JsonObject | undefined
           return meta?.kind === 'goal/change'
diff --git a/examples/headless-agent/tests/resume.e2e.ts b/examples/headless-agent/tests/resume.e2e.ts
index 01c7d52393..a4ded767da 100644
--- a/examples/headless-agent/tests/resume.e2e.ts
+++ b/examples/headless-agent/tests/resume.e2e.ts
@@ -41,7 +41,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('resume: continue a persisted ses
       sessionId: SESSION_ID,
       agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
     })).agent
-    first.send([{ type: 'text', text: `Remember this code for later: ${SECRET}. Just acknowledge it.` }])
+    first.followup([{ type: 'text', text: `Remember this code for later: ${SECRET}. Just acknowledge it.` }])
     await waitForIdle(ctx, first)
     await ctx.fiber.dispose()
     ctx = undefined
@@ -58,7 +58,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('resume: continue a persisted ses
     // The prior user turn is in the rehydrated log before the model is asked.
     expect(JSON.stringify(resumed.session.deriveMessages())).toContain(SECRET)
 
-    resumed.send([{ type: 'text', text: 'What was the code I asked you to remember? Reply with just the code.' }])
+    resumed.followup([{ type: 'text', text: 'What was the code I asked you to remember? Reply with just the code.' }])
     await waitForIdle(ctx, resumed)
 
     // The model recalls it — only possible from the resumed history.
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 76c0f56cbf..045b9bb736 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
@@ -3,7 +3,7 @@
 {"type":"user/message","seq":1,"time":1783957884563,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"}
 {"type":"session/title","seq":2,"time":1783957884563,"data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[1],"source":{"kind":"fallback"}}}
 {"type":"step/start","seq":3,"time":1783957884564,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":1783957884564,"data":{"header":{"config":{"provider":"deepseek","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 /tmp/advanced-headless.\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 text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\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\ndeclare const tools: {\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(args: {\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  }): Promise<string>;\n  /** Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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(args: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"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  }): Promise<string>;\n  /** Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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(args: {\n    /** Body of an async JS function; must `return` the plugin to mount. */\n    code: string;\n  }): Promise<string>;\n  /** Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). */\n  cordis_unmount(args: {\n    /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n    id: string;\n  }): Promise<string>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit(args: {\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  }): Promise<string>;\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(args: {\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  }): Promise<string>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read(args: {\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  }): Promise<string>;\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(args: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  }): Promise<string>;\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 return a task id; collect with `task_output` and stop with `task_kill`. */\n  subagent(args: {\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 task and return its id; collect with task_output or stop with task_kill. */\n    run_in_background?: boolean;\n  }): Promise<string>;\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 return a task id; collect with `task_output` and stop with `task_kill`. */\n  subagent_fork(args: {\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 task and return its id; collect with task_output or stop with task_kill. */\n    run_in_background?: boolean;\n  }): Promise<string>;\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(args: {\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  }): Promise<string>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list(args: Record<string, unknown>): Promise<string>;\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(args: {\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  }): Promise<string>;\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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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(args: {\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  }): Promise<string>;\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 — no oneOf/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(args: {\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      }[];\n    };\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, unknown>;\n  }): Promise<string>;\n  /** Create or fully replace a UTF-8 text file. */\n  write(args: {\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  }): Promise<string>;\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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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","dynamic","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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"name":"cordis_unmount","description":"Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop).","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"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."}},"required":["code"]}},{"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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","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 — no oneOf/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).","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","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\": [...]})."}},"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":4,"time":1783957884564,"data":{"header":{"config":{"provider":"deepseek","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 /tmp/advanced-headless.\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- Calls execute sequentially, even under `Promise.all`.\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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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\" | \"dynamic\" | \"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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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    /** Body of an async JS function; must `return` the plugin to mount. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). */\n  cordis_unmount: {\n    /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\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  /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */\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 task and return its id; collect with task_output or stop with task_kill. */\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 return a task id; collect with `task_output` and stop with `task_kill`. */\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 task and return its id; collect with task_output or stop with task_kill. */\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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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    } & Record<string, JsonValue>)[];\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  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: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: 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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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","dynamic","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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"name":"cordis_unmount","description":"Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop).","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"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."}},"required":["code"]}},{"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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":true,"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":"assistant/chunk","seq":5,"time":1783950001005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":6,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}}
 {"type":"assistant/chunk","seq":7,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","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 d094d80951..8193973bee 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
@@ -3,7 +3,7 @@
 {"type":"user/message","seq":1,"time":1783957884700,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"}
 {"type":"session/title","seq":2,"time":1783957884700,"data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[1],"source":{"kind":"fallback"}}}
 {"type":"step/start","seq":3,"time":1783957884700,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":1783957884701,"data":{"header":{"config":{"provider":"deepseek","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 /tmp/advanced-headless.\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 text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\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\ndeclare const tools: {\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(args: {\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  }): Promise<string>;\n  /** Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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(args: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"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  }): Promise<string>;\n  /** Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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(args: {\n    /** Body of an async JS function; must `return` the plugin to mount. */\n    code: string;\n  }): Promise<string>;\n  /** Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). */\n  cordis_unmount(args: {\n    /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n    id: string;\n  }): Promise<string>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit(args: {\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  }): Promise<string>;\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(args: {\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  }): Promise<string>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read(args: {\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  }): Promise<string>;\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(args: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  }): Promise<string>;\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 return a task id; collect with `task_output` and stop with `task_kill`. */\n  subagent(args: {\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 task and return its id; collect with task_output or stop with task_kill. */\n    run_in_background?: boolean;\n  }): Promise<string>;\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 return a task id; collect with `task_output` and stop with `task_kill`. */\n  subagent_fork(args: {\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 task and return its id; collect with task_output or stop with task_kill. */\n    run_in_background?: boolean;\n  }): Promise<string>;\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(args: {\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  }): Promise<string>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list(args: Record<string, unknown>): Promise<string>;\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(args: {\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  }): Promise<string>;\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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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(args: {\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  }): Promise<string>;\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 — no oneOf/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(args: {\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      }[];\n    };\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, unknown>;\n  }): Promise<string>;\n  /** Create or fully replace a UTF-8 text file. */\n  write(args: {\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  }): Promise<string>;\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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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","dynamic","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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"name":"cordis_unmount","description":"Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop).","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"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."}},"required":["code"]}},{"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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","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 — no oneOf/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).","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","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\": [...]})."}},"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":4,"time":1783957884701,"data":{"header":{"config":{"provider":"deepseek","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 /tmp/advanced-headless.\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- Calls execute sequentially, even under `Promise.all`.\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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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\" | \"dynamic\" | \"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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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    /** Body of an async JS function; must `return` the plugin to mount. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). */\n  cordis_unmount: {\n    /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\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  /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */\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 task and return its id; collect with task_output or stop with task_kill. */\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 return a task id; collect with `task_output` and stop with `task_kill`. */\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 task and return its id; collect with task_output or stop with task_kill. */\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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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    } & Record<string, JsonValue>)[];\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  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: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: 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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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","dynamic","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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"name":"cordis_unmount","description":"Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop).","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"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."}},"required":["code"]}},{"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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":true,"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":"assistant/chunk","seq":5,"time":1783950002005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":6,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}}
 {"type":"assistant/chunk","seq":7,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","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 309158c310..7f913ae905 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -3,7 +3,7 @@
 {"type":"user/message","seq":1,"time":1783957884479,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then reply with exactly ADVANCED_HEADLESS_OK."}],"source":{"kind":"user"}},"surfaceOp":"append"}
 {"type":"session/title","seq":2,"time":1783957884479,"data":{"title":"Run this advanced flow exactly","messageSeqs":[1],"source":{"kind":"fallback"}}}
 {"type":"step/start","seq":3,"time":1783957884486,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":1783957884486,"data":{"header":{"config":{"provider":"deepseek","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 /tmp/advanced-headless.\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 text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\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\ndeclare const tools: {\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(args: {\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  }): Promise<string>;\n  /** Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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(args: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"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  }): Promise<string>;\n  /** Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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(args: {\n    /** Body of an async JS function; must `return` the plugin to mount. */\n    code: string;\n  }): Promise<string>;\n  /** Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). */\n  cordis_unmount(args: {\n    /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n    id: string;\n  }): Promise<string>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit(args: {\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  }): Promise<string>;\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(args: {\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  }): Promise<string>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read(args: {\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  }): Promise<string>;\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(args: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  }): Promise<string>;\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 return a task id; collect with `task_output` and stop with `task_kill`. */\n  subagent(args: {\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 task and return its id; collect with task_output or stop with task_kill. */\n    run_in_background?: boolean;\n  }): Promise<string>;\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 return a task id; collect with `task_output` and stop with `task_kill`. */\n  subagent_fork(args: {\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 task and return its id; collect with task_output or stop with task_kill. */\n    run_in_background?: boolean;\n  }): Promise<string>;\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(args: {\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  }): Promise<string>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list(args: Record<string, unknown>): Promise<string>;\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(args: {\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  }): Promise<string>;\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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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(args: {\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  }): Promise<string>;\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 — no oneOf/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(args: {\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      }[];\n    };\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, unknown>;\n  }): Promise<string>;\n  /** Create or fully replace a UTF-8 text file. */\n  write(args: {\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  }): Promise<string>;\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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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","dynamic","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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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 } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts 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 on 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 on unmount) — 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":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"name":"cordis_unmount","description":"Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop).","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"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."}},"required":["code"]}},{"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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","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 — no oneOf/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).","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","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\": [...]})."}},"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":4,"time":1783957884486,"data":{"header":{"config":{"provider":"deepseek","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 /tmp/advanced-headless.\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- Calls execute sequentially, even under `Promise.all`.\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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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\" | \"dynamic\" | \"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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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    /** Body of an async JS function; must `return` the plugin to mount. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). */\n  cordis_unmount: {\n    /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\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  /** 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 return a task id; collect with `task_output` and stop with `task_kill`. */\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 task and return its id; collect with task_output or stop with task_kill. */\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 return a task id; collect with `task_output` and stop with `task_kill`. */\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 task and return its id; collect with task_output or stop with task_kill. */\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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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    } & Record<string, JsonValue>)[];\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  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: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: 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 that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `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). 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","dynamic","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 NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs 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. Mounts 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 on 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 on unmount) — 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":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"name":"cordis_unmount","description":"Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop).","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"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."}},"required":["code"]}},{"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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 return a task id; collect with `task_output` and stop with `task_kill`.","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 task and return its id; collect with task_output or stop with task_kill."}},"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. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active 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":true,"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":"assistant/chunk","seq":5,"time":1783950000005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":6,"time":1783950000006,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}
 {"type":"assistant/chunk","seq":7,"time":1783950000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}}
@@ -22,7 +22,7 @@
 {"type":"assistant/message","seq":20,"time":1783957884490,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}
 {"type":"tool/call","seq":21,"time":1783957884490,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}
 {"type":"tool/code-dispatch","seq":22,"time":1783957884560,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"dynamic"},"isError":false,"resultSummary":"## dynamic\n- dyn-1: snapshot-marker [active]"}}
-{"type":"tool/result","seq":23,"time":1783957884561,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[21],"surfaceOp":"append"}
+{"type":"tool/result","seq":23,"time":1783957884561,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false},"sourceEventSeqs":[21],"surfaceOp":"append"}
 {"type":"step/end","seq":24,"time":1783957884561,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":25,"time":1783957884562,"data":{"turn":1,"step":3}}
 {"type":"assistant/chunk","seq":26,"time":1783950000026,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
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 0f59fa79d9..0480fdf2ac 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
@@ -21,7 +21,7 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":20,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":21,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch","seq":22,"time":0,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"dynamic"},"isError":false,"resultSummary":"## dynamic\n- dyn-1: snapshot-marker [active]"}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":23,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[21],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":23,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false},"sourceEventSeqs":[21],"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":24,"time":0,"data":{"turn":1,"step":2}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":25,"time":0,"data":{"turn":1,"step":3}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
diff --git a/examples/headless-agent/tests/snapshots/goal-tools/input.json b/examples/headless-agent/tests/snapshots/goal-tools/input.json
index 5263ccd4e2..8449d44c4c 100644
--- a/examples/headless-agent/tests/snapshots/goal-tools/input.json
+++ b/examples/headless-agent/tests/snapshots/goal-tools/input.json
@@ -2,7 +2,7 @@
   "steps": [
     {
       "op": "prompt",
-      "text": "Create a durable goal to finish the snapshot proof, then inspect it."
+      "text": "Probe strict-schema fillers against missing-goal revision 1, then create a durable goal to finish the snapshot proof and inspect it."
     }
   ]
 }
diff --git a/examples/headless-agent/tests/snapshots/goal-tools/replay.override.json b/examples/headless-agent/tests/snapshots/goal-tools/replay.override.json
index aec5204c7d..c4716ba7b0 100644
--- a/examples/headless-agent/tests/snapshots/goal-tools/replay.override.json
+++ b/examples/headless-agent/tests/snapshots/goal-tools/replay.override.json
@@ -1,4 +1,14 @@
 [
+  {
+    "kind": "chunks",
+    "chunks": [
+      { "type": "block-start", "index": 0, "blockType": "tool-call" },
+      { "type": "tool-call-delta", "index": 0, "id": "call_goal_probe", "name": "update_goal", "argumentsDelta": "{\"goal_id\":\"missing-goal\",\"revision\":1,\"action\":\"pause\",\"objective\":\"\",\"max_goal_rounds\":0,\"blocked_reason\":\"\"}" },
+      { "type": "block-end", "index": 0, "block": { "type": "tool-call", "id": "call_goal_probe", "name": "update_goal", "arguments": "{\"goal_id\":\"missing-goal\",\"revision\":1,\"action\":\"pause\",\"objective\":\"\",\"max_goal_rounds\":0,\"blocked_reason\":\"\"}" } },
+      { "type": "usage", "usage": { "inputTokens": 15, "outputTokens": 6 } },
+      { "type": "finish", "reason": { "kind": "tool-calls" } }
+    ]
+  },
   {
     "kind": "chunks",
     "chunks": [
diff --git a/examples/headless-agent/tests/snapshots/goal-tools/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/goal-tools/stream-json.expected.jsonl
index 05a1282a6f..16518b2d03 100644
--- a/examples/headless-agent/tests/snapshots/goal-tools/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/goal-tools/stream-json.expected.jsonl
@@ -1,35 +1,45 @@
 {"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":"Create a durable goal to finish the snapshot proof, then inspect it."}],"source":{"kind":"user"}},"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"session/title","seq":2,"time":0,"data":{"title":"Create a durable goal to","messageSeqs":[1],"source":{"kind":"fallback"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Probe strict-schema fillers against missing-goal revision 1, then create a durable goal to finish the snapshot proof and inspect it."}],"source":{"kind":"user"}},"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"session/title","seq":2,"time":0,"data":{"title":"Probe strict-schema fillers against miss","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-flash"},"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":"tool-call"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_goal_create","name":"create_goal","argumentsDelta":"{\"objective\":\"Finish the headless goal-tool snapshot proof\",\"max_goal_rounds\":7}"}}}}
-{"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":"tool-call","id":"call_goal_create","name":"create_goal","arguments":"{\"objective\":\"Finish the headless goal-tool snapshot proof\",\"max_goal_rounds\":7}"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":20,"outputTokens":8}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_goal_probe","name":"update_goal","argumentsDelta":"{\"goal_id\":\"missing-goal\",\"revision\":1,\"action\":\"pause\",\"objective\":\"\",\"max_goal_rounds\":0,\"blocked_reason\":\"\"}"}}}}
+{"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":"tool-call","id":"call_goal_probe","name":"update_goal","arguments":"{\"goal_id\":\"missing-goal\",\"revision\":1,\"action\":\"pause\",\"objective\":\"\",\"max_goal_rounds\":0,\"blocked_reason\":\"\"}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":15,"outputTokens":6}}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_goal_create","name":"create_goal","arguments":"{\"objective\":\"Finish the headless goal-tool snapshot proof\",\"max_goal_rounds\":7}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":20,"outputTokens":8}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"call_goal_create","name":"create_goal","arguments":"{\"objective\":\"Finish the headless goal-tool snapshot proof\",\"max_goal_rounds\":7}"}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":12,"time":0,"data":{"turn":1,"step":1,"callId":"call_goal_create","content":[{"type":"text","text":"{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the headless goal-tool snapshot proof\",\"phase\":\"active\",\"roundsStarted\":0,\"maxGoalRounds\":7},\"activation\":\"armed\"}"}],"isError":false},"sourceEventSeqs":[11],"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"context/message","seq":13,"time":0,"data":{"content":[{"type":"text","text":"<goal_state>{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the headless goal-tool snapshot proof\",\"phase\":\"active\",\"maxGoalRounds\":7},\"roundsStarted\":0,\"createdAt\":0,\"updatedAt\":0}</goal_state>"}],"source":{"kind":"goal","goalId":"goal-{{sessionId}}","revision":1,"round":0},"meta":{"kind":"goal/change","version":1,"operation":"create","goal":{"id":"goal-{{sessionId}}","revision":1,"objective":"Finish the headless goal-tool snapshot proof","phase":"active","maxGoalRounds":7},"roundsStarted":0,"createdAt":0,"updatedAt":0}},"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":14,"time":0,"data":{"turn":1,"step":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":15,"time":0,"data":{"turn":1,"step":2}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_goal_get","name":"get_goal","argumentsDelta":"{}"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_goal_get","name":"get_goal","arguments":"{}"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":30,"outputTokens":4}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":20,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":21,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"call_goal_get","name":"get_goal","arguments":"{}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":30,"outputTokens":4}},"sourceEventSeqs":[16,17,18,19,20],"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"call_goal_get","name":"get_goal","arguments":"{}"}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":23,"time":0,"data":{"turn":1,"step":2,"callId":"call_goal_get","content":[{"type":"text","text":"{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the headless goal-tool snapshot proof\",\"phase\":\"active\",\"roundsStarted\":0,\"maxGoalRounds\":7},\"activation\":\"armed\"}"}],"isError":false},"sourceEventSeqs":[22],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_goal_probe","name":"update_goal","arguments":"{\"goal_id\":\"missing-goal\",\"revision\":1,\"action\":\"pause\",\"objective\":\"\",\"max_goal_rounds\":0,\"blocked_reason\":\"\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":15,"outputTokens":6}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"call_goal_probe","name":"update_goal","arguments":"{\"goal_id\":\"missing-goal\",\"revision\":1,\"action\":\"pause\",\"objective\":\"\",\"max_goal_rounds\":0,\"blocked_reason\":\"\"}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":12,"time":0,"data":{"turn":1,"step":1,"callId":"call_goal_probe","content":[{"type":"text","text":"Error: no current goal"}],"isError":true,"error":{"name":"GoalError","code":"GOAL_NOT_FOUND"}},"sourceEventSeqs":[11],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":13,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":14,"time":0,"data":{"turn":1,"step":2}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_goal_create","name":"create_goal","argumentsDelta":"{\"objective\":\"Finish the headless goal-tool snapshot proof\",\"max_goal_rounds\":7}"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_goal_create","name":"create_goal","arguments":"{\"objective\":\"Finish the headless goal-tool snapshot proof\",\"max_goal_rounds\":7}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":20,"outputTokens":8}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":20,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"call_goal_create","name":"create_goal","arguments":"{\"objective\":\"Finish the headless goal-tool snapshot proof\",\"max_goal_rounds\":7}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":20,"outputTokens":8}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":21,"time":0,"data":{"turn":1,"step":2,"callId":"call_goal_create","name":"create_goal","arguments":"{\"objective\":\"Finish the headless goal-tool snapshot proof\",\"max_goal_rounds\":7}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"call_goal_create","content":[{"type":"text","text":"{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the headless goal-tool snapshot proof\",\"phase\":\"active\",\"roundsStarted\":0,\"maxGoalRounds\":7},\"activation\":\"armed\"}"}],"isError":false},"sourceEventSeqs":[21],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":23,"time":0,"data":{"content":[{"type":"text","text":"<goal_state>{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the headless goal-tool snapshot proof\",\"phase\":\"active\",\"maxGoalRounds\":7},\"roundsStarted\":0,\"createdAt\":0,\"updatedAt\":0}</goal_state>"}],"source":{"kind":"goal","goalId":"goal-{{sessionId}}","revision":1,"round":0},"meta":{"kind":"goal/change","version":1,"operation":"create","goal":{"id":"goal-{{sessionId}}","revision":1,"objective":"Finish the headless goal-tool snapshot proof","phase":"active","maxGoalRounds":7},"roundsStarted":0,"createdAt":0,"updatedAt":0}},"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":24,"time":0,"data":{"turn":1,"step":2}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":25,"time":0,"data":{"turn":1,"step":3}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":27,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"text-delta","index":0,"text":"GOAL READY"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":28,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"GOAL READY"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":29,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":35,"outputTokens":2}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":30,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":31,"time":0,"data":{"turn":1,"step":3,"content":[{"type":"text","text":"GOAL READY"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":35,"outputTokens":2}},"sourceEventSeqs":[26,27,28,29,30],"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":32,"time":0,"data":{"turn":1,"step":3}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":33,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
-{"type":"result","success":true,"sessionId":"{{sessionId}}","turn":1,"result":"GOAL READY","reason":{"kind":"completed"},"usage":{"inputTokens":85,"outputTokens":14}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":27,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"call_goal_get","name":"get_goal","argumentsDelta":"{}"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":28,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_goal_get","name":"get_goal","arguments":"{}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":29,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":30,"outputTokens":4}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":30,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":31,"time":0,"data":{"turn":1,"step":3,"content":[{"type":"tool-call","id":"call_goal_get","name":"get_goal","arguments":"{}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":30,"outputTokens":4}},"sourceEventSeqs":[26,27,28,29,30],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":32,"time":0,"data":{"turn":1,"step":3,"callId":"call_goal_get","name":"get_goal","arguments":"{}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":33,"time":0,"data":{"turn":1,"step":3,"callId":"call_goal_get","content":[{"type":"text","text":"{\"goal\":{\"id\":\"goal-{{sessionId}}\",\"revision\":1,\"objective\":\"Finish the headless goal-tool snapshot proof\",\"phase\":\"active\",\"roundsStarted\":0,\"maxGoalRounds\":7},\"activation\":\"armed\"}"}],"isError":false},"sourceEventSeqs":[32],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":34,"time":0,"data":{"turn":1,"step":3}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":35,"time":0,"data":{"turn":1,"step":4}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":36,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":37,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"text-delta","index":0,"text":"GOAL READY"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":38,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"GOAL READY"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":39,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":35,"outputTokens":2}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":40,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":41,"time":0,"data":{"turn":1,"step":4,"content":[{"type":"text","text":"GOAL READY"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":35,"outputTokens":2}},"sourceEventSeqs":[36,37,38,39,40],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":42,"time":0,"data":{"turn":1,"step":4}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":43,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
+{"type":"result","success":true,"sessionId":"{{sessionId}}","turn":1,"result":"GOAL READY","reason":{"kind":"completed"},"usage":{"inputTokens":100,"outputTokens":20}}
diff --git a/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl b/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl
index bad2f0353d..d91782e1e2 100644
--- a/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl
@@ -21,7 +21,7 @@
 {"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":20,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"pty-send","name":"terminal_send","arguments":"{\"sessionId\":\"pty-1\",\"text\":\"printf 'PTY_OK\\\\n'\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}
 {"type":"tool/call","seq":21,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","name":"terminal_send","arguments":"{\"sessionId\":\"pty-1\",\"text\":\"printf 'PTY_OK\\\\n'\"}"}}
-{"type":"tool/result","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","content":[{"type":"text","text":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> \n[wait: stdin_read]\n[session: running]"}],"isError":false,"meta":{"viewport":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> ","waitReason":"stdin_read","sessionStatus":{"kind":"running"},"truncated":false}},"sourceEventSeqs":[21],"surfaceOp":"append"}
+{"type":"tool/result","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","content":[{"type":"text","text":"K\ndsh> \n[wait: stdin_read]\n[session: running]\n[output truncated]"}],"isError":false,"meta":{"viewport":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> ","waitReason":"stdin_read","sessionStatus":{"kind":"running"},"truncated":false}},"sourceEventSeqs":[21],"surfaceOp":"append"}
 {"type":"step/end","seq":23,"time":0,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":24,"time":0,"data":{"turn":1,"step":3}}
 {"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
diff --git a/examples/headless-agent/tests/snapshots/pty-tools/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/pty-tools/stream-json.expected.jsonl
index b4db490cb2..ab37662dde 100644
--- a/examples/headless-agent/tests/snapshots/pty-tools/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/pty-tools/stream-json.expected.jsonl
@@ -20,7 +20,7 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":20,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"pty-send","name":"terminal_send","arguments":"{\"sessionId\":\"pty-1\",\"text\":\"printf 'PTY_OK\\\\n'\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":21,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","name":"terminal_send","arguments":"{\"sessionId\":\"pty-1\",\"text\":\"printf 'PTY_OK\\\\n'\"}"}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","content":[{"type":"text","text":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> \n[wait: stdin_read]\n[session: running]"}],"isError":false,"meta":{"viewport":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> ","waitReason":"stdin_read","sessionStatus":{"kind":"running"},"truncated":false}},"sourceEventSeqs":[21],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"pty-send","content":[{"type":"text","text":"K\ndsh> \n[wait: stdin_read]\n[session: running]\n[output truncated]"}],"isError":false,"meta":{"viewport":"printf 'PTY_OK\\n'\nPTY_OK\ndsh> ","waitReason":"stdin_read","sessionStatus":{"kind":"running"},"truncated":false}},"sourceEventSeqs":[21],"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":23,"time":0,"data":{"turn":1,"step":2}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":24,"time":0,"data":{"turn":1,"step":3}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
diff --git a/examples/headless-agent/tests/todo-write.e2e.ts b/examples/headless-agent/tests/todo-write.e2e.ts
index daf5c018b1..c3053572d9 100644
--- a/examples/headless-agent/tests/todo-write.e2e.ts
+++ b/examples/headless-agent/tests/todo-write.e2e.ts
@@ -28,7 +28,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('todo_write: real model records a
     ctx = await codingHarness(workdir, { persona: TODO_SYSTEM_PROMPT })
     const agent = ctx.agentLoop.create(SessionId('e2e-todo'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{ type: 'text', text:
+    agent.followup([{ type: 'text', text:
       'Use the todo_write tool to record a plan of exactly two steps: first '
       + '"inspect the failing test" (in_progress), then "apply the fix" (pending). '
       + 'Send both in one todo_write call, then reply with the single word DONE.' }])
diff --git a/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts b/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts
index fb8ee81f64..cb2ab9687e 100644
--- a/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts
@@ -70,7 +70,6 @@ describe('jsonrpc-agent keyless smoke', () => {
     const address = modelServer.address()
     if (address === null || typeof address === 'string') throw new Error('model server did not bind a TCP port')
     const child = spawn(process.execPath, [
-      '--expose-internals',
       '--import',
       'tsx',
       binScript,
@@ -171,7 +170,6 @@ describe('jsonrpc-agent keyless smoke', () => {
 
   it('rejects an invalid max-token success env value', async () => {
     const child = spawn(process.execPath, [
-      '--expose-internals',
       '--import',
       'tsx',
       binScript,
diff --git a/examples/package.json b/examples/package.json
index db8cc142eb..bd87263340 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -26,6 +26,7 @@
     "@deepseek-ai/dsh-jsonrpc": "workspace:*",
     "@deepseek-ai/dsh-llm": "workspace:*",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:*",
+    "@deepseek-ai/dsh-llm-pi-ai": "workspace:*",
     "@deepseek-ai/dsh-llm-replay": "workspace:*",
     "@deepseek-ai/dsh-lsp": "workspace:*",
     "@deepseek-ai/dsh-lsp-local": "workspace:*",
@@ -38,6 +39,8 @@
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:*",
+    "@deepseek-ai/dsh-session-query": "workspace:*",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:*",
     "@deepseek-ai/dsh-spill-local": "workspace:*",
     "@deepseek-ai/dsh-spill-policy": "workspace:*",
     "@deepseek-ai/dsh-tui-demo": "workspace:*",
diff --git a/examples/tui-agent/README.md b/examples/tui-agent/README.md
index 0a26bb5a6b..2e87df0a27 100644
--- a/examples/tui-agent/README.md
+++ b/examples/tui-agent/README.md
@@ -17,7 +17,7 @@ Type a coding task. The agent works through the `read`/`write`/`edit` filesystem
 
 The `todo_write` task tracker is opt-in and not in the shipped config: add `@deepseek-ai/dsh-tool-todo` to `cordis.yml` (or a personal-config overlay under `~/.dsh`) to expose it. Once loaded, the model records a whole-list plan to the session log and the TUI renders it.
 
-The TUI renders Markdown history, reasoning, tool-owned terminal/diff/generic cards, token totals, and — when `todo_write` is loaded — the latest plan. Long tool bodies keep a head/tail preview; Ctrl+O expands or collapses every card. Enter submits or steers while the agent runs, Ctrl+R toggles reasoning, Escape cancels, and `/help` lists commands. `/plan` selects plan mode for the next step; `/plan <message>` also submits the message into that step. `/status` expands the current session's identity, activity counts, exact token/cache buckets, context use, and timestamps without interrupting a running turn. `/model` opens a keyboard selector for the current provider catalog; use Up/Down and Enter, or `/model <model>` and `/model <provider>/<model>` for direct selection. `ask_user_question` opens a wide bottom-left keyboard panel with batch progress and numbered options.
+The TUI renders Markdown history, reasoning, tool-owned terminal/diff/generic cards, token totals, and — when `todo_write` is loaded — the latest plan. Long tool bodies keep a head/tail preview; Ctrl+O expands or collapses every card. Enter submits or steers while the agent runs, Ctrl+R toggles reasoning, Escape cancels, and `/help` lists commands. `/plan` selects plan mode for the next step; `/plan <message>` also submits the message into that step, while `/plan off` selects the default mode without model input. `/status` expands the current session's identity, activity counts, exact token/cache buckets, context use, and timestamps without interrupting a running turn. `/model` opens a keyboard selector for the current provider catalog; use Up/Down and Enter, or `/model <model>` and `/model <provider>/<model>` for direct selection. `ask_user_question` opens a wide bottom-left keyboard panel with batch progress and numbered options.
 
 ### Resuming a prior session
 
@@ -27,7 +27,7 @@ Each run starts a fresh session by default (its event log lands under `./.sessio
 dsh --resume <prior-session-id>
 ```
 
-The TUI prints this exact command on exit and lists it under `/resume`, so resuming is copy-paste. The flag sets `RESUME_SESSION_ID`, wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); the env var still works directly for the uninstalled demo (`RESUME_SESSION_ID=<prior-session-id> pnpm run demo:tui`), and with neither set the agent starts a new session. A missing or unreadable id starts no agent and emits `agent-loop/config-start-failed`: the TUI prints the failure and exits nonzero.
+`/resume` opens a searchable keyboard selector with titles, activity, last-turn results, model route, durable goal phase, and live/persisted state. The installed `dsh` host flushes and disposes the current app, then replaces the process with `dsh --resume <id>`. The TUI still prints that command on exit and shows it when a custom host cannot hand off. The flag sets `RESUME_SESSION_ID`, wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); the env var still works directly for the uninstalled demo (`RESUME_SESSION_ID=<prior-session-id> pnpm run demo:tui`), and with neither set the agent starts a new session. A missing or unreadable id starts no agent and emits `agent-loop/config-start-failed`: the TUI prints the failure and exits nonzero. The selector has no cross-process session lock, so deployments with concurrent hosts must coordinate session ownership separately.
 
 ## Code Mode
 
@@ -50,14 +50,14 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
 
 | Entry | Demonstrates |
 |---|---|
-| `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:tui` passes |
+| `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it depends on the Loader's internal module access |
 | `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin |
 | `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash` schema (`tool-bash`) and generic `task_*` controls (`tool-tasks`) come from `dsh-agent-spine-demo`, so only the executor is a leaf choice |
 | `tui-agent` (`@deepseek-ai/dsh-tui-demo`) | the app bundle: the agent-spine demo + JSONL persistence + the pi-tui channel + a pre-created `main` agent |
 | `subagent`, `subagent-spawn`, `subagent-fork` | the subagent provider registry plus the two in-process backends: a fresh child and a child seeded with the parent's completed-turn prefix |
 | `tool-subagent`, `tool-subagent-fork` | two model-facing `dsh-tool-subagent` loads, each bound to a different provider and exposed under a distinct tool name (`subagent`, `subagent_fork`) |
 | `workflow-workerthread`, `tool-workflow` | the worker-thread workflow engine and its model-facing `workflow` tool, with child calls routed through the spawn backend |
-| `plan-mode` | the plugin-owned `/plan [message]` command, plan-mode prompt policy, tool restrictions, and reviewed `exit_plan_mode` transition |
+| `plan-mode` | the plugin-owned `/plan [message]` entry and `/plan off` exit commands, plan-mode prompt policy, tool restrictions, and reviewed `exit_plan_mode` transition |
 | `fs-local`, `fs-policy`, `tool-fs` | the filesystem stack: the local `ctx.fs` provider, the read-before-write/edit policy gate (on the `fs/*` event gate), and the model-facing `read`/`write`/`edit` tools. Relative paths resolve against the session workspace |
 
 ## End-to-end tests (`pnpm run test:e2e`)
diff --git a/examples/tui-agent/code-mode.cordis.yml b/examples/tui-agent/code-mode.cordis.yml
index 49dbe62645..46d982794c 100644
--- a/examples/tui-agent/code-mode.cordis.yml
+++ b/examples/tui-agent/code-mode.cordis.yml
@@ -10,7 +10,7 @@
         config:
           provider: deepseek
           model: deepseek-v4-pro
-          resumeSessionId: !!js process.env.RESUME_SESSION_ID
+          resumeSessionId: !!js "typeof resumeSessionId === 'string' ? resumeSessionId : undefined"
           persistenceRoot: './.sessions'
           resumeCommand: 'dsh --resume {session}'
           workspaceContext:
diff --git a/examples/tui-agent/cordis.yml b/examples/tui-agent/cordis.yml
index eeb44dc7fb..af225565e9 100644
--- a/examples/tui-agent/cordis.yml
+++ b/examples/tui-agent/cordis.yml
@@ -1,11 +1,10 @@
 # Full-screen TUI coding agent with swappable DeepSeek and local-bash backends.
 # `dsh-tui-demo` supplies the agent spine, workspace instructions, generic
 # task controls, JSONL persistence, the pi-tui front door, and `main`.
-# HMR remains a leaf because it requires Loader internals; `demo:tui` passes
-# `--expose-internals`. The app bin loads the gitignored root `.env`; this file
-# reads `DEEPSEEK_API_KEY` and optional `DEEPSEEK_BASE_URL` through `!!js`.
+# HMR remains a leaf because it depends on Loader internals. The app bin loads
+# the gitignored root `.env`; this file reads `DEEPSEEK_API_KEY` and optional
+# `DEEPSEEK_BASE_URL` through `!!js`.
 
-# Hot-module reload for the dev/demo loop (needs `node --expose-internals`).
 - id: hmr
   name: '@cordisjs/plugin-hmr'
   config:
@@ -33,12 +32,14 @@
   config:
     provider: deepseek
     model: deepseek-v4-pro
-    # Set RESUME_SESSION_ID to continue a prior persisted session (the ids live
-    # under ./.sessions); unset starts a fresh session each run.
-    resumeSessionId: !!js process.env.RESUME_SESSION_ID
+    # `dsh --resume <id>` provides the session id on the boot context (the ids
+    # live under ./.sessions); with no flag the identifier is undefined and a
+    # fresh session starts each run. The demo bin never provides it, so the
+    # typeof guard reads undefined there rather than throwing.
+    resumeSessionId: !!js "typeof resumeSessionId === 'string' ? resumeSessionId : undefined"
     persistenceRoot: './.sessions'
     # Printed on exit and listed by `/resume`; `{session}` fills the live id.
-    # `dsh --resume <id>` sets RESUME_SESSION_ID above, so run it from this cwd.
+    # `dsh --resume <id>` resumes that session, so run it from this cwd.
     resumeCommand: 'dsh --resume {session}'
     workspaceContext:
       maxBytes: 65536
@@ -122,8 +123,8 @@
 - id: tool-ralph
   name: '@deepseek-ai/dsh-tool-ralph'
 
-# Plan mode gives the TUI a plugin-owned /plan [message] command; the exit
-# review rides the TUI's user-interaction provider.
+# Plan mode gives the TUI plugin-owned /plan [message] entry and /plan off exit
+# commands; the reviewed exit rides the TUI's user-interaction provider.
 - id: plan-mode
   name: '@deepseek-ai/dsh-plan-mode'
   config:
diff --git a/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts b/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts
index b90f69f47e..c3bdbfd1b1 100644
--- a/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts
+++ b/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts
@@ -5,6 +5,8 @@ import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
 const CONTROL_PROBE = '\u001b]2;MODEL_CONTROLLED\u0007\u001b[999CMODEL_CURSOR\u009b31mMODEL_C1'
 const INITIAL_TEXT = `I need one decision before I continue. ${CONTROL_PROBE}`
 const FINAL_TEXT = 'Decision received. Scripted TUI run complete.'
+const DEFAULT_MODE_PROBE = 'Confirm the scripted run left plan mode.'
+const DEFAULT_MODE_TEXT = 'Default mode confirmed.'
 // The `skill` scenario types `/skill:scripted-skill`; the manual-invocation front
 // door delivers the loaded skill as a user turn wrapped in `<skill name="…">`. The
 // body marker below lives in the fixture skill, so echoing it back proves the whole
@@ -53,6 +55,13 @@ class ScriptedTuiAdapter extends LlmAdapter {
       .filter(block => block.type === 'text')
       .map(block => block.text)
       .join('\n')
+    if (lastText.includes(DEFAULT_MODE_PROBE)) {
+      if (options.system?.includes('Stay in plan mode for this scripted TUI test.')) {
+        throw new Error('the scripted TUI request retained plan guidance after /plan off')
+      }
+      for (const chunk of textChunks(DEFAULT_MODE_TEXT)) yield chunk
+      return
+    }
     if (lastText.includes(SKILL_BLOCK_OPEN)) {
       const ack = lastText.includes(SKILL_BODY_MARKER)
         ? SKILL_RECEIVED_TEXT
diff --git a/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml b/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml
index e4548da79e..307c5a1dfe 100644
--- a/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml
+++ b/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml
@@ -29,6 +29,8 @@
     # The smoke's log inspection reads plain `.jsonl`; keep the scripted
     # fixture uncompressed like the other snapshot-facing configs.
     persistenceCompression: none
+    resumeSessionId: !!js "typeof resumeSessionId === 'string' ? resumeSessionId : undefined"
+    resumeCommand: 'dsh --resume {session}'
     workspaceContext:
       maxBytes: 65536
     welcome: 'scripted TUI ready.'
diff --git a/examples/tui-agent/tests/pty-harness.ts b/examples/tui-agent/tests/pty-harness.ts
index 257198b7d2..e55e77f4de 100644
--- a/examples/tui-agent/tests/pty-harness.ts
+++ b/examples/tui-agent/tests/pty-harness.ts
@@ -197,7 +197,6 @@ export async function runTuiPtySmoke(options: TuiPtySmokeOptions): Promise<strin
         /* v8 ignore next -- every caller passes configPath or configArgs; the fallback keeps the type total */
         : [options.configPath ?? './cordis.yml'],
       tsconfigPath: options.tsconfigPath,
-      exposeInternals: true,
       env: {
         DSH_HOME: join(cwd, '.dsh'),
         DSH_AGENTS_HOME: join(cwd, '.agents'),
diff --git a/examples/tui-agent/tests/snapshots/code-mode/session.jsonl b/examples/tui-agent/tests/snapshots/code-mode/session.jsonl
index 8ee160ba26..84a4879050 100644
--- a/examples/tui-agent/tests/snapshots/code-mode/session.jsonl
+++ b/examples/tui-agent/tests/snapshots/code-mode/session.jsonl
@@ -1,150 +1,219 @@
-{"type":"session","version":0,"id":"94cd1ae4-e1d1-4ec8-9d27-50a1f849b6b3","createdAt":1783611771392,"cwd":"/var/folders/2c/psb0_fmx7hbgz558xjt_f0l00000gn/T/acp-snap-cwd-BteTVR","delegationDepth":0}
-{"type":"turn/start","seq":0,"time":1783611771394,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
-{"type":"user/message","seq":1,"time":1783611771394,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"step/start","seq":2,"time":1783611771396,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":3,"time":1783611771396,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
-{"type":"assistant/chunk","seq":4,"time":1783611771869,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"assistant/chunk","seq":5,"time":1783611771869,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
-{"type":"assistant/chunk","seq":6,"time":1783611771978,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
-{"type":"assistant/chunk","seq":7,"time":1783611772007,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
-{"type":"assistant/chunk","seq":8,"time":1783611772008,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
-{"type":"assistant/chunk","seq":9,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}}
-{"type":"assistant/chunk","seq":10,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}}
-{"type":"assistant/chunk","seq":11,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}}
-{"type":"assistant/chunk","seq":12,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}}
-{"type":"assistant/chunk","seq":13,"time":1783611772036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
-{"type":"assistant/chunk","seq":14,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" calls"}}}
-{"type":"assistant/chunk","seq":15,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
-{"type":"assistant/chunk","seq":16,"time":1783611772089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" twice"}}}
-{"type":"assistant/chunk","seq":17,"time":1783611772096,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}}
-{"type":"assistant/chunk","seq":18,"time":1783611772124,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}}
-{"type":"assistant/chunk","seq":19,"time":1783611772153,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}}
-{"type":"assistant/chunk","seq":20,"time":1783611772183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
-{"type":"assistant/chunk","seq":21,"time":1783611772183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}}
-{"type":"assistant/chunk","seq":22,"time":1783611772211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}}
-{"type":"assistant/chunk","seq":23,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
-{"type":"assistant/chunk","seq":24,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
-{"type":"assistant/chunk","seq":25,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
-{"type":"assistant/chunk","seq":26,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}}
-{"type":"assistant/chunk","seq":27,"time":1783611772212,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}}
-{"type":"assistant/chunk","seq":28,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
-{"type":"assistant/chunk","seq":29,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}}
-{"type":"assistant/chunk","seq":30,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
-{"type":"assistant/chunk","seq":31,"time":1783611772241,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}}
-{"type":"assistant/chunk","seq":32,"time":1783611772270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" this"}}}
-{"type":"assistant/chunk","seq":33,"time":1783611772270,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
-{"type":"assistant/chunk","seq":34,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":35,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":""}}}
-{"type":"assistant/chunk","seq":36,"time":1783611772361,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"{"}}}
-{"type":"assistant/chunk","seq":37,"time":1783611772362,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
-{"type":"assistant/chunk","seq":38,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"code"}}}
-{"type":"assistant/chunk","seq":39,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
-{"type":"assistant/chunk","seq":40,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":": "}}}
-{"type":"assistant/chunk","seq":41,"time":1783611772390,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
-{"type":"assistant/chunk","seq":42,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"const"}}}
-{"type":"assistant/chunk","seq":43,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
-{"type":"assistant/chunk","seq":44,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"1"}}}
-{"type":"assistant/chunk","seq":45,"time":1783611772420,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" ="}}}
-{"type":"assistant/chunk","seq":46,"time":1783611772421,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" await"}}}
-{"type":"assistant/chunk","seq":47,"time":1783611772421,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" tools"}}}
-{"type":"assistant/chunk","seq":48,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".b"}}}
-{"type":"assistant/chunk","seq":49,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ash"}}}
-{"type":"assistant/chunk","seq":50,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"({"}}}
-{"type":"assistant/chunk","seq":51,"time":1783611772449,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" command"}}}
-{"type":"assistant/chunk","seq":52,"time":1783611772478,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
-{"type":"assistant/chunk","seq":53,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
-{"type":"assistant/chunk","seq":54,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"echo"}}}
-{"type":"assistant/chunk","seq":55,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" CODE"}}}
-{"type":"assistant/chunk","seq":56,"time":1783611772479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"_"}}}
-{"type":"assistant/chunk","seq":57,"time":1783611772508,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ONE"}}}
-{"type":"assistant/chunk","seq":58,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\","}}}
-{"type":"assistant/chunk","seq":59,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" description"}}}
-{"type":"assistant/chunk","seq":60,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
-{"type":"assistant/chunk","seq":61,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
-{"type":"assistant/chunk","seq":62,"time":1783611772510,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"First"}}}
-{"type":"assistant/chunk","seq":63,"time":1783611772538,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" echo"}}}
-{"type":"assistant/chunk","seq":64,"time":1783611772538,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
-{"type":"assistant/chunk","seq":65,"time":1783611772566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" });\\n"}}}
-{"type":"assistant/chunk","seq":66,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"const"}}}
-{"type":"assistant/chunk","seq":67,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
-{"type":"assistant/chunk","seq":68,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"2"}}}
-{"type":"assistant/chunk","seq":69,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" ="}}}
-{"type":"assistant/chunk","seq":70,"time":1783611772567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" await"}}}
-{"type":"assistant/chunk","seq":71,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" tools"}}}
-{"type":"assistant/chunk","seq":72,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".b"}}}
-{"type":"assistant/chunk","seq":73,"time":1783611772597,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"ash"}}}
-{"type":"assistant/chunk","seq":74,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"({"}}}
-{"type":"assistant/chunk","seq":75,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" command"}}}
-{"type":"assistant/chunk","seq":76,"time":1783611772598,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
-{"type":"assistant/chunk","seq":77,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
-{"type":"assistant/chunk","seq":78,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"echo"}}}
-{"type":"assistant/chunk","seq":79,"time":1783611772625,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" CODE"}}}
-{"type":"assistant/chunk","seq":80,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"_T"}}}
-{"type":"assistant/chunk","seq":81,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"WO"}}}
-{"type":"assistant/chunk","seq":82,"time":1783611772626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\","}}}
-{"type":"assistant/chunk","seq":83,"time":1783611772654,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" description"}}}
-{"type":"assistant/chunk","seq":84,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":":"}}}
-{"type":"assistant/chunk","seq":85,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\""}}}
-{"type":"assistant/chunk","seq":86,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"Second"}}}
-{"type":"assistant/chunk","seq":87,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" echo"}}}
-{"type":"assistant/chunk","seq":88,"time":1783611772655,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
-{"type":"assistant/chunk","seq":89,"time":1783611772684,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" });\\n"}}}
-{"type":"assistant/chunk","seq":90,"time":1783611772685,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"return"}}}
-{"type":"assistant/chunk","seq":91,"time":1783611772685,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
-{"type":"assistant/chunk","seq":92,"time":1783611772713,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"1"}}}
-{"type":"assistant/chunk","seq":93,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".trim"}}}
-{"type":"assistant/chunk","seq":94,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"()"}}}
-{"type":"assistant/chunk","seq":95,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" +"}}}
-{"type":"assistant/chunk","seq":96,"time":1783611772714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" \\\"+"}}}
-{"type":"assistant/chunk","seq":97,"time":1783611772744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\\\""}}}
-{"type":"assistant/chunk","seq":98,"time":1783611772744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" +"}}}
-{"type":"assistant/chunk","seq":99,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":" out"}}}
-{"type":"assistant/chunk","seq":100,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"2"}}}
-{"type":"assistant/chunk","seq":101,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":".trim"}}}
-{"type":"assistant/chunk","seq":102,"time":1783611772745,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"();"}}}
-{"type":"assistant/chunk","seq":103,"time":1783611772772,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"\""}}}
-{"type":"assistant/chunk","seq":104,"time":1783611772773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","argumentsDelta":"}"}}}
-{"type":"assistant/chunk","seq":105,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants a single run_code program that calls bash twice, then returns the two outputs joined with a plus sign. Let me write this."}}}}
-{"type":"assistant/chunk","seq":106,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}}
-{"type":"assistant/chunk","seq":107,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3009,"outputTokens":133,"cacheReadTokens":0,"reasoningTokens":29}}}}
-{"type":"assistant/chunk","seq":108,"time":1783611772836,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":109,"time":1783611772840,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants a single run_code program that calls bash twice, then returns the two outputs joined with a plus sign. Let me write this."},{"type":"tool-call","id":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3009,"outputTokens":133,"cacheReadTokens":0,"reasoningTokens":29}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108],"surfaceOp":"append"}
-{"type":"tool/call","seq":110,"time":1783611772840,"data":{"turn":1,"step":1,"callId":"call_00_DRxnM6R1TThfDwcudW0f2050","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}
-{"type":"tool/code-dispatch","seq":111,"time":1783611772933,"data":{"parentCallId":"call_00_DRxnM6R1TThfDwcudW0f2050","subCallId":"call_00_DRxnM6R1TThfDwcudW0f2050:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"First echo"},"isError":false,"resultSummary":"CODE_ONE\n"}}
-{"type":"tool/code-dispatch","seq":112,"time":1783611772936,"data":{"parentCallId":"call_00_DRxnM6R1TThfDwcudW0f2050","subCallId":"call_00_DRxnM6R1TThfDwcudW0f2050:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Second echo"},"isError":false,"resultSummary":"CODE_TWO\n"}}
-{"type":"tool/result","seq":113,"time":1783611772937,"data":{"turn":1,"step":1,"callId":"call_00_DRxnM6R1TThfDwcudW0f2050","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[110],"surfaceOp":"append"}
-{"type":"step/end","seq":114,"time":1783611772938,"data":{"turn":1,"step":1}}
-{"type":"step/start","seq":115,"time":1783611772938,"data":{"turn":1,"step":2}}
-{"type":"assistant/chunk","seq":116,"time":1783611773376,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"assistant/chunk","seq":117,"time":1783611773376,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
-{"type":"assistant/chunk","seq":118,"time":1783611773480,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
-{"type":"assistant/chunk","seq":119,"time":1783611773511,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}}
-{"type":"assistant/chunk","seq":120,"time":1783611773512,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
-{"type":"assistant/chunk","seq":121,"time":1783611773540,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}}
-{"type":"assistant/chunk","seq":122,"time":1783611773541,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
-{"type":"assistant/chunk","seq":123,"time":1783611773541,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
-{"type":"assistant/chunk","seq":124,"time":1783611773569,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" asked"}}}
-{"type":"assistant/chunk","seq":125,"time":1783611773570,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" for"}}}
-{"type":"assistant/chunk","seq":126,"time":1783611773570,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}}
-{"type":"assistant/chunk","seq":127,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
-{"type":"assistant/chunk","seq":128,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
-{"type":"assistant/chunk","seq":129,"time":1783611773597,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
-{"type":"assistant/chunk","seq":130,"time":1783611773626,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}}
-{"type":"assistant/chunk","seq":131,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
-{"type":"assistant/chunk","seq":132,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
-{"type":"assistant/chunk","seq":133,"time":1783611773627,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
-{"type":"assistant/chunk","seq":134,"time":1783611773654,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":135,"time":1783611773655,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
-{"type":"assistant/chunk","seq":136,"time":1783611773655,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}}
-{"type":"assistant/chunk","seq":137,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
-{"type":"assistant/chunk","seq":138,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}}
-{"type":"assistant/chunk","seq":139,"time":1783611773656,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
-{"type":"assistant/chunk","seq":140,"time":1783611773657,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}}
-{"type":"assistant/chunk","seq":141,"time":1783611773685,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}}
-{"type":"assistant/chunk","seq":142,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is exactly what the user asked for: CODE_ONE+CODE_TWO"}}}}
-{"type":"assistant/chunk","seq":143,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}}
-{"type":"assistant/chunk","seq":144,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":89,"outputTokens":25,"cacheReadTokens":3072,"reasoningTokens":17}}}}
-{"type":"assistant/chunk","seq":145,"time":1783611773686,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":146,"time":1783611773687,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is exactly what the user asked for: CODE_ONE+CODE_TWO"},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":89,"outputTokens":25,"cacheReadTokens":3072,"reasoningTokens":17}},"sourceEventSeqs":[116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145],"surfaceOp":"append"}
-{"type":"step/end","seq":147,"time":1783611773687,"data":{"turn":1,"step":2}}
-{"type":"turn/end","seq":148,"time":1783611773687,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session","version":0,"id":"main-session","createdAt":1784629683717,"cwd":"/tmp/dsh-tui-snapshot-code-mode-8ohx1D"}
+{"type":"turn/start","seq":0,"time":1784629683765,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1784629683765,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO`. Inside that same program, console.log exactly `captured output`, then return the two outputs joined with a plus sign. Reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1784629683777,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1784629683778,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1784629684210,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":5,"time":1784629684211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":6,"time":1784629684309,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":7,"time":1784629684337,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":8,"time":1784629684337,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":9,"time":1784629684337,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":10,"time":1784629684337,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}}
+{"type":"assistant/chunk","seq":11,"time":1784629684365,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
+{"type":"assistant/chunk","seq":12,"time":1784629684366,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}}
+{"type":"assistant/chunk","seq":13,"time":1784629684366,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}}
+{"type":"assistant/chunk","seq":14,"time":1784629684366,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}}
+{"type":"assistant/chunk","seq":15,"time":1784629684366,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}}
+{"type":"assistant/chunk","seq":16,"time":1784629684394,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
+{"type":"assistant/chunk","seq":17,"time":1784629684394,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n"}}}
+{"type":"assistant/chunk","seq":18,"time":1784629684395,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}}
+{"type":"assistant/chunk","seq":19,"time":1784629684395,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":20,"time":1784629684395,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}}
+{"type":"assistant/chunk","seq":21,"time":1784629684424,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}}
+{"type":"assistant/chunk","seq":22,"time":1784629684424,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}}
+{"type":"assistant/chunk","seq":23,"time":1784629684449,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" twice"}}}
+{"type":"assistant/chunk","seq":24,"time":1784629684477,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" -"}}}
+{"type":"assistant/chunk","seq":25,"time":1784629684477,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" first"}}}
+{"type":"assistant/chunk","seq":26,"time":1784629684505,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":27,"time":1784629684505,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":28,"time":1784629684506,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":29,"time":1784629684506,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":30,"time":1784629684533,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":31,"time":1784629684533,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":32,"time":1784629684533,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`,"}}}
+{"type":"assistant/chunk","seq":33,"time":1784629684533,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}}
+{"type":"assistant/chunk","seq":34,"time":1784629684533,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":35,"time":1784629684533,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":36,"time":1784629684561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}}
+{"type":"assistant/chunk","seq":37,"time":1784629684561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}}
+{"type":"assistant/chunk","seq":38,"time":1784629684561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":39,"time":1784629684561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":40,"time":1784629684561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}}
+{"type":"assistant/chunk","seq":41,"time":1784629684561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}}
+{"type":"assistant/chunk","seq":42,"time":1784629684598,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":43,"time":1784629684599,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" console"}}}
+{"type":"assistant/chunk","seq":44,"time":1784629684617,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".log"}}}
+{"type":"assistant/chunk","seq":45,"time":1784629684618,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":46,"time":1784629684645,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":47,"time":1784629684645,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"capt"}}}
+{"type":"assistant/chunk","seq":48,"time":1784629684645,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ured"}}}
+{"type":"assistant/chunk","seq":49,"time":1784629684645,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}}
+{"type":"assistant/chunk","seq":50,"time":1784629684645,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}}
+{"type":"assistant/chunk","seq":51,"time":1784629684646,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}}
+{"type":"assistant/chunk","seq":52,"time":1784629684674,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":53,"time":1784629684675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Return"}}}
+{"type":"assistant/chunk","seq":54,"time":1784629684701,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":55,"time":1784629684701,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}}
+{"type":"assistant/chunk","seq":56,"time":1784629684701,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}}
+{"type":"assistant/chunk","seq":57,"time":1784629684701,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
+{"type":"assistant/chunk","seq":58,"time":1784629684701,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":59,"time":1784629684728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}}
+{"type":"assistant/chunk","seq":60,"time":1784629684728,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}}
+{"type":"assistant/chunk","seq":61,"time":1784629684729,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}}
+{"type":"assistant/chunk","seq":62,"time":1784629684729,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n\n"}}}
+{"type":"assistant/chunk","seq":63,"time":1784629684729,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}}
+{"type":"assistant/chunk","seq":64,"time":1784629684729,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":65,"time":1784629684757,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}}
+{"type":"assistant/chunk","seq":66,"time":1784629684758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" this"}}}
+{"type":"assistant/chunk","seq":67,"time":1784629684758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" carefully"}}}
+{"type":"assistant/chunk","seq":68,"time":1784629684758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":69,"time":1784629684841,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":70,"time":1784629684841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":""}}}
+{"type":"assistant/chunk","seq":71,"time":1784629684868,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"{"}}}
+{"type":"assistant/chunk","seq":72,"time":1784629684869,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":73,"time":1784629684869,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"code"}}}
+{"type":"assistant/chunk","seq":74,"time":1784629684869,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":75,"time":1784629684897,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":": "}}}
+{"type":"assistant/chunk","seq":76,"time":1784629684897,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":77,"time":1784629684897,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":78,"time":1784629684897,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" result"}}}
+{"type":"assistant/chunk","seq":79,"time":1784629684924,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"1"}}}
+{"type":"assistant/chunk","seq":80,"time":1784629684925,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":81,"time":1784629684925,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" await"}}}
+{"type":"assistant/chunk","seq":82,"time":1784629684925,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" tools"}}}
+{"type":"assistant/chunk","seq":83,"time":1784629684925,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".b"}}}
+{"type":"assistant/chunk","seq":84,"time":1784629684953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"ash"}}}
+{"type":"assistant/chunk","seq":85,"time":1784629684953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"({"}}}
+{"type":"assistant/chunk","seq":86,"time":1784629684953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" command"}}}
+{"type":"assistant/chunk","seq":87,"time":1784629684953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":88,"time":1784629684953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":89,"time":1784629684953,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"echo"}}}
+{"type":"assistant/chunk","seq":90,"time":1784629684981,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" CODE"}}}
+{"type":"assistant/chunk","seq":91,"time":1784629684981,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"_"}}}
+{"type":"assistant/chunk","seq":92,"time":1784629684981,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"ONE"}}}
+{"type":"assistant/chunk","seq":93,"time":1784629684981,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\\\","}}}
+{"type":"assistant/chunk","seq":94,"time":1784629684981,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" description"}}}
+{"type":"assistant/chunk","seq":95,"time":1784629684981,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":96,"time":1784629685009,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":97,"time":1784629685010,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"First"}}}
+{"type":"assistant/chunk","seq":98,"time":1784629685037,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" echo"}}}
+{"type":"assistant/chunk","seq":99,"time":1784629685038,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":100,"time":1784629685068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" });\\n"}}}
+{"type":"assistant/chunk","seq":101,"time":1784629685068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":102,"time":1784629685068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" result"}}}
+{"type":"assistant/chunk","seq":103,"time":1784629685068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"2"}}}
+{"type":"assistant/chunk","seq":104,"time":1784629685068,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":105,"time":1784629685069,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" await"}}}
+{"type":"assistant/chunk","seq":106,"time":1784629685096,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" tools"}}}
+{"type":"assistant/chunk","seq":107,"time":1784629685096,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".b"}}}
+{"type":"assistant/chunk","seq":108,"time":1784629685096,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"ash"}}}
+{"type":"assistant/chunk","seq":109,"time":1784629685096,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"({"}}}
+{"type":"assistant/chunk","seq":110,"time":1784629685096,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" command"}}}
+{"type":"assistant/chunk","seq":111,"time":1784629685097,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":112,"time":1784629685129,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":113,"time":1784629685130,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"echo"}}}
+{"type":"assistant/chunk","seq":114,"time":1784629685130,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" CODE"}}}
+{"type":"assistant/chunk","seq":115,"time":1784629685130,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"_T"}}}
+{"type":"assistant/chunk","seq":116,"time":1784629685130,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"WO"}}}
+{"type":"assistant/chunk","seq":117,"time":1784629685130,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\\\","}}}
+{"type":"assistant/chunk","seq":118,"time":1784629685152,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" description"}}}
+{"type":"assistant/chunk","seq":119,"time":1784629685153,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":":"}}}
+{"type":"assistant/chunk","seq":120,"time":1784629685153,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" \\\""}}}
+{"type":"assistant/chunk","seq":121,"time":1784629685153,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"Second"}}}
+{"type":"assistant/chunk","seq":122,"time":1784629685153,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" echo"}}}
+{"type":"assistant/chunk","seq":123,"time":1784629685153,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":124,"time":1784629685180,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" });\\n\\n"}}}
+{"type":"assistant/chunk","seq":125,"time":1784629685181,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":126,"time":1784629685181,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" out"}}}
+{"type":"assistant/chunk","seq":127,"time":1784629685181,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"1"}}}
+{"type":"assistant/chunk","seq":128,"time":1784629685209,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":129,"time":1784629685209,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" result"}}}
+{"type":"assistant/chunk","seq":130,"time":1784629685209,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"1"}}}
+{"type":"assistant/chunk","seq":131,"time":1784629685209,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".stdout"}}}
+{"type":"assistant/chunk","seq":132,"time":1784629685237,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".text"}}}
+{"type":"assistant/chunk","seq":133,"time":1784629685266,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".trim"}}}
+{"type":"assistant/chunk","seq":134,"time":1784629685266,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"();\\n"}}}
+{"type":"assistant/chunk","seq":135,"time":1784629685266,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"const"}}}
+{"type":"assistant/chunk","seq":136,"time":1784629685266,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" out"}}}
+{"type":"assistant/chunk","seq":137,"time":1784629685266,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"2"}}}
+{"type":"assistant/chunk","seq":138,"time":1784629685293,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" ="}}}
+{"type":"assistant/chunk","seq":139,"time":1784629685293,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" result"}}}
+{"type":"assistant/chunk","seq":140,"time":1784629685293,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"2"}}}
+{"type":"assistant/chunk","seq":141,"time":1784629685293,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".stdout"}}}
+{"type":"assistant/chunk","seq":142,"time":1784629685293,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".text"}}}
+{"type":"assistant/chunk","seq":143,"time":1784629685294,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".trim"}}}
+{"type":"assistant/chunk","seq":144,"time":1784629685322,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"();\\n\\n"}}}
+{"type":"assistant/chunk","seq":145,"time":1784629685322,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"console"}}}
+{"type":"assistant/chunk","seq":146,"time":1784629685322,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":".log"}}}
+{"type":"assistant/chunk","seq":147,"time":1784629685322,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"(\\\""}}}
+{"type":"assistant/chunk","seq":148,"time":1784629685322,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"capt"}}}
+{"type":"assistant/chunk","seq":149,"time":1784629685322,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"ured"}}}
+{"type":"assistant/chunk","seq":150,"time":1784629685350,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" output"}}}
+{"type":"assistant/chunk","seq":151,"time":1784629685351,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\\\");\\n\\n"}}}
+{"type":"assistant/chunk","seq":152,"time":1784629685379,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"return"}}}
+{"type":"assistant/chunk","seq":153,"time":1784629685379,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" out"}}}
+{"type":"assistant/chunk","seq":154,"time":1784629685428,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"1"}}}
+{"type":"assistant/chunk","seq":155,"time":1784629685429,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" +"}}}
+{"type":"assistant/chunk","seq":156,"time":1784629685429,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" \\\"+"}}}
+{"type":"assistant/chunk","seq":157,"time":1784629685445,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\\\""}}}
+{"type":"assistant/chunk","seq":158,"time":1784629685446,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" +"}}}
+{"type":"assistant/chunk","seq":159,"time":1784629685446,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":" out"}}}
+{"type":"assistant/chunk","seq":160,"time":1784629685446,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"2"}}}
+{"type":"assistant/chunk","seq":161,"time":1784629685446,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":";\\n"}}}
+{"type":"assistant/chunk","seq":162,"time":1784629685472,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"\""}}}
+{"type":"assistant/chunk","seq":163,"time":1784629685472,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","argumentsDelta":"}"}}}
+{"type":"assistant/chunk","seq":164,"time":1784629685531,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash tool twice - first with `echo CODE_ONE`, then with `echo CODE_TWO`\n2. console.log exactly `captured output`\n3. Return the two outputs joined with a plus sign\n\nLet me write this carefully."}}}}
+{"type":"assistant/chunk","seq":165,"time":1784629685531,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","arguments":"{\"code\": \"const result1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst result2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\n\\nconst out1 = result1.stdout.text.trim();\\nconst out2 = result2.stdout.text.trim();\\n\\nconsole.log(\\\"captured output\\\");\\n\\nreturn out1 + \\\"+\\\" + out2;\\n\"}"}}}}
+{"type":"assistant/chunk","seq":166,"time":1784629685531,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3986,"outputTokens":192,"cacheReadTokens":256,"reasoningTokens":64}}}}
+{"type":"assistant/chunk","seq":167,"time":1784629685531,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":168,"time":1784629685533,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash tool twice - first with `echo CODE_ONE`, then with `echo CODE_TWO`\n2. console.log exactly `captured output`\n3. Return the two outputs joined with a plus sign\n\nLet me write this carefully."},{"type":"tool-call","id":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","arguments":"{\"code\": \"const result1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst result2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\n\\nconst out1 = result1.stdout.text.trim();\\nconst out2 = result2.stdout.text.trim();\\n\\nconsole.log(\\\"captured output\\\");\\n\\nreturn out1 + \\\"+\\\" + out2;\\n\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3986,"outputTokens":192,"cacheReadTokens":256,"reasoningTokens":64}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167],"surfaceOp":"append"}
+{"type":"tool/call","seq":169,"time":1784629685534,"data":{"turn":1,"step":1,"callId":"call_00_38G57TcLdORe1VBnQlXL4801","name":"run_code","arguments":"{\"code\": \"const result1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"First echo\\\" });\\nconst result2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Second echo\\\" });\\n\\nconst out1 = result1.stdout.text.trim();\\nconst out2 = result2.stdout.text.trim();\\n\\nconsole.log(\\\"captured output\\\");\\n\\nreturn out1 + \\\"+\\\" + out2;\\n\"}"}}
+{"type":"tool/code-dispatch","seq":170,"time":1784629685618,"data":{"parentCallId":"call_00_38G57TcLdORe1VBnQlXL4801","subCallId":"call_00_38G57TcLdORe1VBnQlXL4801:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"First echo"},"isError":false,"resultSummary":"CODE_ONE\n"}}
+{"type":"tool/code-dispatch","seq":171,"time":1784629685621,"data":{"parentCallId":"call_00_38G57TcLdORe1VBnQlXL4801","subCallId":"call_00_38G57TcLdORe1VBnQlXL4801:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Second echo"},"isError":false,"resultSummary":"CODE_TWO\n"}}
+{"type":"tool/result","seq":172,"time":1784629685623,"data":{"turn":1,"step":1,"callId":"call_00_38G57TcLdORe1VBnQlXL4801","content":[{"type":"text","text":"captured output\nCODE_ONE+CODE_TWO"}],"isError":false},"sourceEventSeqs":[169],"surfaceOp":"append"}
+{"type":"step/end","seq":173,"time":1784629685623,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":174,"time":1784629685624,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":175,"time":1784629685973,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":176,"time":1784629685973,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":177,"time":1784629686103,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":178,"time":1784629686129,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" asked"}}}
+{"type":"assistant/chunk","seq":179,"time":1784629686129,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":180,"time":1784629686130,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":181,"time":1784629686162,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":182,"time":1784629686162,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":183,"time":1784629686162,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}}
+{"type":"assistant/chunk","seq":184,"time":1784629686184,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
+{"type":"assistant/chunk","seq":185,"time":1784629686184,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}}
+{"type":"assistant/chunk","seq":186,"time":1784629686184,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}}
+{"type":"assistant/chunk","seq":187,"time":1784629686184,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":188,"time":1784629686215,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}}
+{"type":"assistant/chunk","seq":189,"time":1784629686215,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":190,"time":1784629686215,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}}
+{"type":"assistant/chunk","seq":191,"time":1784629686241,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}}
+{"type":"assistant/chunk","seq":192,"time":1784629686242,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}}
+{"type":"assistant/chunk","seq":193,"time":1784629686242,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}}
+{"type":"assistant/chunk","seq":194,"time":1784629686242,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}}
+{"type":"assistant/chunk","seq":195,"time":1784629686269,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":196,"time":1784629686269,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}}
+{"type":"assistant/chunk","seq":197,"time":1784629686269,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":198,"time":1784629686269,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}}
+{"type":"assistant/chunk","seq":199,"time":1784629686269,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":200,"time":1784629686269,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}}
+{"type":"assistant/chunk","seq":201,"time":1784629686300,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}}
+{"type":"assistant/chunk","seq":202,"time":1784629686300,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"`."}}}
+{"type":"assistant/chunk","seq":203,"time":1784629686300,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":204,"time":1784629686300,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":205,"time":1784629686301,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}}
+{"type":"assistant/chunk","seq":206,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":207,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}}
+{"type":"assistant/chunk","seq":208,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}}
+{"type":"assistant/chunk","seq":209,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}}
+{"type":"assistant/chunk","seq":210,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}}
+{"type":"assistant/chunk","seq":211,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user asked me to reply with that joined string only and stop. The joined string is `CODE_ONE+CODE_TWO`."}}}}
+{"type":"assistant/chunk","seq":212,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}}
+{"type":"assistant/chunk","seq":213,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":105,"outputTokens":35,"cacheReadTokens":4352,"reasoningTokens":27}}}}
+{"type":"assistant/chunk","seq":214,"time":1784629686333,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":215,"time":1784629686334,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The user asked me to reply with that joined string only and stop. The joined string is `CODE_ONE+CODE_TWO`."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":105,"outputTokens":35,"cacheReadTokens":4352,"reasoningTokens":27}},"sourceEventSeqs":[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,205,206,207,208,209,210,211,212,213,214],"surfaceOp":"append"}
+{"type":"step/end","seq":216,"time":1784629686334,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":217,"time":1784629686334,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/tui-agent/tests/snapshots/code-mode/terminal.expected.txt b/examples/tui-agent/tests/snapshots/code-mode/terminal.expected.txt
index 0c51281584..af14b32791 100644
--- a/examples/tui-agent/tests/snapshots/code-mode/terminal.expected.txt
+++ b/examples/tui-agent/tests/snapshots/code-mode/terminal.expected.txt
@@ -1,7 +1,7 @@
-terminal 100x36 buffer=normal length=36 base=0 viewport=0
+terminal 100x36 buffer=normal length=38 base=2 viewport=2
 lifecycle started=1 stopped=0 progress=inactive
 title "Using ONE run_code program: call — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=27 bufferRow=27
+cursor hidden column=1 viewportRow=31 bufferRow=33
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
@@ -20,50 +20,70 @@ buffer
   style 0-0 fg=bright-blue
   style 65-77 fg=cyan
   style 92-99 fg=cyan
-7| "▌ CODE_TWO — and return the two outputs joined with a plus sign. Then reply with that joined string "
+7| "▌ CODE_TWO. Inside that same program, console.log exactly captured output, then return the two      "
   style 0-0 fg=bright-blue
   style 2-9 fg=cyan
-8| "▌ only and stop.                                                                                    "
+  style 58-72 fg=cyan
+8| "▌ outputs joined with a plus sign. Reply with that joined string only and stop.                     "
   style 0-0 fg=bright-blue
 9| "▌ "
   style 0-0 fg=bright-blue
 10| <blank>
 11| " Reasoning                                                                                          "
   style 1-9 fg=bright-black italic
-12| " The user wants a single run_code program that calls bash twice, then returns the two outputs       "
-  style 1-99 fg=bright-black italic
-13| " joined with a plus sign. Let me write this.                                                        "
-  style 1-43 fg=bright-black italic
-14| <blank>
-15| "▌ "
+12| " The user wants me to write a single run_code program that:                                         "
+  style 1-58 fg=bright-black italic
+13| " 1. Calls bash tool twice - first with echo CODE_ONE, then with echo CODE_TWO                       "
+  style 1-3 fg=bright-blue
+  style 4-38 fg=bright-black italic
+  style 39-51 fg=cyan
+  style 52-63 fg=bright-black italic
+  style 64-76 fg=cyan
+14| " 2. console.log exactly captured output                                                             "
+  style 1-3 fg=bright-blue
+  style 4-23 fg=bright-black italic
+  style 24-38 fg=cyan
+15| " 3. Return the two outputs joined with a plus sign                                                  "
+  style 1-3 fg=bright-blue
+  style 4-49 fg=bright-black italic
+16| "                                                                                                    "
+17| " Let me write this carefully.                                                                       "
+  style 1-28 fg=bright-black italic
+18| <blank>
+19| "▌ "
   style 0-0 fg=green
-16| "▌ ✓ const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"First echo\" });         "
+20| "▌ ✓ const result1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"First echo\" });      "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-99 bold
-17| "▌ const o                                                                                           "
+21| "▌ cons                                                                                              "
   style 0-0 fg=green
-  style 2-8 bold
-18| "▌ CODE_ONE+CODE_TWO                                                                                 "
+  style 2-5 bold
+22| "▌ captured output                                                                                   "
   style 0-0 fg=green
-19| "▌ "
+23| "▌ CODE_ONE+CODE_TWO                                                                                 "
   style 0-0 fg=green
-20| <blank>
-21| " Reasoning                                                                                          "
+24| "▌ "
+  style 0-0 fg=green
+25| <blank>
+26| " Reasoning                                                                                          "
   style 1-9 fg=bright-black italic
-22| " The output is exactly what the user asked for: CODE_ONE+CODE_TWO                                   "
-  style 1-64 fg=bright-black italic
-23| <blank>
-24| " Assistant                                                                                          "
+27| " The user asked me to reply with that joined string only and stop. The joined string is             "
+  style 1-99 fg=bright-black italic
+28| " CODE_ONE+CODE_TWO.                                                                                 "
+  style 1-17 fg=cyan
+  style 18-18 fg=bright-black italic
+29| <blank>
+30| " Assistant                                                                                          "
   style 1-9 fg=bright-magenta bold
-25| " CODE_ONE+CODE_TWO                                                                                  "
-26| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+31| " CODE_ONE+CODE_TWO                                                                                  "
+32| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-27| "                                                                                                    "
+33| "                                                                                                    "
   style 1-1 inverse
-28| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+34| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-29| "deepseek-v4-flash  /workspace/project  ↑3.1k ↓158  cache 50%  3% context  tools:"
+35| "deepseek-v4-flash  /workspace/project  ↑4.1k ↓227  cache 53%  4% context  tools:"
   style 0-79 dim
   style 82-99 dim
-30-35| <blank>
+36-37| <blank>
diff --git a/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/terminal.expected.txt b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/terminal.expected.txt
index 6508e75b19..c22acfd95b 100644
--- a/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/terminal.expected.txt
+++ b/examples/tui-agent/tests/snapshots/cordis-dynamic-toolchain/terminal.expected.txt
@@ -101,6 +101,6 @@ buffer
   style 1-1 inverse
 46| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-47| "deepseek-v4-flash  /workspace/project  ↑18 ↓18  cache 0%  7% cont"
+47| "deepseek-v4-flash  /workspace/project  ↑18 ↓18  cache 0%  8% cont"
   style 0-90 dim
   style 93-99 dim
diff --git a/examples/tui-agent/tests/snapshots/multi-turn-conversation/terminal.expected.txt b/examples/tui-agent/tests/snapshots/multi-turn-conversation/terminal.expected.txt
index de5389c059..099bf63b81 100644
--- a/examples/tui-agent/tests/snapshots/multi-turn-conversation/terminal.expected.txt
+++ b/examples/tui-agent/tests/snapshots/multi-turn-conversation/terminal.expected.txt
@@ -1,7 +1,7 @@
 terminal 100x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "Reply with exactly the word: — DSH TUI snapshot"
-cursor hidden column=1 viewportRow=28 bufferRow=28
+cursor hidden column=1 viewportRow=33 bufferRow=33
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-blue bold
@@ -11,8 +11,8 @@ buffer
 2| " deepseek-v4-flash  •  main-session"
   style 1-34 dim
 3| <blank>
-4| " Entering plan mode (applies from the next step).                                                   "
-  style 1-48 fg=bright-black
+4| " Entering plan mode (applies from the next step). Use /plan off to leave.                           "
+  style 1-72 fg=bright-black
 5| <blank>
 6| "▌ "
   style 0-0 fg=bright-blue
@@ -33,31 +33,38 @@ buffer
   style 1-9 fg=bright-magenta bold
 15| " ONE                                                                                                "
 16| <blank>
-17| "▌ "
+17| " Leaving plan mode (applies from the next step).                                                    "
+  style 1-47 fg=bright-black
+18| <blank>
+19| " Context · plan-mode                                                                                "
+  style 1-19 dim
+20| " The user switched this session back to the default mode.                                           "
+  style 1-56 fg=bright-black
+21| <blank>
+22| "▌ "
   style 0-0 fg=bright-blue
-18| "▌ You                                                                                               "
+23| "▌ You                                                                                               "
   style 0-0 fg=bright-blue
   style 2-4 fg=bright-blue bold
-19| "▌ Reply with exactly the word: TWO. No tools.                                                       "
+24| "▌ Reply with exactly the word: TWO. No tools.                                                       "
   style 0-0 fg=bright-blue
-20| "▌ "
+25| "▌ "
   style 0-0 fg=bright-blue
-21| <blank>
-22| " Reasoning                                                                                          "
+26| <blank>
+27| " Reasoning                                                                                          "
   style 1-9 fg=bright-black italic
-23| " The user wants me to reply with exactly the word \"TWO\" and no tools.                               "
+28| " The user wants me to reply with exactly the word \"TWO\" and no tools.                               "
   style 1-68 fg=bright-black italic
-24| <blank>
-25| " Assistant                                                                                          "
+29| <blank>
+30| " Assistant                                                                                          "
   style 1-9 fg=bright-magenta bold
-26| " TWO                                                                                                "
-27| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+31| " TWO                                                                                                "
+32| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-28| "                                                                                                    "
+33| "                                                                                                    "
   style 1-1 inverse
-29| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+34| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-30| "deepseek-v4-flash  /workspace/project  ↑2.9k ↓41  cache 49%  3% co"
+35| "deepseek-v4-flash  /workspace/project  ↑2.9k ↓41  cache 49%  3% co"
   style 0-92 dim
   style 95-99 dim
-31-35| <blank>
diff --git a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts
index 624041854e..a1366621a0 100644
--- a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts
+++ b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts
@@ -1,8 +1,11 @@
+import { realpathSync } from 'node:fs'
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS } from '@deepseek-ai/dsh-loader-smoke'
+import { SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import { logPath, toHeaderLine } from '../../../packages/session-persistence/session-persistence-jsonl/src/format.ts'
 import { runTuiPtySmoke, type TuiPtySmokeOptions } from './pty-harness.ts'
 
 const binScript = fileURLToPath(new URL('../../../packages/examples/tui-demo/src/bin.ts', import.meta.url))
@@ -13,14 +16,24 @@ const scriptedConfigPath = fileURLToPath(new URL('./fixtures/tui-scripted.cordis
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 
 /**
- * Seed the harness workspace: personal files land in the isolated Harness home
- * (`.dsh`), skill bundles under the agents home's `skills/` root — the same
- * trees `$DSH_HOME` / `$DSH_AGENTS_HOME` point the child at.
+ * Seed the isolated process workspace: ordinary files land in `cwd`, personal
+ * 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.
  */
 function seedWorkspace(
-  files: { personal?: Record<string, string>; skills?: Record<string, string> },
+  files: {
+    workspace?: Record<string, string>
+    personal?: Record<string, string>
+    skills?: Record<string, string>
+  },
 ): (cwd: string) => Promise<void> {
   return async (cwd) => {
+    for (const [name, content] of Object.entries(files.workspace ?? {})) {
+      const file = join(cwd, name)
+      await mkdir(dirname(file), { recursive: true })
+      await writeFile(file, content)
+    }
     for (const [name, content] of Object.entries(files.personal ?? {})) {
       const file = join(cwd, '.dsh', name)
       await mkdir(dirname(file), { recursive: true })
@@ -34,6 +47,31 @@ function seedWorkspace(
   }
 }
 
+/** Seed one real plaintext JSONL session for the `/resume` selector and host handoff smoke. */
+async function seedResumeSession(cwd: string): Promise<void> {
+  const sessionCwd = realpathSync.native(cwd)
+  const id = SessionId('resume-target')
+  const meta: SessionHeader = { version: 0, id, createdAt: 1_700_000_000_000, cwd: sessionCwd }
+  const events: SessionEvent[] = [
+    { type: 'turn/start', seq: 0, time: 1_700_000_000_001, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    { type: 'user/message', seq: 1, time: 1_700_000_000_002, data: { content: [{ type: 'text', text: 'persisted prompt' }], source: { kind: 'user' } }, surfaceOp: 'append' },
+    { type: 'step/start', seq: 2, time: 1_700_000_000_003, data: { turn: 1, step: 1 } },
+    { type: 'request/header', seq: 3, time: 1_700_000_000_004, data: { header: { config: { provider: 'tui-scripted', model: 'tui-scripted-model' } }, reason: 'initial' } },
+    { type: 'assistant/message', seq: 4, time: 1_700_000_000_005, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'persisted answer' }], provenance: { provider: 'tui-scripted', model: 'tui-scripted-model' } }, surfaceOp: 'append' },
+    { type: 'step/end', seq: 5, time: 1_700_000_000_006, data: { turn: 1, step: 1 } },
+    { type: 'session/title', seq: 6, time: 1_700_000_000_007, data: { title: 'Resume selector design', messageSeqs: [1], source: { kind: 'fallback' } } },
+    { type: 'todo/write', seq: 7, time: 1_700_000_000_008, data: { todos: [{ content: 'Preserve restored state', status: 'in_progress' }] } },
+    { type: 'turn/end', seq: 8, time: 1_700_000_000_009, data: { turn: 1, reason: { kind: 'completed' } } },
+  ]
+  const file = logPath(join(cwd, '.sessions'), sessionCwd, id, 'none')
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, [
+    JSON.stringify(toHeaderLine(meta)),
+    ...events.map(event => JSON.stringify(event)),
+    '',
+  ].join('\n'))
+}
+
 /** The rendered system prompt from the first `request/header` in the workspace's persisted session log. */
 async function readLoggedSystemPrompt(cwd: string): Promise<string> {
   const sessionsDir = join(cwd, '.sessions')
@@ -77,14 +115,16 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
     const output = await smoke({
       label: 'tui-agent boot',
       actions: [
-        { waitFor: 'main-session-', send: '/plan\r' },
-        { waitFor: 'Entering plan mode (applies from the next step).', send: '/exit\r' },
+        { waitFor: 'main-session-', send: '/plan' },
+        { waitFor: '[off|message] — Enter or leave plan mode', send: '\r' },
+        { waitFor: 'Entering plan mode (applies from the next step). Use /plan off to leave.', send: '/exit\r' },
       ],
     })
     expect(output).toContain('DEEPSEEK')
     expect(output).toContain('HARNESS')
     expect(output).toContain('main-session-')
-    expect(output).toContain('Entering plan mode (applies from the next step).')
+    expect(output).toContain('[off|message] — Enter or leave plan mode')
+    expect(output).toContain('Entering plan mode (applies from the next step). Use /plan off to leave.')
     // Borderless: no box-drawing frame around the banner.
     expect(output).not.toContain('╭')
     expect(output).not.toContain('╮')
@@ -110,12 +150,16 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
         // window title as `<session title> — <configured title>` via OSC 0.
         // Gating /status on it keeps the assertion race-free; the diagnostics
         // card is then exercised through the same real Loader/PTY composition.
-        { waitFor: 'scripted session title — DeepSeek Harness', send: '/status\r' },
+        { waitFor: 'scripted session title — DeepSeek Harness', send: '/plan off\r' },
+        { waitFor: 'Leaving plan mode (applies from the next step).', send: 'Confirm the scripted run left plan mode.\r' },
+        { waitFor: 'Default mode confirmed.', send: '/status\r' },
         { waitFor: 'Session status', send: '/exit\r' },
       ],
     })
     expect(output).toContain('I need one decision before I continue.')
-    expect(output).toContain('Entering plan mode (applies from the next step).')
+    expect(output).toContain('Entering plan mode (applies from the next step). Use /plan off to leave.')
+    expect(output).toContain('Leaving plan mode (applies from the next step).')
+    expect(output).toContain('Default mode confirmed.')
     expect(output).toContain(String.raw`\x1b]2;MODEL_CONTROLLED\x07`)
     expect(output).toContain(String.raw`\x1b[999CMODEL_CURSOR`)
     expect(output).toContain(String.raw`\x9b31mMODEL_C1`)
@@ -168,6 +212,27 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
     expect(output).toContain('\u001B[?2004l')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
+  it('fuzzy-completes an @file path without reading or submitting the file', async () => {
+    const output = await smoke({
+      label: 'tui-agent file autocomplete',
+      tempDirPrefix: 'tui-agent-file-autocomplete-',
+      prepare: seedWorkspace({
+        workspace: {
+          'src/terminal-special-case.ts': 'export const marker = true\n',
+          'src/other.ts': 'export const other = true\n',
+        },
+      }),
+      actions: [
+        { waitFor: 'main-session-', send: '@tsc' },
+        { waitFor: 'File · terminal-special-case.t', send: '\t' },
+        { waitFor: '@src/terminal-special-case.ts', send: '\x03/exit\r' },
+      ],
+    })
+    expect(output).toContain('File · terminal-special-case.t')
+    expect(output).toContain('@src/terminal-special-case.ts')
+    expect(output).toContain('\u001B[?2004l')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('boots the Code Mode overlay tree, renders its banner, and exits cleanly', async () => {
     // The overlay's only keyless composition proof: the include+patch tree,
     // worker code runtime, and one-tool registry all mount before the banner.
@@ -181,21 +246,30 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
     expect(output).toContain('\u001B[?2004l')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
-  it('prints a config-resume failure and exits instead of leaving a blank terminal', async () => {
-    const output = await smoke({
-      label: 'tui-agent resume failure',
-      tempDirPrefix: 'tui-agent-resume-',
-      env: {
-        DEEPSEEK_API_KEY: 'keyless-tui-no-call',
-        RESUME_SESSION_ID: 'missing-session',
-      },
-      expectedExitCode: 1,
-    })
-    expect(output).toContain('ui-tui: session "missing-session" failed to start:')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })
 
 describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
+  it('exec-replaces the TUI for /resume and restores the same session state', async () => {
+    const output = await smoke({
+      label: 'dsh in-place resume',
+      tempDirPrefix: 'dsh-in-place-resume-',
+      binScript: dshBinScript,
+      configArgs: [scriptedConfigPath],
+      prepare: seedResumeSession,
+      actions: [
+        { waitFor: 'scripted TUI ready.', send: '/resume\r' },
+        { waitFor: 'Resume selector design', send: 'Resume selector design' },
+        { waitFor: '⌕ Resume selector design', send: '\r' },
+        { waitFor: 'Preserve restored state', send: '/exit\r' },
+      ],
+    })
+    const released = output.indexOf('\u001B[?2004l')
+    const restored = output.indexOf('Resume selector design — DeepSeek Harness')
+    expect(released).toBeGreaterThanOrEqual(0)
+    expect(restored).toBeGreaterThan(released)
+    expect(output).toContain('Preserve restored state')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('boots the shipped default config with no arguments and no personal overlay', async () => {
     const output = await smoke({
       label: 'dsh default boot',
@@ -255,9 +329,9 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
 
   it('routes the --resume flag into the config resume intake, failing loud on a missing id', async () => {
     // The flag path end to end: apps/cli parses `--resume missing-session` and
-    // sets RESUME_SESSION_ID, the shipped config's `!!js` reads it, and the
-    // resume fails loud — proving the printed `dsh --resume <id>` hint reaches
-    // the same intake as the env var.
+    // provides the id on the boot context, the shipped config's `!!js` reads it
+    // as a bare identifier, and the resume fails loud — proving the printed
+    // `dsh --resume <id>` hint reaches the config resume intake with no env var.
     const output = await smoke({
       label: 'dsh resume flag failure',
       tempDirPrefix: 'dsh-resume-flag-',
diff --git a/examples/tui-agent/tests/tui.snapshot.ts b/examples/tui-agent/tests/tui.snapshot.ts
index a36b004def..26ba64f23b 100644
--- a/examples/tui-agent/tests/tui.snapshot.ts
+++ b/examples/tui-agent/tests/tui.snapshot.ts
@@ -26,7 +26,7 @@ import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as ToolRalph from '@deepseek-ai/dsh-tool-ralph'
 import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
-import { createTuiChat } from '@deepseek-ai/dsh-tui'
+import { createTuiChat, FILE_REFERENCE_PROMPT } from '@deepseek-ai/dsh-tui'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-workerthread'
 import { HeadlessTerminal } from '../../../packages/ui/tui/tests/headless-terminal.ts'
@@ -47,6 +47,7 @@ interface Scenario {
   expectedEventCounts?: Record<string, number>
   childSessions?: number
   enterPlanMode?: boolean
+  leavePlanModeAfterFirstTurn?: boolean
   recorded: boolean
   seedWorkspace?: boolean
   /**
@@ -62,8 +63,9 @@ const SCENARIOS: Scenario[] = [
     name: 'multi-turn-conversation',
     composition: 'native',
     expectedTools: [],
-    expectedEventCounts: { 'plan/mode': 1 },
+    expectedEventCounts: { 'plan/mode': 2 },
     enterPlanMode: true,
+    leavePlanModeAfterFirstTurn: true,
     recorded: true,
   },
   {
@@ -294,6 +296,12 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
       remainingPrompts = prompts.slice(1)
     }
 
+    if (scenario.leavePlanModeAfterFirstTurn === true) {
+      terminal.send('/plan off')
+      terminal.send('\r')
+      await settleTerminal(terminal)
+    }
+
     for (const prompt of remainingPrompts) {
       terminal.send(prompt)
       terminal.send('\r')
@@ -302,14 +310,18 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
     }
 
     const events: SessionEvent[] = [...agent.session.events]
+    const firstHeader = events.find(event => event.type === 'request/header')
+    expect(firstHeader?.type === 'request/header' && firstHeader.data.header.system)
+      .toContain(FILE_REFERENCE_PROMPT)
     expect(events.filter(event => event.type === 'tool/call').map(event => event.data.name)).toEqual(scenario.expectedTools)
     for (const [type, count] of Object.entries(scenario.expectedEventCounts ?? {})) {
       expect(events.filter(event => event.type === type), `${scenario.name} must emit ${type}`).toHaveLength(count)
     }
     if (scenario.enterPlanMode === true) {
-      expect(ctx.planMode.get(agent)).toEqual({ active: true })
+      expect(ctx.planMode.get(agent)).toEqual({
+        active: scenario.leavePlanModeAfterFirstTurn !== true,
+      })
       const planMode = events.find(event => event.type === 'plan/mode')
-      const firstHeader = events.find(event => event.type === 'request/header')
       if (planMode === undefined || firstHeader === undefined) {
         throw new Error('plan-mode command snapshot needs plan/mode before its first request/header')
       }
@@ -318,6 +330,20 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
       const firstMessage = events.find(event => event.type === 'user/message')
       expect(firstMessage?.data.content).toEqual([{ type: 'text', text: prompts[0] }])
     }
+    if (scenario.leavePlanModeAfterFirstTurn === true) {
+      const planModes = events.filter(event => event.type === 'plan/mode')
+      expect(planModes.map(event => event.data.active)).toEqual([true, false])
+      const headers = events.filter(event => event.type === 'request/header')
+      const exit = planModes[1]
+      const afterExit = headers[1]
+      if (exit === undefined || afterExit === undefined) {
+        throw new Error('active plan exit snapshot needs a committed exit and changed request header')
+      }
+      expect(exit.seq).toBeLessThan(afterExit.seq)
+      expect(afterExit.data.header.system).not.toContain('Snapshot plan mode instructions.')
+      expect(events.filter(event => event.type === 'user/message' && event.data.source.kind === 'plugin').map(event => (event.data as { content: unknown }).content))
+        .toContainEqual([{ type: 'text', text: 'The user switched this session back to the default mode.' }])
+    }
     expect(events.filter(event => event.type === 'tool/result').every(event => !event.data.isError)).toBe(true)
     expect(events.filter(event => event.type === 'turn/end').every(event => event.data.reason.kind !== 'error')).toBe(true)
     if (scenario.name === 'dynamic-workflow' || scenario.name === 'cordis-dynamic-toolchain') {
diff --git a/knip.json b/knip.json
index 3a7a443718..59658e1df6 100644
--- a/knip.json
+++ b/knip.json
@@ -66,15 +66,11 @@
     },
     "packages/host/runtime": {
       "entry": [
-        "tests/**/*.spec.ts",
-        "tests/**/*.e2e.ts"
+        "tests/**/*.spec.ts"
       ],
       "project": [
         "src/**/*.ts",
         "tests/**/*.ts"
-      ],
-      "ignoreDependencies": [
-        "@deepseek-ai/dsh-client-.+"
       ]
     },
     "packages/client/web-ui": {
@@ -273,6 +269,10 @@
         "tests/**/*.ts"
       ]
     },
+    "packages/session-query/session-query-sqlite": {
+      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"]
+    },
     "packages/code-runtime/code-runtime-worker": {
       "entry": [
         "tests/**/*.spec.ts",
@@ -387,8 +387,14 @@
       ]
     },
     "packages/examples/agent-spine-demo": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/ui/jsonrpc": {
       "entry": [
@@ -544,21 +550,21 @@
         "tests/**/*.tsx"
       ],
       "ignoreDependencies": [
-        "@deepseek-ai/dsh-client-ui-theme",
-        "@deepseek-ai/dsh-client-connection"
+        "@deepseek-ai/dsh-client-ui-theme"
       ]
     },
     "apps/web": {
       "entry": [
         "tests/**/*.e2e.ts",
-        "tests/support.ts"
+        "tests/**/*.snapshot.ts",
+        "tests/support.ts",
+        "src/node-module-stub.ts"
       ],
       "project": [
         "src/**/*.ts",
         "tests/**/*.ts"
       ],
       "ignoreDependencies": [
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-ui-primitives",
         "@deepseek-ai/dsh-client-ui-slots",
         "@deepseek-ai/dsh-client-web-react",
@@ -567,6 +573,32 @@
         "react",
         "react-dom"
       ]
+    },
+    "apps/cli": {
+      "project": [
+        "src/**/*.ts"
+      ],
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-client-.+"
+      ]
+    },
+    "packages/client/modules": {
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
+    "packages/client/hmr": {
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     }
   }
 }
diff --git a/package.json b/package.json
index 38db3a2ac7..3ff149b80a 100644
--- a/package.json
+++ b/package.json
@@ -89,12 +89,13 @@
     "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",
-    "demo:headless": "node --expose-internals --import tsx packages/examples/cli-demo/src/bin.ts --config examples/headless-agent/cordis.yml",
-    "demo:tui": "node --expose-internals --import tsx 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 apps/cli/src/bin.ts",
     "demo:code-mode": "node scripts/demo-code-mode.mjs",
-    "demo:cordis": "node --expose-internals --import tsx packages/examples/tui-demo/src/bin.ts examples/cordis-agent/cordis.yml",
+    "demo:cordis": "node --import tsx packages/examples/tui-demo/src/bin.ts examples/cordis-agent/cordis.yml",
     "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
-    "demo:web": "npm run build:web && node --import tsx apps/cli/src/bin.ts web",
+    "demo:web": "npm run build && npm run build:web && node --import tsx apps/cli/src/bin.ts web",
+    "dev:web": "tsx scripts/dev-web.ts --poll",
     "postinstall": "node scripts/install-lefthook.mjs"
   },
   "devDependencies": {
@@ -121,7 +122,6 @@
     "mermaid": "11.16.0",
     "micromark-extension-gfm": "^3.0.0",
     "publint": "^0.3.21",
-    "saxes": "^6.0.0",
     "tsdown": "^0.22.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
diff --git a/packages/README.md b/packages/README.md
index b138ea0b65..4e18d7b5f8 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -32,7 +32,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`cordis/`](cordis/README.md) | Self-referential runtime toolset: 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)) | 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 capability family: the seam + JSONL/SQLite backends | Product — stable surface |
-| [`session-query/`](session-query/README.md) | Session retrieval: logical corpus, bounded reads, lineage, and event relationships | 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, shared LLM policy, and opt-in providers | Product — stable surface |
 | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md
index f83df567f4..e58145ee67 100644
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -49,6 +49,8 @@ The overlay is computed from the current `ToolExecution` and passed through the
 
 Result text contains stdout, an optional `[stderr]` section, then applicable sandbox-denial, timeout, signal, exit-code, and truncation markers. Timeout is reported independently of final exit status; nonzero exit remains a model-interpreted result rather than `isError`. Truncation links a safe complete spill file or reports it unavailable. Only infrastructure failures such as spawn errors and aborts produce `isError`.
 
+The canonical success is `{ kind: 'foreground', ...BashRunResult }` for a completed foreground process or `{ kind: 'background', taskId }` for a published task. The Native renderer preserves the text above, including exactly `started background task <id>`; programmatic consumers use the typed fields without parsing those strings. Executor stream caps remain acquisition limits on `BashRunResult` and carry their spill paths.
+
 When `run_in_background` is true, this plugin preflights `ctx.tasks.start()` before spawning, registers the calling agent as owner, and adapts the returned `BashProcess` handle into generic cancel/done/incremental-output hooks. The task runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps bash exit/sandbox facts into task output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time.
 
 ## UI presentation
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index 094e594661..81770b1595 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -11,8 +11,9 @@
 import { Service, type Context } from 'cordis'
 import z from 'schemastery'
 import { isAbsolute, resolve as resolvePath } from 'node:path'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineTool, TOOL_ABORTED } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, TerminalCallView, ToolExecution, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools'
+import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-session-persistence'
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -22,7 +23,7 @@ import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandb
 import { ESCALATION_TARGETS, approveEscalation, canonicalPath, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-bash'
-import type { DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-bash'
+import type { BashRunResult, DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-bash'
 import { DSH_HOME_ENV, resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { processOutcome } from './background.ts'
 import { parseExitStatus, renderProcessRead, renderResult } from './render.ts'
@@ -206,7 +207,7 @@ export class BashEnvRegistry extends Service {
   }
 }
 
-/** Parsed tool args; execute validates value constraints absent from SchemaSpec. */
+/** Parsed tool args; execute validates value constraints absent from ParameterSchemaSpec. */
 interface BashToolArgs {
   command: string
   description: string
@@ -318,6 +319,38 @@ function resolveWorkdir(
   return modelWorkdir
 }
 
+/** Detach the executor DTO from readonly seam interfaces into plain JSON data. */
+function canonicalBashResult(result: BashRunResult) {
+  const output = (stream: BashRunResult['stdout']) => ({
+    text: stream.text,
+    truncated: stream.truncated,
+    ...stream.spillPath !== undefined ? { spillPath: stream.spillPath } : {},
+  })
+  return {
+    exitCode: result.exitCode,
+    signal: result.signal,
+    timedOut: result.timedOut,
+    aborted: result.aborted,
+    timeoutMs: result.timeoutMs,
+    stdout: output(result.stdout),
+    stderr: output(result.stderr),
+    ...result.sandbox !== undefined ? {
+      sandbox: {
+        mode: result.sandbox.mode,
+        denied: result.sandbox.denied,
+        ...result.sandbox.enforcement !== undefined ? { enforcement: result.sandbox.enforcement } : {},
+        ...result.sandbox.runnerFailed !== undefined ? { runnerFailed: result.sandbox.runnerFailed } : {},
+      },
+    } : {},
+  }
+}
+
+/** Canonical background-handle properties shared by the bash output union. */
+const BACKGROUND_OUTPUT_PROPERTIES = {
+  kind: { type: 'string', required: true, const: 'background' },
+  taskId: { type: 'string', required: true },
+} as const
+
 export function apply(ctx: Context, config: Config = {}): void {
   const bashEnv = new BashEnvRegistry(ctx, config)
   bashEnv.register({
@@ -415,6 +448,65 @@ export function apply(ctx: Context, config: Config = {}): void {
         },
       } : {},
     },
+    output: {
+      schema: {
+        oneOf: [
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: BACKGROUND_OUTPUT_PROPERTIES,
+          },
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'foreground' },
+              exitCode: { required: true, oneOf: [{ type: 'integer' }, { type: 'null' }] },
+              signal: { required: true, oneOf: [{ type: 'string' }, { type: 'null' }] },
+              timedOut: { type: 'boolean', required: true },
+              aborted: { type: 'boolean', required: true },
+              timeoutMs: { type: 'number', required: true },
+              stdout: {
+                type: 'object',
+                additionalProperties: false,
+                required: true,
+                properties: {
+                  text: { type: 'string', required: true },
+                  truncated: { type: 'boolean', required: true },
+                  spillPath: { type: 'string' },
+                },
+              },
+              stderr: {
+                type: 'object',
+                additionalProperties: false,
+                required: true,
+                properties: {
+                  text: { type: 'string', required: true },
+                  truncated: { type: 'boolean', required: true },
+                  spillPath: { type: 'string' },
+                },
+              },
+              sandbox: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  mode: { type: 'string', required: true },
+                  denied: { type: 'boolean', required: true },
+                  enforcement: { type: 'string' },
+                  runnerFailed: { type: 'boolean' },
+                },
+              },
+            },
+          },
+        ],
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.kind === 'background'
+          ? `started background task ${value.taskId}`
+          : renderResult(value as { kind: 'foreground' } & BashRunResult, escalationModes),
+      }],
+    },
     async execute(args: BashToolArgs, exec) {
       validateBashArgs(args)
       // Description is display metadata; workdir defaults to the caller's session.
@@ -444,7 +536,11 @@ export function apply(ctx: Context, config: Config = {}): void {
           throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
         }
         // The caller owns cancellation until TaskService commits detached ownership.
-        if (exec.signal.aborted) return []
+        if (exec.signal.aborted) {
+          const error = new HarnessError('tool call aborted', TOOL_ABORTED)
+          error.name = 'AbortError'
+          throw error
+        }
         // Task preflight finishes before the starter can spawn a process.
         const id = tasks.start({
           kind: 'bash',
@@ -459,14 +555,14 @@ export function apply(ctx: Context, config: Config = {}): void {
             }
           },
         })
-        return [{ type: 'text', text: `started background task ${id}` }]
+        return { kind: 'background' as const, taskId: id }
       }
       const result = await ctx.bash.run(ctx.bash.resolve({
         ...request,
         signal: exec.signal,
       }))
       if (result.aborted) throw new Error('command aborted')
-      return [{ type: 'text', text: renderResult(result, escalationModes) }]
+      return { kind: 'foreground' as const, ...canonicalBashResult(result) }
     },
     presentCall: presentBashCall,
     presentResult: presentBashResult,
diff --git a/packages/bash/tool-bash/tests/integration.spec.ts b/packages/bash/tool-bash/tests/integration.spec.ts
index 7d04dfe952..8adf2165e0 100644
--- a/packages/bash/tool-bash/tests/integration.spec.ts
+++ b/packages/bash/tool-bash/tests/integration.spec.ts
@@ -109,7 +109,7 @@ describe('bash tool through the agent loop', () => {
     const location = ctx.sessionPersistence.locate(agent.session.header)
     expect(location?.kind).toBe('jsonl')
 
-    agent.send([{ type: 'text', text: 'inspect the current session' }])
+    agent.followup([{ type: 'text', text: 'inspect the current session' }])
     await waitForIdle(ctx, agent)
 
     const result = findEvent(events(agent), 'tool/result')
@@ -128,7 +128,7 @@ describe('bash tool through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-fg'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'run echo integration-ok' }])
+    agent.followup([{ type: 'text', text: 'run echo integration-ok' }])
     await waitForIdle(ctx, agent)
 
     const log = events(agent)
@@ -160,7 +160,7 @@ describe('bash tool through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-exit'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'run exit 9' }])
+    agent.followup([{ type: 'text', text: 'run exit 9' }])
     await waitForIdle(ctx, agent)
 
     const toolResult = findEvent(events(agent), 'tool/result')
@@ -168,7 +168,7 @@ describe('bash tool through the agent loop', () => {
     expect(resultText(toolResult)).toContain('[exit code: 9]')
   })
 
-  it('background: start ack → completion notice as context/message → task_output collects it', async () => {
+  it('background: start ack → completion notice as user/message → task_output collects it', async () => {
     // The task id is deterministic (a fresh TaskService counts per kind from 1),
     // so the script can name `bash-1` without threading a generated id.
     const adapter = new MockAdapter([
@@ -180,7 +180,7 @@ describe('bash tool through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-bg'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'run echo bg-ok in the background' }])
+    agent.followup([{ type: 'text', text: 'run echo bg-ok in the background' }])
     await waitForIdle(ctx, agent)
 
     const firstResult = findEvent(events(agent), 'tool/result')
@@ -188,17 +188,19 @@ describe('bash tool through the agent loop', () => {
     expect(resultText(firstResult)).toBe('started background task bash-1')
 
     // The task settles on its own; the tool-tasks notice listener injects a
-    // durable context/message into the owning agent's session (settlement may
-    // race turn end, so poll for it).
-    await pollUntil(() => events(agent).some(event => event.type === 'context/message'))
-    const notice = findEvent(events(agent), 'context/message')
+    // durable plugin-sourced user/message into the owning agent's session
+    // (settlement may race turn end, so poll for it).
+    const isNotice = (e: SessionEvent): e is SessionEvent<'user/message'> =>
+      e.type === 'user/message' && e.data.source.kind === 'plugin'
+    await pollUntil(() => events(agent).some(isNotice))
+    const notice = events(agent).find(isNotice)!
     expect(notice.data.content.some(
       block => block.type === 'text' && block.text.includes('background task bash-1 (bash: echo bg-ok) finished'),
     )).toBe(true)
     expect(notice.data.source).toEqual({ kind: 'plugin', plugin: 'tool-tasks' })
 
     // The next turn collects the output through the generic task tool.
-    agent.send([{ type: 'text', text: 'collect it' }])
+    agent.followup([{ type: 'text', text: 'collect it' }])
     await waitForIdle(ctx, agent)
     const readResult = findEvent(events(agent), 'tool/result', 'last')
     expect(readResult.data.isError).toBe(false)
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index f430ca07a1..8811da6ca0 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -122,7 +122,13 @@ class RecordingSandboxExecutor extends BashExecutor {
       timeoutMs: spec.timeoutMs,
       stdout: { text: 'ok', truncated: false },
       stderr: { text: '', truncated: false },
-      sandbox: { mode: spec.sandboxPolicy?.mode ?? 'read-only', denied: false },
+      sandbox: {
+        mode: spec.sandboxPolicy?.mode ?? 'read-only',
+        denied: false,
+        ...spec.command === 'without optional sandbox facts'
+          ? {}
+          : { enforcement: 'full' as const, runnerFailed: false },
+      },
     })
   }
 
@@ -213,6 +219,16 @@ describe('bash tool', () => {
     const ctx = await setup()
     const result = await call(ctx, 'bash', { command: 'echo hello', description: 'test command' })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected bash success')
+    expect(result.value).toMatchObject({
+      kind: 'foreground',
+      exitCode: 0,
+      signal: null,
+      timedOut: false,
+      aborted: false,
+      stdout: { text: 'hello\n', truncated: false },
+      stderr: { text: '', truncated: false },
+    })
     expect(text(result)).toBe('hello\n')
   })
 
@@ -296,7 +312,7 @@ describe('bash tool', () => {
   })
 
   // Type and required-key violations are rejected by the harness
-  // (defineTool validates against the SchemaSpec — the arg-validation Agent Note) before execute.
+  // (defineTool validates against the ParameterSchemaSpec — the arg-validation Agent Note) before execute.
   it.each([
     [{}, /missing required property "command"/],
     [{ command: 42, description: 'd' }, /"command" must be a string/],
@@ -312,7 +328,7 @@ describe('bash tool', () => {
     expect(text(result)).toMatch(pattern)
   })
 
-  // Value constraints the SchemaSpec can't express stay in the tool body.
+  // Value constraints the ParameterSchemaSpec can't express stay in the tool body.
   it.each([
     [{ command: '  ', description: 'd' }, /invalid command/],
     [{ command: 'x', description: '   ' }, /invalid description/],
@@ -408,6 +424,8 @@ describe('background execution through the task runtime', () => {
     const ctx = await setupWithTasks()
     const started = await call(ctx, 'bash', { command: 'echo bg-ok', description: 'test command', run_in_background: true })
     expect(started.isError).toBe(false)
+    if (started.isError) throw new Error('expected background bash success')
+    expect(started.value).toEqual({ kind: 'background', taskId: 'bash-1' })
     expect(text(started)).toBe('started background task bash-1')
 
     const read = await callUntilText(ctx, 'task_output', { task_id: 'bash-1' }, 'bg-ok')
@@ -479,7 +497,10 @@ describe('background execution through the task runtime', () => {
       signal: controller.signal,
     })
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(result.error).toEqual({
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    })
     expect(text(result)).toBe('Error: tool call aborted before dispatch')
     expect((ctx.bash as CountingStartExecutor).starts).toBe(0)
   })
@@ -633,7 +654,10 @@ describe('sandbox escalation through the generic task producer', () => {
       signal: controller.signal,
     })
 
-    expect(result.error).toEqual({ name: 'AbortError', code: TOOL_ABORTED })
+    expect(result.error).toEqual({
+      message: 'tool call aborted',
+      info: { name: 'AbortError', code: TOOL_ABORTED },
+    })
     expect(text(result)).toBe('Error: tool call aborted')
     expect(start).not.toHaveBeenCalled()
   })
@@ -647,6 +671,22 @@ describe('sandbox escalation through the generic task producer', () => {
     expect(bash.modes).toEqual(['workspace-write', 'danger-full-access'])
   })
 
+  it('omits sandbox facts the executor did not acquire from the canonical result', async () => {
+    const { ctx } = await setupSandboxed()
+    const result = await call(ctx, 'bash', {
+      command: 'without optional sandbox facts',
+      description: 'exercise optional sandbox facts',
+    })
+
+    if (result.isError) throw new Error('expected foreground bash success')
+    expect(result.value).toMatchObject({
+      kind: 'foreground',
+      sandbox: { mode: 'read-only', denied: false },
+    })
+    expect((result.value as { sandbox: object }).sandbox).not.toHaveProperty('enforcement')
+    expect((result.value as { sandbox: object }).sandbox).not.toHaveProperty('runnerFailed')
+  })
+
   it('keeps the exhaustiveness backstop for a rogue approval implementation', async () => {
     const { ctx } = await setupSandboxed(true)
     ctx.approval.request = () => Promise.resolve('rogue' as ApprovalOutcome)
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index d3011ed85f..5bde15dc2c 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.
+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'`).
 3. **Component props are the four shares, all derived**: `PropsRuntime<K>` (SlotMap: owner params + `useSession`/`sessionId` on session scope + `useSessions`) & `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`, `useStore`, `renderSlot` are the four seats. 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.
@@ -20,9 +20,9 @@ The [slot system standard](../../.agents/notes/implemented/architecture/2026-07-
 
 The `/client` surface of a UI plugin package is a contract face, not a convenience barrel. Three rules, enforced package-wide (do not restate them as per-file comments):
 
-1. **A UI plugin exports no values beyond what cordis loading needs** — `apply` / `inject` (and `Config` where present), plus store factories consumed type-only by components (`ReturnType<typeof createXXXStore>`). Types are the extra allowance: contract types (owner shares, injected shapes, view/toolview entry types) export freely. Implementation components, pure helpers, constants, and store handles stay internal. Adding any new value export requires user sign-off, not a matching consumer.
+1. **A UI plugin exports no values beyond what cordis loading needs** — `apply` / `inject` (and `Config` where present), plus store factories consumed type-only by components (`ReturnType<typeof createXXXStore>`). Types are the extra allowance: contract types (owner shares, injected shapes, composed props aliases) export freely. Implementation components, pure helpers, constants, and store handles stay internal. Adding any new value export requires user sign-off, not a matching consumer.
 2. **Same-package tests import internals directly** — relative `../src/client/xxx.ts` from package tests, or the `./src/*` subpath where a spec lives outside the package. Never widen the public surface to make a test compile.
-3. **Cross-package imports of another plugin's symbols are in principle forbidden.** The sanctioned routes are the slot system (register/renderSlot, the view and toolview registries) and ctx services. If neither fits, stop and escalate — do not add an export to unblock yourself.
+3. **Cross-package imports of another plugin's symbols are in principle forbidden.** The sanctioned routes are the slot system (register/renderSlot) and ctx services. If neither fits, stop and escalate — do not add an export to unblock yourself.
 
 ## ctx discipline (components never see ctx)
 
@@ -45,7 +45,7 @@ Non-negotiables across the layers:
 
 ## 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 the slot/view/toolview registries in `apply` — never module-level side effects.
+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.
 
 ## Styling
 
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index 9ea6ba6dfe..c7e1ed5c68 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -14,7 +14,10 @@ export type {
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
-export { RpcId } 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.
+export { RpcId, transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 export { AbstractApiClient } from '@deepseek-ai/dsh-host-apiproxy/client'
 export type { IApiClient } from '@deepseek-ai/dsh-host-apiproxy/client'
 export type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session/types'
@@ -31,16 +34,3 @@ import type { RpcResponse, RpcResult } from '@deepseek-ai/dsh-host-apiproxy/api'
 export function resultOf<T>(response: RpcResponse<T>): RpcResult<T> {
   return response.result
 }
-
-/**
- * Fold a transport exception into the RpcResult error branch (unified error
- * surface; 'internal' as the catch-all code).
- * @param error - the thrown value from the carrier.
- * @returns the error branch of an RpcResult.
- */
-export function transportError<T>(error: unknown): RpcResult<T> {
-  return {
-    ok: false,
-    error: { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} },
-  }
-}
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index bbf4809466..e1e21dfd78 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2,8 +2,8 @@
 // RpcRequest<P> and returns RpcResponse<T> (echoing the rpcId); streams yield RpcRequest<frame>
 // (the fixture IS the fake server, so it mints frame rpcIds); root respond takes ClientResponse
 // and returns RpcReceipt. fx-alpha carries a hand-built history script (60 turns, pageable);
-// prompt triggers a chunked streaming replay; cancel stops the replay; one resident pending
-// approval (placeholder-card material, subscribed-baseline-replay semantics: stable rpcId reuse).
+// prompt triggers a chunked streaming replay; cancel stops the replay; resident pending
+// approval/question requests exercise replay and composer takeover with stable rpcIds.
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
@@ -24,6 +24,28 @@ function text(t: string): ContentBlock[] {
   return [{ type: 'text', text: t }]
 }
 
+const MARKDOWN_FIXTURE = [
+  '# Markdown fixture',
+  '',
+  'Assistant output renders **strong text**, *emphasis*, and `inline code`.',
+  '',
+  '- first item',
+  '  - nested item',
+  '',
+  '| Surface | State |',
+  '| --- | --- |',
+  '| history | rendered |',
+  '| streaming | stable |',
+  '',
+  '[DeepSeek](https://www.deepseek.com)',
+  '',
+  '```ts',
+  'const markdown = true',
+  '```',
+].join('\n')
+
+const USER_MARKDOWN_LITERAL = '用户字面量：# 不渲染 `code` [link](https://example.com)'
+
 function sid(id: string): SessionId {
   return id as SessionId
 }
@@ -40,16 +62,28 @@ function buildAlphaLog(): SessionEvent[] {
   }
   for (let turn = 0; turn < 60; turn++) {
     push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
-    push({ type: 'user/message', surfaceOp: 'append', data: { content: text(`问题 ${turn}：fixture 历史消息，用于翻页与渲染验收。`), source: { kind: 'user' } } })
+    const userSeq = push({
+      type: 'user/message', surfaceOp: 'append',
+      data: {
+        content: text(turn === 59 ? USER_MARKDOWN_LITERAL : `问题 ${turn}：fixture 历史消息，用于翻页与渲染验收。`),
+        source: { kind: 'user' },
+      },
+    })
+    if (turn === 0) {
+      push({
+        type: 'session/title',
+        data: { title: 'Fixture 历史会话', messageSeqs: [userSeq], source: { kind: 'fallback' } },
+      })
+    }
     if (turn % 9 === 4) {
-      push({ type: 'context/message', surfaceOp: 'append', data: { content: text(`[fixture] 上下文注入（turn ${turn}）`), source: { kind: 'plugin', plugin: 'fixture' } } })
+      push({ type: 'user/message', surfaceOp: 'append', data: { content: text(`[fixture] 上下文注入（turn ${turn}）`), source: { kind: 'plugin', plugin: 'fixture' } } })
     }
     push({ type: 'step/start', data: { turn, step: 0 } })
     const withTool = turn % 5 === 2
     const withReasoning = turn % 3 === 1
     const blocks: ContentBlock[] = []
     if (withReasoning) blocks.push({ type: 'reasoning', text: `思考过程 ${turn}：这是一段可折叠的 reasoning 内容。` })
-    blocks.push({ type: 'text', text: `回答 ${turn}：这是 fixture 生成的历史回复正文。` })
+    blocks.push({ type: 'text', text: turn === 59 ? MARKDOWN_FIXTURE : `回答 ${turn}：这是 fixture 生成的历史回复正文。` })
     if (withTool) {
       const callId = `fx-call-${turn}`
       blocks.push({ type: 'tool-call', id: callId, name: 'echo', arguments: `{"text":"turn ${turn}"}` } as ContentBlock)
@@ -159,6 +193,20 @@ function viewFor(event: SessionEvent, log: readonly SessionEvent[]): ToolEventVi
   return undefined
 }
 
+/** Fold the latest fixture title into the host's control-frame projection. */
+function titleFrameOf(id: SessionId, log: readonly SessionEvent[]): Extract<MuxFrame, { type: 'session/title' }> | undefined {
+  const event = log.findLast(item => (item as { type: string }).type === 'session/title')
+  if (event === undefined) return undefined
+  const titleEvent = event as unknown as { seq: number; time: number; data: { title: string } }
+  return {
+    type: 'session/title',
+    sessionId: id,
+    title: titleEvent.data.title,
+    eventSeq: titleEvent.seq,
+    updatedAt: titleEvent.time,
+  }
+}
+
 /**
  * Message-boundary paging (mirrors the host's paging contract): count
  * maxMessages messages
@@ -253,6 +301,41 @@ export function createFixtureApi(): ApiProxy {
   const mint = (): ReturnType<typeof RpcId> => RpcId(`fx-rpc-${nextRpc++}`)
   /** Resident pending approval (stable rpcId: every mux open replays the same id, matching host replay semantics). */
   const pendingApprovalRpcId = mint()
+  const pendingQuestionRpcId = mint()
+  let questionPending = true
+  const fixtureQuestions: Extract<MuxFrame, { type: 'question/requested' }>['questions'] = [
+    {
+      id: 'harness-profile',
+      header: '偏好',
+      question: '你现在更想招哪类 Agent/Harness 候选人？',
+      options: [
+        { label: '工程落地型 (Recommended)', description: '更看重能直接做 runtime、tool executor、sandbox、trace 和线上问题排查。' },
+        { label: '研究潜力型', description: '更看重 Agent 理解、训练评测思路和长期成长空间。' },
+        { label: '均衡型', description: '同时要求工程能力和 Agent 认知，但可能筛选门槛更高。' },
+      ],
+    },
+    {
+      id: 'work-mode',
+      header: '方式',
+      question: '你希望候选人优先展示哪种工作方式？',
+      options: [
+        { label: '先做小型原型 (Recommended)', description: '用可运行结果尽快验证关键假设。' },
+        { label: '先写完整设计', description: '先收敛边界、协议和风险，再开始实现。' },
+      ],
+    },
+    {
+      id: 'signals',
+      header: '信号',
+      question: '哪些面试信号最重要？',
+      detail: '按当前招聘目标选择；跳过则视为不设偏好。',
+      multiSelect: true,
+      options: [
+        { label: '系统设计' },
+        { label: '代码质量' },
+        { label: 'Agent 产品判断' },
+      ],
+    },
+  ]
 
   const muxConns = new Set<StreamConn<MuxFrame>>()
   const hostConns = new Set<StreamConn<HostFrame>>()
@@ -298,6 +381,10 @@ export function createFixtureApi(): ApiProxy {
     emitMux(view === undefined
       ? { type: 'session/event', sessionId: id, event }
       : { type: 'session/event', sessionId: id, event, view })
+    if ((event as { type: string }).type === 'session/title') {
+      // The raw title is already in this log, so the latest-title fold must find it.
+      emitMux(titleFrameOf(id, log) as Extract<MuxFrame, { type: 'session/title' }>)
+    }
   }
 
   /** At most one in-flight replay per session; cancel clears it. */
@@ -326,6 +413,12 @@ export function createFixtureApi(): ApiProxy {
     appendUser(id: string, msg: string): void {
       append(sid(id), { type: 'user/message', surfaceOp: 'append', data: { content: text(msg), source: { kind: 'user' } } })
     },
+    /** Append a later durable title revision through the normal raw-event + control-frame path. */
+    appendTitle(id: string, title: string): void {
+      const log = logOf(sid(id))
+      const messageSeqs = log.filter(event => event.type === 'user/message').map(event => event.seq)
+      append(sid(id), { type: 'session/title', data: { title, messageSeqs, source: { kind: 'provider', provider: 'fixture' } } })
+    },
     /** Log append WITHOUT the mux emit: a frame lost in transit — history still serves it, the client must repull. */
     appendSilent(id: string, msg: string): void {
       const log = logOf(sid(id))
@@ -343,8 +436,8 @@ export function createFixtureApi(): ApiProxy {
     const step = 0
     append(id, { type: 'step/start', data: { turn, step } })
     append(id, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'block-start', index: 0, blockType: 'text' } } })
-    /* v8 ignore next -- the ?? arm needs a null match, but replyText is never empty (prompt always prefixes 回声). */
-    const pieces = replyText.match(/.{1,6}/gu) ?? [replyText]
+    /* v8 ignore next -- the ?? arm needs a null match, but every fixture reply is non-empty. */
+    const pieces = replyText.match(/[\s\S]{1,6}/gu) ?? [replyText]
     let i = 0
     const finish = (aborted: boolean): void => {
       replays.delete(id)
@@ -410,7 +503,13 @@ export function createFixtureApi(): ApiProxy {
         setRunning(id, true)
         append(id, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
         append(id, { type: 'user/message', surfaceOp: 'append', data: { content, source: { kind: 'user' } } })
-        startReply(id, turn, `回声：${userText}。这是 fixture 的流式回复，用于验证打字机增长与定稿切换。`)
+        startReply(
+          id,
+          turn,
+          userText === 'render markdown'
+            ? MARKDOWN_FIXTURE
+            : `回声：${userText}。这是 fixture 的流式回复，用于验证打字机增长与定稿切换。`,
+        )
         return ok(request, { accepted: true as const })
       },
       cancel: (request) => {
@@ -433,10 +532,12 @@ export function createFixtureApi(): ApiProxy {
         muxConns.add(conn)
         const breakNow = (): void => { conn.breakNow() }
         streamBreakers.add(breakNow)
-        // Open baseline: subscribed for attached (running) sessions + pending approval replay (stable rpcId).
+        // Open baseline: subscribed sessions + pending interactions replayed with stable rpcIds.
         for (const s of sessions) {
           if (!s.running) continue
           conn.push({ rpcId: mint(), payload: { type: 'session/subscribed', sessionId: s.sessionId, lastSeq: (logs.get(s.sessionId)?.length ?? 0) - 1 } })
+          const title = titleFrameOf(s.sessionId, logs.get(s.sessionId) ?? [])
+          if (title !== undefined) conn.push({ rpcId: mint(), payload: title })
         }
         conn.push({
           rpcId: pendingApprovalRpcId,
@@ -446,6 +547,14 @@ export function createFixtureApi(): ApiProxy {
             toolName: 'dangerous_tool', reason: 'fixture 常驻占位审批（可见不可答）',
           },
         })
+        if (questionPending) {
+          conn.push({
+            rpcId: pendingQuestionRpcId,
+            payload: {
+              type: 'question/requested', sessionId: sid('fx-alpha'), questions: fixtureQuestions,
+            },
+          })
+        }
         try {
           yield* conn.drain(signal)
         } finally {
@@ -475,9 +584,16 @@ export function createFixtureApi(): ApiProxy {
       },
     },
     respond(message: ClientResponse): Promise<RpcReceipt> {
-      // The v1 UI never answers (PendingCard is visible but not answerable); implemented for type completeness, always not-pending.
-      void message
-      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+      if (!questionPending || message.rpcId !== pendingQuestionRpcId) {
+        return Promise.resolve({ accepted: false, reason: 'not-pending' })
+      }
+      questionPending = false
+      emitMux({
+        type: 'question/resolved', sessionId: sid('fx-alpha'),
+        questionRpcId: pendingQuestionRpcId,
+        outcome: message.result.ok ? 'answered' : 'cancelled',
+      })
+      return Promise.resolve({ accepted: true })
     },
   }
 }
diff --git a/packages/client/connection/tests/fixture.spec.ts b/packages/client/connection/tests/fixture.spec.ts
index c50921a44d..ac32955c36 100644
--- a/packages/client/connection/tests/fixture.spec.ts
+++ b/packages/client/connection/tests/fixture.spec.ts
@@ -18,6 +18,7 @@ interface TimingHooks {
   setHistoryDelay(ms: number): void
   failNextHistory(): void
   appendUser(id: string, msg: string): void
+  appendTitle(id: string, title: string): void
   appendSilent(id: string, msg: string): void
   breakStreams(): void
 }
@@ -113,7 +114,7 @@ describe('createFixtureApi', () => {
     const missing = await api.sessions.prompt(req({ sessionId: sid('ghost'), mode: 'queue' as const, content: [{ type: 'text' as const, text: 'x' }] }))
     expect(missing.result).toMatchObject({ ok: false, error: { code: 'session-not-found', details: { sessionId: 'ghost' } } })
     // Real prompt: replay starts (running flips true), cancel freezes it.
-    const accepted = await api.sessions.prompt(req({ sessionId: id, mode: 'queue' as const, content: [{ type: 'text' as const, text: '取消我' }] }))
+    const accepted = await api.sessions.prompt(req({ sessionId: id, mode: 'queue' as const, content: [{ type: 'text' as const, text: 'render markdown' }] }))
     expect(accepted.result).toMatchObject({ ok: true, value: { accepted: true } })
     await new Promise(resolve => setTimeout(resolve, 120)) // a couple of typewriter ticks
     await api.sessions.cancel(req({ sessionId: id }))
@@ -148,14 +149,14 @@ describe('createFixtureApi', () => {
     expect(types.at(-1)).toBe('turn/end') // steer did not restart the turn
   })
 
-  it('mux open replays the baseline: subscribed for running sessions + the resident approval with a stable rpcId', async () => {
+  it('mux open replays subscribed sessions and resident interactions with stable rpcIds', async () => {
     const api = createFixtureApi()
     const openOnce = async (): Promise<RpcRequest<MuxFrame>[]> => {
       const abort = new AbortController()
       const envelopes: RpcRequest<MuxFrame>[] = []
       for await (const envelope of api.events.mux(req({}), abort.signal)) {
         envelopes.push(envelope)
-        if (envelopes.length >= 2) abort.abort()
+        if (envelopes.length >= 4) abort.abort()
       }
       return envelopes
     }
@@ -163,8 +164,11 @@ describe('createFixtureApi', () => {
     const second = await openOnce()
     expect(first[0]?.payload).toMatchObject({ type: 'session/subscribed', sessionId: 'fx-alpha' })
     expect((first[0]?.payload as { lastSeq: number }).lastSeq).toBeGreaterThan(0)
-    expect(first[1]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
-    expect(second[1]?.rpcId).toBe(first[1]?.rpcId) // stable rpcId across replays (host replay semantics)
+    expect(first[1]?.payload).toMatchObject({ type: 'session/title', sessionId: 'fx-alpha', title: 'Fixture 历史会话' })
+    expect(first[2]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
+    expect(second[2]?.rpcId).toBe(first[2]?.rpcId) // stable rpcId across replays (host replay semantics)
+    expect(first[3]?.payload).toMatchObject({ type: 'question/requested', sessionId: 'fx-alpha' })
+    expect(second[3]?.rpcId).toBe(first[3]?.rpcId)
   })
 
   it('steer with no replay in flight falls through to a fresh queued turn; non-text blocks stringify empty', async () => {
@@ -217,9 +221,38 @@ describe('createFixtureApi', () => {
     }
   })
 
-  it('respond is a typed stub: always not-pending', async () => {
+  it('respond resolves the resident question once and rejects duplicate or unrelated ids', async () => {
     const api = createFixtureApi()
     expect(await api.respond({ type: 'client-response', rpcId: RpcId('x'), result: { ok: true, value: {} } })).toEqual({ accepted: false, reason: 'not-pending' })
+    const abort = new AbortController()
+    let question: RpcRequest<MuxFrame> | undefined
+    for await (const envelope of api.events.mux(req({}), abort.signal)) {
+      if (envelope.payload.type !== 'question/requested') continue
+      question = envelope
+      abort.abort()
+    }
+    if (question === undefined) throw new Error('fixture question missing')
+    const response = { type: 'client-response' as const, rpcId: question.rpcId, result: { ok: true as const, value: {} } }
+    expect(await api.respond(response)).toEqual({ accepted: true })
+    expect(await api.respond(response)).toEqual({ accepted: false, reason: 'not-pending' })
+
+    const replayAbort = new AbortController()
+    const replayed = await collect(api.events.mux(req({}), replayAbort.signal), replayAbort, frames => frames.length === 2)
+    expect(replayed.every(frame => frame.type !== 'question/requested')).toBe(true)
+
+    const cancelledApi = createFixtureApi()
+    const cancelAbort = new AbortController()
+    let cancelQuestion: RpcRequest<MuxFrame> | undefined
+    for await (const envelope of cancelledApi.events.mux(req({}), cancelAbort.signal)) {
+      if (envelope.payload.type !== 'question/requested') continue
+      cancelQuestion = envelope
+      cancelAbort.abort()
+    }
+    if (cancelQuestion === undefined) throw new Error('fixture cancellation question missing')
+    expect(await cancelledApi.respond({
+      type: 'client-response', rpcId: cancelQuestion.rpcId,
+      result: { ok: false, error: { code: 'cancelled', message: 'skip', details: {} } },
+    })).toEqual({ accepted: true })
   })
 
   it('describe answers the fixture identity', async () => {
@@ -248,10 +281,15 @@ describe('createFixtureApi', () => {
     await new Promise(resolve => setTimeout(resolve, 10))
     hooks.appendSilent('fx-alpha', '静默丢帧')
     hooks.appendUser('fx-alpha', '正常直播')
+    hooks.appendTitle('fx-alpha', 'Fixture 修订标题')
     await vi.waitFor(() => {
       expect(seen.some(f => f.type === 'session/event' && JSON.stringify(f.event.data).includes('正常直播'))).toBe(true)
+      expect(seen.some(f => f.type === 'session/title' && f.title === 'Fixture 修订标题')).toBe(true)
     })
     expect(seen.some(f => f.type === 'session/event' && JSON.stringify(f.event.data).includes('静默丢帧'))).toBe(false)
+    const rawTitleIndex = seen.findIndex(f => f.type === 'session/event' && (f.event as { type: string }).type === 'session/title')
+    const titleControlIndex = seen.findIndex(f => f.type === 'session/title' && f.title === 'Fixture 修订标题')
+    expect(titleControlIndex).toBe(rawTitleIndex + 1)
     // But history serves the silent event (the client's repull finds it).
     const repull = await api.sessions.history(req({ sessionId: sid('fx-alpha'), maxMessages: 5 }))
     if (!repull.result.ok) throw new Error('repull failed')
diff --git a/packages/client/hmr/README.md b/packages/client/hmr/README.md
new file mode 100644
index 0000000000..f6fcd44dba
--- /dev/null
+++ b/packages/client/hmr/README.md
@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-client-hmr
+
+Hot reload for fetch-arrival client plugins. A static-arrival entry composed only into `--dev` graphs (`dsh web --dev`); production graphs omit the row, so the shell-bundled code stays inert.
+
+The plugin subscribes to the webserver's system SSE channel (`GET /plugins/events`) and reloads one plugin per `rebuilt` frame, serialized through a queue (the bundle handoff slot is single). The sequence per frame — `prefetch` (fetch the new bundle before touching anything), `invalidate`, `registry.delete` (before the fiber: a bare fiber dispose trips the vendored Loader's self-dispose branch, which would mark the entry disabled), drain the old fiber, delete `entry.fiber`, remove owned `<style data-plugin>` tags, `entry.refresh()` re-imports and remounts, `fiber.await()` rethrows startup failures loud. Dependents reload through cordis itself: a fiber's activation epoch strings its service providers' uids, so replacing a provider's fiber cascades every dependent with zero client-side graph analysis. Rebuild detection lives on the webserver: in dev mode it stat-polls each plugin's built `lib/client.js` (`fs.watchFile`) and broadcasts the `rebuilt` frame when the bundle's rev changes, so any tsdown watch process producing the bundle triggers HMR with no builder→host channel.
+
+## Model Experience
+
+None, as the reload driver is browser-side machinery; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Reload is coarse by design** — a fresh fiber and fresh components; React state inside the reloaded plugin is lost while the data layer (connection/runtime fibers, Session objects) is untouched. react-refresh-grade state preservation conflicts with "re-executing the bundle re-runs the factory" and is deliberately out.
+- **No failure rollback** — a reload that fails leaves the entry FAILED and loud in the loader status projection; restoring the previous bundle automatically is deferred until a real need shows.
+- **Graph rev is not refreshed by rebuilt frames** — the stale rev is harmless (the bundle endpoint serves no-cache); rev refresh lands with the reconnect-handshake mechanism.
diff --git a/packages/client/hmr/package.json b/packages/client/hmr/package.json
new file mode 100644
index 0000000000..129a7e879a
--- /dev/null
+++ b/packages/client/hmr/package.json
@@ -0,0 +1,51 @@
+{
+  "name": "@deepseek-ai/dsh-client-hmr",
+  "description": "Dev-only hot-reload driver for fetch-arrival client entries: SSE rebuilt frames → prefetch/invalidate → fiber swap through the vendored Loader entry",
+  "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": [],
+    "platform": "web",
+    "immediately": true
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-client-modules": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/hmr/src/client/index.ts b/packages/client/hmr/src/client/index.ts
new file mode 100644
index 0000000000..21df48b561
--- /dev/null
+++ b/packages/client/hmr/src/client/index.ts
@@ -0,0 +1,191 @@
+/**
+ * client-hmr, browser half: hot-reload driver for client plugin entries.
+ *
+ * Listens on the host's system SSE channel (`GET /plugins/events`); on a
+ * `rebuilt` frame it re-fetches the entry's bundle and swaps the cordis
+ * fiber in place. Every graph entry is a plugin bundle under the web2 model
+ * — `immediately` rows differ only in stage-one prefetch (a boot
+ * optimization), so all nine plugin packages share these reload semantics;
+ * normal packages (react family, cordis, shell, pure libs) are not entries
+ * and shell changes still mean a page reload. Cascade is zero-touch:
+ * downstream fibers key their activation epoch on provider fiber uids
+ * (vendor/cordis/src/fiber.ts `_refresh`), so replacing a provider fiber
+ * re-cascades natively — reloading a data-layer plugin (connection/runtime)
+ * cascades into its UI dependents with no HMR-side bookkeeping.
+ *
+ * Reload order (lazy CJS table): invalidate (drop the stale factory and
+ * materialized record) → prefetch (fetch + execute + register the fresh
+ * factory) → registry-first teardown → drain old fiber unload → remove
+ * owned `<style data-plugin>` tags → `entry.refresh()` materializes the new
+ * factory. Invalidate MUST precede prefetch: a live factory makes prefetch
+ * a no-op, and re-executing a bundle over an undeleted registration is a
+ * loud duplicate. The swap is safe because execution is pure registration
+ * under the lazy model — every module side effect (CSS injection included)
+ * lives in the factory closure and runs at materialization, inside
+ * refresh(). That also keeps the CSS ordering guarantee: owned styles are
+ * removed after the old fiber's disposers drained (SlotCore one-owner
+ * unregister) and before materialization re-injects tags under the same
+ * stable tag ids.
+ *
+ * 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
+ * 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.
+ *
+ * Why not the naive `entry.fiber.dispose()` → `entry.refresh()` path —
+ * confirmed against vendor sources:
+ * 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.
+ * 2. A bare `fiber.dispose()` lands in Loader's self-dispose branch
+ *    (vendor/loader/src/index.ts `internal/plugin` case 4: the registry
+ *    still holds the runtime at emit time), which flags the entry
+ *    `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
+ * `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
+ * per runtime, so `registry.delete` never collaterally disposes siblings.
+ *
+ * Self-reload: this plugin is itself a graph entry, so a rebuilt frame may
+ * name it. The in-flight reload keeps running in the old bundle's closure
+ * (its EventSource closes with the old fiber's effects); the new bundle's
+ * 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
+ * fiberless (the next rebuilt frame retries from scratch); an apply failure
+ * leaves a FAILED fiber for the shell's status projection. Both log loudly.
+ */
+import type { Context } from 'cordis'
+import type { Entry, Loader } from '@cordisjs/plugin-loader'
+import type { WebBootGraph } from '@deepseek-ai/dsh-client-modules'
+
+/**
+ * Frames on the `GET /plugins/events` system SSE channel (owned host-side by
+ * dsh-host-webserver's PluginEventFrame). Mirrored here because this is a
+ * wire boundary: frames arrive as JSON text and are validated at the parse
+ * point, not shared as a same-process typed seam.
+ */
+export type PluginsEventFrame =
+  | { type: 'graph'; graph: WebBootGraph }
+  | { type: 'rebuilt'; id: string; rev: string }
+
+/** System SSE endpoint pushing graph/rebuilt frames (wire protocol constant). */
+export const EVENTS_ENDPOINT = '/plugins/events'
+
+/** Cordis plugin name. */
+export const name = 'client-hmr'
+
+/** Required services: the vendored Loader (entry governance) and the client module system (boot provide, service name `modules`). */
+export const inject = ['loader', 'modules']
+
+/** Find the loader entry whose module specifier is `id` (entry tree ids are random; the package name lives in `options.name`). */
+function findEntry(loader: Loader, id: string): Entry | undefined {
+  for (const entry of loader.entries()) {
+    if (entry.options.name === id) return entry
+  }
+  return undefined
+}
+
+/** Remove every `<style data-plugin>` tag owned by `id` (attribute compared verbatim — no CSS-selector escaping pitfalls). */
+function removeOwnedStyles(id: string): void {
+  for (const el of document.querySelectorAll('style[data-plugin]')) {
+    if (el.getAttribute('data-plugin') === id) el.remove()
+  }
+}
+
+/**
+ * Mount the HMR driver: subscribe to the system SSE channel and hot-swap
+ * rebuilt entries.
+ * @param ctx - plugin context with `loader` and `modules` available.
+ */
+export function apply(ctx: Context): void {
+  // Both are declared injections (typed Context merges: `modules` from the
+  // client module loader package, `loader` from the vendored Loader).
+  const modLoader = ctx.modules
+  const loader: Loader = ctx.loader
+
+  async function reload(id: string): Promise<void> {
+    const entry = findEntry(loader, id)
+    if (entry === undefined) {
+      ctx.logger.warn(`client-hmr: rebuilt frame for unknown entry "${id}" (not in the loader tree)`)
+      return
+    }
+    // Invalidate first (drop stale factory + record — a live factory makes
+    // prefetch a no-op and re-registration a loud duplicate), then run the
+    // async half while the old fiber still serves: fetch + execute registers
+    // the fresh factory with zero side effects (lazy CJS — module bodies run
+    // at materialization, not execution).
+    modLoader.invalidate(id)
+    await modLoader.prefetch(id)
+
+    const oldFiber = entry.fiber
+    if (oldFiber !== undefined) {
+      // Registry-first teardown (see module comment): the runtime record must
+      // be gone before the fiber's disposer emits internal/plugin, or the
+      // Loader flags the entry disabled.
+      const runtime = oldFiber.runtime
+      if (runtime !== null) entry.ctx.registry.delete(runtime.callback)
+      // Drain the unload: effect disposers (slots, subscriptions) must finish
+      // before the new bundle executes and the new apply re-registers.
+      while (oldFiber.inertia !== undefined) await oldFiber.inertia
+      delete entry.fiber
+    }
+    // Old owned styles go before materialization re-injects them (the CSS
+    // idempotency guard keys on stable tag ids).
+    removeOwnedStyles(id)
+    // Re-init through the entry: fiber cleared above, so refresh() re-imports
+    // — materializing the prefetched factory (CSS injects here) — and
+    // 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).
+    await entry.fiber?.await()
+  }
+
+  // Serialize reloads: frames can arrive faster than a swap completes, and
+  // interleaved dispose/execute chains would corrupt the single-slot handoff.
+  let queue: Promise<void> = Promise.resolve()
+  const handle = (frame: PluginsEventFrame): void => {
+    switch (frame.type) {
+      case 'rebuilt':
+        queue = queue.then(() => reload(frame.id)).catch((error: unknown) => {
+          ctx.logger.error(`client-hmr: reload of "${frame.id}" failed`)
+          ctx.logger.error(error)
+        })
+        break
+      case 'graph':
+        // Connect-time snapshot, unused in v1. 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.
+        break
+      default:
+        // Merge-extensible frame union: unknown frame types from newer hosts
+        // are ignored by design.
+        break
+    }
+  }
+
+  ctx.effect(() => {
+    const source = new EventSource(EVENTS_ENDPOINT)
+    source.addEventListener('message', (event: MessageEvent<string>) => {
+      let frame: PluginsEventFrame
+      try {
+        frame = JSON.parse(event.data) as PluginsEventFrame
+      } catch {
+        // Wire boundary: a malformed dev-channel frame is dropped loudly.
+        ctx.logger.warn(`client-hmr: unparseable event frame: ${event.data}`)
+        return
+      }
+      handle(frame)
+    })
+    return () => { source.close() }
+  }, 'client-hmr: event source')
+}
diff --git a/packages/client/hmr/src/index.ts b/packages/client/hmr/src/index.ts
new file mode 100644
index 0000000000..cca3c0ddac
--- /dev/null
+++ b/packages/client/hmr/src/index.ts
@@ -0,0 +1,9 @@
+/**
+ * HMR plugin, node half. The package IS a dshClient plugin (dev-only row in
+ * the host graph): the reload driver lives in its client half in full
+ * (src/client/); the empty apply exists so the plugin appears in the host
+ * Loader (lifecycle governance + dshClient discovery).
+ */
+
+/** Host plugin body — no host-side behavior for the HMR plugin. */
+export function apply(): void {}
diff --git a/packages/client/hmr/src/invariant.ts b/packages/client/hmr/src/invariant.ts
new file mode 100644
index 0000000000..a4c546c991
--- /dev/null
+++ b/packages/client/hmr/src/invariant.ts
@@ -0,0 +1,33 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-hmr`.
+ * @module @deepseek-ai/dsh-client-hmr/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-hmr'
+
+/** Cordis companion plugin name. */
+export const name = 'client-hmr-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a dev-only reload driver — it consumes the loader
+ * entry tree and module cache but owns no events and no cross-plugin mutable
+ * state; reload correctness (dispose → style removal → re-execute ordering)
+ * is observable only through the assembled browser runtime, not a host-side
+ * event relation.
+ */
+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/hmr/tests/node-half.spec.ts b/packages/client/hmr/tests/node-half.spec.ts
new file mode 100644
index 0000000000..e340263b7a
--- /dev/null
+++ b/packages/client/hmr/tests/node-half.spec.ts
@@ -0,0 +1,14 @@
+/**
+ * Node half of the HMR plugin: an empty apply placeholder (the reload driver
+ * lives in the client half) whose only contract is mounting and disposing
+ * cleanly in the host Loader.
+ */
+import { describe, expect, it } from 'vitest'
+import { apply } from '@deepseek-ai/dsh-client-hmr'
+
+describe('hmr node half', () => {
+  it('apply is a no-op host placeholder', () => {
+    apply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+})
diff --git a/packages/client/hmr/tsconfig.json b/packages/client/hmr/tsconfig.json
new file mode 100644
index 0000000000..764741c9cb
--- /dev/null
+++ b/packages/client/hmr/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../modules"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/hmr/tsdown.config.ts b/packages/client/hmr/tsdown.config.ts
new file mode 100644
index 0000000000..9a28baba7c
--- /dev/null
+++ b/packages/client/hmr/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-hmr', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/i18n/package.json b/packages/client/i18n/package.json
index 5b5d4e718c..3e617174bf 100644
--- a/packages/client/i18n/package.json
+++ b/packages/client/i18n/package.json
@@ -27,10 +27,6 @@
     "platform": "web",
     "immediately": true
   },
-  "scripts": {
-    "bundle": "tsdown",
-    "watch": "tsdown --watch"
-  },
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-client-runtime": "workspace:^"
diff --git a/packages/client/modules/README.md b/packages/client/modules/README.md
new file mode 100644
index 0000000000..234b8406e6
--- /dev/null
+++ b/packages/client/modules/README.md
@@ -0,0 +1,20 @@
+# @deepseek-ai/dsh-client-modules
+
+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.
+
+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).
+
+Resolution branch order (`import(specifier)`): platform seed word → shell instance; memoized record → surface; shell-own static registry (`registerStatic`, app-shell) → module; registered factory → materialize; graph row (`window.__DSH_BOOT__`) → fetch + execute + materialize; anything else throws — the runtime mirror of the build-time bundle purity gate. The synchronous `require` handed to factories walks the same order minus the fetch branch and records observed edges into the module record. `prefetch` is the stage-one arrival hook (fetch + execute, registration only; concurrent calls share one in-flight task); `invalidate` drops the factory and the materialized record so the next prefetch/import refetches (the HMR hook).
+
+## Model Experience
+
+None, as the module loader is browser-side kernel machinery; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Flat module graph by design** — every bundle is one module node whose edges point only at table leaves; the interface (loadCache/edges/invalidate) is shaped for a general module graph so the externalization granularity can change without an interface change.
+- **No unload bookkeeping of its own** — style removal and fiber teardown ordering live with the HMR driver (`@deepseek-ai/dsh-client-hmr`); the loader only inventories owned style tag ids per record.
diff --git a/packages/client/modules/package.json b/packages/client/modules/package.json
new file mode 100644
index 0000000000..ad2fb78ab1
--- /dev/null
+++ b/packages/client/modules/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-client-modules",
+  "description": "Client module loader: the browser peer of Node's internal ESM loader, consumed by the vendored cordis Loader as its internal seam (resolve/import/loadCache/invalidate over seed table, static registry and fetch bundles)",
+  "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"
+  },
+  "license": "BSD-3-Clause",
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/client/modules/src/index.ts b/packages/client/modules/src/index.ts
new file mode 100644
index 0000000000..cb22dfa7ca
--- /dev/null
+++ b/packages/client/modules/src/index.ts
@@ -0,0 +1,175 @@
+/**
+ * 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` →
+ * `internal.import`), which keeps entry governance (fiber lifecycle, inject
+ * 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
+ * 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
+ * (factory(require) → export surface) happens on first import/require and is
+ * memoized in {@link ClientModuleLoader.loadCache}; a factory that requires
+ * another registered-but-unmaterialized module materializes it recursively,
+ * so load order needs no external sequencing.
+ *
+ * Resolution branch order (import): seed word → shell instance; memoized
+ * record → surface; static registry (shell-own modules, e.g. app-shell) →
+ * module; registered factory → materialize; graph row → fetch + execute +
+ * materialize; anything else → throw (loud — the runtime mirror of the
+ * build-time bundle purity gate). The synchronous `require` handed to
+ * factories walks the same order minus the fetch branch: fetching is async,
+ * so only already-executed bundles can be required — and cross-plugin value
+ * imports are a build error anyway.
+ * @module @deepseek-ai/dsh-client-modules
+ */
+
+import { ClientModuleLoaderImpl } from './loader.ts'
+
+export { ClientModuleLoaderImpl }
+
+declare module 'cordis' {
+  interface Context {
+    /** The client module system the web shell provides at boot (contract C5). */
+    modules: ClientModuleLoader
+  }
+}
+
+/**
+ * One composed client entry pushed by the host (web2 §0 graph row).
+ * `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).
+ *
+ * Wire contract, held on both sides: the producing peer lives in
+ * `@deepseek-ai/dsh-host-webserver` (host packages keep zero workspace
+ * dependencies, so neither side imports the other's shape — drift between
+ * the two declarations is a bug against the web2 contract).
+ */
+export interface WebBootEntry {
+  /** Entry name == package name (or a shell-owned pseudo id, e.g. app-shell). */
+  id: string
+  /**
+   * Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. Absent only on
+   * shell-owned pseudo rows (app-shell) whose module is statically registered
+   * — a row that is neither fetchable nor static-registered fails loud.
+   */
+  url?: string
+  /** Bundle content hash (cache-busting consistency anchor); absent with url. */
+  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
+}
+
+/** The composed client entry graph the host injects as `window.__DSH_BOOT__` (dual-held wire contract — see {@link WebBootEntry}). */
+export 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[]
+}
+
+/** The shape a client bundle hands to `window.__ModuleLoader__.load` (registration handoff, contract C6). */
+export interface ClientPluginHandoff {
+  /** Plugin id (package name) — the registration key; must match the graph row being executed. */
+  id: string
+  /**
+   * Closure factory holding the whole bundle body: receives the synchronous
+   * require bound to the module table and returns the bundle's export
+   * surface. Runs once, at materialization.
+   */
+  factory: (require: (spec: string) => unknown) => Record<string, unknown>
+}
+
+/** Window surface this loader owns (bundle side of the handoff protocol) plus the host-injected graph. */
+export interface DshWindow {
+  /** Host-composed entry graph, injected before the shell bundle runs. */
+  __DSH_BOOT__?: WebBootGraph
+  /** Bundle registration sink; installed once per page by {@link createClientModuleLoader} (contract C6). */
+  __ModuleLoader__?: { load(handoff: ClientPluginHandoff): void }
+}
+
+/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (module-graph seam, flat today). */
+export interface ClientModuleRecord {
+  /** Module id (entry name / package name). */
+  id: string
+  /** The materialized export surface (factory `module.exports`, or the shell module for static registrations). */
+  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). */
+  edges: Set<string>
+}
+
+/**
+ * The internal-seam 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).
+ */
+export interface ClientModuleLoader {
+  /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
+  version: 'client'
+  /** 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
+   * `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).
+   * @returns the module's export surface.
+   */
+  import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>
+  /**
+   * Register a shell-own module (app-shell — code that ships inside the shell
+   * bundle and never arrives as a plugin bundle).
+   * @param id - entry name (shell-owned pseudo id).
+   * @param module - the statically imported module namespace.
+   */
+  registerStatic(id: string, module: unknown): void
+  /**
+   * Stage-one arrival: fetch the entry's bundle and execute it, registering
+   * its factory (no materialization — module side effects wait for import).
+   * No-op for static-registered ids and ids whose factory is already
+   * registered; concurrent calls share one in-flight task. To force a fresh
+   * fetch (HMR), {@link invalidate} first.
+   * @param id - graph entry name.
+   */
+  prefetch(id: string): Promise<void>
+  /**
+   * Full reset of one module: drop its registered factory, its materialized
+   * record, and any consumed bundle text, so the next prefetch/import
+   * refetches and re-executes (the HMR invalidation hook).
+   * @param id - entry name to invalidate.
+   */
+  invalidate(id: string): void
+}
+
+/** Options for {@link createClientModuleLoader} (assembled by the web shell at boot). */
+export interface ClientModuleLoaderOptions {
+  /** Host-composed entry graph. */
+  graph: WebBootGraph
+  /** Module-table seed: platform-singleton specifier → shell instance. */
+  staticModules: Record<string, unknown>
+  /** Bundle fetch seam (parallelizable half). Defaults to same-origin fetch().text(). */
+  fetchBundle?: (url: string) => Promise<string>
+  /**
+   * Bundle execution seam (synchronously performs the load() registration).
+   * Defaults to a <script> element carrying the code.
+   */
+  executeBundle?: (code: string, url: string) => void
+}
+
+/**
+ * Build the client module system.
+ * @param options - entry graph, module-table staticModules, fetch/execute seams.
+ * @returns the loader the shell mounts as `ctx.loader.internal` and provides as `ctx.modules`.
+ */
+export function createClientModuleLoader(options: ClientModuleLoaderOptions): ClientModuleLoader {
+  return new ClientModuleLoaderImpl(options)
+}
diff --git a/packages/client/modules/src/invariant.ts b/packages/client/modules/src/invariant.ts
new file mode 100644
index 0000000000..60f90ed6e5
--- /dev/null
+++ b/packages/client/modules/src/invariant.ts
@@ -0,0 +1,34 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-modules`.
+ * @module @deepseek-ai/dsh-client-modules/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-modules'
+
+/** Cordis companion plugin name. */
+export const name = 'client-modules-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the module loader is pre-plugin kernel machinery —
+ * it emits no cordis events (the vendored Loader owns entry lifecycle events)
+ * and its mutable state (loadCache, handoff slot) lives below the plugin
+ * layer where invariant observers cannot mount before it runs; resolve branch
+ * order and handoff discipline are asserted by the web boot specs against the
+ * real execution path.
+ */
+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/modules/src/loader.ts b/packages/client/modules/src/loader.ts
new file mode 100644
index 0000000000..b2682a4bcd
--- /dev/null
+++ b/packages/client/modules/src/loader.ts
@@ -0,0 +1,239 @@
+/**
+ * ClientModuleLoaderImpl — the implementation behind the {@link ClientModuleLoader}
+ * seam. The conceptual contract (lazy CJS model, resolution branch order) is
+ * documented on the package module and the public interfaces in `./index.ts`;
+ * this file owns the state tables and the fetch/execute/materialize machinery.
+ */
+import type {
+  ClientModuleLoader, ClientModuleLoaderOptions, ClientModuleRecord,
+  ClientPluginHandoff, DshWindow, WebBootEntry,
+} from './index.ts'
+
+/** A registered-but-unmaterialized bundle: the factory plus its source URL (diagnostics). */
+interface RegisteredFactory {
+  factory: ClientPluginHandoff['factory']
+  url: string
+}
+
+/** Default bundle fetch seam: same-origin fetch().text(). */
+const defaultFetchBundle = async (url: string): Promise<string> => {
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`client-modules: bundle fetch ${url} answered ${String(res.status)}`)
+  return res.text()
+}
+
+/** Default bundle execution seam: a <script> element carrying the code. */
+const defaultExecuteBundle = (code: string, url: string): void => {
+  const el = document.createElement('script')
+  // Inline execution (not src) so the fetch half stays parallelizable; the
+  // sourceURL comment keeps devtools stack frames attributed to the bundle.
+  el.textContent = `${code}\n//# sourceURL=${url}`
+  document.head.appendChild(el)
+  // Execution is synchronous for inline scripts: the factory is registered by
+  // now, so the node (and its source text) has no further job. Removing it
+  // keeps repeated HMR rebuilds from accumulating dead script nodes.
+  el.remove()
+}
+
+const urlOf = (row: WebBootEntry): string => {
+  // url is conditional on the wire (shell-own pseudo rows omit it); those
+  // ids resolve through the static registry and never reach a fetch.
+  if (row.url === undefined) throw new Error(`client-modules: entry "${row.id}" has no bundle url and no static registration`)
+  return row.url
+}
+
+/**
+ * A plugin bundle IS its package's client half: `<id>/client` (the exports
+ * subpath external bundles emit) and the bare graph id name the same
+ * surface, so table lookups normalize the suffix away.
+ */
+const stripClientSuffix = (spec: string): string =>
+  spec.endsWith('/client') ? spec.slice(0, -'/client'.length) : spec
+
+/**
+ * Claim and inventory the <style> tags a factory injected during
+ * materialization: preset-emitted tags arrive pre-tagged with data-plugin;
+ * any untagged tag is claimed for the materializing plugin (HMR bookkeeping).
+ */
+const claimStyles = (id: string): string[] => {
+  if (typeof document === 'undefined') return []
+  for (const el of document.querySelectorAll('style:not([data-plugin])')) {
+    el.setAttribute('data-plugin', id)
+  }
+  const owned: string[] = []
+  for (const el of document.querySelectorAll(`style[data-plugin=${JSON.stringify(id)}]`)) {
+    owned.push(el.getAttribute('data-plugin-css') ?? id)
+  }
+  return owned
+}
+
+/**
+ * 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 graph and installs the
+ * `window.__ModuleLoader__` registration sink (contract C6) — once per page.
+ */
+export class ClientModuleLoaderImpl implements ClientModuleLoader {
+  readonly version = 'client'
+  readonly loadCache = new Map<string, ClientModuleRecord>()
+
+  private readonly seed: Map<string, unknown>
+  private readonly statics = new Map<string, unknown>()
+  private readonly factories = new Map<string, RegisteredFactory>()
+  /** In-flight prefetch (fetch + execute) per id; concurrent callers share it. */
+  private readonly pendingArrival = new Map<string, Promise<void>>()
+  /** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
+  private readonly materializing = new Set<string>()
+  private readonly graphRows = new Map<string, WebBootEntry>()
+  // Execution URL of the bundle currently being executed (bound into the
+  // factory registration so diagnostics can name the source).
+  private executingUrl = ''
+  // Graph id of the row currently being executed ('' outside arrive):
+  // the load sink cross-checks the handoff id against it so a mis-stamped
+  // bundle cannot register under another entry's identity.
+  private executingId = ''
+
+  private readonly fetchBundle: (url: string) => Promise<string>
+  private readonly executeBundle: (code: string, url: string) => void
+
+  /**
+   * Build the module system over the host graph.
+   * @param options - entry graph, module-table staticModules, fetch/execute seams.
+   */
+  constructor(options: ClientModuleLoaderOptions) {
+    this.seed = new Map(Object.entries(options.staticModules))
+    this.fetchBundle = options.fetchBundle ?? defaultFetchBundle
+    this.executeBundle = options.executeBundle ?? defaultExecuteBundle
+
+    for (const entry of options.graph.entries) {
+      if (this.graphRows.has(entry.id)) throw new Error(`client-modules: duplicate graph entry "${entry.id}"`)
+      this.graphRows.set(entry.id, entry)
+    }
+
+    const win = globalThis as DshWindow
+    if (win.__ModuleLoader__ !== undefined) throw new Error('client-modules: window.__ModuleLoader__ already installed (double boot?)')
+    win.__ModuleLoader__ = {
+      load: (handoff: ClientPluginHandoff): void => {
+        // Registration is keyed by the handoff id; a duplicate means a bundle
+        // executed twice without an invalidate — always a bug, always loud.
+        if (this.factories.has(handoff.id)) throw new Error(`client-modules: duplicate factory registration for "${handoff.id}" (bundle executed twice without invalidate?)`)
+        // A fetched row's bundle must register the id its row names — a
+        // mis-stamped bundle registering under another entry's identity
+        // would let that entry silently materialize foreign exports.
+        if (this.executingId !== '' && handoff.id !== this.executingId) {
+          throw new Error(`client-modules: bundle ${this.executingUrl} registered "${handoff.id}" while arriving for "${this.executingId}" (mis-stamped bundle id)`)
+        }
+        this.factories.set(handoff.id, { factory: handoff.factory, url: this.executingUrl })
+      },
+    }
+  }
+
+  /** Fetch + execute one graph row so its factory is registered (idempotent per in-flight arrival). */
+  private arrive(row: WebBootEntry): Promise<void> {
+    const { id } = row
+    const pending = this.pendingArrival.get(id)
+    if (pending !== undefined) return pending
+    if (this.factories.has(id)) return Promise.resolve()
+    const task = (async (): Promise<void> => {
+      const url = urlOf(row)
+      const code = await this.fetchBundle(url)
+      this.executingUrl = url
+      this.executingId = id
+      try {
+        this.executeBundle(code, url)
+      } finally {
+        this.executingUrl = ''
+        this.executingId = ''
+      }
+      if (!this.factories.has(id)) {
+        throw new Error(`client-modules: bundle ${url} executed without registering "${id}" via __ModuleLoader__.load`)
+      }
+    })().finally(() => { this.pendingArrival.delete(id) })
+    this.pendingArrival.set(id, task)
+    return task
+  }
+
+  /** Materialize a registered factory (synchronous; memoized in loadCache). */
+  private materialize(id: string): ClientModuleRecord {
+    const existing = this.loadCache.get(id)
+    if (existing !== undefined) return existing
+    const registered = this.factories.get(id)
+    /* v8 ignore next -- callers check the factory branch before dispatching here. */
+    if (registered === undefined) throw new Error(`client-modules: no registered factory for "${id}"`)
+    if (this.materializing.has(id)) {
+      throw new Error(`client-modules: require cycle through "${id}" (factory-form CJS cannot deliver partial exports)`)
+    }
+    this.materializing.add(id)
+    try {
+      const edges = new Set<string>()
+      const surface = registered.factory(this.makeRequire(edges))
+      const record: ClientModuleRecord = { id, surface, styles: claimStyles(id), edges }
+      this.loadCache.set(id, record)
+      return record
+    } finally {
+      this.materializing.delete(id)
+    }
+  }
+
+  /**
+   * The synchronous require answered to factories: seed → static → memoized
+   * record → registered factory (recursive materialization — this is what
+   * makes load order self-resolving). Fetching is async and therefore
+   * unreachable from here; an unregistered plugin specifier is loud (and a
+   * cross-plugin value import is already a build error upstream).
+   */
+  private makeRequire(edges: Set<string>): (spec: string) => unknown {
+    return (spec: string): unknown => {
+      edges.add(spec)
+      if (this.seed.has(spec)) return this.seed.get(spec)
+      if (this.statics.has(spec)) return this.statics.get(spec)
+      const id = stripClientSuffix(spec)
+      const record = this.loadCache.get(id)
+      if (record !== undefined) return record.surface
+      if (this.factories.has(id)) return this.materialize(id).surface
+      throw new Error(
+        `client-modules: require("${spec}") missed the module table — not a platform seed word, not a shell-own module, `
+        + 'and no registered factory (a build-time externals drift, or a forbidden cross-plugin value import)',
+      )
+    }
+  }
+
+  async import(specifier: string): Promise<unknown> {
+    if (this.seed.has(specifier)) return this.seed.get(specifier)
+    const existing = this.loadCache.get(specifier)
+    if (existing !== undefined) return existing.surface
+    if (this.statics.has(specifier)) {
+      const surface = this.statics.get(specifier)
+      this.loadCache.set(specifier, { id: specifier, surface, styles: [], edges: new Set() })
+      return surface
+    }
+    if (!this.factories.has(specifier)) {
+      const row = this.graphRows.get(specifier)
+      if (row === undefined) {
+        throw new Error(
+          `client-modules: cannot resolve "${specifier}" — not a seed word, not a shell-own module, `
+          + 'and not a row in the boot graph (the runtime mirror of the bundle purity gate)',
+        )
+      }
+      await this.arrive(row)
+    }
+    return this.materialize(specifier).surface
+  }
+
+  registerStatic(id: string, module: unknown): void {
+    if (this.statics.has(id)) throw new Error(`client-modules: shell-own module "${id}" registered twice`)
+    this.statics.set(id, module)
+  }
+
+  async prefetch(id: string): Promise<void> {
+    if (this.statics.has(id)) return
+    const row = this.graphRows.get(id)
+    if (row === undefined) throw new Error(`client-modules: prefetch("${id}") — not a graph entry`)
+    await this.arrive(row)
+  }
+
+  invalidate(id: string): void {
+    this.factories.delete(id)
+    this.loadCache.delete(id)
+  }
+}
diff --git a/packages/client/modules/tests/loader.spec.ts b/packages/client/modules/tests/loader.spec.ts
new file mode 100644
index 0000000000..ca2627d266
--- /dev/null
+++ b/packages/client/modules/tests/loader.spec.ts
@@ -0,0 +1,306 @@
+// @vitest-environment jsdom
+/**
+ * ClientModuleLoaderImpl behavior: lazy CJS arrival (bundle execution only
+ * 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 seams, and the loud failure modes (duplicate
+ * registration, cycles, table misses, double boot).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  ClientModuleLoaderImpl, createClientModuleLoader,
+  type ClientModuleLoader, type ClientPluginHandoff, type DshWindow, type WebBootEntry,
+} from '../src/index.ts'
+
+const win = globalThis as DshWindow
+
+type Factory = ClientPluginHandoff['factory']
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  delete win.__ModuleLoader__
+  delete (document as unknown as Record<string, unknown>).__realmBridge
+  for (const el of document.querySelectorAll('style, script')) el.remove()
+})
+
+const row = (id: string): WebBootEntry => ({ id, url: `/plugins/${id}/client.js?rev=0` })
+
+interface Bench {
+  loader: ClientModuleLoader
+  fetched: string[]
+  gates: Map<string, () => void>
+}
+
+/**
+ * Loader over scripted bundles: fetch resolves to the row url (optionally
+ * gated on a release callback); execute registers the scripted factory
+ * through the window sink (`null` scripts a bundle that never calls load).
+ */
+function bench(
+  entries: WebBootEntry[],
+  bundles: Record<string, Factory | null> = {},
+  opts: { seed?: Record<string, unknown>; gated?: string[] } = {},
+): Bench {
+  const fetched: string[] = []
+  const gates = new Map<string, () => void>()
+  const loader = createClientModuleLoader({
+    graph: { rev: 'test', entries },
+    staticModules: opts.seed ?? {},
+    fetchBundle: (url) => {
+      fetched.push(url)
+      if (opts.gated?.includes(url) === true) {
+        return new Promise((resolve) => { gates.set(url, () => { resolve(url) }) })
+      }
+      return Promise.resolve(url)
+    },
+    executeBundle: (code) => {
+      const id = /\/plugins\/(.+)\/client\.js/.exec(code)?.[1]
+      const factory = id === undefined ? undefined : bundles[id]
+      if (factory == null || id === undefined) return
+      win.__ModuleLoader__?.load({ id, factory })
+    },
+  })
+  return { loader, fetched, gates }
+}
+
+describe('lazy CJS arrival', () => {
+  it('prefetch fetches and executes but does not run the factory', async () => {
+    const ran: string[] = []
+    const b = bench([row('a')], { a: () => { ran.push('a'); return {} } })
+    await b.loader.prefetch('a')
+    expect(b.fetched).toEqual(['/plugins/a/client.js?rev=0'])
+    expect(ran).toEqual([])
+    expect(b.loader.loadCache.size).toBe(0)
+  })
+
+  it('import materializes once and memoizes the export surface', async () => {
+    const ran: string[] = []
+    const b = bench([row('a')], { a: () => { ran.push('a'); return { marker: 'a' } } })
+    const first = await b.loader.import('a', '', {})
+    const second = await b.loader.import('a', '', {})
+    expect(first).toBe(second)
+    expect((first as { marker: string }).marker).toBe('a')
+    expect(ran).toEqual(['a'])
+    expect(b.loader.loadCache.get('a')?.id).toBe('a')
+  })
+
+  it('import without prefetch fetches, executes, and materializes in one call', async () => {
+    const b = bench([row('a')], { a: () => ({ marker: 'direct' }) })
+    const surface = await b.loader.import('a', '', {})
+    expect((surface as { marker: string }).marker).toBe('direct')
+    expect(b.fetched).toHaveLength(1)
+  })
+
+  it('concurrent callers share one in-flight arrival and materialize once', async () => {
+    const ran: string[] = []
+    const url = '/plugins/a/client.js?rev=0'
+    const b = bench([row('a')], { a: () => { ran.push('a'); return { marker: 'a' } } }, { gated: [url] })
+    const first = b.loader.import('a', '', {})
+    const second = b.loader.import('a', '', {})
+    const third = b.loader.prefetch('a')
+    b.gates.get(url)?.()
+    const [s1, s2] = await Promise.all([first, second, third])
+    expect(s1).toBe(s2)
+    expect(b.fetched).toEqual([url])
+    expect(ran).toEqual(['a'])
+  })
+
+  it('prefetch after registration is a no-op without invalidate', async () => {
+    const b = bench([row('a')], { a: () => ({}) })
+    await b.loader.prefetch('a')
+    await b.loader.prefetch('a')
+    expect(b.fetched).toHaveLength(1)
+  })
+})
+
+describe('require resolution', () => {
+  it('a factory requiring a registered-but-unmaterialized module materializes it recursively', async () => {
+    const order: string[] = []
+    const b = bench([row('a'), row('b')], {
+      a: (req) => {
+        order.push('a')
+        const dep = req('b/client') as { helper: string }
+        return { got: dep.helper }
+      },
+      b: () => { order.push('b'); return { helper: 'from-b' } },
+    })
+    await b.loader.prefetch('a')
+    await b.loader.prefetch('b')
+    const surface = await b.loader.import('a', '', {})
+    expect((surface as { got: string }).got).toBe('from-b')
+    expect(order).toEqual(['a', 'b'])
+    expect(b.loader.loadCache.get('a')?.edges.has('b/client')).toBe(true)
+    expect(b.loader.loadCache.has('b')).toBe(true)
+  })
+
+  it('require prefers the platform seed word over the module table', async () => {
+    const react = { marker: 'react' }
+    const b = bench([row('a')], {
+      a: req => ({ dep: req('react') }),
+    }, { seed: { react } })
+    const surface = await b.loader.import('a', '', {})
+    expect((surface as { dep: unknown }).dep).toBe(react)
+    expect(await b.loader.import('react', '', {})).toBe(react)
+    expect(b.loader.loadCache.has('react')).toBe(false)
+  })
+
+  it('require answers an already-materialized module from the cache', async () => {
+    let built = 0
+    const b = bench([row('a'), row('c')], {
+      a: req => ({ dep: req('c') }),
+      c: () => { built += 1; return { marker: 'c' } },
+    })
+    const c = await b.loader.import('c', '', {})
+    const a = await b.loader.import('a', '', {})
+    expect((a as { dep: unknown }).dep).toBe(c)
+    expect(built).toBe(1)
+  })
+
+  it('a require that misses the module table is loud', async () => {
+    const b = bench([row('a')], { a: req => ({ dep: req('ghost') }) })
+    await expect(b.loader.import('a', '', {})).rejects.toThrow('require("ghost") missed the module table')
+  })
+
+  it('a require cycle is fatal', async () => {
+    const b = bench([row('a'), row('b')], {
+      a: req => ({ dep: req('b') }),
+      b: req => ({ dep: req('a') }),
+    })
+    await b.loader.prefetch('b')
+    await expect(b.loader.import('a', '', {})).rejects.toThrow('require cycle through "a"')
+  })
+})
+
+describe('static registry', () => {
+  it('serves shell-own modules to import and require without any fetch', async () => {
+    const shell = { marker: 'app-shell' }
+    const b = bench([row('a'), { id: 'app-shell' }], {
+      a: req => ({ dep: req('app-shell') }),
+    })
+    b.loader.registerStatic('app-shell', shell)
+    await b.loader.prefetch('app-shell')
+    expect(await b.loader.import('app-shell', '', {})).toBe(shell)
+    expect(b.loader.loadCache.get('app-shell')?.styles).toEqual([])
+    expect((await b.loader.import('a', '', {}) as { dep: unknown }).dep).toBe(shell)
+    expect(b.fetched).toEqual(['/plugins/a/client.js?rev=0'])
+  })
+
+  it('duplicate static registration is loud', () => {
+    const b = bench([])
+    b.loader.registerStatic('app-shell', {})
+    expect(() => { b.loader.registerStatic('app-shell', {}) }).toThrow('registered twice')
+  })
+})
+
+describe('failure modes', () => {
+  it('duplicate factory registration is loud', () => {
+    bench([])
+    win.__ModuleLoader__?.load({ id: 'x', factory: () => ({}) })
+    expect(() => win.__ModuleLoader__?.load({ id: 'x', factory: () => ({}) }))
+      .toThrow('duplicate factory registration for "x"')
+  })
+
+  it('a bundle that never registers its id is loud', async () => {
+    const b = bench([row('a')], { a: null })
+    await expect(b.loader.import('a', '', {})).rejects.toThrow('without registering "a"')
+  })
+
+  it('an unknown import specifier is loud', async () => {
+    const b = bench([])
+    await expect(b.loader.import('nope', '', {})).rejects.toThrow('cannot resolve "nope"')
+  })
+
+  it('an unknown prefetch id is loud', async () => {
+    const b = bench([])
+    await expect(b.loader.prefetch('nope')).rejects.toThrow('prefetch("nope") — not a graph entry')
+  })
+
+  it('a graph row with no url and no static registration is loud', async () => {
+    const b = bench([{ id: 'ghost' }])
+    await expect(b.loader.import('ghost', '', {})).rejects.toThrow('no bundle url and no static registration')
+  })
+
+  it('a duplicate graph entry is loud at construction', () => {
+    expect(() => bench([row('a'), row('a')])).toThrow('duplicate graph entry "a"')
+  })
+
+  it('double boot is loud', () => {
+    bench([])
+    expect(() => new ClientModuleLoaderImpl({ graph: { rev: 't', entries: [] }, staticModules: {} }))
+      .toThrow('already installed (double boot?)')
+  })
+})
+
+describe('HMR reset', () => {
+  it('invalidate drops the factory and record so the module refetches and re-registers', async () => {
+    let generation = 0
+    const b = bench([row('a')], { a: () => ({ generation: ++generation }) })
+    const first = await b.loader.import('a', '', {})
+    b.loader.invalidate('a')
+    expect(b.loader.loadCache.has('a')).toBe(false)
+    await b.loader.prefetch('a')
+    const second = await b.loader.import('a', '', {})
+    expect(b.fetched).toHaveLength(2)
+    expect((first as { generation: number }).generation).toBe(1)
+    expect((second as { generation: number }).generation).toBe(2)
+  })
+})
+
+describe('style claiming', () => {
+  it('claims untagged style tags for the materializing plugin and inventories owned css ids', async () => {
+    const foreign = document.createElement('style')
+    foreign.setAttribute('data-plugin', 'other')
+    document.head.appendChild(foreign)
+    const b = bench([row('a')], {
+      a: () => {
+        document.head.appendChild(document.createElement('style'))
+        const tagged = document.createElement('style')
+        tagged.setAttribute('data-plugin', 'a')
+        tagged.setAttribute('data-plugin-css', 'sheet-1')
+        document.head.appendChild(tagged)
+        return {}
+      },
+    })
+    await b.loader.import('a', '', {})
+    expect(b.loader.loadCache.get('a')?.styles).toEqual(['a', 'sheet-1'])
+    expect(document.querySelectorAll('style[data-plugin="a"]')).toHaveLength(2)
+    expect(foreign.getAttribute('data-plugin')).toBe('other')
+  })
+
+  it('materialization without a document skips the style inventory', async () => {
+    const b = bench([row('a')], { a: () => ({}) })
+    vi.stubGlobal('document', undefined)
+    try {
+      await b.loader.import('a', '', {})
+    } finally {
+      vi.unstubAllGlobals()
+    }
+    expect(b.loader.loadCache.get('a')?.styles).toEqual([])
+  })
+})
+
+describe('default transport seams', () => {
+  it('fetches same-origin and executes through an inline script tag', async () => {
+    // In a browser the loader's globalThis IS the page window; vitest's jsdom
+    // evaluates <script> in a separate realm that shares only the document,
+    // so the fixture bundle restores the sink from a document bridge before
+    // using the normal calling convention.
+    const code = 'window.__ModuleLoader__ = document.__realmBridge;\n'
+      + 'window.__ModuleLoader__.load({ id: "dee", factory: function () { return { marker: "via-script" } } })'
+    vi.stubGlobal('fetch', async () => ({ ok: true, text: async () => code }))
+    const loader = createClientModuleLoader({ graph: { rev: 't', entries: [row('dee')] }, staticModules: {} })
+    ;(document as unknown as Record<string, unknown>).__realmBridge = win.__ModuleLoader__
+    const surface = await loader.import('dee', '', {})
+    expect((surface as { marker: string }).marker).toBe('via-script')
+    // The script node is removed right after its synchronous execution —
+    // repeated HMR rebuilds must not accumulate dead script nodes.
+    expect([...document.querySelectorAll('script')]).toEqual([])
+  })
+
+  it('a non-ok bundle response is loud with the status', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 404 }))
+    const loader = createClientModuleLoader({ graph: { rev: 't', entries: [row('dee')] }, staticModules: {} })
+    await expect(loader.prefetch('dee')).rejects.toThrow('answered 404')
+  })
+})
diff --git a/packages/client/modules/tsconfig.json b/packages/client/modules/tsconfig.json
new file mode 100644
index 0000000000..076aa22e9f
--- /dev/null
+++ b/packages/client/modules/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 66eb5b22ac..4fd5d15905 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -2,6 +2,10 @@
 
 Client cordis boot + core services: SlotsService (Service wrapper over SlotCore + 'slots/changed' bridge), SessionsService (list store projection, scope tree, bindings, ancestry), the Session object layer (exported as a type; instances are owned and handed out by SessionsService — the manager/paging internals stay package-internal, tests reach them via src), ClientLoader (`./loader` subpath, statically held by the shell). Contract: api-contracts v3 §4.
 
+## Session title projection
+
+`SessionManager` retains the latest validated `session/title` control snapshot independently of list and session-instance arrival. Newer event seqs replace older snapshots, title timestamps contribute to list recency, and a subscription baseline discards any retained title beyond its `lastSeq` before the optional folded title arrives. Explicit session removal also clears the retained title. The client-facing `SessionSummary.title` is therefore only the actual durable title; `displayTitle` is always present and falls back through the cwd basename and session id. A cold persisted session keeps that fallback until opening or resuming it causes the host to fold and project its log-backed title.
+
 ## Model Experience
 
 None, as the client runtime hosts browser-side services and the session object layer; nothing here reaches a model request.
@@ -13,6 +17,5 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **`loader.unload` is a stub (throws not-implemented)** — the full chain (fiber dispose → registration cascade → style removal) lands with the HMR project.
-- **Scope teardown is watch-approximated** — the most recently resolved binding stands in for "who is watching"; a removed-while-watched session's scope survives until the watch moves away, not until true observer count reaches zero.
+- **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 (`cell()`/`binding()`/`scope()`) is pure addressing, render-safe. 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).
-- **`SessionSummary.title` is a display projection** — the wire summary carries no title yet; the cwd basename stands in, then the raw id.
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index 384b2e2e3c..4bd95595c1 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-runtime",
-  "description": "Client cordis boot and core services: SlotsService, SessionsService (scope tree + object layer), ClientLoader",
+  "description": "Client core services: SlotsService, SessionsService (scope tree + object layer)",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -15,10 +15,6 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
-    "./loader": {
-      "types": "./lib/types/client/loader/index.d.ts",
-      "default": "./lib/loader.js"
-    },
     "./client": {
       "types": "./lib/types/client/index.d.ts",
       "default": "./lib/client.js"
@@ -37,6 +33,7 @@
   "dependencies": {
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "immer": "^10.1.1",
@@ -56,7 +53,6 @@
     "lib/index.js",
     "lib/invariant.js",
     "lib/client.js",
-    "lib/loader.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 77b51a68b5..33097d4573 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -2,17 +2,15 @@
  * Browser half: the whole runtime contract surface (api-contracts v3 §4) —
  * SlotsService (declaration ledger + renderer seam + store axis, built-in
  * 'root'), SessionsService (list store + current selection + scope tree +
- * object layer), the ClientLoader interface, and the cordis Context/Events
- * merges. apply
- * mounts ctx.slots + ctx.sessions and wires the connection stream loop into
- * the object layer. The loader machinery implementation is NOT in the plugin
- * bundle — it ships via the package's `./loader` subpath, statically held by
- * the web shell (a loader cannot load itself).
+ * object layer), and the cordis Context/Events merges. apply mounts
+ * ctx.slots + ctx.sessions and wires the connection stream loop into the
+ * object layer. A static-arrival entry: the web shell bundles this module
+ * and mounts it through the host graph (module loading lives in
+ * @deepseek-ai/dsh-client-modules, entry governance in the vendored Loader).
  */
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SnapshotStore } from './contract/store.ts'
 import { SlotsService } from './slots.ts'
 import { SessionsService } from './sessions/service.ts'
 import type { SessionListState } from './sessions/service.ts'
@@ -34,9 +32,12 @@ export type {
 } from './contract/store.ts'
 export type {
   AssistantBlock, AssistantMessageNode, ContextMessageNode, ConversationNode, ConversationSnapshot,
-  PendingInteraction, RunningToolCall, SteeringMessageNode,
+  RunningToolCall, SteeringMessageNode,
   ToolResultNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
+// PendingWait is a value export: tests construct fixture waits directly.
+export { PendingWait } from './sessions/pending.ts'
+export type { PendingInteraction, PendingKind, PendingPayloads } from './sessions/pending.ts'
 export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 
 // ---- Narrowed aliases (the single narrowing point of the slot type chain:
@@ -51,7 +52,7 @@ export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
  */
 export type ClientContext = Context
 
-/** The conversation-snapshot selector hook (ConvViewProps/ToolViewProps take this). */
+/** The conversation-snapshot selector hook (ConvViewProps/ToolRowProps take this). */
 export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>
 
 /**
@@ -92,48 +93,9 @@ declare module 'cordis' {
   interface Context {
     slots: import('./slots.ts').SlotsService
     sessions: import('./sessions/service.ts').SessionsService
-    loader: ClientLoader
   }
 }
 
-/** One __DSH_BOOT__ manifest row. */
-export interface BootPluginEntry { id: string; url: string; inject: string[]; immediately?: boolean }
-
-/** Per-plugin load status store shape. */
-export type LoaderStatus = Record<string, 'loading' | 'active' | 'failed'>
-
-/**
- * Client bundle loader. The immediately group loads first (parallel fetch,
- * apply in inject topology order); remaining plugins follow in inject
- * topology. Loaded bundle export surfaces are registered back into the
- * require module table. Implementation lives in the `./loader` subpath
- * (shell-held machinery).
- */
-export interface ClientLoader {
-  /** Start loading from window.__DSH_BOOT__ (non-blocking). */
-  start(): void
-  /**
-   * Load one plugin bundle (script inject, factory handoff, ctx.plugin, style registration).
-   * @param id - plugin id (package name).
-   */
-  load(id: string): Promise<void>
-  /**
-   * Unload a plugin. P-I: not implemented (full chain lands with HMR).
-   * @param id - plugin id.
-   */
-  unload(id: string): Promise<void>
-  /** Resolves when every manifest plugin reached active (AppRoot gates the real UI on this). */
-  settled(): Promise<void>
-  /**
-   * Read a loaded module's export surface from the module table (same
-   * implementation the bundle-facing require uses; unknown spec throws).
-   * @param spec - module specifier (package name or seeded library id).
-   */
-  requireModule(spec: string): unknown
-  /** Per-plugin status store. */
-  readonly status: SnapshotStore<LoaderStatus>
-}
-
 /** Required services: the wire handle mounted by the connection plugin. */
 export const inject = ['connection']
 
diff --git a/packages/client/runtime/src/client/loader/index.ts b/packages/client/runtime/src/client/loader/index.ts
deleted file mode 100644
index 81148a7dfc..0000000000
--- a/packages/client/runtime/src/client/loader/index.ts
+++ /dev/null
@@ -1,247 +0,0 @@
-/**
- * ClientLoader implementation (shell-held machinery — the loader cannot load
- * itself, so the web shell imports this subpath statically and mounts the
- * instance as ctx.loader; the runtime package's own client bundle never
- * includes it).
- *
- * Load chain per plugin: fetch bundle text → execute (script injection) → the
- * bundle calls window.DSHClientProxy.loadPlugin({id, factory}) (single-slot
- * handoff, id reconciled) → factory(require) with require bound to the module
- * table → ctx.plugin(exports.apply) → the export surface is registered into
- * the module table under the plugin id (inject topology guarantees later
- * loaders can require earlier ones) → <style data-plugin> ownership recorded.
- *
- * start(): the `immediately` group is fetched in parallel and executed in
- * group-internal inject topology (execution is serial — the handoff slot is
- * single); a full-group barrier precedes the remaining plugins, which then
- * load one by one in inject topology.
- */
-import type { Context } from 'cordis'
-import { createSnapshotStore } from '../contract/store.ts'
-import type { BootPluginEntry, ClientLoader, LoaderStatus } from '../index.ts'
-
-export type { BootPluginEntry, ClientLoader, LoaderStatus } from '../index.ts'
-
-/** The shape a client bundle hands to window.DSHClientProxy.loadPlugin. */
-export interface ClientPluginHandoff {
-  /** Plugin id (package name) — must match the manifest row being loaded. */
-  id: string
-  /**
-   * Closure factory: receives the DI require and returns the module's export
-   * surface; an `apply` export is applied as a cordis plugin.
-   */
-  factory: (require: (spec: string) => unknown) => Record<string, unknown>
-}
-
-/** Window surface the loader owns (bundle side of the handoff protocol). */
-interface DshWindow {
-  __DSH_BOOT__?: { plugins: BootPluginEntry[] }
-  DSHClientProxy?: { loadPlugin(handoff: ClientPluginHandoff): void }
-}
-
-/** Options for createClientLoader (assembled by the web shell at boot). */
-export interface ClientLoaderOptions {
-  /** Client root context: plugin applies mount under it. */
-  ctx: Context
-  /**
-   * Seeded module table: pure-library entities (react, react-dom, cordis,
-   * ui-slots, web-react, ui-primitives). The loader takes ownership and
-   * registers loaded bundle export surfaces alongside them.
-   */
-  modules: Record<string, unknown>
-  /**
-   * Boot manifest; defaults to window.__DSH_BOOT__. Fixture pages inject the
-   * same protocol shape.
-   */
-  boot?: { plugins: BootPluginEntry[] }
-  /** Bundle fetch seam (parallelizable half). Defaults to same-origin fetch().text(). */
-  fetchBundle?: (url: string) => Promise<string>
-  /**
-   * Bundle execution seam (serial half; execution synchronously performs the
-   * loadPlugin handoff). Defaults to a <script> element carrying the code.
-   */
-  executeBundle?: (code: string, url: string) => void
-}
-
-/** Per-plugin bookkeeping across the load chain. */
-interface PluginRecord {
-  entry: BootPluginEntry
-  state: 'idle' | 'loading' | 'active' | 'failed'
-  fetch?: Promise<string>
-  load?: Promise<void>
-}
-
-const NOT_LOADED = Symbol('dsh.loader.not-loaded')
-
-/**
- * Build the client bundle loader.
- * @param options - ctx, seeded module table, boot manifest, fetch/execute seams.
- * @returns the ClientLoader the shell mounts as ctx.loader.
- */
-export function createClientLoader(options: ClientLoaderOptions): ClientLoader {
-  const { ctx } = options
-  const win = globalThis as DshWindow
-  const boot = options.boot ?? win.__DSH_BOOT__
-  if (boot === undefined) throw new Error('client-loader: no boot manifest (window.__DSH_BOOT__ missing)')
-
-  const modules = new Map<string, unknown>(Object.entries(options.modules))
-  const records = new Map<string, PluginRecord>()
-  for (const entry of boot.plugins) {
-    if (records.has(entry.id)) throw new Error(`client-loader: duplicate manifest id "${entry.id}"`)
-    records.set(entry.id, { entry, state: 'idle' })
-  }
-
-  const status = createSnapshotStore<LoaderStatus>({})
-  const publish = (id: string, state: 'loading' | 'active' | 'failed'): void => {
-    status.update((draft) => { draft[id] = state })
-  }
-
-  // Single-slot handoff: bundle execution synchronously calls loadPlugin;
-  // doLoad arms the slot before executing and reconciles the id after.
-  let slot: ClientPluginHandoff | typeof NOT_LOADED = NOT_LOADED
-  if (win.DSHClientProxy !== undefined) throw new Error('client-loader: window.DSHClientProxy already installed (double boot?)')
-  win.DSHClientProxy = {
-    loadPlugin: (handoff: ClientPluginHandoff): void => {
-      if (slot !== NOT_LOADED) {
-        throw new Error(`client-loader: overlapping loadPlugin handoff (got "${handoff.id}" while a previous handoff is unclaimed)`)
-      }
-      slot = handoff
-    },
-  }
-
-  const fetchBundle = options.fetchBundle ?? (async (url: string): Promise<string> => {
-    const res = await fetch(url)
-    if (!res.ok) throw new Error(`client-loader: bundle fetch ${url} answered ${String(res.status)}`)
-    return res.text()
-  })
-
-  const executeBundle = options.executeBundle ?? ((code: string, url: string): void => {
-    const el = document.createElement('script')
-    // Inline execution (not src) so the fetch half stays parallelizable; the
-    // sourceURL comment keeps devtools stack frames attributed to the bundle.
-    el.textContent = `${code}\n//# sourceURL=${url}`
-    document.head.appendChild(el)
-  })
-
-  const requireModule = (spec: string): unknown => {
-    if (!modules.has(spec)) {
-      throw new Error(`client-loader: module "${spec}" is not available — not a seeded library and no loaded plugin registered it (check dshClient.inject ordering)`)
-    }
-    return modules.get(spec)
-  }
-
-  /** Tag styles the bundle injected during execution (unload bookkeeping; plugin CSS lands untagged). */
-  const claimStyles = (id: string): void => {
-    if (typeof document === 'undefined') return
-    for (const el of document.querySelectorAll('style:not([data-plugin])')) {
-      el.setAttribute('data-plugin', id)
-    }
-  }
-
-  /** Start (or reuse) the parallelizable fetch half. */
-  const prefetch = (record: PluginRecord): Promise<string> =>
-    (record.fetch ??= fetchBundle(record.entry.url))
-
-  async function doLoad(record: PluginRecord): Promise<void> {
-    const { id } = record.entry
-    record.state = 'loading'
-    publish(id, 'loading')
-    try {
-      // Dependencies must already be active (start() sequences this; direct
-      // load() callers get the same fail-loud check).
-      for (const dep of record.entry.inject) {
-        const depRecord = records.get(dep)
-        if (depRecord === undefined) throw new Error(`client-loader: "${id}" injects unknown plugin "${dep}"`)
-        if (depRecord.state !== 'active') throw new Error(`client-loader: "${id}" loaded before its dependency "${dep}" is active`)
-      }
-      const code = await prefetch(record)
-      executeBundle(code, record.entry.url)
-      if (slot === NOT_LOADED) throw new Error(`client-loader: bundle ${record.entry.url} executed without calling DSHClientProxy.loadPlugin`)
-      const handoff = slot
-      slot = NOT_LOADED
-      if (handoff.id !== id) throw new Error(`client-loader: bundle id mismatch — manifest "${id}" vs handoff "${handoff.id}"`)
-      const exports = handoff.factory(requireModule)
-      if (typeof exports.apply !== 'function') throw new Error(`client-loader: plugin "${id}" exports no apply function`)
-      // The whole export surface is the plugin: cordis object-plugin form
-      // keeps the bundle's exported `inject`/`name` (an apply-only pass would
-      // silently drop the dependency declaration — postmortem 0001).
-      const fiber = ctx.plugin(exports as { apply: (ctx: Context) => void })
-      await fiber.await()
-      // Register under both specifier forms bundles emit: the bare package
-      // name (deep-import rewrites) and the /client subpath (CLIENT_EXTERNALS
-      // form) — the loaded surface IS the client half either way.
-      modules.set(id, exports)
-      modules.set(`${id}/client`, exports)
-      claimStyles(id)
-      record.state = 'active'
-      publish(id, 'active')
-    } catch (error) {
-      record.state = 'failed'
-      publish(id, 'failed')
-      throw error
-    }
-  }
-
-  const load = (id: string): Promise<void> => {
-    const record = records.get(id)
-    if (record === undefined) return Promise.reject(new Error(`client-loader: unknown plugin "${id}"`))
-    record.load ??= doLoad(record)
-    return record.load
-  }
-
-  /** Topologically order `ids` by inject (edges inside the set only — an early-group member never waits on a later-group one). */
-  const topo = (ids: string[]): string[] => {
-    const pool = new Set(ids)
-    const ordered: string[] = []
-    const done = new Set<string>()
-    const visiting = new Set<string>()
-    const visit = (id: string): void => {
-      if (done.has(id)) return
-      if (visiting.has(id)) throw new Error(`client-loader: inject cycle through "${id}"`)
-      visiting.add(id)
-      const record = records.get(id)
-      /* v8 ignore next -- ids come from records; unknown ids are caught per-dep below. */
-      if (record === undefined) throw new Error(`client-loader: manifest references unknown plugin "${id}"`)
-      for (const dep of record.entry.inject) {
-        if (!records.has(dep)) throw new Error(`client-loader: "${id}" injects unknown plugin "${dep}"`)
-        if (pool.has(dep)) visit(dep)
-      }
-      visiting.delete(id)
-      done.add(id)
-      ordered.push(id)
-    }
-    for (const id of ids) visit(id)
-    return ordered
-  }
-
-  let settledPromise: Promise<void> | undefined
-
-  async function run(): Promise<void> {
-    const all = [...records.values()]
-    const early = all.filter(r => r.entry.immediately === true)
-    const rest = all.filter(r => r.entry.immediately !== true)
-    // Early group: parallel fetch (all requests in flight at once), serial
-    // inject-topology execution, full-group barrier before anything else.
-    const earlyOrder = topo(early.map(r => r.entry.id))
-    for (const record of early) void prefetch(record).catch(() => {}) // surfaced by the awaited load below
-    for (const id of earlyOrder) await load(id)
-    // Remaining plugins: one by one in inject topology.
-    for (const id of topo(rest.map(r => r.entry.id))) await load(id)
-  }
-
-  return {
-    start: () => {
-      settledPromise ??= run()
-      // Failures surface through settled()/status — start() itself is fire-and-forget.
-      settledPromise.catch(() => {})
-    },
-    load,
-    unload: (id: string) => Promise.reject(new Error(`client-loader: unload("${id}") is not implemented (lands with HMR)`)),
-    settled: () => {
-      if (settledPromise === undefined) throw new Error('client-loader: settled() before start()')
-      return settledPromise
-    },
-    requireModule,
-    status,
-  }
-}
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 18c5501972..08b80f2a26 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -4,7 +4,8 @@
 // string here (narrow to real brands when convenient).
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { RpcError, RpcId, SessionId, ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { RpcError, SessionId, ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { PendingInteraction } from './pending.ts'
 
 /** Assistant content blocks sorted by what the UI cares about
  *  (text body / collapsible reasoning / tool-call card head / other fallback). */
@@ -41,6 +42,8 @@ export function toAssistantBlock(block: ContentBlock): AssistantBlock {
 export interface UserMessageNode {
   kind: 'user'
   seq: number
+  /** Unix epoch ms from the source session event. */
+  time: number
   content: readonly ContentBlock[]
   source: unknown
 }
@@ -49,6 +52,8 @@ export interface UserMessageNode {
 export interface AssistantMessageNode {
   kind: 'assistant'
   seq: number
+  /** Unix epoch ms from the source session event (or turn/end when frozen from a partial). */
+  time: number
   turn: number
   step: number
   blocks: readonly AssistantBlock[]
@@ -62,6 +67,8 @@ export interface AssistantMessageNode {
 export interface SteeringMessageNode {
   kind: 'steering'
   seq: number
+  /** Unix epoch ms from the source session event. */
+  time: number
   turn: number
   content: readonly ContentBlock[]
   source: unknown
@@ -71,6 +78,8 @@ export interface SteeringMessageNode {
 export interface ContextMessageNode {
   kind: 'context'
   seq: number
+  /** Unix epoch ms from the source session event. */
+  time: number
   content: readonly ContentBlock[]
   source: unknown
   meta?: unknown
@@ -80,9 +89,13 @@ export interface ContextMessageNode {
 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: { 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. */
+  callTime: number | null
   content: readonly ContentBlock[]
   isError: boolean
   error?: { name: string; code: string }
@@ -97,6 +110,8 @@ export interface ToolResultNode {
 export interface UnknownSurfaceNode {
   kind: 'unknown'
   seq: number
+  /** Unix epoch ms from the source session event when known. */
+  time: number
   type: string
   data: unknown
 }
@@ -117,15 +132,12 @@ export interface RunningToolCall {
   argsRaw: string
   turn: number
   step: number
+  /** Unix epoch ms when the tool/call event was logged. */
+  time: number
   /** Host-computed render intent riding the tool/call frame; null = generic JSON card. */
   callView: ToolCallView | null
 }
 
-/** Approval/question placeholder cards (visible, not answerable;
- *  rpcId = the requested frame's envelope id, the future respond backfill key). */
-export type PendingInteraction =
-  | { kind: 'approval'; rpcId: RpcId; approvalId: string; toolName: string; callId?: string; reason?: string }
-  | { kind: 'question'; rpcId: RpcId; questions: readonly unknown[] }
 
 /** In-progress assistant output (chunk accumulator product). */
 export interface PartialAssistant {
diff --git a/packages/client/runtime/src/client/sessions/fold-adapter.ts b/packages/client/runtime/src/client/sessions/fold-adapter.ts
index ccb48a0161..23b35f86bf 100644
--- a/packages/client/runtime/src/client/sessions/fold-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/fold-adapter.ts
@@ -18,6 +18,8 @@ export interface CallIndexEntry {
   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
 }
@@ -38,24 +40,37 @@ function materializeNode(
 ): ConversationNode {
   switch (event.type) {
     case 'user/message':
-      return { kind: 'user', seq: event.seq, 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.
+      if (event.data.source.kind !== 'user') {
+        return {
+          kind: 'context', seq: event.seq, time: event.time,
+          content: event.data.content, source: event.data.source,
+          meta: event.data.meta,
+        }
+      }
+      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, turn: event.data.turn, step: event.data.step,
+        kind: 'assistant', seq: event.seq, time: event.time,
+        turn: event.data.turn, step: event.data.step,
         blocks: toAssistantBlocks(event.data.content), usage: event.data.usage,
       }
     case 'steering/message':
-      return { kind: 'steering', seq: event.seq, turn: event.data.turn, content: event.data.content, source: event.data.source }
-    case 'context/message':
       return {
-        kind: 'context', seq: event.seq, content: event.data.content, source: event.data.source,
-        meta: event.data.meta,
+        kind: 'steering', seq: event.seq, time: event.time, turn: event.data.turn,
+        content: event.data.content, source: event.data.source,
       }
     case 'tool/result': {
       const call = callIndex.get(String(event.data.callId))
       return {
-        kind: 'tool-result', seq: event.seq, callId: String(event.data.callId),
+        kind: 'tool-result', seq: event.seq, time: event.time,
+        callId: String(event.data.callId),
         call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
+        callTime: call?.time ?? null,
         content: event.data.content, isError: event.data.isError,
         ...(event.data.error !== undefined ? { error: event.data.error } : {}),
         meta: event.data.meta,
@@ -63,11 +78,14 @@ function materializeNode(
         resultView,
       }
     }
-    /* v8 ignore next 2 -- defensive arm: fold output only carries the five
+    /* v8 ignore next 2 -- defensive arm: fold output only carries the four
     surface-eligible types, and each has a case above; reachable only if core
     adds an eligible type. */
     default:
-      return { kind: 'unknown', seq: event.seq, type: event.type, data: (event as { data?: unknown }).data }
+      return {
+        kind: 'unknown', seq: event.seq, time: event.time,
+        type: event.type, data: (event as { data?: unknown }).data,
+      }
   }
 }
 
@@ -186,6 +204,7 @@ export class FoldAdapter {
     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
diff --git a/packages/client/runtime/src/client/sessions/lineage.ts b/packages/client/runtime/src/client/sessions/lineage.ts
index 4f67f33343..c6bd572ea7 100644
--- a/packages/client/runtime/src/client/sessions/lineage.ts
+++ b/packages/client/runtime/src/client/sessions/lineage.ts
@@ -4,9 +4,15 @@
 
 import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
 
+/** Host list summary enriched with the latest mux-projected durable title. */
+export interface TitledSessionSummary extends SessionSummary {
+  title?: string
+}
+
 /** One flattened session-list row (summary + lineage indent depth). */
 export interface SessionListEntry {
   sessionId: SessionId
+  title?: string
   updatedAt: number
   running: boolean
   parentSessionId?: SessionId
@@ -21,12 +27,12 @@ export interface SessionListEntry {
  * @param summaries - the host's session.list items.
  * @returns display rows in render order.
  */
-export function flattenLineage(summaries: readonly SessionSummary[]): SessionListEntry[] {
-  const byId = new Map<SessionId, SessionSummary>()
+export function flattenLineage(summaries: readonly TitledSessionSummary[]): SessionListEntry[] {
+  const byId = new Map<SessionId, TitledSessionSummary>()
   for (const s of summaries) byId.set(s.sessionId, s)
 
-  const children = new Map<SessionId, SessionSummary[]>()
-  const roots: SessionSummary[] = []
+  const children = new Map<SessionId, TitledSessionSummary[]>()
+  const roots: TitledSessionSummary[] = []
   for (const s of summaries) {
     if (s.parentSessionId !== undefined && byId.has(s.parentSessionId)) {
       const list = children.get(s.parentSessionId) ?? []
@@ -37,12 +43,12 @@ export function flattenLineage(summaries: readonly SessionSummary[]): SessionLis
     }
   }
 
-  const byUpdatedDesc = (a: SessionSummary, b: SessionSummary): number => b.updatedAt - a.updatedAt
+  const byUpdatedDesc = (a: TitledSessionSummary, b: TitledSessionSummary): number => b.updatedAt - a.updatedAt
   roots.sort(byUpdatedDesc)
 
   const out: SessionListEntry[] = []
   const visited = new Set<SessionId>()
-  const walk = (s: SessionSummary, depth: number): void => {
+  const walk = (s: TitledSessionSummary, depth: number): void => {
     if (visited.has(s.sessionId)) {
       console.warn(`[web-runtime] lineage cycle at ${s.sessionId}; emitting as root`)
       return
diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts
index 2881fea468..b65935a97d 100644
--- a/packages/client/runtime/src/client/sessions/manager.ts
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -3,8 +3,10 @@
 // List data never enters zustand; React connects via subscribe/getListSnapshot.
 
 import type { IApiClient, HostFrame, MuxFrame, RpcError, RpcRequest, RpcResult, SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
-import { transportError } from '@deepseek-ai/dsh-client-connection/client'
-import type { SessionListEntry } from './lineage.ts'
+// Value import from the inline-safe wire layer (not the connection plugin):
+// plugin-to-plugin value imports are a bundle purity error.
+import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { SessionListEntry, TitledSessionSummary } from './lineage.ts'
 import { flattenLineage } from './lineage.ts'
 import { Notifier } from './notifier.ts'
 import { Session } from './session.ts'
@@ -19,6 +21,13 @@ export interface SessionListSnapshot {
 /** Per-session cap for pre-instantiation approval/question buffering (low-frequency frames; a few dozen covers any real backlog). */
 const PENDING_BUFFER_CAP = 32
 
+/** Latest title control snapshot retained independently of list/instance arrival. */
+interface SessionTitleSnapshot {
+  title: string
+  eventSeq: number
+  updatedAt: number
+}
+
 /** Instance cluster + frame entry + the session list (see the web client architecture RFC). */
 export class SessionManager {
   private readonly sessions = new Map<SessionId, Session>()
@@ -27,6 +36,7 @@ export class SessionManager {
    *  drop-and-backfill path; replayed and cleared on instantiation. Bounded per session (these
    *  frames are low-frequency; overflow drops oldest) and dropped on session-removed (audit S7). */
   private readonly pendingBuffers = new Map<SessionId, RpcRequest<MuxFrame>[]>()
+  private readonly titleSnapshots = new Map<SessionId, SessionTitleSnapshot>()
   private summaries: SessionSummary[] = []
   private listState: 'idle' | 'loading' | 'error' = 'idle'
   private listError: RpcError | null = null
@@ -158,6 +168,24 @@ export class SessionManager {
   handleMuxEnvelope(envelope: RpcRequest<MuxFrame>): void {
     const frame = envelope.payload
     if (frame.type === 'stream/error') return // Controller already treats this as stream failure
+    if (frame.type === 'session/title') {
+      const current = this.titleSnapshots.get(frame.sessionId)
+      if (current !== undefined && current.eventSeq >= frame.eventSeq) return
+      this.titleSnapshots.set(frame.sessionId, {
+        title: frame.title,
+        eventSeq: frame.eventSeq,
+        updatedAt: frame.updatedAt,
+      })
+      this.notifier.markDirty()
+      return
+    }
+    if (frame.type === 'session/subscribed') {
+      const current = this.titleSnapshots.get(frame.sessionId)
+      if (current !== undefined && current.eventSeq > frame.lastSeq) {
+        this.titleSnapshots.delete(frame.sessionId)
+        this.notifier.markDirty()
+      }
+    }
     const session = this.sessions.get(frame.sessionId)
     if (session === undefined) {
       // Approval/question frames never hit history: buffer for replay on instantiation;
@@ -204,6 +232,7 @@ export class SessionManager {
         this.summaries = this.summaries.filter(s => s.sessionId !== frame.sessionId)
         this.sessions.get(frame.sessionId)?.handleRemoved() // instance survives (resident-instance rule), only flagged in the snapshot
         this.pendingBuffers.delete(frame.sessionId) // a removed session's buffered frames must not replay on a future instantiation
+        this.titleSnapshots.delete(frame.sessionId)
         this.notifier.markDirty()
         return
       }
@@ -230,12 +259,19 @@ export class SessionManager {
   }
 
   private buildListSnapshot(): SessionListSnapshot {
-    const fresh = flattenLineage(this.summaries)
+    const merged: TitledSessionSummary[] = this.summaries.map((summary) => {
+      const title = this.titleSnapshots.get(summary.sessionId)
+      return title === undefined
+        ? summary
+        : { ...summary, title: title.title, updatedAt: Math.max(summary.updatedAt, title.updatedAt) }
+    })
+    const fresh = flattenLineage(merged)
     const items = fresh.map((entry) => {
       const prev = this.entryCache.get(entry.sessionId)
       if (
         prev !== undefined && prev.updatedAt === entry.updatedAt && prev.running === entry.running
-        && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd && prev.depth === entry.depth
+        && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd
+        && prev.title === entry.title && prev.depth === entry.depth
       ) return prev
       this.entryCache.set(entry.sessionId, entry)
       return entry
diff --git a/packages/client/runtime/src/client/sessions/pending.ts b/packages/client/runtime/src/client/sessions/pending.ts
new file mode 100644
index 0000000000..ba69a6951e
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/pending.ts
@@ -0,0 +1,79 @@
+// PendingWait: the carrier-protocol half of a pending host interaction. The runtime owns only
+// envelope knowledge (rpcId backfill into a client-response); domain result encoding belongs to
+// the interaction's consumer package.
+
+import type {
+  ClientResponse, MuxFrame, RpcId, RpcReceipt, SessionId,
+} from '@deepseek-ai/dsh-client-connection/client'
+
+/** Kind-keyed payload map: the requested frame's domain fields (envelope fields stripped). */
+export interface PendingPayloads {
+  approval: Omit<Extract<MuxFrame, { type: 'approval/requested' }>, 'type' | 'sessionId'>
+  question: Omit<Extract<MuxFrame, { type: 'question/requested' }>, 'type' | 'sessionId'>
+}
+
+/** Pending-interaction discriminant (the keys of PendingPayloads). */
+export type PendingKind = keyof PendingPayloads
+
+/** Kind-discriminated union of concrete waits: narrowing on `kind` types `payload`. */
+export type PendingInteraction = { [K in PendingKind]: PendingWait<K> }[PendingKind]
+
+/** Key prefixes, one per kind (the key doubles as the Session pending-map key). */
+const KEY_PREFIX: Record<PendingKind, string> = { approval: 'a', question: 'q' }
+
+/**
+ * One pending host-owned interaction wait: an immutable render face
+ * (kind/key/sessionId/payload) plus the response carrier. respond() backfills
+ * the requested frame's rpcId into a client-response envelope — no consumer
+ * ever sees the raw rpcId. Settlement is expressed only by pending-list
+ * membership (the settled flag is a fail-loud guard, not a render input).
+ */
+export class PendingWait<K extends PendingKind = PendingKind> {
+  /** Interaction kind (union discriminant). */
+  readonly kind: K
+  /** Opaque render identity, `<prefix>:<rpcId>` — stable across baseline replay, usable as a React key. */
+  readonly key: string
+  /** Owning session. */
+  readonly sessionId: SessionId
+  /** The requested frame's domain fields, verbatim. */
+  readonly payload: PendingPayloads[K]
+  #settled = false
+  readonly #rpcId: RpcId
+  readonly #respond: (message: ClientResponse) => Promise<RpcReceipt>
+
+  /**
+   * Minted by Session on a requested frame (public construction is the test-fixture path).
+   * @param kind - interaction kind.
+   * @param rpcId - the requested frame's stable envelope id (kept private; respond echoes it).
+   * @param sessionId - owning session.
+   * @param payload - the requested frame's domain fields.
+   * @param respond - the client-response carrier (api.respond).
+   */
+  constructor(
+    kind: K, rpcId: RpcId, sessionId: SessionId, payload: PendingPayloads[K],
+    respond: (message: ClientResponse) => Promise<RpcReceipt>,
+  ) {
+    this.kind = kind
+    this.key = `${KEY_PREFIX[kind]}:${rpcId}`
+    this.sessionId = sessionId
+    this.payload = payload
+    this.#rpcId = rpcId
+    this.#respond = respond
+  }
+
+  /**
+   * Send a result for this wait: wraps it into the client-response envelope
+   * with the rpcId backfilled. Throws synchronously once settled.
+   * @param result - the result shell (ok value / error envelope), domain-encoded by the caller.
+   * @returns the carrier receipt.
+   */
+  respond(result: ClientResponse['result']): Promise<RpcReceipt> {
+    if (this.#settled) throw new Error(`pending wait ${this.key} is already settled`)
+    return this.#respond({ type: 'client-response', rpcId: this.#rpcId, result })
+  }
+
+  /** Session-only settlement mark (the authoritative resolved frame arrived); respond() throws afterwards. */
+  markSettled(): void {
+    this.#settled = true
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
index ec63b8f70d..d8a6f05762 100644
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -5,13 +5,14 @@
  * slot-parity design), session scope tree (mintScope pattern: no-op plugin
  * Fiber + ctx.extend scope tag), stable SessionBinding cache, ancestry walk.
  *
- * Scope lifecycle is watch-driven: a scope is minted lazily on first
- * resolution; a session leaving the list tears its scope down only when
- * nobody is watching it. "Watched" is approximated as the most recently
- * resolved binding id — SessionProvider re-resolves on every selection
- * change (keyed remount), so a switch away always re-evaluates the deferred
- * teardown; a host-side death without list removal keeps the scope (frozen
- * read-only view).
+ * Scope lifecycle is stage-driven: a scope is minted lazily on first
+ * resolution (pure — resolution has no side effects and is render-safe);
+ * the event window and deferred teardown key off the STAGED session, which
+ * follows `list.current` exactly. Staging is the open signal: the window
+ * opens ⟺ the session is on stage (today the stage is `current`; the staged
+ * state can widen to a multi-pane list later). A session leaving the list
+ * tears its scope down immediately unless it is the staged one, whose scope
+ * survives frozen (read-only view) until the stage moves on.
  */
 import type { Context, Fiber } from 'cordis'
 import type { IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
@@ -24,7 +25,10 @@ import type { Session } from './session.ts'
 /** Session list row projected from the host list RPC plus live stream increments. */
 export interface SessionSummary {
   id: SessionId
-  title: string
+  /** Latest durable log-backed title, absent until the host projects one. */
+  title?: string
+  /** Human-facing label: durable title, project basename, then session id. */
+  displayTitle: string
   cwd?: string
   parentId?: SessionId
   running: boolean
@@ -61,10 +65,11 @@ export function scopeOf(ctx: Context): SessionId | undefined {
 function sessionScope(): void {}
 
 /**
- * Display title projection. The wire summary carries no title yet (P-I
- * ledger): the project directory's basename stands in, then the raw id.
+ * Display title projection: durable title, project directory basename, then
+ * the raw id.
  */
-function titleOf(cwd: string | undefined, id: SessionId): string {
+function displayTitleOf(title: string | undefined, cwd: string | undefined, id: SessionId): string {
+  if (title !== undefined) return title
   if (cwd !== undefined && cwd !== '') {
     const base = cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
     if (base !== undefined && base !== '') return base
@@ -90,23 +95,29 @@ export class SessionsService {
   /**
    * Persisted selection cell (the durable half of `list.current`). Private on
    * purpose: reads go through the list snapshot; writes through {@link
-   * SessionsService.open}. Projection validates it against the live list
-   * instead of destructively pruning, so a selection survives transient list
-   * states (reconnect re-pull) and resurfaces when its session returns.
+   * SessionsService.open} / {@link SessionsService.clear}. Projection
+   * validates it against the live list instead of destructively pruning, so a
+   * selection survives transient list states (reconnect re-pull) and
+   * resurfaces when its session returns.
    */
   private readonly selection: SnapshotStore<{ sessionId?: SessionId }>
 
   private readonly scopes = new Map<SessionId, ScopeRecord>()
-  /** Most recently resolved binding id — the watch approximation for deferred teardown. */
+  /**
+   * The staged session id — follows `list.current` exactly, holding its last
+   * defined value across masked gaps (a transiently absent selection blanks
+   * `current` without moving the stage, so reconnect re-pulls and removals
+   * keep the staged scope's frozen view alive until the stage moves on).
+   */
   private watched: SessionId | undefined
-  /** Removed-while-watched sessions whose teardown waits for the watch to move away. */
+  /** Removed-while-staged sessions whose teardown waits for the stage to move away. */
   private readonly deferredRemovals = new Set<SessionId>()
 
   /**
    * @param ctx - client root context (scope fibers mount under it).
    * @param api - wire client shared with every Session.
    */
-  constructor(private readonly rootCtx: Context, api: IApiClient) {
+  constructor(private readonly rootCtx: Context, private readonly api: IApiClient) {
     this.manager = new SessionManager(api)
     this.selection = createSnapshotStore<{ sessionId?: SessionId }>(
       {},
@@ -115,12 +126,19 @@ export class SessionsService {
     // The manager owns wire truth; the store is its projection. Manager
     // notifications are already microtask-batched.
     this.manager.subscribe(() => { this.projectList() })
+    // Stage follower: every current write (open() and projection alike)
+    // re-evaluates staging, so startup restore (persisted selection validated
+    // by the projection) and reconnect resurfacing open their window with no
+    // dedicated code path. Safe to run synchronously inside the store notify:
+    // the follower writes no list state — session.open()'s synchronous prefix
+    // touches only session-side state and its own microtask-batched notifier.
+    this.list.subscribe(() => { this.followCurrent() })
     rootCtx.reflect.provide('sessions', this, undefined)
   }
 
   /**
    * Select a session as current. Unknown ids fail loud instead of navigating
-   * nowhere (the sole selection write path).
+   * nowhere.
    * @param id - session id (must exist in the list store).
    */
   open(id: SessionId): void {
@@ -131,6 +149,17 @@ export class SessionsService {
     this.list.update((draft) => { draft.current = id })
   }
 
+  /**
+   * Clear the current selection so the layout shows the no-session empty
+   * state. Wipes the persisted selection too — a reload stays on empty until
+   * the user opens or starts a session. Staging holds the previous occupant
+   * across the blank (same masked-gap rule as a transient list miss).
+   */
+  clear(): void {
+    this.selection.set({})
+    this.list.update((draft) => { draft.current = undefined })
+  }
+
   /**
    * Create a session on the host.
    * @param opts - creation options (project directory).
@@ -142,6 +171,27 @@ export class SessionsService {
     return result.value.sessionId
   }
 
+  /**
+   * Create a workspace folder under the host process cwd and a session in it.
+   * Name is a single path segment (no separators); the host mkdir runs inside
+   * session.create. Caller opens the returned id when it wants the session staged.
+   * @param name - workspace folder basename.
+   * @returns the new session id.
+   */
+  async createWorkspace(name: string): Promise<SessionId> {
+    const trimmed = name.trim()
+    if (trimmed === '') throw new Error('sessions.createWorkspace: name is required')
+    if (/[/\\]/.test(trimmed)) {
+      throw new Error('sessions.createWorkspace: name must not contain path separators')
+    }
+    const { result } = await this.api.host.describe({})
+    if (!result.ok) {
+      throw new Error(`host.describe failed: ${result.error.code}: ${result.error.message}`)
+    }
+    const hostCwd = result.value.cwd.replace(/[/\\]+$/, '')
+    return this.create({ cwd: `${hostCwd}/${trimmed}` })
+  }
+
   /**
    * Resolve a session-scoped context view (use-and-discard).
    * @param id - session id.
@@ -152,35 +202,62 @@ export class SessionsService {
   }
 
   /**
-   * Resolve the stable session binding (SessionProvider's resolveBinding feed).
+   * Read the session scope tag off a context. Service-method seam: 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.
+   * @param ctx - any client context.
+   * @returns the session id, or undefined on root contexts.
+   */
+  scopeOf(ctx: Context): SessionId | undefined {
+    return scopeOf(ctx)
+  }
+
+  /**
+   * Resolve the stable session binding (scope-addressed assembly feed). Pure
+   * resolution — no staging, no window side effects.
    * @param id - session id.
    * @returns binding, or undefined for a session neither listed nor already scoped.
    */
   binding(id: SessionId): SessionBinding | undefined {
-    const record = this.resolve(id)
-    if (record === undefined) return undefined
-    if (this.watched !== id) {
-      this.watched = id
-      this.sweepDeferred()
-    }
-    return record.binding
+    return this.resolve(id)?.binding
   }
 
   /**
    * Resolve the render-layer session cell (SessionProvider's feed through
-   * the renderer host; ctx never enters the render layer). Marks the session
-   * watched, same as {@link SessionsService.binding}.
+   * the renderer host; ctx never enters the render layer). Pure resolution —
+   * render-safe: SessionProvider calls this during render, so no staging, no
+   * window side effects (StrictMode double-invokes and concurrent discarded
+   * passes must stay free).
    * @param id - session id.
    * @returns cell, or undefined for a session neither listed nor already scoped.
    */
   cell(id: string): SessionCell | undefined {
-    const record = this.resolve(id as SessionId)
-    if (record === undefined) return undefined
-    if (this.watched !== id) {
-      this.watched = id as SessionId
-      this.sweepDeferred()
+    return this.resolve(id as SessionId)?.cell
+  }
+
+  /**
+   * Move the stage to the list's current session: sweep teardowns deferred
+   * behind the previous occupant and pull the new occupant's history window.
+   * Staging IS the open signal — the window opens ⟺ the session is on stage
+   * — and open() is idempotent (an in-flight or completed open no-ops; a
+   * failed one retries the next time current is touched).
+   */
+  private followCurrent(): void {
+    const current = this.list.getSnapshot().current
+    // A masked gap (current blanked while the selection's session is
+    // transiently absent) holds the stage: tearing down on the gap would
+    // destroy exactly the frozen scope the mask exists to preserve.
+    if (current === undefined || current === this.watched) return
+    this.watched = current
+    this.sweepDeferred()
+    const record = this.resolve(current)
+    /* v8 ignore next 3 -- defensive: current is always a listed id (open()
+     * validates and the projection masks absent selections), so resolve
+     * cannot miss; kept so a future current writer cannot crash the notify. */
+    if (record !== undefined) {
+      void record.binding.session.open()
     }
-    return record.cell
   }
 
   /**
@@ -231,9 +308,10 @@ export class SessionsService {
       ids.push(entry.sessionId)
       byId[entry.sessionId] = {
         id: entry.sessionId,
-        title: titleOf(entry.cwd, entry.sessionId),
+        displayTitle: displayTitleOf(entry.title, entry.cwd, entry.sessionId),
         running: entry.running,
         updatedAt: entry.updatedAt,
+        ...(entry.title !== undefined ? { title: entry.title } : {}),
         ...(entry.cwd !== undefined ? { cwd: entry.cwd } : {}),
         ...(entry.parentSessionId !== undefined ? { parentId: entry.parentSessionId } : {}),
       }
@@ -246,7 +324,7 @@ export class SessionsService {
     this.pruneScopes(byId)
   }
 
-  /** Tear down scopes for removed sessions nobody watches; the watched one defers until the watch moves. */
+  /** Tear down scopes for removed sessions off stage; the staged one defers until the stage moves. */
   private pruneScopes(byId: Record<SessionId, SessionSummary>): void {
     for (const [id, record] of this.scopes) {
       if (byId[id] !== undefined) continue
@@ -268,11 +346,11 @@ export class SessionsService {
     this.rootCtx.get('slots')?.pruneStoreScope(id)
   }
 
-  /** Run deferred teardowns whose session is no longer watched (called when the watch moves). */
+  /** Run deferred teardowns whose session is no longer staged (called when the stage moves). */
   private sweepDeferred(): void {
     for (const id of [...this.deferredRemovals]) {
-      /* v8 ignore next -- defensive: only the watched id ever defers, and every
-       * watch move sweeps first, so the set cannot contain the id the watch just
+      /* v8 ignore next -- defensive: only the staged id ever defers, and every
+       * stage move sweeps first, so the set cannot contain the id the stage just
        * moved to; kept as a guard against future extra sweep call sites. */
       if (id === this.watched) continue
       // Still absent from the list? (A re-added id cancels the deferred teardown.)
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 761aca96c2..6b773e0903 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -5,12 +5,19 @@
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import type { HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult, SessionId, ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
-import { transportError } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult,
+  SessionId, ToolEventView,
+} from '@deepseek-ai/dsh-client-connection/client'
+// Value import from the inline-safe wire layer (not the connection plugin):
+// plugin-to-plugin value imports are a bundle purity error.
+import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { ObservableSnapshot } from '../contract/store.ts'
 import type {
-  ConversationNode, ConversationSnapshot, OpenState, PendingInteraction, PromptError, RunningToolCall,
+  ConversationNode, ConversationSnapshot, OpenState, PromptError, RunningToolCall,
 } from './conversation.ts'
+import type { PendingInteraction } from './pending.ts'
+import { PendingWait } from './pending.ts'
 import { FoldAdapter } from './fold-adapter.ts'
 import { Notifier } from './notifier.ts'
 import { PartialAccumulator } from './partial.ts'
@@ -183,7 +190,9 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
     this.events = []
     this.views = []
     this.baseSeq = 0
-    this.pending.clear() // the subscribed baseline replay re-sends still-pending requested frames verbatim
+    // 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.
+    this.pending.clear()
     this.pendingRev++
     this.subscribedLastSeq = null
     this.liveBuffer = []
@@ -229,33 +238,27 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
         return // pure baseline bookkeeping, no visible change
       }
       case 'approval/requested': {
-        this.pending.set(`a:${rpcId}`, {
-          kind: 'approval', rpcId, approvalId: frame.approvalId, toolName: frame.toolName,
-          ...(frame.callId !== undefined ? { callId: frame.callId } : {}),
-          ...(frame.reason !== undefined ? { reason: frame.reason } : {}),
-        })
-        this.pendingRev++
+        const { type: _type, sessionId: _sid, ...payload } = frame
+        this.mint(new PendingWait('approval', rpcId, this.sessionId, payload, m => this.api.respond(m)))
         this.notifier.markDirty()
         return
       }
       case 'approval/resolved': {
-        for (const [key, item] of this.pending) {
-          if (item.kind === 'approval' && item.approvalId === frame.approvalId) {
-            this.pending.delete(key)
-            this.pendingRev++
-          }
+        for (const item of this.pending.values()) {
+          if (item.kind === 'approval' && item.payload.approvalId === frame.approvalId) this.settle(item)
         }
         this.notifier.markDirty()
         return
       }
       case 'question/requested': {
-        this.pending.set(`q:${rpcId}`, { kind: 'question', rpcId, questions: frame.questions })
-        this.pendingRev++
+        const { type: _type, sessionId: _sid, ...payload } = frame
+        this.mint(new PendingWait('question', rpcId, this.sessionId, payload, m => this.api.respond(m)))
         this.notifier.markDirty()
         return
       }
       case 'question/resolved': {
-        if (this.pending.delete(`q:${frame.questionRpcId}`)) this.pendingRev++
+        const item = this.pending.get(`q:${frame.questionRpcId}`)
+        if (item !== undefined) this.settle(item)
         this.notifier.markDirty()
         return
       }
@@ -295,6 +298,19 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
 
   // ---- 私有 ----
 
+  /** Requested-frame arrival: the wait enters the pending map under its own key. */
+  private mint(wait: PendingInteraction): void {
+    this.pending.set(wait.key, wait)
+    this.pendingRev++
+  }
+
+  /** Authoritative resolved-frame settlement: mark, then drop from the pending map. */
+  private settle(wait: PendingInteraction): void {
+    wait.markSettled()
+    this.pending.delete(wait.key)
+    this.pendingRev++
+  }
+
   /** @param generation - openGeneration at launch; every await re-checks it and a stale pass
    *  drops all writes (resync superseded this open — its outcome belongs to a dead connection). */
   private async doOpen(generation: number): Promise<void> {
@@ -418,7 +434,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
       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,
+          turn: event.data.turn, step: event.data.step, time: event.time,
           callView: view?.for === 'call' ? view.view : null,
         })
         this.callsRev++
@@ -439,7 +455,8 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
           if (visible) {
             // Fractional seq: strictly after every event of this turn (all < turn/end seq), before the next turn.
             this.frozenNodes.push({
-              kind: 'assistant', seq: event.seq - 0.9, turn: this.partial.turn, step: this.partial.step,
+              kind: 'assistant', seq: event.seq - 0.9, time: event.time,
+              turn: this.partial.turn, step: this.partial.step,
               blocks, interrupted: true,
             })
             this.frozenRev++
@@ -453,8 +470,10 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
           this.callsRev++
           // The spinner card becomes an interrupted terminal card (never vanishes mid-flow).
           this.frozenNodes.push({
-            kind: 'tool-result', seq: event.seq - 0.8 + callOffset++ * 0.01, callId,
+            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,
           })
diff --git a/packages/client/runtime/src/client/slots.ts b/packages/client/runtime/src/client/slots.ts
index 700026df52..0930787e0a 100644
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -66,6 +66,10 @@ interface ErasedRegisterOptions {
   id?: string
   order?: number
   label?: string
+  /** Chain-slot routing selector (pure; the core validates presence for chain targets). */
+  select?: (owner: never) => unknown
+  /** Chain-slot explicit ordering override (ascending; registration order otherwise). */
+  priority?: number
   registrant?: string
 }
 
diff --git a/packages/client/runtime/tests/client-loader.spec.ts b/packages/client/runtime/tests/client-loader.spec.ts
deleted file mode 100644
index 457b1fc13c..0000000000
--- a/packages/client/runtime/tests/client-loader.spec.ts
+++ /dev/null
@@ -1,289 +0,0 @@
-/**
- * ClientLoader: handoff protocol (single slot, id reconciliation), DI require
- * with export-surface re-registration, immediately-group barrier (parallel
- * fetch / topology execution / full-group barrier), status store, settled,
- * failure modes (missing handoff, unknown dep, cycle, unload stub).
- */
-import { Context } from 'cordis'
-import { afterEach, describe, expect, it } from 'vitest'
-import { createClientLoader } from '../src/client/loader/index.ts'
-import type { BootPluginEntry, ClientPluginHandoff } from '../src/client/loader/index.ts'
-
-type Win = { DSHClientProxy?: { loadPlugin(h: ClientPluginHandoff): void }; __DSH_BOOT__?: { plugins: BootPluginEntry[] } }
-const win = globalThis as Win
-
-afterEach(() => {
-  delete win.DSHClientProxy
-  delete win.__DSH_BOOT__
-})
-
-interface FakeBundle {
-  handoff: ClientPluginHandoff | null | ((require: (spec: string) => unknown) => Record<string, unknown>)
-}
-
-interface Bench {
-  loader: ReturnType<typeof createClientLoader>
-  fetched: string[]
-  executed: string[]
-  fetchGate: Map<string, () => void>
-}
-
-/** Build a loader over scripted fake bundles keyed by url; fetches resolve when released (or immediately). */
-function bench(
-  plugins: BootPluginEntry[],
-  bundles: Record<string, FakeBundle>,
-  opts: { modules?: Record<string, unknown>; gated?: string[] } = {},
-): Bench {
-  const ctx = new Context()
-  const fetched: string[] = []
-  const executed: string[] = []
-  const fetchGate = new Map<string, () => void>()
-  const loader = createClientLoader({
-    ctx,
-    modules: opts.modules ?? { react: { marker: 'react' } },
-    boot: { plugins },
-    fetchBundle: (url) => {
-      fetched.push(url)
-      if (opts.gated?.includes(url) === true) {
-        return new Promise<string>((resolve) => { fetchGate.set(url, () => { resolve(url) }) })
-      }
-      return Promise.resolve(url)
-    },
-    executeBundle: (code) => {
-      executed.push(code)
-      const bundle = bundles[code]
-      if (bundle === undefined) throw new Error(`no fake bundle for ${code}`)
-      if (bundle.handoff === null) return // simulates a bundle that never calls loadPlugin
-      if (typeof bundle.handoff === 'function') {
-        win.DSHClientProxy?.loadPlugin({ id: code.replace('/client.js', '').replace('/plugins/', ''), factory: bundle.handoff })
-        return
-      }
-      win.DSHClientProxy?.loadPlugin(bundle.handoff)
-    },
-  })
-  return { loader, fetched, executed, fetchGate }
-}
-
-const entry = (id: string, inject: string[] = [], immediately?: boolean): BootPluginEntry =>
-  ({ id, url: `/plugins/${id}/client.js`, inject, ...(immediately === true ? { immediately: true } : {}) })
-
-const okBundle = (applied?: string[], exports: Record<string, unknown> = {}): FakeBundle => ({
-  handoff: require => ({
-    apply: (pluginCtx: Context) => { void pluginCtx; applied?.push('applied') },
-    require,
-    ...exports,
-  }),
-})
-
-describe('load chain', () => {
-  it('runs fetch→execute→handoff→factory(require)→apply→export re-registration→status active', async () => {
-    const applied: string[] = []
-    const b = bench(
-      [entry('fake-base', [], true), entry('feature', ['fake-base'])],
-      {
-        '/plugins/fake-base/client.js': { handoff: () => ({ apply: () => { applied.push('fake-base') }, helper: 'base-helper' }) },
-        '/plugins/feature/client.js': {
-          handoff: (require) => {
-            // Later loader requires the earlier one's export surface (inject topology guarantee).
-            const fakeBase = ['fake','base'].join('-') // assembled so knip's static require() scan skips the fake id
-            const base = require(fakeBase) as { helper: string }
-            expect(base.helper).toBe('base-helper')
-            expect((require('react') as { marker: string }).marker).toBe('react')
-            return { apply: () => { applied.push('feature') } }
-          },
-        },
-      },
-    )
-    b.loader.start()
-    await b.loader.settled()
-    expect(applied).toEqual(['fake-base', 'feature'])
-    expect(b.loader.status.getSnapshot()).toEqual({ 'fake-base': 'active', feature: 'active' })
-    expect((b.loader.requireModule('fake-base') as { helper: string }).helper).toBe('base-helper')
-    expect(() => b.loader.requireModule('ghost')).toThrow(/not available/)
-  })
-
-  it('fetches the immediately group in parallel and holds the barrier before the rest', async () => {
-    const b = bench(
-      [entry('a', [], true), entry('b', ['a'], true), entry('later')],
-      {
-        '/plugins/a/client.js': okBundle(),
-        '/plugins/b/client.js': okBundle(),
-        '/plugins/later/client.js': okBundle(),
-      },
-      { gated: ['/plugins/a/client.js'] },
-    )
-    b.loader.start()
-    await Promise.resolve()
-    // Both early fetches are in flight before any execution; the late plugin is not fetched yet.
-    expect(b.fetched).toEqual(['/plugins/a/client.js', '/plugins/b/client.js'])
-    expect(b.executed).toEqual([])
-    b.fetchGate.get('/plugins/a/client.js')?.()
-    await b.loader.settled()
-    expect(b.executed).toEqual(['/plugins/a/client.js', '/plugins/b/client.js', '/plugins/later/client.js'])
-  })
-
-  it('orders execution by inject topology within each group', async () => {
-    const b = bench(
-      [entry('z-ui', ['a-base']), entry('a-base')],
-      { '/plugins/a-base/client.js': okBundle(), '/plugins/z-ui/client.js': okBundle() },
-    )
-    b.loader.start()
-    await b.loader.settled()
-    expect(b.executed).toEqual(['/plugins/a-base/client.js', '/plugins/z-ui/client.js'])
-  })
-})
-
-describe('failure modes (fail loud)', () => {
-  it('rejects settled and marks failed when a bundle never calls loadPlugin', async () => {
-    const b = bench([entry('silent')], { '/plugins/silent/client.js': { handoff: null } })
-    b.loader.start()
-    await expect(b.loader.settled()).rejects.toThrow(/without calling DSHClientProxy.loadPlugin/)
-    expect(b.loader.status.getSnapshot().silent).toBe('failed')
-  })
-
-  it('rejects on manifest/handoff id mismatch', async () => {
-    const b = bench([entry('expected')], {
-      '/plugins/expected/client.js': { handoff: { id: 'imposter', factory: () => ({ apply: () => {} }) } },
-    })
-    b.loader.start()
-    await expect(b.loader.settled()).rejects.toThrow(/id mismatch/)
-  })
-
-  it('rejects unknown inject targets, cycles, missing apply, unknown load ids, duplicate manifest ids', async () => {
-    // Sequential benches: each loader owns the window proxy, so release it between them.
-    const fresh = <T>(build: () => T): T => {
-      delete win.DSHClientProxy
-      return build()
-    }
-
-    const missing = fresh(() => bench([entry('x', ['nope'])], { '/plugins/x/client.js': okBundle() }))
-    missing.loader.start()
-    await expect(missing.loader.settled()).rejects.toThrow(/injects unknown plugin "nope"/)
-
-    const cyclic = fresh(() => bench(
-      [entry('p', ['q']), entry('q', ['p'])],
-      { '/plugins/p/client.js': okBundle(), '/plugins/q/client.js': okBundle() },
-    ))
-    cyclic.loader.start()
-    await expect(cyclic.loader.settled()).rejects.toThrow(/inject cycle/)
-
-    const applyless = fresh(() => bench([entry('noap')], { '/plugins/noap/client.js': { handoff: { id: 'noap', factory: () => ({}) } } }))
-    applyless.loader.start()
-    await expect(applyless.loader.settled()).rejects.toThrow(/exports no apply/)
-
-    const b = fresh(() => bench([entry('a')], { '/plugins/a/client.js': okBundle() }))
-    await expect(b.loader.load('ghost')).rejects.toThrow(/unknown plugin "ghost"/)
-
-    expect(() => fresh(() => bench([entry('dup'), entry('dup')], {}))).toThrow(/duplicate manifest id/)
-  })
-
-  it('throws on missing boot manifest, double proxy install, and pre-start settled', () => {
-    expect(() => createClientLoader({ ctx: new Context(), modules: {} })).toThrow(/no boot manifest/)
-    const b = bench([], {})
-    expect(() => b.loader.settled()).toThrow(/settled\(\) before start\(\)/)
-    // First bench installed the proxy; a second loader must refuse.
-    expect(() => createClientLoader({ ctx: new Context(), modules: {}, boot: { plugins: [] } })).toThrow(/already installed/)
-  })
-
-  it('direct load() before a dependency is active fails loud (same check start() sequences)', async () => {
-    const b = bench(
-      [entry('dep', [], true), entry('needy', ['dep'])],
-      { '/plugins/dep/client.js': okBundle(), '/plugins/needy/client.js': okBundle() },
-    )
-    await expect(b.loader.load('needy')).rejects.toThrow(/loaded before its dependency "dep" is active/)
-  })
-
-  it('direct load() naming an unknown inject target fails loud', async () => {
-    const b = bench([entry('solo', ['phantom'])], { '/plugins/solo/client.js': okBundle() })
-    await expect(b.loader.load('solo')).rejects.toThrow(/injects unknown plugin "phantom"/)
-  })
-
-  it('an immediately-group fetch failure surfaces through settled, not as an unhandled prefetch rejection', async () => {
-    // The fire-and-forget prefetch swallow arm must absorb the early
-    // rejection; the awaited load surfaces the same failure via settled().
-    const ctx = new Context()
-    delete win.DSHClientProxy
-    const loader = createClientLoader({
-      ctx,
-      modules: {},
-      boot: { plugins: [{ id: 'kaboom', url: '/plugins/kaboom/client.js', inject: [], immediately: true }] },
-      fetchBundle: () => Promise.reject(new Error('bundle fetch exploded')),
-      executeBundle: () => {},
-    })
-    loader.start()
-    await expect(loader.settled()).rejects.toThrow(/bundle fetch exploded/)
-  })
-
-  it('unload is the P-I stub', async () => {
-    const b = bench([], {})
-    await expect(b.loader.unload('x')).rejects.toThrow(/not implemented/)
-  })
-})
-
-describe('DOM default seams (stubbed globals)', () => {
-  it('default fetchBundle uses fetch, rejects non-OK; default executeBundle injects an inline script; claimStyles tags orphans', async () => {
-    const origFetch = globalThis.fetch
-    const appended: { textContent?: string | null }[] = []
-    const styleTag = {
-      attrs: {} as Record<string, string>,
-      setAttribute(k: string, v: string) { this.attrs[k] = v },
-    }
-    const fakeDoc = {
-      createElement: () => {
-        const el = { textContent: null as string | null }
-        return el
-      },
-      head: { appendChild: (el: { textContent?: string | null }) => { appended.push(el) } },
-      querySelectorAll: () => [styleTag],
-    }
-    const g = globalThis as { document?: unknown; fetch: typeof fetch }
-    g.document = fakeDoc
-    g.fetch = (url: URL | RequestInfo) => Promise.resolve(
-      (typeof url === 'string' ? url : url instanceof URL ? url.href : url.url).includes('bad')
-        ? new Response('x', { status: 500 })
-        : new Response('window.DSHClientProxy.loadPlugin(globalThis.__seamHandoff)', { status: 200 }),
-    )
-    try {
-      delete win.DSHClientProxy
-      const ctx = new Context()
-      const loader = createClientLoader({
-        ctx,
-        modules: {},
-        boot: { plugins: [
-          { id: 'seam-ok', url: '/plugins/seam-ok/client.js', inject: [] },
-          { id: 'seam-bad', url: '/plugins/bad/client.js', inject: [] },
-        ] },
-        // NO seams injected (keys omitted, not undefined — exactOptional):
-        // the DOM defaults are under test.
-      })
-      const seamHandoff: ClientPluginHandoff = {
-        id: 'seam-ok',
-        factory: () => ({ apply: () => {} }),
-      }
-      // Default executeBundle only APPENDS the script element (no execution in
-      // our fake DOM), so drive the handoff manually before load resolves it.
-      const loadOk = loader.load('seam-ok')
-      await Promise.resolve()
-      ;(globalThis as Win).DSHClientProxy?.loadPlugin(seamHandoff)
-      await loadOk
-      expect(appended).toHaveLength(1)
-      expect(appended[0]?.textContent).toContain('sourceURL=/plugins/seam-ok/client.js')
-      expect(styleTag.attrs['data-plugin']).toBe('seam-ok')
-      await expect(loader.load('seam-bad')).rejects.toThrow(/answered 500/)
-    } finally {
-      g.fetch = origFetch
-      delete (globalThis as { document?: unknown }).document
-    }
-  })
-})
-
-describe('handoff slot protocol', () => {
-  it('rejects an overlapping loadPlugin before the loader claims the pending handoff', () => {
-    delete win.DSHClientProxy
-    createClientLoader({ ctx: new Context(), modules: {}, boot: { plugins: [] } })
-    const proxy = (globalThis as Win).DSHClientProxy
-    proxy?.loadPlugin({ id: 'first', factory: () => ({ apply: () => {} }) })
-    expect(() => proxy?.loadPlugin({ id: 'second', factory: () => ({ apply: () => {} }) }))
-      .toThrow(/overlapping loadPlugin handoff/)
-  })
-})
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index c13ef09fcb..25f12c2b70 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -2,7 +2,7 @@
 // data source on a real clock; behavior tests need per-case responses and
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type {
-  HostFrame, IApiClient, MuxFrame, RpcError, RpcRequest, RpcResponse, SessionId,
+  ClientResponse, HostFrame, IApiClient, MuxFrame, RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId,
 } from '@deepseek-ai/dsh-client-connection/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
 
@@ -93,8 +93,10 @@ export class FakeApiClient implements IApiClient {
     host: (_payload: unknown, signal: AbortSignal, onOpen?: () => void) => this.openStream(this.hostConns, signal, onOpen),
   }
 
-  respond(): Promise<{ accepted: false; reason: 'not-pending' }> {
-    return Promise.resolve({ accepted: false, reason: 'not-pending' })
+  onRespond: (message: ClientResponse) => Promise<RpcReceipt> = () => Promise.resolve({ accepted: true })
+
+  respond(message: ClientResponse): Promise<RpcReceipt> {
+    return this.record('respond', message, this.onRespond(message))
   }
 
   /** Push one mux frame to every open mux stream (rpcId minted unless pinned by the case). */
diff --git a/packages/client/runtime/tests/fold-adapter.spec.ts b/packages/client/runtime/tests/fold-adapter.spec.ts
index 3214c44ee9..bb360e2a67 100644
--- a/packages/client/runtime/tests/fold-adapter.spec.ts
+++ b/packages/client/runtime/tests/fold-adapter.spec.ts
@@ -40,7 +40,7 @@ describe('FoldAdapter', () => {
       ev.user(0, '用户'),
       ev.assistant(1, 0, '助手'),
       at(2, { type: 'steering/message', surfaceOp: 'append', data: { turn: 0, content: [{ type: 'text', text: '插话' }], source: { kind: 'user' } } }),
-      at(3, { type: 'context/message', surfaceOp: 'append', data: { content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' } } }),
+      at(3, { type: 'user/message', surfaceOp: 'append', data: { content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' } } }),
       ev.toolCall(4, 0, 'c1', 'echo', '{"x":1}'),
       ev.toolResult(5, 0, 'c1', '结果'),
     ]
diff --git a/packages/client/runtime/tests/manager.spec.ts b/packages/client/runtime/tests/manager.spec.ts
index af7bc60fd2..d37ef6dbce 100644
--- a/packages/client/runtime/tests/manager.spec.ts
+++ b/packages/client/runtime/tests/manager.spec.ts
@@ -34,7 +34,7 @@ describe('instances', () => {
     manager.handleMuxEnvelope({ rpcId: 'ra' as never, payload: { type: 'approval/requested', sessionId: S1, approvalId: 'ap1' as never, toolName: 'rm' } })
     manager.handleMuxEnvelope({ rpcId: 're' as never, payload: { type: 'session/event', sessionId: S1, event: plainTurn(0, 0, 'x', 'y')[0] as never } })
     const session = manager.get(S1)
-    expect(session.getSnapshot().pending).toMatchObject([{ kind: 'approval', approvalId: 'ap1' }])
+    expect(session.getSnapshot().pending).toMatchObject([{ kind: 'approval', payload: { approvalId: 'ap1' } }])
     // Buffer cleared: a second instantiation of another id gets nothing.
     expect(manager.get(S2).getSnapshot().pending).toEqual([])
   })
@@ -48,7 +48,7 @@ describe('instances', () => {
     }
     const pending = manager.get(S1).getSnapshot().pending
     expect(pending).toHaveLength(32)
-    expect(pending.map(p => p.rpcId)).toEqual(Array.from({ length: 32 }, (_, i) => `q${i + 8}`)) // oldest 8 dropped
+    expect(pending.map(p => p.key)).toEqual(Array.from({ length: 32 }, (_, i) => `q:q${i + 8}`)) // oldest 8 dropped
     // Removed session: buffered frames must not replay on a future instantiation.
     manager.handleMuxEnvelope({ rpcId: 'qz' as never, payload: { type: 'question/requested', sessionId: S2, questions: [] } })
     manager.handleHostEnvelope({ rpcId: 'hz' as never, payload: { type: 'host/session-removed', sessionId: S2 } })
@@ -89,6 +89,66 @@ describe('list lifecycle', () => {
     expect(result).toMatchObject({ ok: true, value: { sessionId: S2 } })
     expect(manager.getListSnapshot().items.map(i => i.sessionId)).toEqual([S2])
   })
+
+  it('retains monotonic title snapshots before list arrival, merges recency, and clears them on removal', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    manager.handleMuxEnvelope({
+      rpcId: 'title-new' as never,
+      payload: { type: 'session/title', sessionId: S1, title: 'Newest', eventSeq: 4, updatedAt: 300 },
+    })
+    manager.handleMuxEnvelope({
+      rpcId: 'title-stale' as never,
+      payload: { type: 'session/title', sessionId: S1, title: 'Stale', eventSeq: 3, updatedAt: 900 },
+    })
+    manager.handleMuxEnvelope({
+      rpcId: 'title-equal' as never,
+      payload: { type: 'session/title', sessionId: S1, title: 'Equal', eventSeq: 4, updatedAt: 901 },
+    })
+    api.onList = () => Promise.resolve(ok({
+      items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[],
+    }))
+    await manager.refreshList()
+
+    const titled = manager.getListSnapshot()
+    expect(titled.items.map(item => item.sessionId)).toEqual([S1, S2])
+    expect(titled.items[0]).toMatchObject({ title: 'Newest', updatedAt: 300 })
+    expect(titled.items[1]?.title).toBeUndefined()
+
+    manager.handleHostEnvelope({ rpcId: 'removed' as never, payload: { type: 'host/session-removed', sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'readded' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    expect(manager.getListSnapshot().items.find(item => item.sessionId === S1)?.title).toBeUndefined()
+  })
+
+  it('drops a retained title beyond the subscription baseline before accepting its durable replay', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1)] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    manager.handleMuxEnvelope({
+      rpcId: 'title-unflushed' as never,
+      payload: { type: 'session/title', sessionId: S1, title: 'Unflushed', eventSeq: 4, updatedAt: 400 },
+    })
+
+    manager.handleMuxEnvelope({
+      rpcId: 'subscribed-recovered' as never,
+      payload: { type: 'session/subscribed', sessionId: S1, lastSeq: 2 },
+    })
+    expect(manager.getListSnapshot().items[0]?.title).toBeUndefined()
+    expect(manager.getListSnapshot().items[0]?.updatedAt).toBe(100)
+
+    manager.handleMuxEnvelope({
+      rpcId: 'title-durable' as never,
+      payload: { type: 'session/title', sessionId: S1, title: 'Durable', eventSeq: 2, updatedAt: 200 },
+    })
+    expect(manager.getListSnapshot().items[0]).toMatchObject({ title: 'Durable', updatedAt: 200 })
+
+    manager.handleMuxEnvelope({
+      rpcId: 'subscribed-current' as never,
+      payload: { type: 'session/subscribed', sessionId: S1, lastSeq: 2 },
+    })
+    expect(manager.getListSnapshot().items[0]).toMatchObject({ title: 'Durable', updatedAt: 200 })
+  })
 })
 
 describe('host frame routing', () => {
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index 149f73c1fc..b980a674fe 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -251,6 +251,36 @@ describe('pending interactions', () => {
     session.handleMuxEnvelope('ry' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'rq' as never, outcome: 'answered' })
     expect(session.getSnapshot().pending).toEqual([])
   })
+
+  it('mints waits whose respond() backfills the requested rpcId into the client-response envelope', async () => {
+    const { api, session } = makeSession()
+    session.handleMuxEnvelope('rq-answer' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    const wait = session.getSnapshot().pending[0]!
+    expect(wait).toMatchObject({ kind: 'question', key: 'q:rq-answer', sessionId: SID, payload: { questions: [] } })
+    const receipt = await wait.respond({
+      ok: true,
+      value: { sessionId: SID, answer: { answers: [{ id: 'mode', selected: ['Fast'] }] } },
+    })
+    expect(receipt).toEqual({ accepted: true })
+    expect(api.callsOf('respond')).toEqual([{
+      type: 'client-response', rpcId: 'rq-answer',
+      result: {
+        ok: true,
+        value: { sessionId: SID, answer: { answers: [{ id: 'mode', selected: ['Fast'] }] } },
+      },
+    }])
+  })
+
+  it('settles the wait on the authoritative resolved frame: respond() then throws synchronously', async () => {
+    const { api, session } = makeSession()
+    session.handleMuxEnvelope('rq1' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    const wait = session.getSnapshot().pending[0]!
+    session.handleMuxEnvelope('ry' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'rq1' as never, outcome: 'answered' })
+    expect(session.getSnapshot().pending).toEqual([])
+    expect(() => wait.respond({ ok: false, error: { code: 'internal', message: 'x', details: {} } }))
+      .toThrow('already settled')
+    expect(api.callsOf('respond')).toEqual([])
+  })
 })
 
 describe('remaining branches', () => {
@@ -355,7 +385,7 @@ describe('remaining branches', () => {
     session.handleMuxEnvelope('ra' as never, {
       type: 'approval/requested', sessionId: SID, approvalId: 'ap2' as never, toolName: 'rm', callId: 'c1' as never, reason: '危险',
     })
-    expect(session.getSnapshot().pending[0]).toMatchObject({ kind: 'approval', callId: 'c1', reason: '危险' })
+    expect(session.getSnapshot().pending[0]).toMatchObject({ kind: 'approval', payload: { callId: 'c1', reason: '危险' } })
     session.handleMuxEnvelope('rx' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap2' as never, outcome: 'approved' as never })
     session.handleMuxEnvelope('rx2' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap2' as never, outcome: 'approved' as never })
     session.handleMuxEnvelope('ry2' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'never-was' as never, outcome: 'cancelled' })
@@ -568,6 +598,22 @@ describe('resync', () => {
     expect(cold.api.calls).toEqual([]) // never opened: no traffic
   })
 
+  it('re-mints a replayed requested frame as a fresh wait with the same key (old reference superseded)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    session.handleMuxEnvelope('rq-replay' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    const before = session.getSnapshot().pending[0]!
+    await session.resync()
+    session.handleMuxEnvelope('rq-replay' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    const after = session.getSnapshot().pending[0]!
+    expect(after).not.toBe(before)
+    expect(after.key).toBe(before.key)
+    // Superseded ≠ settled: an in-flight respond on the stale reference still reaches the host.
+    await before.respond({ ok: false, error: { code: 'internal', message: 'x', details: {} } })
+    expect(api.callsOf('respond')).toMatchObject([{ rpcId: 'rq-replay' }])
+  })
+
   it('drops a stale in-flight open superseded by resync (generation guard)', async () => {
     const { api, session } = makeSession()
     const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
diff --git a/packages/client/runtime/tests/sessions-service.spec.ts b/packages/client/runtime/tests/sessions-service.spec.ts
index 9d18069887..8c850426bd 100644
--- a/packages/client/runtime/tests/sessions-service.spec.ts
+++ b/packages/client/runtime/tests/sessions-service.spec.ts
@@ -2,8 +2,9 @@
  * SessionsService: list store projection (manager → {ids, byId, current}
  * with derived titles), the migrated current-selection account (open
  * validation, persisted mask semantics, cell resolution), scope-tree
- * lifecycle (lazy mint / frozen survival / removed teardown with watch
- * deferral), binding identity, ancestry walk, create.
+ * lifecycle (lazy mint / frozen survival / removed teardown with staged
+ * deferral — the stage follows list.current), binding identity, ancestry
+ * walk, create.
  */
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -40,16 +41,21 @@ async function feedList(b: Bench, rows: { id: string; cwd?: string; parentId?: s
 }
 
 describe('list store projection', () => {
-  it('projects ids/byId with cwd-basename titles (id fallback) and parent links', async () => {
+  it('projects durable titles separately from cwd/id display fallbacks and parent links', async () => {
     const b = bench()
+    b.svc.manager.handleMuxEnvelope({
+      rpcId: 'title' as never,
+      payload: { type: 'session/title', sessionId: sid('s1'), title: 'Durable title', eventSeq: 2, updatedAt: 3 },
+    })
     await feedList(b, [
       { id: 's1', cwd: '/home/u/proj-a/' },
       { id: 's2', parentId: 's1', running: true },
     ])
     const state = b.svc.list.getSnapshot()
     expect(state.ids).toEqual(['s1', 's2'])
-    expect(state.byId[sid('s1')]).toMatchObject({ title: 'proj-a', cwd: '/home/u/proj-a/' })
-    expect(state.byId[sid('s2')]).toMatchObject({ title: 's2', parentId: 's1', running: true })
+    expect(state.byId[sid('s1')]).toMatchObject({ title: 'Durable title', displayTitle: 'Durable title', cwd: '/home/u/proj-a/' })
+    expect(state.byId[sid('s2')]).toMatchObject({ displayTitle: 's2', parentId: 's1', running: true })
+    expect(state.byId[sid('s2')]?.title).toBeUndefined()
   })
 
   it('reflects live increments (host stream via manager) into the store', async () => {
@@ -76,21 +82,21 @@ describe('scope tree', () => {
     expect(binding?.ctx).toBe(scoped)
   })
 
-  it('tears down an unwatched removed session but defers the watched one until the watch moves', async () => {
+  it('tears down an off-stage removed session but defers the staged one until the stage moves', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }, { id: 's2' }])
     const ctx1 = b.svc.scope(sid('s1'))
-    b.svc.binding(sid('s1')) // s1 is watched
-    b.svc.scope(sid('s2')) // s2 scoped but not watched
+    b.svc.open(sid('s1')) // s1 staged (current)
+    b.svc.scope(sid('s2')) // s2 scoped but off stage
 
-    await feedList(b, [{ id: 's1' }]) // s2 removed, unwatched: torn down
+    await feedList(b, [{ id: 's1' }]) // s2 removed, off stage: torn down
     expect(b.svc.scope(sid('s2'))).toBeUndefined()
 
-    await feedList(b, []) // s1 removed while watched: deferred, scope survives
+    await feedList(b, []) // s1 removed while staged (current masks): deferred, scope survives
     expect(b.svc.scope(sid('s1'))).toBe(ctx1)
 
     await feedList(b, [{ id: 's3' }])
-    b.svc.binding(sid('s3')) // watch moves: deferred teardown sweeps s1
+    b.svc.open(sid('s3')) // stage moves: deferred teardown sweeps s1
     expect(b.svc.scope(sid('s1'))).toBeUndefined()
   })
 
@@ -106,10 +112,10 @@ describe('scope tree', () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }])
     const scoped = b.svc.scope(sid('s1'))
-    b.svc.binding(sid('s1'))
-    await feedList(b, []) // removed while watched → deferred
-    await feedList(b, [{ id: 's1' }, { id: 's2' }]) // reappears
-    b.svc.binding(sid('s2')) // watch moves; sweep must NOT tear down the re-listed s1
+    b.svc.open(sid('s1'))
+    await feedList(b, []) // removed while staged → deferred
+    await feedList(b, [{ id: 's1' }, { id: 's2' }]) // reappears (current resurfaces, stage unchanged)
+    b.svc.open(sid('s2')) // stage moves; sweep must NOT tear down the re-listed s1
     expect(b.svc.scope(sid('s1'))).toBe(scoped)
   })
 })
@@ -127,6 +133,26 @@ describe('current selection (migrated from ui-layout, arbitrated into the list s
     expect(b.svc.list.getSnapshot().current).toBe('s1') // failed open leaves the selection alone
   })
 
+  it('clear() blanks list.current and the persisted selection', async () => {
+    const storage = new Map<string, string>()
+    vi.stubGlobal('localStorage', {
+      getItem: (k: string) => storage.get(k) ?? null,
+      setItem: (k: string, v: string) => { storage.set(k, v) },
+      removeItem: (k: string) => { storage.delete(k) },
+      clear: () => { storage.clear() },
+    })
+    const b = bench()
+    await feedList(b, [{ id: 's1' }])
+    b.svc.open(sid('s1'))
+    expect(storage.get('dsh.sessions.current')).toContain('s1')
+    b.svc.clear()
+    expect(b.svc.list.getSnapshot().current).toBeUndefined()
+    // Persisted wipe: a fresh service with the same storage stays on empty.
+    const again = bench()
+    await feedList(again, [{ id: 's1' }])
+    expect(again.svc.list.getSnapshot().current).toBeUndefined()
+  })
+
   it('masks (not destroys) the selection while its session is off the list', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }, { id: 's2' }])
@@ -168,15 +194,52 @@ describe('cell (render-layer session kit)', () => {
     expect(b.svc.cell('ghost')).toBeUndefined()
   })
 
-  it('moves the watch like binding(): switching cells sweeps a deferred removal', async () => {
+  it('cell()/binding() are pure resolution: no staging, no deferred sweep', async () => {
     const b = bench()
-    await feedList(b, [{ id: 's1' }])
-    b.svc.cell('s1') // watched
-    await feedList(b, []) // removed while watched → deferred, scope survives
+    await feedList(b, [{ id: 's1' }, { id: 's2' }])
+    b.svc.open(sid('s1')) // staged
+    b.svc.cell('s2') // resolution only — must NOT move the stage
+    b.svc.binding(sid('s2'))
+    await feedList(b, [{ id: 's2' }]) // s1 removed: still staged → deferred, scope survives
     expect(b.svc.scope(sid('s1'))).toBeDefined()
-    await feedList(b, [{ id: 's2' }])
-    b.svc.cell('s2') // watch moves → sweep tears s1 down
-    expect(b.svc.scope(sid('s1'))).toBeUndefined()
+  })
+
+  it('staging (current write) opens the session event window; resolution and re-staging do not re-pull', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }, { id: 's2' }])
+    const historyCalls = () => b.api.calls.filter(c => c.method === 'session.history')
+    // Resolution is addressing, not staging: no window pull.
+    b.svc.scope(sid('s1'))
+    b.svc.cell('s1')
+    b.svc.binding(sid('s1'))
+    expect(historyCalls()).toHaveLength(0)
+    b.svc.open(sid('s1'))
+    expect(historyCalls().map(c => (c.payload as { sessionId: string }).sessionId)).toEqual(['s1'])
+    // Same current again: no second pull.
+    b.svc.open(sid('s1'))
+    expect(historyCalls()).toHaveLength(1)
+    // Stage moves: the new occupant opens.
+    b.svc.open(sid('s2'))
+    expect(historyCalls().map(c => (c.payload as { sessionId: string }).sessionId)).toEqual(['s1', 's2'])
+  })
+
+  it('startup restore: a persisted selection validated by the first projection opens its window unprompted', async () => {
+    const storage = new Map<string, string>([
+      ['dsh.sessions.current', JSON.stringify({ sessionId: 's1' })],
+    ])
+    vi.stubGlobal('localStorage', {
+      getItem: (k: string) => storage.get(k) ?? null,
+      setItem: (k: string, v: string) => { storage.set(k, v) },
+    })
+    try {
+      const b = bench()
+      expect(b.api.calls.filter(c => c.method === 'session.history')).toHaveLength(0)
+      await feedList(b, [{ id: 's1' }]) // projection validates the persisted id → current lands → stage follows
+      const historyCalls = b.api.calls.filter(c => c.method === 'session.history')
+      expect(historyCalls.map(c => (c.payload as { sessionId: string }).sessionId)).toEqual(['s1'])
+    } finally {
+      vi.unstubAllGlobals()
+    }
   })
 })
 
@@ -187,12 +250,13 @@ describe('slot-store scope prune hook', () => {
     b.ctx.reflect.provide('slots', { pruneStoreScope })
     await feedList(b, [{ id: 's1' }, { id: 's2' }])
     b.svc.scope(sid('s1'))
-    b.svc.binding(sid('s2')) // s2 watched
-    await feedList(b, []) // s1 unwatched → immediate drop; s2 watched → deferred
+    b.svc.scope(sid('s2'))
+    b.svc.open(sid('s2')) // s2 staged
+    await feedList(b, []) // s1 off stage → immediate drop; s2 staged → deferred
     expect(pruneStoreScope).toHaveBeenCalledWith('s1')
     expect(pruneStoreScope).not.toHaveBeenCalledWith('s2')
     await feedList(b, [{ id: 's3' }])
-    b.svc.binding(sid('s3')) // watch moves → deferred sweep drops s2
+    b.svc.open(sid('s3')) // stage moves → deferred sweep drops s2
     expect(pruneStoreScope).toHaveBeenCalledWith('s2')
   })
 
@@ -233,53 +297,77 @@ describe('create', () => {
   })
 })
 
+describe('createWorkspace', () => {
+  it('joins host.describe cwd with the name and creates there', async () => {
+    const b = bench()
+    b.api.onDescribe = () => Promise.resolve(ok({ version: '0', cwd: '/host/root', attachedSessions: 0 }))
+    b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('ws') }))
+    await expect(b.svc.createWorkspace('My Proj')).resolves.toBe('ws')
+    expect(b.api.callsOf('session.create')).toEqual([{ cwd: '/host/root/My Proj' }])
+  })
+
+  it('rejects empty names and path separators; surfaces describe failures', async () => {
+    const b = bench()
+    await expect(b.svc.createWorkspace('  ')).rejects.toThrow(/name is required/)
+    await expect(b.svc.createWorkspace('a/b')).rejects.toThrow(/path separators/)
+    b.api.onDescribe = () => Promise.resolve({
+      rpcId: 'e' as never,
+      result: { ok: false as const, error: { code: 'internal' as const, message: 'down', details: {} } },
+    } as never)
+    await expect(b.svc.createWorkspace('ok')).rejects.toThrow(/host.describe failed/)
+  })
+})
+
 describe('coverage tails (branch duals)', () => {
-  it('titleOf falls back to the id for empty and separator-only cwd', async () => {
+  it('displayTitleOf falls back to the id for empty and separator-only cwd', async () => {
     const b = bench()
     await feedList(b, [{ id: 'no-base', cwd: '///' }, { id: 'empty-cwd', cwd: '' }])
     const { byId } = b.svc.list.getSnapshot()
-    expect(byId[sid('no-base')]?.title).toBe('no-base')
-    expect(byId[sid('empty-cwd')]?.title).toBe('empty-cwd')
+    expect(byId[sid('no-base')]?.displayTitle).toBe('no-base')
+    expect(byId[sid('empty-cwd')]?.displayTitle).toBe('empty-cwd')
+    expect(byId[sid('no-base')]?.title).toBeUndefined()
   })
 
-  it('binding for an unknown session returns undefined without moving the watch', async () => {
+  it('binding for an unknown session returns undefined and leaves the staged scope intact', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }])
-    b.svc.binding(sid('s1'))
+    b.svc.open(sid('s1'))
     expect(b.svc.binding(sid('ghost'))).toBeUndefined()
-    // Watch unchanged: removing s1 defers (still watched), proving the ghost lookup did not steal the watch.
+    // Stage unchanged: removing s1 defers (still staged), proving the ghost lookup touched nothing.
     await feedList(b, [])
     expect(b.svc.scope(sid('s1'))).toBeDefined()
   })
 
-  it('sweep skips the id that is itself still watched and tolerates a scope record already gone', async () => {
+  it('a masked current gap holds the stage (no teardown, no re-open) until the stage moves', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }])
-    b.svc.binding(sid('s1'))
-    await feedList(b, []) // deferred removal of the watched id
-    // Re-resolving the SAME watched id: sweep runs but must skip it (watched-continue branch).
-    expect(b.svc.binding(sid('s1'))).toBeDefined()
+    b.svc.open(sid('s1'))
+    const historyCalls = () => b.api.calls.filter(c => c.method === 'session.history')
+    expect(historyCalls()).toHaveLength(1)
+    await feedList(b, []) // removed while staged: current masks to undefined, stage holds → deferred
     expect(b.svc.scope(sid('s1'))).toBeDefined()
+    // Resurfacing re-projects current = s1: same stage occupant, no second pull.
+    await feedList(b, [{ id: 's1' }])
+    expect(historyCalls()).toHaveLength(1)
+    expect(b.svc.list.getSnapshot().current).toBe('s1')
   })
 
-  it('sweep hits both deferral edges: watched-id skip and an already-vacated scope record', async () => {
+  it('sweep hits both deferral edges: staged-id skip and an already-vacated scope record', async () => {
     const b = bench()
     await feedList(b, [{ id: 'a' }, { id: 'b' }])
-    b.svc.binding(sid('a'))
-    b.svc.binding(sid('b')) // watch: b; both scoped
-    await feedList(b, []) // a removed unwatched → torn immediately; b removed watched → deferred
-    // Move the watch to a THIRD id while b stays deferred: sweep now walks a
-    // set containing b (torn) — and the watched-continue branch fires when the
-    // deferral set still holds the current watch target.
+    b.svc.scope(sid('a'))
+    b.svc.open(sid('b')) // stage: b; both scoped
+    await feedList(b, []) // a removed off stage → torn immediately; b removed staged → deferred
+    // Move the stage to a THIRD id while b stays deferred: sweep walks a set
+    // containing b (torn).
     await feedList(b, [{ id: 'c' }])
-    b.svc.binding(sid('c'))
+    b.svc.open(sid('c'))
     expect(b.svc.scope(sid('b'))).toBeUndefined()
-    // Deferral for an id whose record was never minted: force-add via removed
-    // list state (scope teardown raced) — sweep must tolerate the missing record.
-    await feedList(b, [])
-    b.svc.binding(sid('c')) // c now watched+removed → deferred
+    // Deferral for an id whose record was never minted: force the deferral
+    // via removed list state — sweep must tolerate the missing record.
+    await feedList(b, []) // c removed while staged → deferred (scope exists)
     await feedList(b, [{ id: 'd' }])
-    b.svc.binding(sid('d')) // sweep tears c
+    b.svc.open(sid('d')) // sweep tears c
     expect(b.svc.scope(sid('c'))).toBeUndefined()
   })
 
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index 9584ecc857..2e22ea1013 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -20,6 +20,9 @@
     {
       "path": "../connection"
     },
+    {
+      "path": "../../host/apiproxy"
+    },
     {
       "path": "../../llm/llm"
     },
diff --git a/packages/client/runtime/tsdown.config.ts b/packages/client/runtime/tsdown.config.ts
index a1bb544eb0..11118f7f4e 100644
--- a/packages/client/runtime/tsdown.config.ts
+++ b/packages/client/runtime/tsdown.config.ts
@@ -1,23 +1,3 @@
-import type { UserConfig } from 'tsdown'
 import { clientBundle } from '../tsdown.client.ts'
 
-/**
- * Standard dual-entry shape plus the loader lib half: exports["./loader"]
- * promises lib/loader.js (the web shell statically imports the machinery —
- * a loader cannot load itself), and the shared preset only emits
- * lib/{index,invariant}.js, so the extra config supplies it.
- */
-const configs = clientBundle('@deepseek-ai/dsh-client-runtime', ['lib/types/index.js', 'lib/types/invariant.js'])
-
-const loaderLib: UserConfig = {
-  entry: { loader: 'lib/types/client/loader/index.js' },
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'neutral',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-}
-
-export default [...configs, loaderLib]
+export default clientBundle('@deepseek-ai/dsh-client-runtime', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts
index 94d050765d..56bdd29320 100644
--- a/packages/client/tsdown.client.ts
+++ b/packages/client/tsdown.client.ts
@@ -1,6 +1,6 @@
 /**
  * Shared tsdown preset for UI plugin client bundles. Emits a closure-factory
- * artifact: the bundle calls window.DSHClientProxy.loadPlugin({id, factory})
+ * artifact: the bundle calls window.__ModuleLoader__.load({id, factory})
  * and resolves externals through the injected require (loader module table —
  * cordis DI entities, no globals, no import map). CSS Modules are compiled by
  * lightningcss inside the bundle: importing `x.module.css` yields the
@@ -11,6 +11,7 @@ import { readFile } from 'node:fs/promises'
 import { basename, dirname, resolve as resolvePath } from 'node:path'
 import type { UserConfig } from 'tsdown'
 import { transform } from 'lightningcss'
+import { PLATFORM_MODULES } from './web/src/platform.ts'
 
 /**
  * Virtual-id wrapper keeping module CSS away from tsdown's own css pipeline
@@ -28,22 +29,20 @@ const CSS_VIRTUAL_SUFFIX = '.mjs'
  */
 export const INLINE_SAFE = /^@deepseek-ai\/dsh-(host-apiproxy|session|llm|tools|brand)(\/|$)/
 
-/** Externals resolved from the loader module table (keep in sync with the shell's seeding list). */
-export const CLIENT_EXTERNALS = [
-  'react',
-  'react-dom',
-  'react/jsx-runtime',
-  'cordis',
-  '@deepseek-ai/dsh-client-ui-slots',
-  '@deepseek-ai/dsh-client-web-react',
-  '@deepseek-ai/dsh-client-ui-primitives',
-  '@deepseek-ai/dsh-client-connection/client',
-  '@deepseek-ai/dsh-client-runtime/client',
-  '@deepseek-ai/dsh-client-ui-layout/client',
-  '@deepseek-ai/dsh-client-ui-conversation/client',
-  '@deepseek-ai/dsh-client-ui-theme/client',
-  '@deepseek-ai/dsh-client-i18n/client',
-]
+/**
+ * Documented TEMPORARY exemption, not a platform module (hence not in
+ * platform.ts): the snapshot-store engine (createSnapshotStore/defineStore/
+ * shallowEqual) lives in runtime pending its promotion-time rehoming, and
+ * five importers (i18n, ui-layout, ui-conversation ×3) ride this single
+ * exemption. At runtime the lazy CJS table answers the require natively:
+ * runtime is an immediately-tier row, its factory is registered before any
+ * dependent bundle materializes. TODO(webload/store-rehome): remove with the
+ * store-engine relocation follow-up.
+ */
+const RUNTIME_STORE_EXEMPTION = '@deepseek-ai/dsh-client-runtime/client'
+
+/** Externals resolved from the loader module table: the platform seed entries plus the documented runtime exemption. */
+export const CLIENT_EXTERNALS: readonly string[] = [...PLATFORM_MODULES, RUNTIME_STORE_EXEMPTION]
 
 /**
  * Build the tsdown config for one UI plugin package: the node-half lib build
@@ -51,8 +50,8 @@ export const CLIENT_EXTERNALS = [
  * 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 loadPlugin handoff
- * and onto the injected style tags.
+ * @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).
@@ -79,7 +78,7 @@ export function clientBundle(id: string, libEntry: readonly string[]): UserConfi
     // Types ship from lib/types (tsc); dts here would wrap the banner/footer into .d.cts and break parsing.
     dts: false,
     clean: false,
-    external: CLIENT_EXTERNALS,
+    external: [...CLIENT_EXTERNALS],
     // Browser bundles inline node-idiom deps (zustand/immer read
     // process.env.NODE_ENV; zustand's esm build also probes
     // import.meta.env.MODE, which a CJS output cannot carry — rolldown flags
@@ -102,24 +101,20 @@ export function clientBundle(id: string, libEntry: readonly string[]): UserConfi
     // opinion for table entries (external above wins), bundle everything else.
     noExternal: (id: string) => (CLIENT_EXTERNALS.includes(id) ? undefined : true),
     plugins: [{
-      // Bundle purity gate: a bare-name import of a module-table package would
-      // slip past CLIENT_EXTERNALS (which lists the /client form) and INLINE a
-      // second copy of that package — duplicate runtime identity (a second
-      // scope Symbol was tonight's white-screen root cause). Resolve-time is
-      // the earliest, most precise interception: rewrite bare table names to
-      // their /client form (the loader registers both specifiers), and reject
-      // any other @deepseek-ai/* leak that is not an inline-safe wire layer.
+      // Bundle purity gate (build-time mirror of the module-edge rules):
+      // platform seed entries stay external, inline-safe wire layers inline,
+      // and every other @deepseek-ai value import is a build error — a
+      // cross-plugin value import either inlines a duplicate runtime instance
+      // or requires a specifier the frozen module table cannot answer.
+      // Cross-plugin collaboration goes through cordis services instead.
       name: 'dsh-client-bundle-purity',
       resolveId(source: string) {
         if (!source.startsWith('@deepseek-ai/')) return null
-        if (CLIENT_EXTERNALS.includes(source)) return null // external wins
-        if (CLIENT_EXTERNALS.includes(`${source}/client`)) {
-          return { id: `${source}/client`, external: true }
-        }
+        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
         throw new Error(
-          `client bundle purity: "${source}" is not in CLIENT_EXTERNALS and not an inline-safe wire layer — `
-          + 'import the /client form, add it to the module table, or it inlines a duplicate runtime instance',
+          `client bundle purity: "${source}" is not a platform module (CLIENT_EXTERNALS) and not an inline-safe wire layer — `
+          + 'cross-plugin value imports are forbidden; collaborate through cordis services (type-only imports are erased and never reach this gate)',
         )
       },
     }, {
@@ -158,7 +153,7 @@ export function clientBundle(id: string, libEntry: readonly string[]): UserConfi
     }],
     outputOptions: {
       entryFileNames: 'client.js',
-      banner: `window.DSHClientProxy.loadPlugin({ id: ${JSON.stringify(id)}, factory: (require) => {`,
+      banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(id)}, factory: (require) => {`,
       footer: `return module.exports; } });`,
       intro: 'var module = { exports: {} }; var exports = module.exports;',
     },
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 3bf1c3bd6e..ebd7474298 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -1,12 +1,16 @@
 # @deepseek-ai/dsh-client-ui-conversation
 
-Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation), ctx.toolviews named registry with bash samples, 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, stats line, per-tool row slot with a bash sample registrant), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).
+
+The view ring IS a slot: the conversation registration declares the `'conversation.view'` list slot (session scope) in its `children` table, ConversationRoot renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from the ring ledger's registration options (`id`/`order`/`label`). The chat view is this package's own ring entry; other plugins (ui-trajectory) contribute tabs through plain `ctx.slots.register` — the former package-local view registry (`registerView`/`ViewEntry`/`ConversationViewMap` and the chrome attachment table) is retired, with per-view chrome dissolved into the view components themselves.
 
 Generic tool rows classify the built-in bash, read, search, write, and edit names into dedicated visual variants. The filesystem variants render the edit icon and `Write · <path>` or `Edit · <path>` summary while retaining the shared row-to-details interaction.
 
-Per-session UI state (selection, composer draft, active view) lives in the declared chat store (`stores.ts` `createChatStore`): apply constructs one handle and passes it to both the conversation and details registrations, so the two session slots share one instance per session (selection written by conversation, read by details) and the framework owns instance lifecycle and draft persistence. Components are pure — the framework standard kit (`useSession`/`sessionId`/`useSessions`) and the store faces (`useStore`/`actions`) arrive automatically from the registration declaration; the inject factories contribute plain data and callbacks only (send/stop choreography, view registry read face, startSession chain).
+Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.toolviews`/outlet) is retired. The chat entry declares the keyed `'conversation.chat.toolview'` hole (session scope; the key space is runtime-open); its 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` pre-composes it with the session standard kit. A registrant is a plain plugin: `ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)` with `inject: ['slots', 'conversation']` as the load-order seam (apply mounts ConversationService after the chat registration, so the service being present guarantees the slot is declared); session differentiation happens inside the component (`useSessions` reading `parentId` — the bash sample is the third-party-posture exemplar). Trajectory/waterfall toolview slots share this shape and land with their own render sites (RendersCheck rejects a declaration nobody renders).
 
-`src/client/` is organized for the future package split: `contract/` is the sole inter-domain shared face (`slots.ts` composed slot props, `views.ts` view ring, `toolview.ts` tool ring, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` 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).
+Per-session UI state (selection, composer draft, active view) lives in the declared chat store (`stores.ts` `createChatStore`): apply constructs one handle and passes it to the conversation, chat-view, and details registrations, so the session slots share one instance per session (selection written by the chat view, read by details) and the framework owns instance lifecycle and draft persistence. Components are pure — the framework standard kit (`useSession`/`sessionId`/`useSessions`) and the store faces (`useStore`/`actions`) arrive automatically from the registration declaration; the inject factories contribute plain data and callbacks only (send/stop choreography, tab read face, details/paging callbacks, startSession chain).
+
+`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).
 
 ## Model Experience
 
@@ -22,5 +26,4 @@ None; this package neither assembles nor sends a provider request.
 - **Details panel is the minimal form** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred.
 - **Assistant footer extensions (IconActions row, per-message paging) are reserved slots** — drawn in the design, not implemented.
 - **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export.
-- **Approval/question cards are display-only placeholders** — web-side answering (composer takeover panel) is the P-II approvals project.
-- **Module-level toolview caches are single-bundle state** — the inject cache and registry maps must reach cross-bundle consumers through the package export surface and loader module table, never by a second bundle copy.
+- **Approval cards are display-only placeholders** — question requests answer through the composer chain (ui-question), while web-side approval answering is the P-II approvals project.
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 51bdffb2d6..d7306a6810 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -24,6 +24,8 @@
   },
   "dshClient": {
     "inject": [
+      "@deepseek-ai/dsh-client-i18n",
+      "@deepseek-ai/dsh-client-runtime",
       "@deepseek-ai/dsh-client-ui-layout"
     ],
     "platform": "web"
@@ -34,22 +36,25 @@
   },
   "license": "BSD-3-Clause",
   "dependencies": {
-    "@deepseek-ai/dsh-client-i18n": "workspace:^",
+    "clsx": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^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-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
-    "clsx": "^2.0.0",
-    "react": "^18.2.0"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
-  "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
-    "cordis": "^4.0.0-rc.7"
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
   },
   "files": [
     "lib/index.js",
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 266602e1b2..372eb36c80 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -1,39 +1,32 @@
 /**
- * Client plugin body: provide the conversation service and toolview registry,
- * register the conversation/details slot occupants and the no-session empty
- * state, and mount the chat view with its samples. Assembly only — components
- * receive everything through props: the framework standard kit and store
- * faces arrive automatically from the declarations below; the inject
- * factories contribute the plain-data-and-callbacks business face (design §5).
+ * Client plugin body: register the conversation/details slot occupants and
+ * the no-session empty state, contribute the chat entry into the
+ * 'conversation.view' ring that the conversation registration declares, then
+ * mount the conversation service (class plugin) and the bash toolview sample.
+ * Assembly only — components receive everything through props: the framework
+ * standard kit and store faces arrive automatically from the declarations
+ * below; the inject factories contribute the plain-data-and-callbacks
+ * business face (design §5). Tool rows are ordinary keyed-slot registrations
+ * into 'conversation.chat.toolview' — no dedicated registry exists.
  */
 import type { Context } from 'cordis'
 import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SessionId, SessionsService, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { LayoutService } from '@deepseek-ai/dsh-client-ui-layout/client'
-import type { I18nService } from '@deepseek-ai/dsh-client-i18n/client'
-import type { SelectionTarget } from './contract/views.ts'
-import type { ConversationInjected, DetailsInjected, EmptyStateInjected } from './contract/slots.ts'
+import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { ViewTab } from './contract/views.ts'
+import type {
+  ChatViewInjected, ConversationInjected, DetailsInjected, EmptyStateInjected,
+} from './contract/slots.ts'
 import { createChatStore } from './stores.ts'
 import { ConversationService } from './service.ts'
-import { ToolViewRegistry } from './toolviews/registry.ts'
-import { childSessionScope, registerChat } from './chat/register.ts'
-import { registerBashSamples } from './toolviews/bash-sample.tsx'
+import { ChatView } from './chat/ChatView.tsx'
+import { bashToolviewSample } from './toolviews/bash-sample.tsx'
 import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
 import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 import { EmptyState } from './skeleton/EmptyState.tsx'
 
 /** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
-export const inject = ['slots', 'layout', 'sessions', 'i18n']
-
-/** Resolve a service via ctx.get, failing loud. Property access is reserved
- *  for contexts whose fiber declares the inject (scope fibers do not). */
-// T is the caller-named cast target; inlining `as T` per call site would scatter the budgeted cast.
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-function need<T>(ctx: Context, name: string): T {
-  const value = ctx.get(name) as T | undefined
-  if (value === undefined) throw new Error(`ui-conversation: ${name} service unavailable`)
-  return value
-}
+export const inject = ['slots', 'layout', 'sessions']
 
 /** Resolve the session-scoped conversation service (scope-addressed send/cancel), failing loud. */
 function scopedConversation(sessions: SessionsService, id: SessionId): ConversationService {
@@ -49,48 +42,51 @@ function scopedConversation(sessions: SessionsService, id: SessionId): Conversat
  * @param ctx - client root context.
  */
 export function apply(ctx: Context): void {
-  const sessions = need<SessionsService>(ctx, 'sessions')
-  const layout = need<LayoutService>(ctx, 'layout')
-  const i18n = need<I18nService>(ctx, 'i18n')
-  const slots = need<SlotsService>(ctx, 'slots')
-
-  const conversation = new ConversationService(ctx)
-  const toolviews = new ToolViewRegistry()
-  ctx.provide('toolviews', toolviews)
-
-  const t = i18n.bind('conversation')
-  // Chat view + StatsLine footer; bash samples assembled here (apply is the
-  // only cross-domain point — chat consumes the resolver face, samples come
-  // from the toolviews domain). registerView inside registerChat is already
-  // effect-scoped; the raw sample registrations need the effect wrapper to
-  // ride the fiber cascade.
-  ctx.effect(
-    () => registerChat({ conversation, toolviews, t }),
-    'ui-conversation: chat view')
-  ctx.effect(
-    () => registerBashSamples(toolviews, childSessionScope(sessions.list)),
-    'ui-conversation: bash toolview samples')
+  const sessions = ctx.sessions
+  const layout = ctx.layout
+  const slots = ctx.slots
 
   // Shared store handle, constructed here so its identity lives and dies with
-  // this fiber (a module-level handle would be a de-facto singleton). Both
-  // session-slot registrations declare it; same scope key = same instance, so
-  // conversation writes and details reads meet in one store.
-  const chat = createChatStore()
+  // this fiber (a module-level handle would be a de-facto singleton). The
+  // conversation, chat-view, and details registrations all declare it; same
+  // scope key = same instance, so chat-view selection writes and details
+  // reads meet in one store.
+  const chatStore = createChatStore()
 
+  // Tab projection over the view ring's ledger (list entries carry id/order/
+  // label as registration options; the ledger keeps them order-sorted).
+  const viewTabs = (): ViewTab[] => {
+    const tabs: ViewTab[] = []
+    for (const entry of slots.entries('conversation.view')) {
+      /* v8 ignore next -- unreachable: list registration validates id at load. */
+      if (entry.options.id === undefined) continue
+      tabs.push({ id: entry.options.id, label: entry.options.label ?? entry.options.id })
+    }
+    return tabs
+  }
+
+  // Conversation occupant. Declaring the view ring here is claiming it:
+  // ConversationRoot is the only component authorized to render the ring.
   slots.register({
     name: 'conversation',
-    store: chat,
-    inject: (sessionId: SessionId, actions: BoundActions<typeof chat>): ConversationInjected => {
-      const session = sessions.manager.get(sessionId)
+    // The composer chain rides the same declaration table: takeover plugins
+    // register selector-routed replacements of the InputBar.
+    children: {
+      'conversation.view': { kind: 'list', scope: 'session' },
+      'conversation.composer': { kind: 'chain', scope: 'session' },
+    },
+    store: chatStore,
+    inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ConversationInjected => {
+      // History pull is NOT triggered here: the runtime sessions service opens
+      // the event window when the watch lands on the session (cell/binding
+      // resolution) — an inject factory assembles callbacks, it has no side
+      // effect on session state.
       const scoped = scopedConversation(sessions, sessionId)
-      // Watch-driven history pull: assembling the surface IS the watch signal
-      // (once per entry x session; open() is idempotent and self-recovers).
-      void session.open()
       return {
         views: {
-          list: () => conversation.views(),
-          subscribe: fn => conversation.subscribeViews(fn),
-          version: () => conversation.viewsVersion(),
+          list: viewTabs,
+          subscribe: fn => slots.subscribe('conversation.view', fn),
+          version: () => slots.getVersion('conversation.view'),
         },
         send: (text, mode) => {
           const trimmed = text.trim()
@@ -107,19 +103,46 @@ export function apply(ctx: Context): void {
             // Stop failure surfaces via snapshot.promptError; nothing to restore.
           })
         },
-        openDetails: (target: SelectionTarget) => {
-          actions.select(target)
-          layout.openDetails()
-        },
-        loadOlder: () => { void session.loadOlder() },
         open: (target: SessionId) => { sessions.open(target) },
       }
     },
   }, ConversationRoot)
 
+  // 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.
+  slots.register({
+    name: 'conversation.view',
+    id: 'chat',
+    order: 0,
+    label: 'Chat',
+    children: { 'conversation.chat.toolview': { kind: 'keyed', scope: 'session' } },
+    store: chatStore,
+    inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => ({
+      openDetails: (target) => {
+        actions.select(target)
+        layout.openDetails()
+      },
+      loadOlder: () => { void sessions.manager.get(sessionId).loadOlder() },
+    }),
+  }, ChatView)
+
+  // Class-plugin mount (packages/AGENTS.md service form): the service
+  // registers itself as `conversation` and lives on its own child fiber.
+  // Mounted AFTER the chat entry register above — construction guarantee for
+  // toolview registrants using `inject: ['conversation']` as their load-order
+  // seam: the service being present implies the chat entry (and with it the
+  // 'conversation.chat.toolview' declaration) is on the ledger.
+  ctx.plugin(ConversationService)
+
+  // The bash sample rides that exact seam, in third-party posture.
+  ctx.plugin(bashToolviewSample)
+
   slots.register({
     name: 'details',
-    store: chat,
+    store: chatStore,
     inject: (): DetailsInjected => ({
       closeDetails: () => { layout.closeDetails() },
     }),
@@ -128,7 +151,19 @@ export function apply(ctx: Context): void {
   slots.register({
     name: 'conversation.empty',
     inject: (): EmptyStateInjected => ({
-      startSession: opts => conversation.startSession(opts),
+      // ctx.get, not ctx.conversation: the service mounts on this plugin's
+      // own child fiber, so it is not in the inject topology the property
+      // proxy enforces; get reads the global store and stays loud on a torn
+      // boot through the optional-chain throw below.
+      startSession: (opts) => {
+        const conversation = ctx.get('conversation')
+        if (conversation === undefined) throw new Error('ui-conversation: conversation service unavailable')
+        return conversation.startSession(opts)
+      },
+      createWorkspaceSession: async (name) => {
+        const id = await sessions.createWorkspace(name)
+        sessions.open(id)
+      },
     }),
   }, EmptyState)
 }
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index fd612990ce..90eb3e3bee 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -1,12 +1,13 @@
 // AssistantMarkdown: renders assistant blocks in order — markdown text body,
 // reasoning as the figma Think summary row (expand = indented gray text),
 // other-block JSON fallback. Tool-call heads are NOT rendered here: the chat
-// view groups them into tool rows via the toolview outlet (figma step-summary
-// flow). Shared by finalized nodes and the streaming partial (pulse marker).
+// view groups them into tool rows through its keyed toolview slot (figma
+// step-summary flow). Shared by finalized nodes and the streaming partial
+// (pulse marker).
 
 import { memo } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
-import { IconThinkOutline14, JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconThinkOutline14, JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import { ToolRow } from './ToolRow.tsx'
 import css from './AssistantMarkdown.module.css'
 
@@ -43,7 +44,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({ blocks, strea
     <div className={css.root} data-streaming={streaming || undefined}>
       {blocks.map((block, i) => {
         switch (block.kind) {
-          case 'text': return <MessageText key={i} text={block.text} />
+          case 'text': return <MarkdownText key={i} text={block.text} />
           case 'reasoning': return <ThinkRow key={i} text={block.text} running={streaming && i === last} />
           // Tool-call heads render as tool rows in the chat view's grouping pass.
           case 'tool-call': return null
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index b444e557ec..8023acddde 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -1,53 +1,55 @@
 // 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. Created via factory so plugin deps
-// (toolviews registry, i18n) arrive by closure, never by import.
+// cards, paging, bottom-follow, and the session stats line under the flow
+// (chrome dissolved into the view: the footer is part of what a chat view
+// IS, not registration metadata). 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).
 //
 // 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.
+// 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.
 
 import {
-  memo, useLayoutEffect, useMemo, useRef, useState, type FC, type ReactNode,
+  memo, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
 } from 'react'
 import type {
-  ConversationNode, ConversationSnapshot, RunningToolCall, SessionId, ToolResultNode,
+  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'
-import type { ConvViewProps, SelectionTarget, Translate } from '../contract/views.ts'
-import type { ToolViewProps } from '../contract/toolview.ts'
-import type { ToolViewResolver } from '../contract/toolview.ts'
+import type { ChatViewSlotProps } from '../contract/slots.ts'
+import type { SelectionTarget } from '../contract/views.ts'
 import { deriveChatFlow, type ChatFlowItem } from './chat-flow.ts'
 import { AssistantMarkdown } from './AssistantMarkdown.tsx'
+import { GenericToolCard } from './GenericToolCard.tsx'
 import { MessageItem } from './MessageItem.tsx'
 import { PendingCard } from './PendingCard.tsx'
-import { ToolViewOutlet } from './ToolViewOutlet.tsx'
+import { StatsLine } from './StatsLine.tsx'
 import css from './ChatView.module.css'
 
-/** Plugin-supplied closure deps (assembled in registerChat, apply world). */
-export interface ChatViewDeps {
-  toolviews: ToolViewResolver
-  t: Translate
-}
-
 const FOLLOW_THRESHOLD = 24
 
 type OpenDetails = (target: SelectionTarget) => void
 
+/** The declared toolview hole's render share (stable framework binding, passed through memoized rows). */
+type RenderToolRow = ChatViewSlotProps['renderSlot']
+
 /** 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>
 
-/** One tool call row (result or running): builds the bound ToolViewProps. */
-const CallRow = memo(function CallRow({ registry, sessionId, useSession, t, callId, toolName, block, seq, onOpenDetails, selected }: {
-  registry: ToolViewResolver
-  sessionId: SessionId
-  useSession: ConvViewProps['useSession']
-  t: Translate
+/** 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. */
+const CallRow = memo(function CallRow({ renderSlot, callId, toolName, block, seq, onOpenDetails, selected }: {
+  renderSlot: RenderToolRow
   callId: string
   toolName: string
   block: ToolResultNode | RunningToolCall
@@ -56,24 +58,23 @@ const CallRow = memo(function CallRow({ registry, sessionId, useSession, t, call
   onOpenDetails: OpenDetails
   selected: boolean
 }) {
-  const viewProps = useMemo<ToolViewProps>(() => ({
-    callId, toolName, block, useSession,
-    actions: { openDetails: () => onOpenDetails({ turnSeq: seq, callId, toolName }) },
-    t,
-  }), [callId, toolName, block, useSession, seq, onOpenDetails, t])
+  const owner = useMemo(() => ({
+    callId, toolName, block,
+    openDetails: () => { onOpenDetails({ turnSeq: seq, callId, toolName }) },
+  }), [callId, toolName, block, seq, onOpenDetails])
   return (
     <div className={css.callRow} data-selected={selected || undefined}>
-      <ToolViewOutlet registry={registry} sessionId={sessionId} toolName={toolName} viewProps={viewProps} />
+      {renderSlot('conversation.chat.toolview', owner, {
+        entryKey: toolName,
+        fallback: <GenericToolCard {...owner} />,
+      })}
     </div>
   )
 })
 
 /** Consecutive tool results as one step-run group (figma VERTICAL gap10). */
-const ToolGroup = memo(function ToolGroup({ registry, sessionId, useSession, t, results, onOpenDetails, selectedCallId }: {
-  registry: ToolViewResolver
-  sessionId: SessionId
-  useSession: ConvViewProps['useSession']
-  t: Translate
+const ToolGroup = memo(function ToolGroup({ renderSlot, results, onOpenDetails, selectedCallId }: {
+  renderSlot: RenderToolRow
   results: readonly ToolResultNode[]
   onOpenDetails: OpenDetails
   /** Only set when the selected call lives in THIS group (memo economy). */
@@ -84,10 +85,7 @@ const ToolGroup = memo(function ToolGroup({ registry, sessionId, useSession, t,
       {results.map((node) => (
         <CallRow
           key={node.callId}
-          registry={registry}
-          sessionId={sessionId}
-          useSession={useSession}
-          t={t}
+          renderSlot={renderSlot}
           callId={node.callId}
           toolName={node.call?.name ?? ''}
           block={node}
@@ -114,180 +112,166 @@ function StreamingTail({ useSession, onGrow }: {
   return <AssistantMarkdown blocks={partial.blocks} streaming />
 }
 
-/**
- * Build the chat view component over plugin deps.
- * @param deps - toolview registry and bound translator.
- * @returns the ConvViewProps component registered as the chat view.
- */
-export function createChatView(deps: ChatViewDeps): FC<ConvViewProps> {
-  const { toolviews, t } = deps
+/** The chat view slot entry: pure component over the composed props (tool rows render through the declared keyed hole's renderSlot share). */
+export function ChatView({ useSession, useStore, renderSlot, openDetails, loadOlder }: ChatViewSlotProps) {
+  const nodes = useSession((s) => s.nodes)
+  const runningCalls = useSession((s) => s.runningCalls)
+  const pending = useSession((s) => s.pending)
+  const openState = useSession((s) => s.openState)
+  const openErrorMessage = useSession((s) => s.openError === null ? null : `${s.openError.message}（${s.openError.code}）`)
+  const hasMore = useSession((s) => s.hasMore)
+  const loadingOlder = useSession((s) => s.loadingOlder)
+  const selectedCallId = useStore((s) => s.selection?.callId)
 
-  return function ChatView({ sessionId, useSession: useSessionWide, useStore, actions }: ConvViewProps) {
-    const useSession = useSessionWide as UseConversation
-    const nodes = useSession((s) => s.nodes)
-    const runningCalls = useSession((s) => s.runningCalls)
-    const pending = useSession((s) => s.pending)
-    const openState = useSession((s) => s.openState)
-    const openErrorMessage = useSession((s) => s.openError === null ? null : `${s.openError.message}（${s.openError.code}）`)
-    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 items = useMemo(() => deriveChatFlow(nodes), [nodes])
+  const listRef = useRef<HTMLDivElement | null>(null)
+  const atBottomRef = useRef(true)
+  const [atBottom, setAtBottom] = useState(true)
+  /** Paging anchor: height/position at click, compensated after the prepend lands. */
+  const anchorRef = useRef<{ h: number; t: number } | null>(null)
+  const firstSeqRef = useRef<number | null>(null)
+  const openedRef = useRef(false)
+  const lastKeyRef = useRef<string | null>(null)
 
-    const listRef = useRef<HTMLDivElement | null>(null)
-    const atBottomRef = useRef(true)
-    const [atBottom, setAtBottom] = useState(true)
-    /** Paging anchor: height/position at click, compensated after the prepend lands. */
-    const anchorRef = useRef<{ h: number; t: number } | null>(null)
-    const firstSeqRef = useRef<number | null>(null)
-    const openedRef = useRef(false)
-    const lastKeyRef = useRef<string | null>(null)
+  const firstSeq = nodes[0]?.seq ?? null
+  const lastItem = items[items.length - 1]
 
-    const firstSeq = nodes[0]?.seq ?? null
-    const lastItem = items[items.length - 1]
-
-    const toBottom = (el: HTMLDivElement): void => {
-      el.scrollTop = el.scrollHeight
-      atBottomRef.current = true
-      setAtBottom(true)
-    }
-
-    useLayoutEffect(() => {
-      const el = listRef.current
-      /* v8 ignore next -- ref-null guard: React attaches the ref before layout effects run. */
-      if (el === null) return
-      // Open completed: jump to the bottom once.
-      if (openState === 'open' && !openedRef.current) {
-        openedRef.current = true
-        toBottom(el)
-        firstSeqRef.current = firstSeq
-        lastKeyRef.current = lastItem?.key ?? null
-        return
-      }
-      // Prepend (head seq decreased): compensate by the height delta.
-      if (anchorRef.current !== null && firstSeq !== null && firstSeqRef.current !== null && firstSeq < firstSeqRef.current) {
-        el.scrollTop = anchorRef.current.t + (el.scrollHeight - anchorRef.current.h)
-        anchorRef.current = null
-        firstSeqRef.current = firstSeq
-        /* v8 ignore next -- ?? arm: a prepend adds nodes, so the flow list here is never empty. */
-        lastKeyRef.current = lastItem?.key ?? null
-        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).
-      const lastKey = lastItem?.key ?? null
-      const appendedUser = lastKey !== lastKeyRef.current
-        && lastItem !== undefined && lastItem.kind === 'node' && lastItem.node.kind === 'user'
-      lastKeyRef.current = lastKey
-      if (appendedUser || atBottomRef.current) toBottom(el)
-    })
-
-    const onScroll = (): void => {
-      const el = listRef.current
-      /* v8 ignore next -- ref-null guard: the handler only fires on the mounted element. */
-      if (el === null) return
-      const isAtBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= FOLLOW_THRESHOLD + 1
-      atBottomRef.current = isAtBottom
-      setAtBottom(isAtBottom)
-    }
-
-    // Follow streaming growth the parent never re-renders for (stable ref).
-    // The ref starts null and is assigned every render, so the placeholder
-    // initializer a function initial value would need never exists.
-    const followRef = useRef<(() => void) | null>(null)
-    followRef.current = () => {
-      const el = listRef.current
-      if (el !== null && atBottomRef.current) el.scrollTop = el.scrollHeight
-    }
-    const onGrow = useRef(() => followRef.current?.()).current
-
-    const loadOlder = (): void => {
-      const el = listRef.current
-      /* v8 ignore next -- ref-null guard: the paging button renders inside the list tree. */
-      if (el !== null) anchorRef.current = { h: el.scrollHeight, t: el.scrollTop }
-      actions.loadOlder()
-    }
-
-    const renderItem = (item: ChatFlowItem): ReactNode => {
-      if (item.kind === 'tool-group') {
-        const inGroup = selectedCallId !== undefined
-          && item.results.some((r) => r.callId === selectedCallId)
-        return (
-          <ToolGroup
-            key={item.key}
-            registry={toolviews}
-            sessionId={sessionId}
-            useSession={useSession}
-            t={t}
-            results={item.results}
-            onOpenDetails={actions.openDetails}
-            selectedCallId={inGroup ? selectedCallId : undefined}
-          />
-        )
-      }
-      const node: ConversationNode = item.node
-      if (node.kind === 'assistant') {
-        return <AssistantMarkdown key={item.key} blocks={node.blocks} streaming={false} interrupted={node.interrupted} />
-      }
-      /* v8 ignore next -- tool-result never reaches here: deriveChatFlow folds them into groups. */
-      if (node.kind === 'tool-result') return null
-      return <MessageItem key={item.key} node={node} />
-    }
-
-    return (
-      <div className={css.root}>
-        <div ref={listRef} className={css.scroll} onScroll={onScroll}>
-          <div className={css.column}>
-          {openState === 'loading' && <div className={css.hint}>载入历史…</div>}
-          {openState === 'error' && <div className={css.openError}>历史加载失败：{openErrorMessage}</div>}
-          {hasMore && (
-            <div className={css.older}>
-              <button type="button" disabled={loadingOlder} onClick={loadOlder}>
-                {loadingOlder ? '加载中…' : '加载更早'}
-              </button>
-            </div>
-          )}
-          {items.map(renderItem)}
-          <StreamingTail useSession={useSession} onGrow={onGrow} />
-          {runningCalls.length > 0 && (
-            <div className={css.toolGroup}>
-              {runningCalls.map((call) => (
-                <CallRow
-                  key={call.callId}
-                  registry={toolviews}
-                  sessionId={sessionId}
-                  useSession={useSession}
-                  t={t}
-                  callId={call.callId}
-                  toolName={call.name}
-                  block={call}
-                  seq={call.turn}
-                  onOpenDetails={actions.openDetails}
-                  selected={call.callId === selectedCallId}
-                />
-              ))}
-            </div>
-          )}
-          {pending.map((item) => <PendingCard key={item.rpcId} item={item} />)}
-          </div>
-        </div>
-        {!atBottom && (
-          <button
-            type="button"
-            className={css.toBottom}
-            aria-label="回到底部"
-            onClick={() => {
-              const el = listRef.current
-              /* v8 ignore next -- ref-null guard: the button only renders alongside the mounted list. */
-              if (el !== null) toBottom(el)
-            }}
-          >
-            <IconChevronDownOutline14 />
-          </button>
-        )}
-      </div>
-    )
+  const toBottom = (el: HTMLDivElement): void => {
+    el.scrollTop = el.scrollHeight
+    atBottomRef.current = true
+    setAtBottom(true)
   }
+
+  useLayoutEffect(() => {
+    const el = listRef.current
+    /* v8 ignore next -- ref-null guard: React attaches the ref before layout effects run. */
+    if (el === null) return
+    // Open completed: jump to the bottom once.
+    if (openState === 'open' && !openedRef.current) {
+      openedRef.current = true
+      toBottom(el)
+      firstSeqRef.current = firstSeq
+      lastKeyRef.current = lastItem?.key ?? null
+      return
+    }
+    // Prepend (head seq decreased): compensate by the height delta.
+    if (anchorRef.current !== null && firstSeq !== null && firstSeqRef.current !== null && firstSeq < firstSeqRef.current) {
+      el.scrollTop = anchorRef.current.t + (el.scrollHeight - anchorRef.current.h)
+      anchorRef.current = null
+      firstSeqRef.current = firstSeq
+      /* v8 ignore next -- ?? arm: a prepend adds nodes, so the flow list here is never empty. */
+      lastKeyRef.current = lastItem?.key ?? null
+      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).
+    const lastKey = lastItem?.key ?? null
+    const appendedUser = lastKey !== lastKeyRef.current
+      && lastItem !== undefined && lastItem.kind === 'node' && lastItem.node.kind === 'user'
+    lastKeyRef.current = lastKey
+    if (appendedUser || atBottomRef.current) toBottom(el)
+  })
+
+  const onScroll = (): void => {
+    const el = listRef.current
+    /* v8 ignore next -- ref-null guard: the handler only fires on the mounted element. */
+    if (el === null) return
+    const isAtBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= FOLLOW_THRESHOLD + 1
+    atBottomRef.current = isAtBottom
+    setAtBottom(isAtBottom)
+  }
+
+  // Follow streaming growth the parent never re-renders for (stable ref).
+  // The ref starts null and is assigned every render, so the placeholder
+  // initializer a function initial value would need never exists.
+  const followRef = useRef<(() => void) | null>(null)
+  followRef.current = () => {
+    const el = listRef.current
+    if (el !== null && atBottomRef.current) el.scrollTop = el.scrollHeight
+  }
+  const onGrow = useRef(() => followRef.current?.()).current
+
+  const loadOlderAnchored = (): void => {
+    const el = listRef.current
+    /* v8 ignore next -- ref-null guard: the paging button renders inside the list tree. */
+    if (el !== null) anchorRef.current = { h: el.scrollHeight, t: el.scrollTop }
+    loadOlder()
+  }
+
+  const renderItem = (item: ChatFlowItem): ReactNode => {
+    if (item.kind === 'tool-group') {
+      const inGroup = selectedCallId !== undefined
+        && item.results.some((r) => r.callId === selectedCallId)
+      return (
+        <ToolGroup
+          key={item.key}
+          renderSlot={renderSlot}
+          results={item.results}
+          onOpenDetails={openDetails}
+          selectedCallId={inGroup ? selectedCallId : undefined}
+        />
+      )
+    }
+    const node: ConversationNode = item.node
+    if (node.kind === 'assistant') {
+      return <AssistantMarkdown key={item.key} blocks={node.blocks} streaming={false} interrupted={node.interrupted} />
+    }
+    /* v8 ignore next -- tool-result never reaches here: deriveChatFlow folds them into groups. */
+    if (node.kind === 'tool-result') return null
+    return <MessageItem key={item.key} node={node} />
+  }
+
+  return (
+    <div className={css.root}>
+      <div ref={listRef} className={css.scroll} onScroll={onScroll}>
+        <div className={css.column}>
+        {openState === 'loading' && <div className={css.hint}>载入历史…</div>}
+        {openState === 'error' && <div className={css.openError}>历史加载失败：{openErrorMessage}</div>}
+        {hasMore && (
+          <div className={css.older}>
+            <button type="button" disabled={loadingOlder} onClick={loadOlderAnchored}>
+              {loadingOlder ? '加载中…' : '加载更早'}
+            </button>
+          </div>
+        )}
+        {items.map(renderItem)}
+        <StreamingTail useSession={useSession} onGrow={onGrow} />
+        {runningCalls.length > 0 && (
+          <div className={css.toolGroup}>
+            {runningCalls.map((call) => (
+              <CallRow
+                key={call.callId}
+                renderSlot={renderSlot}
+                callId={call.callId}
+                toolName={call.name}
+                block={call}
+                seq={call.turn}
+                onOpenDetails={openDetails}
+                selected={call.callId === selectedCallId}
+              />
+            ))}
+          </div>
+        )}
+        {pending.map((item) => <PendingCard key={item.key} item={item} />)}
+        </div>
+      </div>
+      <StatsLine useSession={useSession} />
+      {!atBottom && (
+        <button
+          type="button"
+          className={css.toBottom}
+          aria-label="回到底部"
+          onClick={() => {
+            const el = listRef.current
+            /* v8 ignore next -- ref-null guard: the button only renders alongside the mounted list. */
+            if (el !== null) toBottom(el)
+          }}
+        >
+          <IconChevronDownOutline14 />
+        </button>
+      )}
+    </div>
+  )
 }
diff --git a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
index 958a90526f..9b507e0662 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
@@ -1,13 +1,15 @@
-// GenericToolCard: the registry-miss fallback toolview — classifies the tool
-// into one of the five figma row variants and renders the summary row. Also
-// the shared base the bash sample builds on: any ToolViewProps consumer.
+// 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
+// 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, IconEditOutline16, IconSearchOutline16, IconThinkOutline14,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ToolViewProps } from '../contract/toolview.ts'
-import { toolRowModel, type ToolCallBlock, type ToolRowVariant } from '../contract/tool-call-model.ts'
+import type { ToolRowOwnerProps } from '../contract/slots.ts'
+import { toolRowModel, type ToolRowVariant } from '../contract/tool-call-model.ts'
 import { ToolRow } from './ToolRow.tsx'
 import { IconSparkle16 } from './IconSparkle16.tsx'
 
@@ -22,8 +24,8 @@ const VARIANT_ICONS: Record<ToolRowVariant, ReactNode> = {
   others: <IconSparkle16 />,
 }
 
-export function GenericToolCard({ toolName, block, actions }: ToolViewProps) {
-  const model = toolRowModel(toolName, block as ToolCallBlock)
+export function GenericToolCard({ toolName, block, openDetails }: ToolRowOwnerProps) {
+  const model = toolRowModel(toolName, block)
   return (
     <ToolRow
       variant={model.variant}
@@ -32,7 +34,7 @@ export function GenericToolCard({ toolName, block, actions }: ToolViewProps) {
       summary={model.summary}
       body={model.body}
       state={model.state}
-      onOpenDetails={actions.openDetails}
+      onOpenDetails={openDetails}
     />
   )
 }
diff --git a/packages/client/ui-conversation/src/client/chat/PendingCard.tsx b/packages/client/ui-conversation/src/client/chat/PendingCard.tsx
index 56b886c9ad..b6825aed9a 100644
--- a/packages/client/ui-conversation/src/client/chat/PendingCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/PendingCard.tsx
@@ -16,13 +16,13 @@ export const PendingCard = memo(function PendingCard({ item }: PendingCardProps)
     <div className={css.card}>
       {item.kind === 'approval' ? (
         <>
-          <div className={css.title}>等待审批：<span className={css.mono}>{item.toolName}</span></div>
-          {item.reason !== undefined && <div className={css.reason}>{item.reason}</div>}
+          <div className={css.title}>等待审批：<span className={css.mono}>{item.payload.toolName}</span></div>
+          {item.payload.reason !== undefined && <div className={css.reason}>{item.payload.reason}</div>}
         </>
       ) : (
         <>
-          <div className={css.title}>等待回答（{item.questions.length} 题）</div>
-          <JsonBlock label="问题内容" payload={item.questions} />
+          <div className={css.title}>等待回答（{item.payload.questions.length} 题）</div>
+          <JsonBlock label="问题内容" payload={item.payload.questions} />
         </>
       )}
       <div className={css.hint}>请在原客户端处理（web 端作答后续里程碑提供）</div>
diff --git a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
index ebaa485117..d7211f2f91 100644
--- a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
@@ -1,14 +1,13 @@
 // StatsLine: the session stats row (figma 122:11212 "cache hit 92% · 1,284
-// tokens · 45.2s · 5 turns · 32 steps"), mounted as the chat view's
-// chrome.footer — the first chrome-attachment consumer. Duration has no data
-// source in P-I (ledger). Subscribes to `nodes` only: chunk batches never swap
-// that reference, so the row renders zero times during streaming (the RFC
-// performance model's acceptance row).
+// tokens · 45.2s · 5 turns · 32 steps"), rendered by ChatView under the flow
+// (part of the chat view body — the chrome attachment mechanism retired with
+// the view ring). Duration has no data source in P-I (ledger). Subscribes to
+// `nodes` only: chunk batches never swap that reference, so the row renders
+// zero times during streaming (the RFC performance model's acceptance row).
 
 import { memo, useMemo } from 'react'
 import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ChromeProps } from '../contract/views.ts'
 import css from './StatsLine.module.css'
 
 interface UsageTotals {
@@ -55,8 +54,11 @@ export function deriveStats(nodes: ConversationSnapshot['nodes']): UsageTotals {
   }
 }
 
-export const StatsLine = memo(function StatsLine({ useSession }: ChromeProps) {
-  const nodes = (useSession as SnapshotSelectorHook<ConversationSnapshot>)((s) => s.nodes)
+/** Props: the conversation-snapshot selector hook (handed down by ChatView). */
+export interface StatsLineProps { useSession: SnapshotSelectorHook<ConversationSnapshot> }
+
+export const StatsLine = memo(function StatsLine({ useSession }: StatsLineProps) {
+  const nodes = useSession((s) => s.nodes)
   const stats = useMemo(() => deriveStats(nodes), [nodes])
   if (stats.steps === 0) return null
   const parts: string[] = []
diff --git a/packages/client/ui-conversation/src/client/chat/ToolViewOutlet.tsx b/packages/client/ui-conversation/src/client/chat/ToolViewOutlet.tsx
deleted file mode 100644
index 9f376f593a..0000000000
--- a/packages/client/ui-conversation/src/client/chat/ToolViewOutlet.tsx
+++ /dev/null
@@ -1,80 +0,0 @@
-// ToolViewOutlet: resolves the toolview for one call through ctx.toolviews
-// (uSES over the registry version so unload falls back live) and renders it
-// behind a per-row error boundary. GenericToolCard is the render-side
-// fallback for both a registry miss and a crashed custom row. Pure props
-// machinery, zero React context: a registrant inject factory receives the
-// sessionId this outlet already holds, is called once per (registration x
-// session) and cached, mirroring the slot injection discipline.
-
-import { Component, useSyncExternalStore, type ReactNode } from 'react'
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ToolViewInject, ToolViewProps, ToolViewResolver } from '../contract/toolview.ts'
-import { GenericToolCard } from './GenericToolCard.tsx'
-
-export interface ToolViewOutletProps {
-  registry: ToolViewResolver
-  sessionId: SessionId
-  toolName: string
-  viewProps: ToolViewProps
-}
-
-/** Inject cache: per inject-factory (stable per registration) x session id.
- *  The inner Map lives and dies with its factory (WeakMap entry), so entries
- *  are bounded by the session count over the registration's lifetime. */
-const injectCache = new WeakMap<ToolViewInject<object>, Map<SessionId, object>>()
-
-function cachedInject(inject: ToolViewInject<object>, sessionId: SessionId): object {
-  let perSession = injectCache.get(inject)
-  if (!perSession) {
-    perSession = new Map()
-    injectCache.set(inject, perSession)
-  }
-  let props = perSession.get(sessionId)
-  if (!props) {
-    props = inject(sessionId)
-    perSession.set(sessionId, props)
-  }
-  return props
-}
-
-class RowErrorBoundary extends Component<
-  { resetKey: unknown; fallback: ReactNode; children: ReactNode }, { failed: boolean }
-> {
-  override state = { failed: false }
-  // Fallback state MUST flip here (render phase): a boundary whose derived
-  // state does not change re-renders the crashing children and React gives
-  // up after the second throw, escalating past the boundary.
-  static getDerivedStateFromError(): { failed: boolean } {
-    return { failed: true }
-  }
-  override componentDidCatch(error: unknown): void {
-    console.error('toolview row crashed:', error)
-  }
-  // A re-registration (resetKey bump) retries the custom row.
-  override componentDidUpdate(prev: { resetKey: unknown }): void {
-    if (this.state.failed && prev.resetKey !== this.props.resetKey) {
-      this.setState({ failed: false })
-    }
-  }
-  override render(): ReactNode {
-    if (this.state.failed) return this.props.fallback
-    return this.props.children
-  }
-}
-
-export function ToolViewOutlet({ registry, sessionId, toolName, viewProps }: ToolViewOutletProps) {
-  const version = useSyncExternalStore(
-    (fn) => registry.subscribe(fn),
-    () => registry.getVersion(),
-  )
-  const resolved = registry.resolve(toolName, sessionId)
-  if (resolved === undefined) return <GenericToolCard {...viewProps} />
-  const Row = resolved.component
-  return (
-    <RowErrorBoundary resetKey={version} fallback={<GenericToolCard {...viewProps} />}>
-      {resolved.inject === undefined
-        ? <Row {...viewProps} />
-        : <Row {...{ ...cachedInject(resolved.inject, sessionId), ...viewProps }} />}
-    </RowErrorBoundary>
-  )
-}
diff --git a/packages/client/ui-conversation/src/client/chat/register.ts b/packages/client/ui-conversation/src/client/chat/register.ts
deleted file mode 100644
index b417ab4c0b..0000000000
--- a/packages/client/ui-conversation/src/client/chat/register.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-/**
- * Chat-side registration entry, called from the plugin apply (the assembly
- * point): registers the chat view with the stats-line footer chrome. The
- * chat domain touches the tool ring only through the contract resolver face;
- * bash sample registration moved to apply (cross-domain assembly).
- */
-import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ConversationService } from '../service.ts'
-import type { Translate } from '../contract/views.ts'
-import type { ToolViewResolver } from '../contract/toolview.ts'
-import { createChatView } from './ChatView.tsx'
-import { StatsLine } from './StatsLine.tsx'
-
-/** Read face of the sessions list store (subscription not needed: the filter
- *  reads the latest snapshot at each resolve). */
-export interface SessionListReader { getSnapshot(): SessionListState }
-
-/**
- * Default scoped-sample filter: the sub-session family. Sub-agent rows
- * rendering differently is the registry's canonical product scenario, and
- * forking gives W5 acceptance a real entry point to observe the differential.
- * @param list - injected sessions list read face.
- * @returns filter matching sessions with a parent.
- */
-export function childSessionScope(list: SessionListReader): (sessionId: SessionId) => boolean {
-  return sessionId => list.getSnapshot().byId[sessionId]?.parentId !== undefined
-}
-
-/** Assembly inputs for {@link registerChat} (resolved by apply, not here). */
-export interface RegisterChatDeps {
-  conversation: ConversationService
-  /** Toolview read face consumed by the chat rows' outlet. */
-  toolviews: ToolViewResolver
-  /** Translator bound to the conversation namespace. */
-  t: Translate
-}
-
-/**
- * Register the chat view (footer chrome included).
- * @param deps - assembled service instances.
- * @returns disposer removing the registration.
- */
-export function registerChat(deps: RegisterChatDeps): () => void {
-  const { conversation, toolviews, t } = deps
-  return conversation.registerView({
-    id: 'chat',
-    label: 'Chat',
-    order: 0,
-    component: createChatView({ toolviews, t }),
-    chrome: { footer: StatsLine },
-  })
-}
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index a7001fb21e..ffbc13ff59 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -1,31 +1,109 @@
 /**
- * Slot-ring contract for the conversation package: the composed props shapes
- * its registrants mount into the layout-owned slots (conversation / details /
- * conversation.empty). Terminal slot design (§3): full component props are the
- * automatic shares — PropsRuntime<K> (framework standard kit) & PropsStore<H>
+ * Slot-ring contract for the conversation package: the 'conversation.view'
+ * slot this package declares (the view ring — one list entry per conversation
+ * view tab), the chat view's per-tool row hole ('conversation.chat.toolview',
+ * keyed on the wire tool name), and the composed props shapes its registrants
+ * mount into the layout-owned slots (conversation / details /
+ * conversation.empty) plus its own slots. Terminal slot design (§3): full
+ * component props are the automatic shares — PropsRuntime<K> (framework
+ * standard kit) & PropsRenderSlots<S> (declared children) & PropsStore<H>
  * (declared store's read/write faces) & the injected business face declared
- * here. No renderSlot share: none of the three registrations declares
- * children, so the zero-renderSlot inference applies.
+ * here.
  */
-import type { PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
+import type { PendingInteraction, SessionId, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
 import type { createChatStore } from '../stores.ts'
-import type { SelectionTarget, ViewEntry } from './views.ts'
+import type { CallId, SelectionTarget, ViewTab } from './views.ts'
 
-/** The shared chat store handle type (apply constructs one; conversation and details both declare it). */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /**
+     * The conversation view ring: one list entry per view tab (chat here;
+     * trajectory/waterfall from ui-trajectory), rendered one-at-a-time by
+     * ConversationRoot via `only: <active id>`. Declared by this package's
+     * 'conversation' entry (declaring is claiming). Session scope: views read
+     * the conversation snapshot through the standard kit.
+     */
+    '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.
+     */
+    'conversation.chat.toolview': { kind: 'keyed'; scope: 'session'; owner: ToolRowOwnerProps }
+    /**
+     * The composer takeover chain: entries are selector-routed replacements
+     * of the default InputBar. Declared by this package's 'conversation'
+     * entry; the owner dispatches the {@link ComposerChainProps} currency and
+     * routing lives in entry selectors — new takeover kinds register with
+     * zero owner changes.
+     */
+    'conversation.composer': { kind: 'chain'; scope: 'session'; owner: ComposerChainProps }
+  }
+}
+
+/**
+ * View-slot owner share: deliberately empty — ConversationRoot supplies
+ * nothing at its renderSlot site (sessionId and the snapshot hook arrive as
+ * framework-standard props; tool rows go through each view's own declared
+ * toolview hole). Kept as the named owner seat so a future cross-view
+ * payload has a home.
+ */
+export interface ConvViewOwnerProps {}
+
+/**
+ * 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). */
+  callId: CallId
+  /** Wire tool name (also the keyed dispatch key at the render site). */
+  toolName: string
+  /** Frozen call slice: the running call or the settled result node. */
+  block: ToolCallBlock
+  /** Open the details panel for this call (session-level facility, supplied by the view). */
+  openDetails(): 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'>
+
+/**
+ * Base props of a conversation view entry: the framework standard kit for the
+ * session-scope 'conversation.view' slot (useSession narrowed to the
+ * conversation snapshot by the runtime merge, sessionId, useSessions).
+ * Entries declaring the shared store or an inject face compose their shares
+ * on top (the chat entry's {@link ChatViewSlotProps}); store-less pure
+ * readers (ui-trajectory) take this base alone.
+ */
+export type ConvViewProps = PropsRuntime<'conversation.view'>
+
+/** The shared chat store handle type (apply constructs one; the conversation, details, and chat-view registrations all declare it). */
 export type ChatStore = ReturnType<typeof createChatStore>
 
 /**
  * Injected share of the conversation slot: plain data and callbacks only
  * (design §5 — hooks are framework-made). The store lines that used to ride
- * here live in the declared {@link ChatStore} now; ancestry derives from the
- * standard useSessions hook in-component; view rendering moved into the
- * component, which holds every share a view needs.
+ * here live in the declared {@link ChatStore}; ancestry derives from the
+ * standard useSessions hook in-component; views render through the declared
+ * 'conversation.view' child slot, with this face projecting the tab strip.
  */
 export interface ConversationInjected {
-  /** View registry read face (uSES triple from the conversation service). */
+  /** View tab read face (uSES triple over the 'conversation.view' slot ledger). */
   views: {
-    list(): readonly ViewEntry[]
+    list(): readonly ViewTab[]
     subscribe(fn: () => void): () => void
     version(): number
   }
@@ -33,17 +111,42 @@ export interface ConversationInjected {
   send(text: string, mode: 'queue' | 'steer'): void
   /** Cancel the in-flight turn (failure surfaces via snapshot.promptError). */
   stop(): void
-  /** Selection write + details panel opening in one gesture (store action + layout orchestration). */
-  openDetails(target: SelectionTarget): void
-  /** Pull one older history page. */
-  loadOlder(): void
   /** Navigate to another session (breadcrumb ancestors). */
   open(id: SessionId): void
 }
 
-/** Full conversation-slot component props: runtime share & store share & injected share. */
+/**
+ * Composer chain currency: what ConversationRoot dispatches at its
+ * renderSlotChain site. The owner declares the currency only — never a
+ * per-entry contract; takeover packages narrow it in their own selectors
+ * (`interactions.find(i => i.kind === ...)`), so new takeover kinds register
+ * with zero owner changes.
+ */
+export interface ComposerChainProps {
+  /** The session's live pending waits, in arrival order (snapshot reference). */
+  interactions: readonly PendingInteraction[]
+}
+
+/** Full conversation-slot component props: runtime & child-render (view ring + composer chain) & store & injected shares. */
 export type ConversationSlotProps =
-  PropsRuntime<'conversation'> & PropsStore<ChatStore> & ConversationInjected
+  PropsRuntime<'conversation'> & PropsRenderSlots<'conversation.view' | 'conversation.composer'>
+  & PropsStore<ChatStore> & ConversationInjected
+
+/**
+ * Injected share of the chat view entry: the two callbacks whose targets live
+ * outside the view (layout orchestration; the session object layer).
+ */
+export interface ChatViewInjected {
+  /** Selection write + details panel opening in one gesture (store action + layout orchestration). */
+  openDetails(target: SelectionTarget): void
+  /** Pull one older history page. */
+  loadOlder(): void
+}
+
+/** Full chat-view component props: runtime share & the declared toolview hole's render share & store share & injected share. */
+export type ChatViewSlotProps =
+  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.toolview'>
+  & PropsStore<ChatStore> & ChatViewInjected
 
 /**
  * Injected share of the details slot: the panel is otherwise a pure reader of
@@ -61,6 +164,11 @@ export type DetailsSlotProps = PropsRuntime<'details'> & PropsStore<ChatStore> &
 export interface EmptyStateInjected {
   /** The create → navigate → first-send chain, in one service call. */
   startSession(opts: { cwd?: string; text: string; mode: 'queue' | 'steer' }): Promise<void>
+  /**
+   * Create a workspace folder under the host cwd, mint a session there, and
+   * open it (Create-new modal success path).
+   */
+  createWorkspaceSession(name: string): Promise<void>
 }
 
 /** Full empty-state component props (root slot: no store; cwd options derive from useSessions in-component). */
diff --git a/packages/client/ui-conversation/src/client/contract/tool-call-model.ts b/packages/client/ui-conversation/src/client/contract/tool-call-model.ts
index ea566eb248..1072b0cbbb 100644
--- a/packages/client/ui-conversation/src/client/contract/tool-call-model.ts
+++ b/packages/client/ui-conversation/src/client/contract/tool-call-model.ts
@@ -3,9 +3,12 @@
  * one-line summary and expanded-body text from the frozen call slice. No
  * inline output ever — full results live in the details panel.
  */
-import type { ToolCallBlock } from './toolview.ts'
+// The block union's defining home is runtime (fold-product types); this
+// contract only forwards it (type-definition authority stays with the layer
+// that produces the values).
+import type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
 
-export type { ToolCallBlock } from './toolview.ts'
+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). */
diff --git a/packages/client/ui-conversation/src/client/contract/toolview.ts b/packages/client/ui-conversation/src/client/contract/toolview.ts
deleted file mode 100644
index f79478a57e..0000000000
--- a/packages/client/ui-conversation/src/client/contract/toolview.ts
+++ /dev/null
@@ -1,78 +0,0 @@
-/**
- * Tool-ring contract: the props surface handed to toolview components, the
- * registry's resolve/registration shapes, and the tool-call block union.
- * Shared face between the chat domain (ToolViewOutlet consumes resolve) and
- * the toolviews domain (registry implementation + sample rows); domain
- * implementation files import this, never each other.
- */
-import type { FC } from 'react'
-import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SessionId, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
-import type { CallId, Translate } from './views.ts'
-
-// The block union's defining home is runtime (fold-product types); the
-// contract only forwards it (type-definition authority stays with the layer
-// that produces the values).
-export type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
-
-/** Props handed to registered toolview components. */
-export interface ToolViewProps {
-  callId: CallId
-  toolName: string
-  block: ToolCallBlock
-  useSession: UseSession
-  actions: { openDetails(): void }
-  t: Translate
-}
-
-/**
- * Toolview inject factory: produces the registrant's private injected share
- * `I`, called once per (registration x session) and cached by the render
- * outlet. Mirrors the slot inject shape (parameters derive from the
- * declaration): toolviews are session-domain by nature, so the factory
- * receives the session id only — service access goes through the
- * registrant's own apply-closure ctx (design §5; binding objects retired).
- */
-export type ToolViewInject<I extends object> = (sessionId: SessionId) => I
-
-/** Options accepted by the toolview registry's register; `I` is inferred from the inject factory. */
-export interface ToolViewOptions<I extends object = object> {
-  /** Session filter; absent = global registration. */
-  scope?: (sessionId: SessionId) => boolean
-  /** Private inject factory merged into the row's props by the render outlet. */
-  inject?: ToolViewInject<I>
-}
-
-/**
- * A resolved toolview registration. `I` is erased to `object` on the resolve
- * read face (storage erases the per-registration parameter; the outlet merges
- * injected props untyped — the register site already proved component ⊇ I).
- */
-export interface ResolvedToolView<I extends object = object> {
-  component: FC<ToolViewProps & I>
-  inject?: ToolViewInject<I>
-}
-
-/** The registry's read face consumed by render outlets (implementation lives in the toolviews domain). */
-export interface ToolViewResolver {
-  /**
-   * Resolve the renderer for a tool in a session. Order: scope match (later
-   * registration wins) > global > undefined (caller falls back to the
-   * generic card).
-   * @param tool - tool name.
-   * @param sessionId - session the row renders in.
-   * @returns resolved view, or undefined when nothing matches.
-   */
-  resolve(tool: string, sessionId: SessionId): ResolvedToolView | undefined
-  /**
-   * Subscribe to registration changes (synchronous).
-   * @param fn - change callback.
-   * @returns unsubscribe.
-   */
-  subscribe(fn: () => void): () => void
-  /**
-   * Monotonic version for uSES pairing.
-   * @returns current version.
-   */
-  getVersion(): number
-}
diff --git a/packages/client/ui-conversation/src/client/contract/views.ts b/packages/client/ui-conversation/src/client/contract/views.ts
index e201b67e20..da573f007a 100644
--- a/packages/client/ui-conversation/src/client/contract/views.ts
+++ b/packages/client/ui-conversation/src/client/contract/views.ts
@@ -1,89 +1,39 @@
 /**
- * View-ring contract: the typed conversation view table, the chat store state
- * shared through it, and the props surfaces handed to registered views.
- * Shared face between the skeleton domain (ConversationRoot renders views)
- * and the chat domain (registers the chat view); domain implementation files
- * import this, never each other.
+ * Shared conversation contract primitives: the view tab projection (slot
+ * entries in 'conversation.view' surface as tabs), the chat store state
+ * shared through the declared store, and the selection primitives every
+ * domain consumes. Shared face between the skeleton domain (tab strip +
+ * view outlet) and the chat domain; domain implementation files import this,
+ * never each other. The view ring itself IS the 'conversation.view' slot
+ * (contract in slots.ts) — the package-local view registry is retired, and
+ * so is the hand-threaded translate channel (framework-level per-slot i18n
+ * injection is the planned replacement).
  */
-import type { FC } from 'react'
-import type { SnapshotSelectorHook, UseSession } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-
-/**
- * One ConversationViewMap entry: per-view props extension shapes (design
- * ledger, view ring). `chromeProps` extends {@link ChromeProps} for the
- * view's chrome attachments; `extraProps` extends {@link ConvViewProps} for
- * the view component itself. Both optional — the common bases stay the floor.
- */
-export interface ViewEntryDef { chromeProps?: object; extraProps?: object }
-
-/**
- * Typed conversation view table; ui-trajectory merges {trajectory, waterfall}.
- * The chat entry is declared inline here (self-merge from a sibling module
- * trips TS6305 under tsc -b).
- */
-export interface ConversationViewMap { chat: ViewEntryDef }
-
-/** View id constrained to registered ConversationViewMap keys (all string literals; chat is declared inline). */
-export type ViewId = keyof ConversationViewMap
-
-/** Per-view chrome props: the common base plus the entry's declared extension. */
-export type ChromePropsOf<Id extends ViewId> =
-  ChromeProps & (ConversationViewMap[Id] extends { chromeProps: infer C extends object } ? C : object)
-
-/** Per-view component props: the common base plus the entry's declared extension. */
-export type ConvViewPropsOf<Id extends ViewId> =
-  ConvViewProps & (ConversationViewMap[Id] extends { extraProps: infer E extends object } ? E : object)
 
 /** Tool call identity as carried on the wire (branded upstream in connection). */
 export type CallId = string
 
-/** Translate function bound to a namespace via i18n. */
-export type Translate = (key: string, params?: Record<string, unknown>) => string
-
-/** One registered conversation view (props positions keyed by the entry's declared shapes). */
-export interface ViewEntry<Id extends ViewId = ViewId> {
-  id: Id
-  label: string
-  order?: number
-  component: FC<ConvViewPropsOf<Id>>
-  /** Per-view chrome attachments (chat mounts the stats line as footer). */
-  chrome?: { header?: FC<ChromePropsOf<Id>>; footer?: FC<ChromePropsOf<Id>> }
-}
-
-/** Props for view chrome attachments. */
-export interface ChromeProps { sessionId: SessionId; useSession: UseSession }
-
 /** Selection target for the details linkage channel (toolcall is the step special case). */
 export interface SelectionTarget { turnSeq: number; stepSeq?: number; callId?: CallId; toolName?: string }
 
+/**
+ * One conversation view tab, projected from a 'conversation.view' slot
+ * entry's registration options (label falls back to the entry id).
+ */
+export interface ViewTab { id: string; label: string }
+
 /**
  * Chat store state (slot terminal design §4): the per-session store shared by
- * the conversation and details registrations. `createChatStore` implements
- * this shape; views read it through {@link ConvViewProps}'s pass-through hook.
- * `view` may carry a stale persisted id after a view plugin unloads — the
- * registry is the runtime validator (unknown ids fall back to the first view).
+ * the conversation, chat-view, and details registrations. `createChatStore`
+ * implements this shape. `view` may carry a stale persisted id after a view
+ * plugin unloads — the slot ledger is the runtime validator (unknown ids fall
+ * back to the first registered view).
  */
 export interface ChatStoreState {
   /** Details-linkage channel (conversation writes, details reads). */
   selection: SelectionTarget | null
   /** Composer draft (persisted; survives session switches and reloads). */
   draft: string
-  /** Active conversation view id; null falls back to the first registered view. */
-  view: ViewId | null
-}
-
-/**
- * Props handed to registered conversation views. `useSession` and `useStore`
- * are the framework hooks ConversationRoot received as a slot registrant,
- * passed through unchanged (hook transfer is plain props passing; no
- * business-made subscription exists on this path). No renderSlot share: the
- * view ring delegates no sub-slots.
- */
-export interface ConvViewProps {
-  sessionId: SessionId
-  useSession: UseSession
-  /** Chat store read face (selection is the only slice views consume today). */
-  useStore: SnapshotSelectorHook<ChatStoreState>
-  actions: { openDetails(t: SelectionTarget): void; loadOlder(): void }
+  /** Active conversation view id ('conversation.view' entry id); null falls back to the first view. */
+  view: string | null
 }
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index 5605971c54..8cfebac81c 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -1,34 +1,31 @@
 /**
  * Conversation domain plugin, browser half: skeleton (header/tabs/composer),
- * typed view registry, scope-addressed ConversationService, named toolview
- * registry, minimal details panel. Contract: api-contracts v3 section 7.
- * Thin shell: type surfaces live in contract/, assembly in apply.ts; the
- * three implementation domains (skeleton/chat/toolviews) never import each
- * other — contract/ is their only shared face.
+ * the 'conversation.view' slot ring (chat entry here; other plugins
+ * contribute view tabs through ctx.slots), the chat view's keyed
+ * 'conversation.chat.toolview' row hole, scope-addressed ConversationService,
+ * minimal details panel. Contract: api-contracts v3 section 7. Thin shell:
+ * type surfaces live in contract/, assembly in apply.ts; the implementation
+ * domains (skeleton/chat) never import each other — contract/ is their only
+ * shared face.
  */
 import type { ConversationService } from './service.ts'
-import type { ToolViewRegistry } from './toolviews/registry.ts'
 
 export { apply, inject } from './apply.ts'
 export { ConversationService } from './service.ts'
-export { ToolViewRegistry } from './toolviews/registry.ts'
 
 export type {
-  CallId, ChatStoreState, ChromeProps, ChromePropsOf, ConversationViewMap, ConvViewProps,
-  ConvViewPropsOf, SelectionTarget, Translate, ViewEntry, ViewEntryDef, ViewId,
+  CallId, ChatStoreState, SelectionTarget, ViewTab,
 } from './contract/views.ts'
+export type { ToolCallBlock } from './contract/tool-call-model.ts'
 export type {
-  ResolvedToolView, ToolCallBlock, ToolViewOptions, ToolViewProps, ToolViewResolver,
-} from './contract/toolview.ts'
-export type {
-  ChatStore, ConversationInjected, ConversationSlotProps, DetailsInjected, DetailsSlotProps,
-  EmptyStateInjected, EmptyStateSlotProps,
+  ChatStore, ChatViewInjected, ChatViewSlotProps, ComposerChainProps, ConversationInjected,
+  ConversationSlotProps, ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
+  EmptyStateInjected, EmptyStateSlotProps, ToolRowOwnerProps, ToolRowProps,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.
 
 declare module 'cordis' {
   interface Context {
     conversation: ConversationService
-    toolviews: ToolViewRegistry
   }
 }
diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts
index 9c9ee639b8..0c6b9632bb 100644
--- a/packages/client/ui-conversation/src/client/service.ts
+++ b/packages/client/ui-conversation/src/client/service.ts
@@ -1,10 +1,10 @@
 /**
- * ConversationService implementation: scope-addressed send/cancel, view
- * registry with a uSES read face, and the empty-state startSession chain.
- * Contract: api-contracts v3 section 7. Selection/draft state moved to the
- * declared chat store (slot terminal design §4) — the per-scope store maps,
- * lazy construction, and prune bookkeeping this service used to carry are
- * retired; what remains is the send/stop orchestration face.
+ * ConversationService implementation: scope-addressed send/cancel and the
+ * empty-state startSession chain. Contract: api-contracts v3 section 7.
+ * Selection/draft state moved to the declared chat store (slot terminal
+ * design §4); the view registry moved to the 'conversation.view' slot (slot
+ * ledger owns registration, ordering, and disposal) — what remains is the
+ * send/stop orchestration face.
  *
  * Scope addressing rides the cordis Service tracker: property access through
  * `ctx.conversation` rebinds `this.ctx` to the caller's context, so methods
@@ -15,31 +15,13 @@
  */
 import { Service } from 'cordis'
 import type { Context } from 'cordis'
-// Value import MUST use the /client subpath: only that specifier is in the
-// bundle externals (CLIENT_EXTERNALS), so it resolves to the shared runtime
-// module at load time. A bare-specifier value import gets INLINED as a second
-// module instance whose private scope-tag Symbol never matches the one
-// SessionsService tags contexts with — scopeOf then always returns undefined
-// in the browser while unit tests (single-instance path resolution) stay green.
-import { scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
-import type { Session, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ViewEntry, ViewId } from './index.ts'
-
-/** Mutable view-registry cell (plain object: mutation never crosses the tracker proxy). */
-interface ViewsState {
-  entries: Map<string, ViewEntry>
-  /** Sorted projection cache; null = rebuild on next read. */
-  cache: readonly ViewEntry[] | null
-  tick: number
-  listeners: Set<() => void>
-}
+// Type-only imports: a plugin-to-plugin value import is a bundle purity
+// error, so scope resolution goes through the sessions service (scopeOf
+// method) instead of the standalone helper.
+import type { Session, SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
 
 /** Scope-addressed conversation service (root singleton, provided as `conversation`). */
 export class ConversationService extends Service {
-  private readonly viewsState: ViewsState = {
-    entries: new Map(), cache: null, tick: 0, listeners: new Set(),
-  }
-
   /**
    * @param ctx - owning root context (the plugin apply context; the service
    * registers itself and follows that fiber's lifetime).
@@ -68,60 +50,6 @@ export class ConversationService extends Service {
     if (!result.ok) throw new Error(`conversation.cancel failed: ${result.error.code}: ${result.error.message}`)
   }
 
-  /**
-   * Register a conversation view. Duplicate ids throw; the registration is an
-   * effect on the caller's fiber (plugin unload collects it).
-   * @param entry - the view entry.
-   * @returns disposer removing the view.
-   */
-  registerView<Id extends ViewId>(entry: ViewEntry<Id>): () => void {
-    const views = this.viewsState
-    const dispose = this.ctx.effect(() => {
-      if (views.entries.has(entry.id)) {
-        throw new Error(`conversation view "${entry.id}" is already registered`)
-      }
-      views.entries.set(entry.id, entry)
-      bumpViews(views)
-      return () => {
-        views.entries.delete(entry.id)
-        bumpViews(views)
-      }
-    }, 'conversation.registerView()')
-    // The effect disposer settles asynchronously; the registry face stays a
-    // synchronous fire-and-forget disposer.
-    return () => { void dispose() }
-  }
-
-  /**
-   * Registered views ordered by `order` (ties keep registration sequence).
-   * Stable array reference between mutations (uSES getSnapshot source).
-   * @returns the view entries.
-   */
-  views(): readonly ViewEntry[] {
-    const state = this.viewsState
-    state.cache ??= [...state.entries.values()].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
-    return state.cache
-  }
-
-  /**
-   * Subscribe to view registry changes (synchronous, like the toolview registry).
-   * @param fn - change callback.
-   * @returns unsubscribe.
-   */
-  subscribeViews(fn: () => void): () => void {
-    const { listeners } = this.viewsState
-    listeners.add(fn)
-    return () => { listeners.delete(fn) }
-  }
-
-  /**
-   * Monotonic view registry version for uSES pairing.
-   * @returns current version.
-   */
-  viewsVersion(): number {
-    return this.viewsState.tick
-  }
-
   /**
    * Empty-state first-send chain (root-context method; does not read scope):
    * create the session, navigate to it, then send through the new scope.
@@ -151,11 +79,17 @@ export class ConversationService extends Service {
 
   /** Resolve the caller scope's Session or throw on root contexts. */
   private scopedSession(op: string): Session {
-    const id = scopeOf(this.ctx)
+    const id = this.scopeId(op)
+    return this.requireSessions().manager.get(id)
+  }
+
+  /** Read the caller's session scope tag via the sessions service; root contexts fail loud. */
+  private scopeId(op: string): SessionId {
+    const id = this.requireSessions().scopeOf(this.ctx)
     if (id === undefined) {
       throw new Error(`conversation.${op} requires a session scope — address one via ctx.sessions.scope(id).conversation`)
     }
-    return this.requireSessions().manager.get(id)
+    return id
   }
 
   private requireSessions(): SessionsService {
@@ -167,9 +101,3 @@ export class ConversationService extends Service {
     return sessions
   }
 }
-
-function bumpViews(state: ViewsState): void {
-  state.cache = null
-  state.tick += 1
-  for (const fn of [...state.listeners]) fn()
-}
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
index de970381ff..59346a557b 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
@@ -1,16 +1,18 @@
 // ConversationRoot: the conversation slot's skeleton (figma Header 39:27730 +
 // Tab_Group + view area + composer). Pure component — everything arrives via
 // props: the framework standard kit (useSession/sessionId/useSessions), the
-// declared chat store's useStore/actions, and the injected business face.
+// declared chat store's useStore/actions, the injected business face, and the
+// renderSlot share for the declared 'conversation.view' child slot (views are
+// slot entries; the active one renders via the list `only` filter) plus the
+// renderSlotChain share for the 'conversation.composer' takeover chain.
 // Breadcrumbs derive from useSessions with a pure parentId walk; the active
 // view id lives in the chat store's `view` field (per-session by store scope).
 
-import { useMemo, useSyncExternalStore, type ReactNode } from 'react'
+import { useSyncExternalStore } from 'react'
 import clsx from 'clsx'
 import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSlotProps } from '../contract/slots.ts'
-import type { ConvViewProps, ViewEntry } from '../contract/views.ts'
 import { InputBar } from './InputBar.tsx'
 import type { InputBarError } from './InputBar.tsx'
 import css from './ConversationRoot.module.css'
@@ -35,15 +37,15 @@ function deriveAncestry(list: SessionListState, id: SessionId): readonly Session
 }
 
 export function ConversationRoot({
-  sessionId, useSession, useSessions, useStore, actions,
-  views, send, stop, openDetails, loadOlder, open,
+  sessionId, useSession, useSessions, useStore, actions, renderSlot, renderSlotChain,
+  views, send, stop, open,
 }: ConversationRootProps) {
   useSyncExternalStore(views.subscribe, views.version)
-  const list = views.list()
+  const tabs = views.list()
   // The store's persisted view id may be stale (view plugin unloaded); the
-  // registry is the runtime validator — unknown ids fall to the first view.
+  // slot ledger is the runtime validator — unknown ids fall to the first view.
   const activeId = useStore(s => s.view) ?? 'chat'
-  const active = list.find(v => v.id === activeId) ?? list[0]
+  const active = tabs.find(v => v.id === activeId) ?? tabs[0]
 
   const ancestry = useSessions(s => deriveAncestry(s, sessionId), shallowEqual)
   const draft = useStore(s => s.draft)
@@ -51,31 +53,26 @@ export function ConversationRoot({
   const removed = useSession(s => s.removed)
   const promptError = useSession(s => s.promptError)
   const turns = useSession(s => countTurns(s))
+  const pending = useSession(s => s.pending)
 
   const error: InputBarError | null = promptError === null
     ? null
     : { op: promptError.op, message: `${promptError.error.message}（${promptError.error.code}）` }
 
-  // Views receive the shares this component already holds (hook transfer is
-  // plain props passing); the callback slice is referentially stable per
-  // injected identity so memoized view rows hold.
-  const viewProps = useMemo<ConvViewProps>(() => ({
-    sessionId, useSession, useStore,
-    actions: { openDetails, loadOlder },
-  }), [sessionId, useSession, useStore, openDetails, loadOlder])
-
-  const renderView = (entry: ViewEntry): ReactNode => {
-    const Header = entry.chrome?.header
-    const Footer = entry.chrome?.footer
-    const View = entry.component
-    return (
-      <>
-        {Header !== undefined && <Header sessionId={sessionId} useSession={useSession} />}
-        <View {...viewProps} />
-        {Footer !== undefined && <Footer sessionId={sessionId} useSession={useSession} />}
-      </>
-    )
-  }
+  // The default composer doubles as the chain's all-decline fallback: a
+  // pending wait with no registered takeover must still leave the input usable.
+  const composerBar = (
+    <InputBar
+      draft={draft}
+      running={running}
+      disabled={removed}
+      error={error}
+      variant="composer"
+      onDraftChange={actions.setDraft}
+      onSend={(mode) => { send(draft, mode) }}
+      onStop={stop}
+    />
+  )
 
   return (
     <div className={css.root}>
@@ -93,7 +90,7 @@ export function ConversationRoot({
                     disabled={last}
                     onClick={() => { open(s.id) }}
                   >
-                    {s.title}
+                    {s.displayTitle}
                   </button>
                 </span>
               )
@@ -104,9 +101,9 @@ export function ConversationRoot({
           {/* Header button row (Fork / Session log / I/O Details): a P-I visual
               placeholder registry slot is deferred — buttons land with their features. */}
         </div>
-        {list.length > 1 && (
+        {tabs.length > 1 && (
           <div className={css.tabs} role="tablist">
-            {list.map(v => (
+            {tabs.map(v => (
               <button
                 key={v.id}
                 type="button"
@@ -123,19 +120,10 @@ export function ConversationRoot({
       </header>
 
       <div className={css.viewArea}>
-        {active !== undefined && renderView(active)}
+        {active !== undefined && renderSlot('conversation.view', {}, { only: active.id })}
       </div>
 
-      <InputBar
-        draft={draft}
-        running={running}
-        disabled={removed}
-        error={error}
-        variant="composer"
-        onDraftChange={actions.setDraft}
-        onSend={(mode) => { send(draft, mode) }}
-        onStop={stop}
-      />
+      {renderSlotChain('conversation.composer', { interactions: pending }, { fallback: composerBar })}
     </div>
   )
 }
diff --git a/packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css b/packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css
index fbe2f25c09..bc5d9d62d0 100644
--- a/packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css
@@ -1,6 +1,6 @@
-/* NEW SESSION hero: headline over the shared InputBar card, centered in the
-   conversation column. The card is the same component as the composer —
-   only positioning lives here. */
+/* NEW SESSION hero (figma Input_Bottom 75:8208): fish + title, workspace chip
+   above the shared InputBar card. The input itself is InputBar — only stack
+   geometry and the chip live here. */
 
 .root {
   display: flex;
@@ -11,58 +11,154 @@
   padding: 24px;
 }
 
-/* figma hero group 34:10409: headline block sits 36px above the input card. */
-.card {
+/* Cap matches InputBar card width (800). Glow may paint past the sides. */
+.stack {
   display: flex;
   flex-direction: column;
-  gap: 36px;
+  align-items: stretch;
+  /* figma 75:8208: 12 between title block / workspace / card. */
+  gap: 12px;
   width: 100%;
-  max-width: 776px;
+  max-width: 800px;
+  overflow: visible;
 }
 
-/* figma 34:10411: fish + title row, gap 10, centered; title 26/32 wt600 (34:10414). */
+/* figma 34:10411: fish + title, gap 10, centered; 26/32 wt600; title block
+   keeps 36px below the headline before the flex gap. */
 .headline {
   display: flex;
   align-items: center;
   justify-content: center;
   gap: 10px;
+  padding-bottom: 36px;
   font-size: 26px;
   line-height: 32px;
   font-weight: 600;
   color: var(--dsw-alias-label-primary);
 }
 
-/* figma 34:10412/10413: brand-blue vector. */
+/* figma fish fill rides business blue. */
 .fish {
   flex: none;
   color: var(--dsw-alias-state-business-primary);
 }
 
-.picker {
+/* Workspace row sits 12px above the input card (figma y80 → y112). Glow is
+   centered on this block so it stays under the picker + InputBar together. */
+.body {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  min-width: 0;
+  overflow: visible;
+}
+
+/* Design input 776 → glow SVG 1051×468 (ellipse 851×268 + blur pad). */
+.glow {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  z-index: 0;
+  width: calc(100% * 1051 / 776);
+  aspect-ratio: 1051 / 468;
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+}
+
+.body > :not(.glow) {
+  position: relative;
+  z-index: 1;
+}
+
+/* Must beat `.body > :not(.glow)` specificity so the open Menu (and its
+   right-hand submenu) paints above the InputBar card. */
+.body > .workspaceRow {
+  z-index: 10;
   display: flex;
   align-items: center;
   min-width: 0;
+  /* figma 75:8208 workspace row: px 8 above the card. */
+  padding-left: 8px;
 }
 
-.select,
-.customInput {
-  max-width: 320px;
-  padding: 4px 10px;
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+/* Folder + label + chevron — transparent at rest; fill only on hover / open. */
+.workspace {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  max-width: 100%;
+  min-height: 28px;
+  padding: 0 8px;
+  border: none;
   border-radius: 12px;
-  background: var(--dsw-alias-bg-base);
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
   font-size: 13px;
   line-height: 20px;
-  color: var(--dsw-alias-label-secondary);
+  font-weight: 500;
+  cursor: pointer;
 }
 
-.customInput {
-  width: 320px;
-  outline: none;
+.workspace:hover,
+.workspace[aria-expanded='true'] {
+  background: var(--dsw-alias-interactive-bg-hover);
 }
 
-.customInput:focus {
-  /* Business blue, not brand-primary: that token resolves to ink in this sheet. */
-  border-color: var(--dsw-alias-state-business-primary);
+.folder {
+  flex: none;
   color: var(--dsw-alias-label-primary);
 }
+
+.workspaceLabel {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.chevron {
+  flex: none;
+  color: var(--dsw-alias-label-caption);
+}
+
+/* Workspace menu width tracks the longest basename in the Figma frame. */
+.workspaceMenu :global([role='menu']) {
+  min-width: 240px;
+}
+
+/* Dialog field (figma 451:18655 Input): h44, r22, px 14, caption placeholder. */
+.modalInput {
+  width: 100%;
+  height: 44px;
+  padding: 0 14px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 22px;
+  outline: none;
+  background: transparent;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.modalInput::placeholder {
+  color: var(--dsw-alias-label-caption);
+}
+
+.modalInput:focus {
+  border-color: var(--dsw-alias-state-business-primary);
+}
+
+.modalInput:disabled {
+  color: var(--dsw-alias-label-dimmed);
+}
+
+.modalAction {
+  min-width: 72px;
+}
+
+.modalError {
+  margin-top: 8px;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-state-error-primary);
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx b/packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx
index 420ff7a622..b112dfa432 100644
--- a/packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx
@@ -1,21 +1,37 @@
-// EmptyState (figma NEW SESSION screen): centered hero card built around the
-// SAME InputBar component the resident composer uses (the empty→content
-// transition is one component changing position, never a swap). Project
-// picker: cwd set derived in-component from the standard useSessions hook
-// (subscription is the framework's, derivation is a pure function — design
-// §6) plus a free-form new-directory input; submit runs the startSession
-// chain (create → open → send) in one service call.
+// EmptyState (figma NEW SESSION screen): centered hero — fish + title,
+// workspace picker row (MenuDropdown 122:9481 + New Workspace submenu
+// 419:16920 + Dialog 451:18655), then the SAME InputBar the resident
+// composer uses (empty→content is a position move, never a swap). Project
+// options derive in-component from useSessions; Create new runs
+// createWorkspaceSession (host mkdir + session.create + open).
 
-import { useMemo, useState } from 'react'
-import { FishLogo } from '@deepseek-ai/dsh-client-ui-primitives'
+import { useId, useMemo, useState } from 'react'
+import {
+  Button,
+  FishLogo,
+  IconChevronDownOutline14,
+  IconFolderClose16,
+  IconFolderOpen16,
+  IconPlusOutline16,
+  Menu,
+  Modal,
+  type MenuEntry,
+} from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
 import type { EmptyStateSlotProps } from '../contract/slots.ts'
 import { InputBar } from './InputBar.tsx'
 import type { InputBarError } from './InputBar.tsx'
 import css from './EmptyState.module.css'
 
-/** Select sentinel for the free-form directory entry (impossible as a real path: not absolute). */
-const NEW_DIR = '::new-directory'
+/** Menu id for "New Workspace" (opens submenu; not a cwd). */
+const NEW_WORKSPACE = '::new-workspace'
+/** Submenu: path modal (figma 451:18655 copy). */
+const USE_EXISTING = '::use-existing'
+/** Submenu: create-workspace modal → mkdir + default session. */
+const CREATE_NEW = '::create-new'
+
+/** Which full-page dialog is open (null = none). */
+type ModalKind = 'path' | 'create' | null
 
 /** Full props composed by reference from the contract (runtime share & injected share; no store). */
 export type EmptyStateProps = EmptyStateSlotProps
@@ -30,16 +46,30 @@ function deriveCwds(state: SessionListState): readonly string[] {
   return [...seen]
 }
 
-export function EmptyState({ useSessions, startSession }: EmptyStateProps) {
+/** Basename for the workspace chip / menu row; empty → the design's "New Workspace" label. */
+function workspaceLabel(cwd: string): string {
+  if (cwd === '') return 'New Workspace'
+  const base = cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
+  return base !== undefined && base !== '' ? base : cwd
+}
+
+export function EmptyState({ useSessions, startSession, createWorkspaceSession }: EmptyStateProps) {
   const list = useSessions(s => s)
   const cwds = useMemo(() => deriveCwds(list), [list])
   // Local viewing state: the empty state owns no session, so its draft is
   // ephemeral by design (drafts are keyed by session id; there is none yet).
   const [draft, setDraft] = useState('')
-  const [cwd, setCwd] = useState<string>('')
-  const [custom, setCustom] = useState(false)
+  const [cwd, setCwd] = useState('')
+  const [menuOpen, setMenuOpen] = useState(false)
+  const [modalKind, setModalKind] = useState<ModalKind>(null)
+  const [pathDraft, setPathDraft] = useState('')
+  const [workspaceName, setWorkspaceName] = useState('New WorkSpace')
+  const [creating, setCreating] = useState(false)
+  const [modalError, setModalError] = useState<string | null>(null)
   const [sending, setSending] = useState(false)
   const [error, setError] = useState<InputBarError | null>(null)
+  // Stable filter id so multiple EmptyState mounts do not collide in the DOM.
+  const glowFilterId = `empty-glow-${useId().replace(/:/g, '')}`
 
   const submit = (mode: 'queue' | 'steer'): void => {
     const text = draft.trim()
@@ -58,62 +88,218 @@ export function EmptyState({ useSessions, startSession }: EmptyStateProps) {
     // Success needs no cleanup: the session selection swaps this slot out for the session body.
   }
 
-  const picker = (
-    <div className={css.picker}>
-      {custom
-        ? (
-            <input
-              className={css.customInput}
-              value={cwd}
-              autoFocus
-              placeholder="目录路径，如 /home/me/proj"
-              onChange={(e) => { setCwd(e.target.value) }}
-            />
-          )
-        : (
-            <select
-              className={css.select}
-              value={cwd}
-              aria-label="项目目录"
-              onChange={(e) => {
-                if (e.target.value === NEW_DIR) {
-                  setCustom(true)
-                  setCwd('')
-                } else {
-                  setCwd(e.target.value)
-                }
-              }}
-            >
-              <option value="">默认目录</option>
-              {cwds.map(c => <option key={c} value={c}>{c}</option>)}
-              <option value={NEW_DIR}>新目录…</option>
-            </select>
-          )}
-    </div>
-  )
+  const items: MenuEntry[] = [
+    ...cwds.map(c => ({
+      id: c,
+      label: workspaceLabel(c),
+      icon: <IconFolderClose16 size={16} />,
+    })),
+    ...(cwds.length > 0 ? [{ type: 'separator' as const, id: 'sep-new' }] : []),
+    {
+      id: NEW_WORKSPACE,
+      label: 'New Workspace',
+      icon: <IconPlusOutline16 size={16} />,
+      submenu: [
+        { id: USE_EXISTING, label: 'Use a existing folder' },
+        { id: CREATE_NEW, label: 'Create new' },
+      ],
+    },
+  ]
+
+  const closeModal = (): void => {
+    if (creating) return
+    setModalKind(null)
+    setModalError(null)
+  }
+
+  const openPathModal = (): void => {
+    setPathDraft(cwd)
+    setModalError(null)
+    setModalKind('path')
+  }
+
+  const openCreateModal = (): void => {
+    setWorkspaceName('New WorkSpace')
+    setModalError(null)
+    setModalKind('create')
+  }
+
+  const confirmPath = (): void => {
+    const next = pathDraft.trim()
+    if (next === '') return
+    setCwd(next)
+    setModalKind(null)
+  }
+
+  const confirmCreate = (): void => {
+    if (creating) return
+    setCreating(true)
+    setModalError(null)
+    createWorkspaceSession(workspaceName)
+      .catch((reason: unknown) => {
+        setModalError(reason instanceof Error ? reason.message : String(reason))
+        setCreating(false)
+      })
+    // Success swaps this slot out for the new session body — no local cleanup.
+  }
+
+  const modalBusy = creating
+  const isPath = modalKind === 'path'
+  const isCreate = modalKind === 'create'
 
   return (
     <div className={css.root}>
-      <div className={css.card}>
+      <div className={css.stack}>
         <div className={css.headline}>
-          {/* figma 34:10412: fish 34x25 leading the headline, gap 10. */}
+          {/* figma 34:10412: fish 34×25 leading the headline, gap 10. */}
           <FishLogo size={34} className={css.fish} />
           Let&apos;s start building
         </div>
-        <InputBar
-          draft={draft}
-          running={false}
-          disabled={sending}
-          error={error}
-          variant="hero"
-          placeholder="Message to run task, plan and build"
-          accessory={picker}
-          onDraftChange={setDraft}
-          onSend={submit}
-          /* v8 ignore next -- structural noop: hero never passes running=true, so stop is unreachable. */
-          onStop={() => {}}
-        />
+        <div className={css.body}>
+          {/* figma 313:14109: soft ellipse behind workspace + InputBar; width
+              tracks the card (glow asset 1051 vs design card 776) so blur
+              scales in userSpace with it. */}
+          <svg className={css.glow} viewBox="0 0 1051 468" fill="none" aria-hidden="true">
+            <defs>
+              <filter
+                id={glowFilterId}
+                x="0"
+                y="0"
+                width="1051"
+                height="468"
+                filterUnits="userSpaceOnUse"
+                colorInterpolationFilters="sRGB"
+              >
+                <feFlood floodOpacity="0" result="BackgroundImageFix" />
+                <feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape" />
+                <feGaussianBlur stdDeviation="50" result="effect1_foregroundBlur" />
+              </filter>
+            </defs>
+            <g filter={`url(#${glowFilterId})`}>
+              <ellipse cx="525.5" cy="234" rx="425.5" ry="134" fill="#6187D8" fillOpacity="0.1" />
+            </g>
+          </svg>
+          <div className={css.workspaceRow}>
+            <Menu
+              open={menuOpen}
+              onClose={() => { setMenuOpen(false) }}
+              {...(cwd !== '' ? { selectedId: cwd } : {})}
+              items={items}
+              side="top"
+              className={css.workspaceMenu!}
+              onSelect={(id) => {
+                if (id === USE_EXISTING) {
+                  setMenuOpen(false)
+                  openPathModal()
+                  return
+                }
+                if (id === CREATE_NEW) {
+                  setMenuOpen(false)
+                  openCreateModal()
+                  return
+                }
+                setCwd(id)
+                setMenuOpen(false)
+              }}
+              anchor={(
+                <button
+                  type="button"
+                  className={css.workspace}
+                  aria-label="项目目录"
+                  aria-haspopup="menu"
+                  aria-expanded={menuOpen}
+                  onClick={() => { setMenuOpen(!menuOpen) }}
+                >
+                  <IconFolderOpen16 className={css.folder} size={16} />
+                  <span className={css.workspaceLabel}>{workspaceLabel(cwd)}</span>
+                  <IconChevronDownOutline14 className={css.chevron} size={12} />
+                </button>
+              )}
+            />
+          </div>
+          <InputBar
+            draft={draft}
+            running={false}
+            disabled={sending}
+            error={error}
+            variant="hero"
+            placeholder="Message to run task, plan and build, enter for / commands"
+            onDraftChange={setDraft}
+            onSend={submit}
+            /* v8 ignore next -- structural noop: hero never passes running=true, so stop is unreachable. */
+            onStop={() => {}}
+          />
+        </div>
       </div>
+      <Modal
+        open={isPath}
+        onClose={closeModal}
+        title="Enter an existing folder path"
+        footer={(
+          <>
+            <Button variant="outline" className={css.modalAction!} onClick={closeModal}>Cancel</Button>
+            <Button
+              variant="primary"
+              className={css.modalAction!}
+              disabled={pathDraft.trim() === ''}
+              onClick={confirmPath}
+            >
+              Open Folder
+            </Button>
+          </>
+        )}
+      >
+        <input
+          className={css.modalInput}
+          value={pathDraft}
+          aria-label="Folder path"
+          autoFocus
+          placeholder="ex. User/Documents/Harness/Space"
+          onChange={(e) => { setPathDraft(e.target.value) }}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              e.preventDefault()
+              confirmPath()
+            }
+          }}
+        />
+      </Modal>
+      <Modal
+        open={isCreate}
+        onClose={closeModal}
+        title="Create new workspace"
+        footer={(
+          <>
+            <Button variant="outline" className={css.modalAction!} disabled={modalBusy} onClick={closeModal}>
+              Cancel
+            </Button>
+            <Button
+              variant="primary"
+              className={css.modalAction!}
+              disabled={modalBusy || workspaceName.trim() === ''}
+              onClick={confirmCreate}
+            >
+              Create
+            </Button>
+          </>
+        )}
+      >
+        <input
+          className={css.modalInput}
+          value={workspaceName}
+          aria-label="Workspace name"
+          autoFocus
+          disabled={modalBusy}
+          onChange={(e) => { setWorkspaceName(e.target.value) }}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              e.preventDefault()
+              confirmCreate()
+            }
+          }}
+        />
+        {modalError !== null && <div className={css.modalError} role="alert">{modalError}</div>}
+      </Modal>
     </div>
   )
 }
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 1139c3c9c1..7161a31931 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -1,7 +1,7 @@
-/* Floating capsule input (figma Input_Bottom 34:11445): card floats above the
+/* 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
-   column (776 is a cap, not a fixed size — layout rule: the box shrinks with
+   column (800 is a cap, not a fixed size — layout rule: the box shrinks with
    the center column keeping its padding). Hero variant = the same card
    centered in the empty state; the transition between the two is a position
    move of one component. */
@@ -10,8 +10,8 @@
   display: flex;
   flex-direction: column;
   align-items: center;
-  /* figma Input_Bottom 34:11445: pad L32/R32/B12; the bottom gradient mask is
-     owned by the chat scroller. Top 8 hosts the error strip's breathing room. */
+  /* figma Input_Bottom: pad L32/R32/B12; the bottom gradient mask is owned by
+     the chat scroller. Top 8 hosts the error strip's breathing room. */
   padding: 8px 32px 12px;
 }
 
@@ -21,7 +21,7 @@
 
 .error {
   width: 100%;
-  max-width: 776px;
+  max-width: 800px;
   margin-bottom: 6px;
   padding: 4px 8px;
   border-radius: 8px;
@@ -34,10 +34,12 @@
 .card {
   display: flex;
   flex-direction: column;
-  /* figma Input 34:11458: 12px between the text area and the button row. */
+  /* figma Input 75:8208: 12px between the text area and the button row; 10px
+     top pad on the card before .InputText. */
   gap: 12px;
   width: 100%;
-  max-width: 776px;
+  max-width: 800px;
+  padding-top: 10px;
   /* Input stroke: black/0.10 light, white/0.06 dark (figma darkmode note says
      the input border is one notch weaker than buttons) — exactly the
      l2-darkmode-thin pair. Fill: the input surface token (elevated in dark). */
@@ -49,11 +51,6 @@
   line-height: 24px;
 }
 
-/* New-session state rounds up (figma: r24 and a taller box). */
-.hero .card {
-  border-radius: 24px;
-}
-
 .accessory {
   display: flex;
   align-items: center;
@@ -85,7 +82,8 @@
 
 .input,
 .mirror {
-  padding: 12px 16px 0;
+  /* figma .InputText 34:10434: pl 16 / pr 12 / pt 4. */
+  padding: 4px 12px 0 16px;
   font-size: inherit;
   line-height: inherit;
   white-space: pre-wrap;
@@ -108,23 +106,98 @@
 .mirror {
   visibility: hidden;
   pointer-events: none;
-  /* 2-line floor: 2 × 24px line + 12px top padding; 14-line cap (336px). */
-  min-height: 60px;
+  /* figma min-h 52 (= ~2 × 24 line + 4pt); 14-line cap (336px). */
+  min-height: 52px;
   max-height: 336px;
   overflow: hidden;
 }
 
-.hero .mirror {
-  /* New-session box is taller at rest (figma 118px input area). */
-  min-height: 84px;
-}
-
-/* figma Frame 1123 (34:11463): pad 12/0/10/10, buttons vertically centered. */
+/* Toolbar: attach + Plan + Read-only on the left; model + send on the right
+   (figma Input_Bottom chrome). */
 .row {
   display: flex;
   align-items: center;
-  justify-content: flex-end;
-  padding: 0 10px 10px 12px;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 0 10px 10px 10px;
+  min-width: 0;
+}
+
+.tools,
+.modes,
+.trailing {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+/* figma 75:8208: 16 between + and the mode chips; 4 between Plan / Read-only. */
+.tools {
+  gap: 16px;
+}
+
+.modes {
+  gap: 4px;
+}
+
+.trailing {
+  flex: none;
+  gap: 12px;
+}
+
+/* Attach circle (figma + control): 28px, selector fill, primary glyph. */
+.add {
+  display: grid;
+  place-items: center;
+  flex: none;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 999px;
+  background: var(--dsw-specific-selector);
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+}
+
+.add:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover-solid);
+}
+
+.add:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+/* Plan / Read-only / model — native <select>, chip-like closed chrome
+   (figma ToggleButton: 13/20 medium secondary, 12px chevron). */
+.select {
+  max-width: 220px;
+  height: 28px;
+  padding: 0 20px 0 8px;
+  border: none;
+  border-radius: 8px;
+  outline: none;
+  background-color: transparent;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12' fill='none'%3E%3Cpath d='M3 4.5L6 7.5L9 4.5' stroke='%2381858C' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 4px center;
+  background-size: 12px 12px;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  white-space: nowrap;
+  cursor: pointer;
+  appearance: none;
+}
+
+.select:hover:not(:disabled) {
+  background-color: var(--dsw-alias-interactive-bg-hover);
+}
+
+.select:disabled {
+  opacity: 0.5;
+  cursor: default;
 }
 
 /* Primary send (figma IconButton 34:10465): 34px circle, #3964FE light /
@@ -133,6 +206,7 @@
 .primary {
   display: grid;
   place-items: center;
+  flex: none;
   width: 34px;
   height: 34px;
   border: none;
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index c5c8307ffc..04d1dd867d 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -4,10 +4,14 @@
 // position move of this component, never a swap (layout ruling). Running
 // LOCKS the input: textarea disabled with the draft visible, stop is the only
 // action; the turn ending re-enables and refocuses.
+//
+// Bottom chrome (attach / Plan / Read-only / model) is visual-only for now —
+// local native <select> state, no host wiring.
 
-import { useEffect, useRef } from 'react'
-import type { KeyboardEvent, MouseEvent, ReactNode } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import type { ChangeEvent, KeyboardEvent, MouseEvent, ReactNode } from 'react'
 import clsx from 'clsx'
+import { IconPlusOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import css from './InputBar.module.css'
 
 /** Prompt failure surface (mirrors the session snapshot's promptError shape). */
@@ -24,13 +28,33 @@ export interface InputBarProps {
   /** Hero = empty-state centered card; composer = resident bottom bar. */
   variant: 'hero' | 'composer'
   placeholder?: string
-  /** Optional leading accessory row content (the empty state mounts its cwd picker here). */
+  /** Optional leading accessory row above the textarea (kept for callers; empty state no longer uses it). */
   accessory?: ReactNode
   onDraftChange: (text: string) => void
   onSend: (mode: 'queue' | 'steer') => void
   onStop: () => void
 }
 
+interface SelectOption {
+  id: string
+  label: string
+}
+
+const PLAN_OPTIONS: readonly SelectOption[] = [
+  { id: 'plan', label: 'Plan' },
+  { id: 'agent', label: 'Agent' },
+]
+
+const READONLY_OPTIONS: readonly SelectOption[] = [
+  { id: 'readonly', label: 'Read-only' },
+  { id: 'readwrite', label: 'Read-write' },
+]
+
+const MODEL_OPTIONS: readonly SelectOption[] = [
+  { id: 'v4-pro-high', label: 'DeepSeek-V4-Pro High' },
+  { id: 'v4-pro', label: 'DeepSeek-V4-Pro' },
+]
+
 export function InputBar({
   draft, running, disabled, error, variant, placeholder, accessory, onDraftChange, onSend, onStop,
 }: InputBarProps) {
@@ -48,6 +72,11 @@ export function InputBar({
     }, 10)
   }
 
+  // Placeholder chrome: selection is local until plan/mode/model seams land.
+  const [planId, setPlanId] = useState('plan')
+  const [readonlyId, setReadonlyId] = useState('readonly')
+  const [modelId, setModelId] = useState('v4-pro-high')
+
   // Locked while running: the browser drops keystrokes AND focus on a disabled
   // textarea — no sending mid-turn, stop or wait.
   const locked = disabled || running
@@ -88,6 +117,25 @@ export function InputBar({
     if (!empty && !disabled) onSend('queue')
   }
 
+  const renderSelect = (
+    aria: string,
+    value: string,
+    options: readonly SelectOption[],
+    onPick: (id: string) => void,
+  ): ReactNode => (
+    <select
+      className={css.select}
+      aria-label={aria}
+      value={value}
+      disabled={locked}
+      onChange={(e: ChangeEvent<HTMLSelectElement>) => { onPick(e.target.value) }}
+    >
+      {options.map(opt => (
+        <option key={opt.id} value={opt.id}>{opt.label}</option>
+      ))}
+    </select>
+  )
+
   return (
     <div className={clsx(css.root, variant === 'hero' && css.hero)}>
       {error !== null && (
@@ -116,25 +164,44 @@ export function InputBar({
           <div aria-hidden className={css.mirror}>{`${draft}\n`}</div>
         </div>
         <div className={css.row}>
-          <button
-            type="button"
-            className={clsx(css.primary, running && css.stopping)}
-            aria-label={primaryLabel}
-            title={running ? '停止本轮' : '发送（Enter）'}
-            disabled={!running && (empty || disabled)}
-            onMouseDown={keepFocus}
-            onClick={onPrimary}
-          >
-            {running ? (
-              <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden>
-                <rect x="4" y="4" width="8" height="8" rx="1.5" fill="currentColor" />
-              </svg>
-            ) : (
-              <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden>
-                <path d="M8 13V3.8M8 3.8L3.8 8M8 3.8L12.2 8" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" fill="none" />
-              </svg>
-            )}
-          </button>
+          <div className={css.tools}>
+            <button
+              type="button"
+              className={css.add}
+              aria-label="添加"
+              title="添加"
+              disabled={locked}
+              onMouseDown={keepFocus}
+            >
+              <IconPlusOutline16 size={14} />
+            </button>
+            <div className={css.modes}>
+              {renderSelect('Plan mode', planId, PLAN_OPTIONS, setPlanId)}
+              {renderSelect('Access mode', readonlyId, READONLY_OPTIONS, setReadonlyId)}
+            </div>
+          </div>
+          <div className={css.trailing}>
+            {renderSelect('Model', modelId, MODEL_OPTIONS, setModelId)}
+            <button
+              type="button"
+              className={clsx(css.primary, running && css.stopping)}
+              aria-label={primaryLabel}
+              title={running ? '停止本轮' : '发送（Enter）'}
+              disabled={!running && (empty || disabled)}
+              onMouseDown={keepFocus}
+              onClick={onPrimary}
+            >
+              {running ? (
+                <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden>
+                  <rect x="4" y="4" width="8" height="8" rx="1.5" fill="currentColor" />
+                </svg>
+              ) : (
+                <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden>
+                  <path d="M8 13V3.8M8 3.8L3.8 8M8 3.8L12.2 8" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" fill="none" />
+                </svg>
+              )}
+            </button>
+          </div>
         </div>
       </div>
     </div>
diff --git a/packages/client/ui-conversation/src/client/stores.ts b/packages/client/ui-conversation/src/client/stores.ts
index ed27290827..9ce47e0baa 100644
--- a/packages/client/ui-conversation/src/client/stores.ts
+++ b/packages/client/ui-conversation/src/client/stores.ts
@@ -10,7 +10,7 @@
  * in the module cache (a de-facto singleton surviving plugin reloads).
  */
 import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ChatStoreState, SelectionTarget, ViewId } from './contract/views.ts'
+import type { ChatStoreState, SelectionTarget } from './contract/views.ts'
 
 /**
  * Annotation twin of the actions literal below (the export needs a declared
@@ -21,22 +21,22 @@ type ChatActions = {
   setDraft: (draft: ChatStoreState, text: string) => void
   clearDraft: (draft: ChatStoreState) => void
   restoreDraft: (draft: ChatStoreState, text: string) => void
-  setView: (draft: ChatStoreState, view: ViewId) => void
+  setView: (draft: ChatStoreState, view: string) => void
 }
 
 /**
  * Declare the per-session chat store. `selection` is the details-linkage
  * channel (conversation writes, details reads); `draft` is the composer text
  * (persisted so it survives session switches and reloads); `view` is the
- * active conversation view id (previously layout.viewFor — store seat is the
- * cross-remount survival channel, null falls back to the first registered view).
+ * active conversation view id (a 'conversation.view' entry id — store seat is
+ * the cross-remount survival channel, null falls back to the first view).
  * @returns the store handle (spec + identity + factory in one value).
  */
 export function createChatStore(): EngineStoreHandle<ChatStoreState, ChatActions> {
   return defineStore({
-    // Anchored to the contract shape: views consume the store through
-    // ConvViewProps' SnapshotSelectorHook<ChatStoreState>, so init and the
-    // contract cannot drift.
+    // Anchored to the contract shape: consumers read the store through
+    // PropsStore<ChatStore>'s SnapshotSelectorHook<ChatStoreState>, so init
+    // and the contract cannot drift.
     init: (): ChatStoreState => ({ selection: null, draft: '', view: null }),
     persist: 'dsh.conversation.chat',
     actions: {
@@ -46,7 +46,7 @@ export function createChatStore(): EngineStoreHandle<ChatStoreState, ChatActions
       // Optimistic-send failure restore: only when the user typed nothing new
       // since the clear (send choreography lives in the inject factory).
       restoreDraft: (d, text: string) => { if (d.draft === '') d.draft = text },
-      setView: (d, view: ViewId) => { d.view = view },
+      setView: (d, view: string) => { d.view = view },
     },
   })
 }
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 eda731f586..9968c3b46e 100644
--- a/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
+++ b/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
@@ -1,20 +1,32 @@
 // Bash toolview sample, written in third-party posture: everything below uses
-// only the public registration surface (ctx.toolviews.register + ToolViewProps)
-// — the differential-rendering acceptance proof for the registry chain.
-// Two registrations: a global bash row, and a scope-filtered variant that
-// takes over for matching sessions only (later registration wins its tier).
+// only the public slot surface (ctx.slots.register into the keyed
+// 'conversation.chat.toolview' hole + ToolRowProps) — the acceptance proof
+// that a plain plugin can take over a tool row with zero dedicated machinery.
+// Session-dimension differentiation happens INSIDE the component (the
+// canonical sub-agent scenario): rows in child sessions render the scoped
+// variant, derived from the standard useSessions kit — no registry predicates.
 
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ToolViewProps } from '../contract/toolview.ts'
-import type { ToolViewRegistry } from './registry.ts'
-import { toolRowModel, type ToolCallBlock } from '../contract/tool-call-model.ts'
+import type { Context } from 'cordis'
+import type { ToolRowProps } from '../contract/slots.ts'
+import { toolRowModel } from '../contract/tool-call-model.ts'
 import css from './bash-sample.module.css'
 
-/** Global bash row: command-first monospace summary (replaces the generic row). */
-export function BashRow({ toolName, block, actions }: ToolViewProps) {
-  const model = toolRowModel(toolName, block as ToolCallBlock)
+/** Bash row: command-first monospace summary replacing the generic card.
+ *  Sub-session rows (parentId present) swap the prompt for a scoped badge —
+ *  the differential stays observable per session from one registration. */
+export function BashRow({ toolName, block, openDetails, sessionId, useSessions }: ToolRowProps) {
+  const model = toolRowModel(toolName, block)
+  const isChild = useSessions(list => list.byId[sessionId]?.parentId !== undefined)
+  if (isChild) {
+    return (
+      <div className={css.row} data-sample="bash-scoped" onClick={openDetails}>
+        <span className={css.scopeBadge}>scoped</span>
+        <span className={css.command}>{model.summary}</span>
+      </div>
+    )
+  }
   return (
-    <div className={css.row} data-sample="bash-global" onClick={actions.openDetails}>
+    <div className={css.row} data-sample="bash-global" onClick={openDetails}>
       <span className={css.prompt} aria-hidden>$</span>
       <span className={css.command}>{model.summary}</span>
       {model.state === 'error' && <span className={css.err}>failed</span>}
@@ -22,31 +34,20 @@ export function BashRow({ toolName, block, actions }: ToolViewProps) {
   )
 }
 
-/** Scoped variant: visually distinct so the differential hit is observable. */
-export function ScopedBashRow({ toolName, block, actions }: ToolViewProps) {
-  const model = toolRowModel(toolName, block as ToolCallBlock)
-  return (
-    <div className={css.row} data-sample="bash-scoped" onClick={actions.openDetails}>
-      <span className={css.scopeBadge}>scoped</span>
-      <span className={css.command}>{model.summary}</span>
-    </div>
-  )
-}
-
 /**
- * Register both sample rows.
- * @param toolviews - the conversation plugin's registry service.
- * @param scope - session filter for the scoped variant.
- * @returns disposer removing both registrations.
+ * The sample as a plain registrant plugin. `inject` carries the load-order
+ * seam: requiring the conversation service guarantees the chat entry (and
+ * with it the 'conversation.chat.toolview' declaration) is registered —
+ * ui-conversation's apply mounts the service after the chat entry.
  */
-export function registerBashSamples(
-  toolviews: ToolViewRegistry,
-  scope: (sessionId: SessionId) => boolean,
-): () => void {
-  const offGlobal = toolviews.register('bash', BashRow)
-  const offScoped = toolviews.register('bash', ScopedBashRow, { scope })
-  return () => {
-    offGlobal()
-    offScoped()
-  }
+export const bashToolviewSample = {
+  name: 'bash-toolview-sample',
+  inject: ['slots', 'conversation'],
+  /**
+   * Register the bash row into the chat view's keyed toolview hole.
+   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
+   */
+  apply(ctx: Context): void {
+    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'bash' }, BashRow)
+  },
 }
diff --git a/packages/client/ui-conversation/src/client/toolviews/registry.ts b/packages/client/ui-conversation/src/client/toolviews/registry.ts
deleted file mode 100644
index 76e447f386..0000000000
--- a/packages/client/ui-conversation/src/client/toolviews/registry.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-/**
- * ToolViewRegistry: named per-tool component registry, session-scope aware
- * (api-contracts v3 section 7). Consumed by chat now, trajectory/waterfall
- * later — deliberately a named service, not a SlotMap key. The tool key set
- * is deliberately open (model-side tools arrive at runtime): the strong
- * typing lives inside the Entry — `I` is inferred from the inject factory at
- * the register site and proves component props ⊇ ToolViewProps & I.
- */
-import type { FC } from 'react'
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ResolvedToolView, ToolViewOptions, ToolViewProps } from '../contract/toolview.ts'
-
-/** Stored registration: the per-registration inject parameter is erased
- *  (storage-erase/read-restore is the typed-Map boundary, one cast budgeted). */
-interface Registration extends ToolViewOptions {
-  component: FC<ToolViewProps & object>
-}
-
-/**
- * Per-tool renderer registry. Resolution order: scope match (later
- * registration wins) > global (same tie-break) > undefined, where the caller
- * falls back to GenericToolCard.
- */
-export class ToolViewRegistry {
-  private byTool = new Map<string, Registration[]>()
-  private version = 0
-  private listeners = new Set<() => void>()
-
-  /**
-   * Register a tool row renderer. The component must accept the shared
-   * ToolViewProps plus its own injected share `I` — mismatches (missing keys,
-   * wrong types, an inject factory that does not produce what the component
-   * declares) are register-site compile errors.
-   * @param tool - tool name the renderer takes over.
-   * @param component - row component over ToolViewProps & I.
-   * @param opts - optional session-scope filter and private inject factory.
-   * @returns disposer removing this registration.
-   */
-  register<I extends object = object>(
-    tool: string, component: FC<ToolViewProps & I>, opts?: ToolViewOptions<I>): () => void {
-    const list = this.byTool.get(tool) ?? []
-    if (list.length === 0) this.byTool.set(tool, list)
-    // Storage erases I (heterogeneous registrations share one list); resolve
-    // restores the erased shape on the read face.
-    const entry: Registration = { component: component as FC<ToolViewProps & object>, ...opts }
-    list.push(entry)
-    this.bump()
-    let disposed = false
-    return () => {
-      if (disposed) return
-      disposed = true
-      const at = list.indexOf(entry)
-      /* v8 ignore next -- negative arm: an entry lives in one list and only its
-         own once-guarded disposer removes it, so a live disposer always finds it. */
-      if (at >= 0) list.splice(at, 1)
-      if (list.length === 0) this.byTool.delete(tool)
-      this.bump()
-    }
-  }
-
-  /**
-   * Resolve the renderer for a tool in a session.
-   * @param tool - tool name.
-   * @param sessionId - session the row renders in (fed to scope filters).
-   * @returns resolved view, or undefined when nothing matches.
-   */
-  resolve(tool: string, sessionId: SessionId): ResolvedToolView | undefined {
-    const list = this.byTool.get(tool)
-    if (list === undefined) return undefined
-    let global: Registration | undefined
-    let scoped: Registration | undefined
-    for (const entry of list) {
-      if (entry.scope === undefined) global = entry
-      else if (entry.scope(sessionId)) scoped = entry
-    }
-    const hit = scoped ?? global
-    if (hit === undefined) return undefined
-    return hit.inject === undefined ? { component: hit.component } : { component: hit.component, inject: hit.inject }
-  }
-
-  /**
-   * Subscribe to registration changes (render outlets re-resolve on notify).
-   * @param fn - change listener.
-   * @returns disposer.
-   */
-  subscribe(fn: () => void): () => void {
-    this.listeners.add(fn)
-    return () => this.listeners.delete(fn)
-  }
-
-  /**
-   * Monotonic registration version for uSES getSnapshot.
-   * @returns current version.
-   */
-  getVersion(): number {
-    return this.version
-  }
-
-  private bump(): void {
-    this.version += 1
-    for (const fn of this.listeners) fn()
-  }
-}
diff --git a/packages/client/ui-conversation/src/invariant.ts b/packages/client/ui-conversation/src/invariant.ts
index 3100170938..f4ecd7e260 100644
--- a/packages/client/ui-conversation/src/invariant.ts
+++ b/packages/client/ui-conversation/src/invariant.ts
@@ -15,11 +15,10 @@ export const name = 'client-ui-conversation-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the conversation service emits no cordis events — its
- * view and toolview registries notify through package-local subscribe faces
- * whose ordering (synchronous version bump before notification) is exercised
- * directly by the behavior specs, and the per-scope store accounts are owned
- * mutable state with no cross-plugin observer to contradict.
+ * 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
+ * invariants live with the runtime slots package.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/client/ui-conversation/tests/apply-inject.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
index 4631e08d77..edd9f7d54d 100644
--- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
@@ -2,10 +2,12 @@
 // apply inject factories exercised end to end against the terminal thin
 // shape: the conversation surface (views triple, send choreography incl.
 // optimistic clear + failure restore THROUGH the declared store actions,
-// openDetails = select action + layout orchestration, watch-driven open,
-// sessions.open navigation), the injectless-but-closeDetails details surface,
-// and the one-callback empty surface. Complements chat-apply.spec.tsx
-// (registration) and selection-survival.spec.ts (store axis).
+// openDetails = select action + layout orchestration, sessions.open
+// navigation), the injectless-but-closeDetails details surface, and the
+// one-callback empty surface. Complements chat-apply.spec.tsx (registration)
+// and selection-survival.spec.ts (store axis). History opening is NOT an
+// inject concern anymore — the runtime sessions service opens on watch
+// (sessions-service.spec.ts owns that behavior).
 
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -13,10 +15,10 @@ import { cleanup } from '@testing-library/react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { SlotsService, scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SlotRendererHost } from '@deepseek-ai/dsh-client-ui-slots'
-import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SlotRendererHost } from '@deepseek-ai/dsh-client-web-react'
+import { ConversationService, apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
-  ConversationInjected, DetailsInjected, EmptyStateInjected,
+  ChatViewInjected, ConversationInjected, DetailsInjected, EmptyStateInjected,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { createChatStore } from '../src/client/stores.ts'
 
@@ -49,7 +51,7 @@ async function bench() {
 
   const listStore = createSnapshotStore<SessionListState>({
     ids: [ROOT],
-    byId: { [ROOT]: { id: ROOT, title: 'R', cwd: '/proj', running: false, updatedAt: 1 } },
+    byId: { [ROOT]: { id: ROOT, title: 'R', displayTitle: 'R', cwd: '/proj', running: false, updatedAt: 1 } },
     current: ROOT,
   } as SessionListState)
   const sessionFake = {
@@ -74,7 +76,9 @@ async function bench() {
     manager: { get: () => sessionFake },
     scope: (id: SessionId) => mint(id),
     cell: () => undefined,
+    scopeOf,
     create: vi.fn(() => Promise.resolve(ROOT)),
+    createWorkspace: vi.fn(() => Promise.resolve(ROOT)),
     open: vi.fn(),
   }
   ctx.provide('sessions', sessionsFake)
@@ -103,7 +107,7 @@ async function bench() {
   slots.install({ renderRoot: (h) => { host = h; return null } })
   slots.renderSlot('root', {})
   const hostFace = host!
-  const entryOf = (key: 'conversation' | 'details' | 'conversation.empty') => hostFace.entriesOf(key)[0]!
+  const entryOf = (key: 'conversation' | 'conversation.view' | 'details' | 'conversation.empty') => hostFace.entriesOf(key)[0]!
   /** Resolve store instance + call the inject the way the outlet would. */
   const conversationSurface = (id: SessionId) => {
     const entry = entryOf('conversation')
@@ -112,18 +116,30 @@ async function bench() {
       id, instance.actions)
     return { instance, injected }
   }
-  return { ctx, slots, hostFace, entryOf, conversationSurface, sessionFake, sessionsFake, layoutFake, mint }
+  /** Same resolution for the chat entry riding the view ring. */
+  const chatViewSurface = (id: SessionId) => {
+    const entry = entryOf('conversation.view')
+    const instance = hostFace.storeOf(entry, id) as ChatInstance
+    const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ChatViewInjected)(
+      id, instance.actions)
+    return { instance, injected }
+  }
+  return { ctx, slots, hostFace, entryOf, conversationSurface, chatViewSurface, sessionFake, sessionsFake, layoutFake, mint }
 }
 
 describe('conversation slot inject surface', () => {
-  it('assembles the thin surface, pulls history through the watch signal, navigates via sessions.open', async () => {
+  it('assembles the thin surface side-effect-free, navigates via sessions.open', async () => {
     const b = await bench()
     const { injected } = b.conversationSurface(ROOT)
-    expect(b.sessionFake.open).toHaveBeenCalledTimes(1)
+    // Assembly has no session side effects: opening the event window belongs
+    // to the runtime watch path, not the inject factory.
+    expect(b.sessionFake.open).not.toHaveBeenCalled()
     expect(injected.views.list().map(v => v.id)).toEqual(['chat'])
     injected.open(ROOT)
     expect(b.sessionsFake.open).toHaveBeenCalledWith(ROOT)
-    injected.loadOlder()
+    // loadOlder moved to the chat view entry's face (the ring rider).
+    const chatView = b.chatViewSurface(ROOT)
+    chatView.injected.loadOlder()
     expect(b.sessionFake.loadOlder).toHaveBeenCalledTimes(1)
   })
 
@@ -161,27 +177,51 @@ describe('conversation slot inject surface', () => {
     expect(b.sessionFake.cancel).toHaveBeenCalledTimes(1)
   })
 
-  it('openDetails writes the selection through the store actions and opens the panel', async () => {
+  it('inject fails loud when the session resolves no scope or the scope lacks the service', async () => {
     const b = await bench()
-    const { instance, injected } = b.conversationSurface(ROOT)
+    const entry = b.entryOf('conversation')
+    const instance = b.hostFace.storeOf(entry, ROOT) as ChatInstance
+    const injectFn = entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ConversationInjected
+    // Unknown session: sessions.scope answers nothing.
+    ;(b.sessionsFake.scope as unknown) = () => undefined
+    expect(() => injectFn(ROOT, instance.actions)).toThrow(/resolved no scope/)
+    // A scope minted outside the service tree: no conversation service on it.
+    const foreign = new Context()
+    ;(b.sessionsFake.scope as unknown) = () => foreign.plugin(() => {}).ctx.extend({})
+    expect(() => injectFn(ROOT, instance.actions)).toThrow(/unavailable through the session scope/)
+  })
+
+  it('openDetails (chat view face) writes the selection through the store actions and opens the panel', async () => {
+    const b = await bench()
+    const { instance, injected } = b.chatViewSurface(ROOT)
     injected.openDetails({ turnSeq: 2, callId: 'c1' })
     expect(instance.store.getSnapshot().selection).toEqual({ turnSeq: 2, callId: 'c1' })
     expect(b.layoutFake.openDetails).toHaveBeenCalledTimes(1)
+    // The chat view shares the conversation entry's store instance: selection
+    // writes land where the skeleton and details read.
+    const conv = b.conversationSurface(ROOT)
+    expect(conv.instance).toBe(instance)
   })
 
-  it('views read face forwards to the service registry (subscribe/version)', async () => {
+  it('views read face projects the ring ledger (subscribe/version through ctx.slots)', async () => {
     const b = await bench()
     const { injected } = b.conversationSurface(ROOT)
     const before = injected.views.version()
     const listener = vi.fn()
     const unsub = injected.views.subscribe(listener)
-    const conversation = b.ctx.get('conversation') as
-      import('@deepseek-ai/dsh-client-ui-conversation/client').ConversationService
-    const off = conversation.registerView({ id: 'chat2', label: 'X', component: () => null } as never)
+    // A second ring rider (what ui-trajectory does in production).
+    const off = b.slots.register(
+      { name: 'conversation.view', id: 'chat2', order: 5, label: 'X' } as never, (() => null) as never)
+    await Promise.resolve() // ledger notifications batch per microtask
     expect(listener).toHaveBeenCalled()
     expect(injected.views.version()).toBeGreaterThan(before)
     expect(injected.views.list().map(v => v.id)).toEqual(['chat', 'chat2'])
+    // Label falls back to the id when a rider declares none.
+    const off2 = b.slots.register(
+      { name: 'conversation.view', id: 'bare', order: 6 } as never, (() => null) as never)
+    expect(injected.views.list().map(v => v.label)).toEqual(['Chat', 'X', 'bare'])
     off()
+    off2()
     unsub()
   })
 })
@@ -200,15 +240,29 @@ describe('details and empty inject surfaces', () => {
     expect(details).toBe(conv)
   })
 
-  it('empty injects the startSession chain only (no store, cwds derive in-component)', async () => {
+  it('empty injects startSession and createWorkspaceSession (no store, cwds derive in-component)', async () => {
     const b = await bench()
     const entry = b.entryOf('conversation.empty')
     expect(entry.store).toBeUndefined()
     const injected = (entry.inject as unknown as () => EmptyStateInjected)()
-    expect(Object.keys(injected)).toEqual(['startSession'])
+    expect(Object.keys(injected).sort()).toEqual(['createWorkspaceSession', 'startSession'])
     await injected.startSession({ text: 'go', mode: 'queue' })
     expect(b.sessionsFake.create).toHaveBeenCalled()
     expect(b.sessionsFake.open).toHaveBeenCalledWith(ROOT)
     expect(b.sessionFake.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'go' }], 'queue')
+    b.sessionsFake.open.mockClear()
+    await injected.createWorkspaceSession('Fresh')
+    expect(b.sessionsFake.createWorkspace).toHaveBeenCalledWith('Fresh')
+    expect(b.sessionsFake.open).toHaveBeenCalledWith(ROOT)
+  })
+
+  it('startSession fails loud on a torn boot (conversation service fiber gone)', async () => {
+    const b = await bench()
+    const injected = (b.entryOf('conversation.empty').inject as unknown as () => EmptyStateInjected)()
+    // Tear the service's own fiber (registry keyed by the class): the slot
+    // entries survive, so the gesture-time read hits the loud branch.
+    b.ctx.registry.delete(ConversationService)
+    await vi.waitFor(() => { expect(b.ctx.get('conversation')).toBeUndefined() })
+    expect(() => injected.startSession({ text: 'go', mode: 'queue' })).toThrow(/conversation service unavailable/)
   })
 })
diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
index 68734b9d10..adb9271c71 100644
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -1,9 +1,11 @@
 // @vitest-environment jsdom
-// apply wiring: services provided, chat view + footer chrome registered, the
-// three slot registrations land against a root entry's children declarations
-// (the AppFrame role), the shared store handle rides both session slots, and
-// the bash samples resolve differentially (sub-session default scope).
-// Full-chain rendering belongs to the shell e2e; this spec stops at the
+// apply wiring: the conversation service provided, the chat view registered
+// as the first 'conversation.view' ring entry declaring the keyed toolview
+// hole, the three slot registrations land against a root entry's children
+// declarations (the AppFrame role), the shared store handle rides all session
+// entries, and the bash sample mounts through the load-order seam as a keyed
+// entry. Full-chain rendering belongs to the machinery spec
+// (chat-toolview-slot.spec.tsx) and the shell e2e; this spec stops at the
 // assembly surface.
 
 import { Context } from 'cordis'
@@ -11,8 +13,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
-import { apply, inject, ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 const ROOT = 'root-1' as SessionId
 const CHILD = 'child-1' as SessionId
@@ -25,8 +26,8 @@ async function bench() {
   const listStore = createSnapshotStore<SessionListState>({
     ids: [ROOT, CHILD],
     byId: {
-      [ROOT]: { id: ROOT, title: 'R', running: false, updatedAt: 1 },
-      [CHILD]: { id: CHILD, title: 'C', parentId: ROOT, running: false, updatedAt: 2 },
+      [ROOT]: { id: ROOT, title: 'R', displayTitle: 'R', running: false, updatedAt: 1 },
+      [CHILD]: { id: CHILD, title: 'C', displayTitle: 'C', parentId: ROOT, running: false, updatedAt: 2 },
     },
     current: undefined,
   } as SessionListState)
@@ -60,62 +61,69 @@ async function bench() {
 }
 
 /** First stored entry for a key (inject/store live directly on StoredEntry). */
-function renderEntryOf(slots: SlotsService, key: 'conversation' | 'details' | 'conversation.empty') {
+function renderEntryOf(slots: SlotsService, key: 'conversation' | 'conversation.view' | 'details' | 'conversation.empty') {
   return slots.entries(key)[0] as undefined | { inject?: unknown; store?: unknown }
 }
 
 describe('apply wiring', () => {
-  it('provides conversation and toolviews services', async () => {
+  it('provides the conversation service', async () => {
     const b = await bench()
     await b.fiber.await()
     expect(b.ctx.get('conversation')).toBeDefined()
-    expect(b.ctx.get('toolviews')).toBeInstanceOf(ToolViewRegistry)
   })
 
-  it('registers the chat view with the stats footer', async () => {
+  it('registers the chat view as the first ring entry, declaring the keyed toolview hole', async () => {
     const b = await bench()
     await b.fiber.await()
-    const conversation = b.ctx.get('conversation') as ConversationService
-    const views = conversation.views()
-    expect(views.map((v) => v.id)).toEqual(['chat'])
-    expect(views[0]?.chrome?.footer).toBeDefined()
+    const entries = b.slots.entries('conversation.view')
+    expect(entries.map((e) => e.options.id)).toEqual(['chat'])
+    expect(entries[0]?.options.label).toBe('Chat')
+    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' })
   })
 
-  it('occupies the three slots; session pair shares one store handle, empty declares none', async () => {
+  it('occupies the three slots + the ring; session entries share one store handle, empty declares none', async () => {
     const b = await bench()
     await b.fiber.await()
     const conversation = renderEntryOf(b.slots, 'conversation')
+    const chatView = renderEntryOf(b.slots, 'conversation.view')
     const details = renderEntryOf(b.slots, 'details')
     const empty = renderEntryOf(b.slots, 'conversation.empty')
     expect(conversation?.inject).toBeTypeOf('function')
+    expect(chatView?.inject).toBeTypeOf('function')
     expect(details?.inject).toBeTypeOf('function')
     expect(empty?.inject).toBeTypeOf('function')
-    // The shared handle: one apply-built store value on BOTH session entries.
+    // The shared handle: one apply-built store value on ALL session entries.
     expect(conversation?.store).toBeDefined()
     expect(details?.store).toBe(conversation?.store)
+    expect(chatView?.store).toBe(conversation?.store)
     // The empty slot is storeless (local state + useSessions derivation).
     expect(empty?.store).toBeUndefined()
   })
 
-  it('bash samples resolve differentially: scoped row for sub-sessions, global for roots', async () => {
+  it('mounts the bash sample as a keyed entry through the load-order seam', async () => {
     const b = await bench()
     await b.fiber.await()
-    const toolviews = b.ctx.get('toolviews') as ToolViewRegistry
-    const forChild = toolviews.resolve('bash', CHILD)
-    const forRoot = toolviews.resolve('bash', ROOT)
-    expect(forChild).toBeDefined()
-    expect(forRoot).toBeDefined()
-    expect(forChild!.component).not.toBe(forRoot!.component)
+    // The sample plugin's inject: ['slots', 'conversation'] resolved — the
+    // service being present implies the chat entry declared the hole first.
+    const entries = b.slots.entries('conversation.chat.toolview')
+    expect(entries.map((e) => e.options.key)).toEqual(['bash'])
   })
 
-  it('plugin fiber disposal collects every registration (unload cascade)', async () => {
+  it('plugin fiber disposal collects every registration (unload cascade, ring and hole included)', async () => {
     const b = await bench()
     await b.fiber.await()
     await b.fiber.dispose()
     expect(b.slots.entries('conversation')).toHaveLength(0)
+    // 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('details')).toHaveLength(0)
     expect(b.slots.entries('conversation.empty')).toHaveLength(0)
     expect(b.ctx.get('conversation')).toBeUndefined()
-    expect(b.ctx.get('toolviews')).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 aad467f9f5..be50356185 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -1,41 +1,22 @@
 // @vitest-environment jsdom
 // Remaining chat branch tails: MessageItem context/unknown/steering arms,
-// ToolViewOutlet inject cache + crash fallback + retry, StatsLine no-cache
-// join, PendingCard reason strip, AssistantMarkdown single-line reasoning,
-// ChatView view-body fallbacks, and apply's action lambdas.
+// StatsLine no-cache join, PendingCard reason strip, AssistantMarkdown
+// single-line reasoning. (Tool-row dispatch tails live with the keyed-slot
+// machinery specs since the tool ring dissolved into renderSlot.)
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
-import { act } from '@testing-library/react'
-import type { SessionId, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
-import type { RpcId } from '@deepseek-ai/dsh-client-connection/client'
-import { hookOf } from './hook.ts'
-import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
-import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type { ToolViewProps, Translate } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { MessageItem } from '../src/client/chat/MessageItem.tsx'
 import { PendingCard } from '../src/client/chat/PendingCard.tsx'
 import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
-import { StatsLine } from '../src/client/chat/StatsLine.tsx'
-import { ToolViewOutlet } from '../src/client/chat/ToolViewOutlet.tsx'
+import { StatsLine, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
 
 afterEach(cleanup)
 
-const SID = 's1' as SessionId
-
-const result = (callId: string): ToolResultNode => ({
-  kind: 'tool-result', seq: 3, callId,
-  call: { name: 'bash', argsRaw: '{"command":"x"}' },
-  content: [], isError: false, callView: null, resultView: null,
-})
-
-const viewProps = (): ToolViewProps => ({
-  callId: 'c1', toolName: 'bash', block: result('c1'),
-  useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
-  actions: { openDetails: vi.fn() },
-  t: ((k: string) => k) as Translate,
-})
-
 describe('MessageItem arms', () => {
   it('steering bubbles carry the interjection badge and non-text rest blocks', () => {
     const view = render(
@@ -65,7 +46,7 @@ describe('MessageItem arms', () => {
 describe('small branch tails', () => {
   it('PendingCard approval reason renders when present', () => {
     const view = render(
-      <PendingCard item={{ kind: 'approval', rpcId: 'r1' as RpcId, approvalId: 'a1', toolName: 'rm', reason: 'careful' }} />,
+      <PendingCard item={new PendingWait('approval', RpcId('r1'), 's1' as SessionId, { approvalId: 'a1', toolName: 'rm', reason: 'careful' } as PendingWait<'approval'>['payload'], vi.fn())} />,
     )
     expect(view.getByText('careful')).toBeTruthy()
   })
@@ -85,71 +66,8 @@ describe('small branch tails', () => {
     }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
-      <StatsLine sessionId={SID} useSession={hookOf(source) as unknown as UseSession} />,
+      <StatsLine useSession={bindSnapshotSelector(source) as unknown as StatsLineProps['useSession']} />,
     )
     expect(view.getByText('10 tokens · 1 turns · 1 steps')).toBeTruthy()
   })
 })
-
-describe('ToolViewOutlet dispatch', () => {
-  it('caches the inject factory per (registration x session) and merges its props', () => {
-    const registry = new ToolViewRegistry()
-    const inject = vi.fn((sessionId: SessionId) => ({ extra: `injected:${sessionId}` }))
-    registry.register('bash',
-      (p: ToolViewProps & { extra: string }) => <div data-testid="row">{p.extra}</div>,
-      { inject })
-    // Pure props machinery: the outlet feeds its own sessionId to the
-    // factory — no provider/context needed (terminal channel form).
-    const view = render(
-      <ToolViewOutlet registry={registry} sessionId={SID} toolName="bash" viewProps={viewProps()} />,
-    )
-    expect(view.getByTestId('row').textContent).toBe(`injected:${SID}`)
-    expect(inject).toHaveBeenCalledTimes(1)
-    // Remount under the SAME session: cache hit, factory not re-run.
-    view.unmount()
-    const second = render(
-      <ToolViewOutlet registry={registry} sessionId={SID} toolName="bash" viewProps={viewProps()} />,
-    )
-    expect(second.getByTestId('row').textContent).toBe(`injected:${SID}`)
-    expect(inject).toHaveBeenCalledTimes(1)
-    // A different session is a distinct cache key: factory runs once more.
-    second.unmount()
-    const other = render(
-      <ToolViewOutlet registry={registry} sessionId={'s2' as SessionId} toolName="bash" viewProps={viewProps()} />,
-    )
-    expect(other.getByTestId('row').textContent).toBe('injected:s2')
-    expect(inject).toHaveBeenCalledTimes(2)
-  })
-
-  it('a crashing custom row falls back to GenericToolCard and retries on re-registration', () => {
-    const registry = new ToolViewRegistry()
-    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
-    // React dev builds re-dispatch boundary-caught errors as window 'error'
-    // events (invokeGuardedCallback); swallow them so vitest sees the caught path.
-    const swallow = (e: Event): void => { e.preventDefault() }
-    window.addEventListener('error', swallow)
-    try {
-      const Bomb = () => { throw new Error('row bomb') }
-      registry.register('bash', Bomb as never)
-      const view = render(
-        <ToolViewOutlet registry={registry} sessionId={SID} toolName="bash" viewProps={viewProps()} />,
-      )
-      // Crash caught: generic row rendered instead.
-      expect(view.getByText('Bash')).toBeTruthy()
-      // A new registration bumps the version; the boundary retries the custom row.
-      act(() => { registry.register('bash', (() => <div data-testid="fixed" />) as never) })
-      expect(view.getByTestId('fixed')).toBeTruthy()
-    } finally {
-      window.removeEventListener('error', swallow)
-      consoleError.mockRestore()
-    }
-  })
-
-  it('registry miss renders the generic row directly', () => {
-    const registry = new ToolViewRegistry()
-    const view = render(
-      <ToolViewOutlet registry={registry} sessionId={SID} toolName="bash" viewProps={viewProps()} />,
-    )
-    expect(view.getByText('Bash')).toBeTruthy()
-  })
-})
diff --git a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx b/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
index 9b6d6e94a7..4d3383b2d1 100644
--- a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
@@ -1,28 +1,26 @@
 // @vitest-environment jsdom
-// StatsLine (chrome.footer first consumer): totals derivation + the RFC hard
-// acceptance — zero renders during streaming. Bash sample: differential
-// registry hits per session, teardown reverts to the generic row.
+// StatsLine (rendered inside the chat view body): totals derivation + the RFC
+// hard acceptance — zero renders during streaming. Bash sample row: the
+// canonical sub-agent differential decided INSIDE the component off the
+// standard useSessions kit (no registry predicates — tool ring dissolved).
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import type {
-  AssistantMessageNode, ConversationSnapshot, SessionId, ToolResultNode,
+  AssistantMessageNode, ConversationSnapshot, SessionId, SessionListState, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
-import { hookOf } from './hook.ts'
-import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ChromeProps, ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { StatsLine, deriveStats } from '../src/client/chat/StatsLine.tsx'
-import { BashRow, ScopedBashRow, registerBashSamples } from '../src/client/toolviews/bash-sample.tsx'
-import { ToolViewOutlet } from '../src/client/chat/ToolViewOutlet.tsx'
-import { childSessionScope } from '../src/client/chat/register.ts'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { StatsLine, deriveStats, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
+import { BashRow } from '../src/client/toolviews/bash-sample.tsx'
 
 afterEach(cleanup)
 
 const SID = 's1' as SessionId
 
 const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessageNode => ({
-  kind: 'assistant', seq, turn, step: seq, blocks: [{ kind: 'text', text: `t${seq}` }],
+  kind: 'assistant', seq, time: seq * 1_000, turn, step: seq, blocks: [{ kind: 'text', text: `t${seq}` }],
   ...(usage === undefined ? {} : { usage }),
 })
 
@@ -67,7 +65,7 @@ describe('deriveStats', () => {
 
   it('cache hit stays null with no cache accounting; non-assistant nodes ignored', () => {
     const tool: ToolResultNode = {
-      kind: 'tool-result', seq: 5, callId: 'c', call: null, content: [],
+      kind: 'tool-result', seq: 5, time: 5_000, callId: 'c', call: null, callTime: null, content: [],
       isError: false, callView: null, resultView: null,
     }
     const stats = deriveStats([tool, assistant(1, 1)])
@@ -77,8 +75,8 @@ describe('deriveStats', () => {
 })
 
 describe('StatsLine', () => {
-  function props(source: { getSnapshot(): ConversationSnapshot; subscribe(fn: () => void): () => void }): ChromeProps {
-    return { sessionId: SID, useSession: hookOf(source) as unknown as UseSession }
+  function props(source: { getSnapshot(): ConversationSnapshot; subscribe(fn: () => void): () => void }): StatsLineProps {
+    return { useSession: bindSnapshotSelector(source) }
   }
 
   it('renders the joined stats row and hides with zero steps', () => {
@@ -95,7 +93,7 @@ describe('StatsLine', () => {
   it('renders ZERO times during streaming chunk frames (RFC hard acceptance)', () => {
     const { set, source } = makeSource({ nodes: [assistant(1, 1)] })
     let renders = 0
-    function Counting(p: ChromeProps) {
+    function Counting(p: StatsLineProps) {
       renders += 1
       return <StatsLine {...p} />
     }
@@ -109,71 +107,80 @@ describe('StatsLine', () => {
   })
 })
 
-describe('bash toolview samples', () => {
+describe('bash sample row', () => {
+  const ROOT = 'root-1' as SessionId
+  const CHILD = 'child-1' as SessionId
+
   const result = (callId: string): ToolResultNode => ({
-    kind: 'tool-result', seq: 3, callId,
+    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,
   })
 
-  const viewProps = (openDetails = vi.fn()): ToolViewProps => ({
-    callId: 'c1', toolName: 'bash', block: result('c1'),
-    useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
-    actions: { openDetails },
-    t: (k) => k,
-  })
-
-  function outlet(registry: ToolViewRegistry, sessionId: SessionId, p = viewProps()) {
-    return render(
-      <ToolViewOutlet registry={registry} sessionId={sessionId} toolName="bash" viewProps={p} />,
-    )
+  /** Real list-store engine: the family fixture the in-component parentId branch reads. */
+  function listStore() {
+    return createSnapshotStore<SessionListState>({
+      ids: [ROOT, CHILD],
+      byId: {
+        [ROOT]: { id: ROOT, title: 'r', displayTitle: 'r', running: false, updatedAt: 0 },
+        [CHILD]: { id: CHILD, title: 'c', displayTitle: 'c', parentId: ROOT, running: false, updatedAt: 0 },
+      },
+      current: undefined,
+    } as SessionListState)
   }
 
-  it('differential rendering: scoped row for the matching session, global elsewhere', () => {
-    const registry = new ToolViewRegistry()
-    registerBashSamples(registry, (id) => id === ('swarm' as SessionId))
-    const scoped = outlet(registry, 'swarm' as SessionId)
+  const rowProps = (sessionId: SessionId, over?: {
+    store?: ReturnType<typeof listStore>
+    openDetails?: () => void
+  }): ToolRowProps => ({
+    callId: 'c1', toolName: 'bash', block: result('c1'),
+    openDetails: over?.openDetails ?? vi.fn(),
+    sessionId,
+    useSessions: bindSnapshotSelector(over?.store ?? listStore()),
+  } as unknown as ToolRowProps)
+
+  it('differential rendering: the scoped variant in sub-sessions, global at roots', () => {
+    const scoped = render(<BashRow {...rowProps(CHILD)} />)
     expect(scoped.container.querySelector('[data-sample="bash-scoped"]')).not.toBeNull()
-    const plain = outlet(registry, SID)
+    expect(scoped.getByText('scoped')).toBeTruthy()
+    const plain = render(<BashRow {...rowProps(ROOT)} />)
     expect(plain.container.querySelector('[data-sample="bash-global"]')).not.toBeNull()
   })
 
-  it('teardown removes both registrations and falls back to the generic row', () => {
-    const registry = new ToolViewRegistry()
-    const off = registerBashSamples(registry, () => true)
-    const view = outlet(registry, SID)
-    expect(view.container.querySelector('[data-sample="bash-scoped"]')).not.toBeNull()
-    act(() => off())
-    expect(view.container.querySelector('[data-sample]')).toBeNull()
-    expect(view.getByText('Bash')).toBeTruthy()
+  it('a session outside the list renders the global arm (no parent known)', () => {
+    const view = render(<BashRow {...rowProps('gone' as SessionId)} />)
+    expect(view.container.querySelector('[data-sample="bash-global"]')).not.toBeNull()
   })
 
-  it('childSessionScope matches sub-sessions via the injected list read face', () => {
-    const child = 'child' as SessionId
-    const root = 'root' as SessionId
-    const scope = childSessionScope({
-      getSnapshot: () => ({
-        ids: [root, child],
-        current: undefined,
-        byId: {
-          [root]: { id: root, title: 'r', running: false, updatedAt: 0 },
-          [child]: { id: child, title: 'c', parentId: root, running: false, updatedAt: 0 },
-        },
-      }),
+  it('a live parentId write flips the row to the scoped variant (store subscription)', () => {
+    const store = listStore()
+    const orphan = 'late-child' as SessionId
+    store.update((d) => {
+      d.ids.push(orphan)
+      d.byId[orphan] = { id: orphan, title: 'l', displayTitle: 'l', running: false, updatedAt: 0 }
     })
-    expect(scope(child)).toBe(true)
-    expect(scope(root)).toBe(false)
-    expect(scope('gone' as SessionId)).toBe(false)
+    const view = render(<BashRow {...rowProps(orphan, { store })} />)
+    expect(view.container.querySelector('[data-sample="bash-global"]')).not.toBeNull()
+    act(() => {
+      store.update((d) => { d.byId[orphan]!.parentId = ROOT })
+    })
+    expect(view.container.querySelector('[data-sample="bash-scoped"]')).not.toBeNull()
   })
 
-  it('sample rows summarize the command and hand clicks to openDetails', () => {
-    const open = vi.fn()
-    const p = viewProps(open)
-    const global = render(<BashRow {...p} />)
-    expect(global.getByText('Build')).toBeTruthy()
-    fireEvent.click(global.getByText('Build'))
-    expect(open).toHaveBeenCalledTimes(1)
-    const scoped = render(<ScopedBashRow {...p} />)
-    expect(scoped.getByText('scoped')).toBeTruthy()
+  it('summarizes the command and hands clicks to openDetails on both arms', () => {
+    const openGlobal = vi.fn()
+    const global = render(<BashRow {...rowProps(ROOT, { openDetails: openGlobal })} />)
+    // Two renders share document.body: query inside each container.
+    const globalRow = global.container.querySelector('[data-sample="bash-global"]')!
+    expect(globalRow.textContent).toContain('Build')
+    fireEvent.click(globalRow)
+    expect(openGlobal).toHaveBeenCalledTimes(1)
+    const openScoped = vi.fn()
+    const scoped = render(<BashRow {...rowProps(CHILD, { openDetails: openScoped })} />)
+    const scopedRow = scoped.container.querySelector('[data-sample="bash-scoped"]')!
+    expect(scopedRow.textContent).toContain('Build')
+    fireEvent.click(scopedRow)
+    expect(openScoped).toHaveBeenCalledTimes(1)
   })
 })
diff --git a/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx b/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
index f8a74adeef..a221a4028b 100644
--- a/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
@@ -4,21 +4,21 @@ import { cleanup, fireEvent, render } from '@testing-library/react'
 
 afterEach(cleanup)
 import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
-import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
 import { classifyTool, 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 } from '../src/client/chat/GenericToolCard.tsx'
-import type { ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ToolRowOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}',
-  turn: 1, step: 1, callView: null, ...over,
+  turn: 1, step: 1, time: 1_000, callView: null, ...over,
 })
 
 const result = (over?: Partial<ToolResultNode>): ToolResultNode => ({
-  kind: 'tool-result', seq: 10, callId: 'c1',
+  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,
 })
 
@@ -139,11 +139,8 @@ describe('ThinkRow', () => {
 })
 
 describe('GenericToolCard', () => {
-  const props = (toolName: string, block: RunningToolCall | ToolResultNode): ToolViewProps => ({
-    callId: 'c1', toolName, block,
-    useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
-    actions: { openDetails: vi.fn() },
-    t: (k) => k,
+  const props = (toolName: string, block: RunningToolCall | ToolResultNode): ToolRowOwnerProps => ({
+    callId: 'c1', toolName, block, openDetails: vi.fn(),
   })
 
   it('renders the classified variant row from the frozen slice', () => {
@@ -188,10 +185,10 @@ describe('GenericToolCard', () => {
     expect(view.container.querySelector('svg')).not.toBeNull()
   })
 
-  it('row click reaches actions.openDetails', () => {
+  it('row click reaches openDetails', () => {
     const p = props('bash', result())
     const view = render(<GenericToolCard {...p} />)
     fireEvent.click(view.getByText('List files'))
-    expect(p.actions.openDetails).toHaveBeenCalledTimes(1)
+    expect(p.openDetails).toHaveBeenCalledTimes(1)
   })
 })
diff --git a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx b/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
new file mode 100644
index 0000000000..5d2b3408a2
--- /dev/null
+++ b/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
@@ -0,0 +1,233 @@
+// @vitest-environment jsdom
+// The dissolved tool ring's acceptance chain on the REAL machinery stack:
+// 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
+// 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
+// (sessionId) => I into row components, and a registrant's
+// inject: ['slots', 'conversation'] load-order seam suspends on real fiber
+// semantics until the service (and with it the hole declaration) is present.
+
+import { Context } from 'cordis'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ConversationSnapshot, SessionId, SessionListState, ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
+import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const SID = 's1' as SessionId
+
+afterEach(cleanup)
+// The chat store persists under its declared key; clear between cases.
+beforeEach(() => {
+  localStorage.clear()
+})
+
+const toolResult = (seq: number, callId: string, name: string, args = '{"command":"make build","description":"Build"}'): ToolResultNode => ({
+  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,
+})
+
+function snapshotWith(nodes: ToolResultNode[]): ConversationSnapshot {
+  return {
+    sessionId: SID, nodes, foldDegraded: false, partial: null, runningCalls: [],
+    pending: [], running: false, removed: false, openState: 'open', openError: null,
+    hasMore: false, loadingOlder: false, promptError: null, lastAgentError: null,
+  } as ConversationSnapshot
+}
+
+/** Test-owned AppFrame role: declares the layout-owned children and renders the conversation area under the framework session provider. */
+type AppRootProps = PropsRenderSlots<'conversation' | 'details' | 'conversation.empty'>
+function AppRoot({ renderSlot, SessionProvider }: AppRootProps) {
+  return <SessionProvider>{() => renderSlot('conversation', {})}</SessionProvider>
+}
+
+/**
+ * Real-stack bench: SlotsService plugin, renderer installed, sessions/layout
+ * fakes at the service seams only (external boundaries), the package apply on
+ * its own fiber, and the test AppFrame occupying 'root'.
+ */
+async function bench(nodes: ToolResultNode[]) {
+  const ctx = new Context()
+  const slotsFiber = ctx.plugin(SlotsService)
+  await slotsFiber.await()
+  const slots = ctx.get('slots') as SlotsService
+
+  const session = createSnapshotStore<ConversationSnapshot>(snapshotWith(nodes))
+  const list = createSnapshotStore<SessionListState>({
+    ids: [SID],
+    byId: { [SID]: { id: SID, title: 'S', running: false, updatedAt: 1 } },
+    current: SID,
+  } as SessionListState)
+  // Identity-stable cell: the renderer caches hooks per source and inject
+  // results per cell, both by object identity.
+  const cell = { sessionId: SID, session }
+  const scoped = { send: vi.fn(async () => {}), cancel: vi.fn(async () => {}) }
+  const layout = { openDetails: vi.fn(), closeDetails: vi.fn() }
+  ctx.provide('sessions', {
+    list,
+    manager: { get: () => ({ loadOlder: vi.fn() }) },
+    scope: () => ({ get: () => scoped }),
+    cell: (id: string) => (id === SID ? cell : undefined),
+    create: vi.fn(),
+    open: vi.fn(),
+  })
+  ctx.provide('layout', layout)
+  ctx.provide('i18n', { bind: () => (key: string) => key })
+
+  slots.install(createSlotRenderer())
+  slots.register({
+    name: 'root',
+    children: {
+      'conversation': { kind: 'single', scope: 'session' },
+      'details': { kind: 'single', scope: 'session' },
+      'conversation.empty': { kind: 'single', scope: 'root' },
+    },
+  }, AppRoot)
+
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  await fiber.await()
+  return { ctx, slots, fiber, session, list, layout }
+}
+
+/** Render the whole tree through the ctx-level root seam (the shell's own entry). */
+function mountApp(slots: SlotsService) {
+  return render(<>{slots.renderSlot('root', {})}</>)
+}
+
+describe('keyed toolview hole through the real machinery', () => {
+  it('dispatches registered rows by entryKey and unregistered tools to the GenericToolCard fallback', async () => {
+    const b = await bench([
+      toolResult(3, 'c1', 'bash'),
+      toolResult(4, 'c2', 'mystery', '{"n":1}'),
+    ])
+    const view = mountApp(b.slots)
+    // bash: the sample plugin's keyed registration took the row (root
+    // session → global arm, decided inside the component off useSessions).
+    expect(view.container.querySelector('[data-sample="bash-global"]')).not.toBeNull()
+    expect(view.getByText('Build')).toBeTruthy()
+    // mystery: no registration under that key → render-site fallback.
+    expect(view.getByText('Tool call')).toBeTruthy()
+  })
+
+  it('row clicks travel owner openDetails → chat inject → layout orchestration', async () => {
+    const b = await bench([toolResult(3, 'c1', 'bash')])
+    const view = mountApp(b.slots)
+    view.getByText('Build').click()
+    expect(b.layout.openDetails).toHaveBeenCalledTimes(1)
+  })
+
+  it('a live keyed registration takes over its tool row and unload reverts to the fallback', async () => {
+    const b = await bench([toolResult(3, 'c2', 'mystery', '{"n":1}')])
+    const view = mountApp(b.slots)
+    expect(view.getByText('Tool call')).toBeTruthy()
+    let dispose = (): void => {}
+    await act(async () => {
+      dispose = b.slots.register(
+        { name: 'conversation.chat.toolview', key: 'mystery' },
+        () => <div data-testid="mystery-row" />)
+    })
+    // Per-key version tick: the row flipped without a remount of the view.
+    expect(view.getByTestId('mystery-row')).toBeTruthy()
+    expect(view.queryByText('Tool call')).toBeNull()
+    await act(async () => { dispose() })
+    expect(view.queryByTestId('mystery-row')).toBeNull()
+    expect(view.getByText('Tool call')).toBeTruthy()
+  })
+
+  it('a duplicate key registration fails loud at load', async () => {
+    const b = await bench([])
+    // The bash sample already holds the 'bash' key (later-wins retired with
+    // the ring — the keyed ledger throws instead).
+    expect(() => b.slots.register(
+      { name: 'conversation.chat.toolview', key: 'bash' },
+      () => null,
+    )).toThrow(/key "bash"/)
+  })
+
+  it('the inject channel feeds (sessionId) => I into the row component', async () => {
+    const b = await bench([toolResult(3, 'c3', 'probe', '{"x":1}')])
+    const poked: string[] = []
+    b.slots.register({
+      name: 'conversation.chat.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.
+      inject: (sessionId: SessionId) => ({
+        mark: `for:${sessionId}`,
+        poke: () => { poked.push(sessionId) },
+      }),
+    }, ({ mark, poke }: ToolRowProps & { mark: string; poke: () => void }) => (
+      <button data-testid="probe-row" onClick={poke}>{mark}</button>
+    ))
+    const view = mountApp(b.slots)
+    const row = view.getByTestId('probe-row')
+    expect(row.textContent).toBe(`for:${SID}`)
+    row.click()
+    expect(poked).toEqual([SID])
+  })
+})
+
+describe('registrant load-order seam', () => {
+  it("suspends a registrant on inject: ['slots', 'conversation'] until the service (and the hole) exists", async () => {
+    const ctx = new Context()
+    const slotsFiber = ctx.plugin(SlotsService)
+    await slotsFiber.await()
+    const slots = ctx.get('slots') as SlotsService
+    ctx.provide('sessions', {
+      list: createSnapshotStore<SessionListState>({ ids: [], byId: {}, current: undefined } as SessionListState),
+      manager: { get: vi.fn() },
+      scope: () => undefined,
+      cell: () => undefined,
+      create: vi.fn(),
+      open: vi.fn(),
+    })
+    ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+    ctx.provide('i18n', { bind: () => (key: string) => key })
+    slots.register({
+      name: 'root',
+      children: {
+        'conversation': { kind: 'single', scope: 'session' },
+        'details': { kind: 'single', scope: 'session' },
+        'conversation.empty': { kind: 'single', scope: 'root' },
+      },
+    }, AppRoot)
+
+    // Third-party posture, mounted BEFORE ui-conversation: real fiber inject
+    // semantics hold it — apply must not run while 'conversation' is absent.
+    // (Plain arrow, not vi.fn: mock functions carry a prototype and trip the
+    // fiber's isConstructor branch.)
+    let applyRuns = 0
+    const registrantApply = (registrantCtx: Context): void => {
+      applyRuns += 1
+      registrantCtx.slots.register(
+        { name: 'conversation.chat.toolview', key: 'late' }, () => null)
+    }
+    const late = ctx.plugin({
+      name: 'late-registrant',
+      inject: ['slots', 'conversation'],
+      apply: registrantApply,
+    })
+    await Promise.resolve()
+    expect(applyRuns).toBe(0)
+
+    // Mounting the package resolves the seam: service present ⟹ the chat
+    // entry (and its hole declaration) is already on the ledger, so the
+    // suspended registrant lands without an undeclared-slot throw.
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    await late.await()
+    expect(applyRuns).toBe(1)
+    expect(slots.entries('conversation.chat.toolview').map(e => e.options.key))
+      .toEqual(expect.arrayContaining(['bash', 'late']))
+  })
+})
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 3bbef02fe8..3f1db55199 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -7,14 +7,14 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Profiler } from 'react'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import type {
-  AssistantMessageNode, ConversationNode, ConversationSnapshot, RunningToolCall, SessionId, ToolResultNode, UserMessageNode,
+  AssistantMessageNode, ConversationNode, ConversationSnapshot, RunningToolCall, SessionId, SessionListState, ToolResultNode, UserMessageNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
-import { hookOf } from './hook.ts'
-import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ConvViewProps, SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/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 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { createChatStore } from '../src/client/stores.ts'
-import { createChatView } from '../src/client/chat/ChatView.tsx'
+import { ChatView } from '../src/client/chat/ChatView.tsx'
 import { deriveChatFlow, flowKeys } from '../src/client/chat/chat-flow.ts'
 
 afterEach(cleanup)
@@ -54,37 +54,56 @@ function makeSource(init?: Partial<ConversationSnapshot>) {
 }
 
 const user = (seq: number, text: string): UserMessageNode => ({
-  kind: 'user', seq, content: [{ type: 'text', text }] as never, source: null,
+  kind: 'user', seq, time: seq * 1_000, content: [{ type: 'text', text }] as never, source: null,
 })
 const assistant = (seq: number, text: string): AssistantMessageNode => ({
-  kind: 'assistant', seq, turn: 1, step: 1, blocks: [{ kind: 'text', text }],
+  kind: 'assistant', seq, time: seq * 1_000, turn: 1, step: 1, blocks: [{ kind: 'text', text }],
 })
 const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({
-  kind: 'tool-result', seq, callId,
+  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 runningCall = (callId: string, name = 'bash'): RunningToolCall => ({
-  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, callView: null,
+  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, time: 1_000, callView: null,
 })
 
+/** Empty sessions-list hook stub (the global standard-kit seat; engines carry no hook since the store migration — bind here). */
+function emptySessions() {
+  const store = createSnapshotStore<SessionListState>(
+    { ids: [], byId: {}, current: undefined } as SessionListState)
+  return bindSnapshotSelector(store)
+}
+
 function makeHarness(init?: Partial<ConversationSnapshot>) {
   const { set, source } = makeSource(init)
-  const registry = new ToolViewRegistry()
-  const ChatView = createChatView({ toolviews: registry, t: (k) => k })
   const openDetails = vi.fn<(t: SelectionTarget) => void>()
   const loadOlder = vi.fn()
   // Selection rides the REAL chat store (same construction path as
-  // production; the view reads it through the ConvViewProps useStore share).
+  // 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 props: ConvViewProps = {
+  const renderSlot = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
+    opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlot']
+  // 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)}</>
+  const props: ChatViewSlotProps = {
     sessionId: SID,
-    useSession: hookOf(source) as unknown as UseSession,
-    useStore: hookOf(chat),
-    actions: { openDetails, loadOlder },
+    useSession: bindSnapshotSelector(source),
+    useSessions: emptySessions(),
+    useStore: bindSnapshotSelector(chat),
+    actions: chat.actions,
+    renderSlot,
+    SessionProvider: SessionProviderStub,
+    openDetails,
+    loadOlder,
   }
   const setSelection = (next: SelectionTarget | null): void => { chat.actions.select(next) }
-  return { set, registry, ChatView, props, openDetails, loadOlder, setSelection }
+  return { set, ChatView, props, openDetails, loadOlder, setSelection }
 }
 
 describe('chat-flow derivation', () => {
@@ -140,6 +159,44 @@ describe('ChatView', () => {
     expect(view.getByText('run a')).toBeTruthy()
   })
 
+  it('renders assistant Markdown across history, streaming, final, and interrupted states while user text stays literal', () => {
+    const markdown = '# Rendered\n\n- **one**\n- `two`'
+    const h = makeHarness({ nodes: [user(1, markdown), assistant(2, markdown)] })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.container.querySelectorAll('h1')).toHaveLength(1)
+    const literal = view.getByText((_content, element) => (
+      element?.tagName === 'DIV' && element.childElementCount === 0 && element.textContent === markdown
+    ))
+    expect(literal.querySelector('h1')).toBeNull()
+
+    act(() => {
+      h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: markdown }] } })
+    })
+    expect(view.container.querySelectorAll('h1')).toHaveLength(2)
+    expect(view.container.querySelector('[data-streaming="true"] h1')?.textContent).toBe('Rendered')
+
+    act(() => {
+      h.set({
+        nodes: [user(1, markdown), assistant(2, markdown), assistant(3, markdown)],
+        partial: null,
+      })
+    })
+    expect(view.container.querySelectorAll('h1')).toHaveLength(2)
+    expect(view.container.querySelector('[data-streaming="true"]')).toBeNull()
+
+    act(() => {
+      h.set({
+        nodes: [
+          user(1, markdown),
+          assistant(2, markdown),
+          { ...assistant(3, markdown), interrupted: true },
+        ],
+      })
+    })
+    expect(view.getByText('已停止')).toBeTruthy()
+    expect(view.container.querySelectorAll('h1')).toHaveLength(2)
+  })
+
   it('streaming partial frames re-render only the tail (Profiler count)', () => {
     const h = makeHarness({
       nodes: [user(1, 'q'), assistant(2, 'old answer'), toolResult(3, 'a')],
@@ -169,11 +226,13 @@ describe('ChatView', () => {
     const h = makeHarness({
       nodes: [user(1, 'q'), assistant(2, 'old'), toolResult(3, 'a')],
     })
+    // 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.registry.register('bash', () => {
+    h.props.renderSlot = (((_key: string, _owner: object) => {
       rowRenders += 1
       return <div data-testid="counting-row" />
-    })
+    }) as unknown as ChatViewSlotProps['renderSlot'])
     const view = render(<h.ChatView {...h.props} />)
     expect(view.getByTestId('counting-row')).toBeTruthy()
     const afterMount = rowRenders
@@ -211,21 +270,19 @@ describe('ChatView', () => {
     expect(view.getByText('cmd-r1')).toBeTruthy()
   })
 
-  it('a scoped toolview registration takes over rendering for its session only', () => {
+  it('dispatches each tool row through the keyed slot with the tool name as entryKey', () => {
     const h = makeHarness({ nodes: [toolResult(3, 'a')] })
-    h.registry.register('bash', () => <div data-testid="custom-bash" />, { scope: (id) => id === SID })
-    const view = render(<h.ChatView {...h.props} />)
-    expect(view.getByTestId('custom-bash')).toBeTruthy()
-  })
-
-  it('unregistering a toolview falls back to the generic row live', () => {
-    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
-    const off = h.registry.register('bash', () => <div data-testid="custom-bash" />)
-    const view = render(<h.ChatView {...h.props} />)
-    expect(view.getByTestId('custom-bash')).toBeTruthy()
-    act(() => off())
-    expect(view.queryByTestId('custom-bash')).toBeNull()
-    expect(view.getByText('Bash')).toBeTruthy()
+    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 } : {}) })
+      return opts?.fallback ?? null
+    }) as unknown as ChatViewSlotProps['renderSlot'])
+    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' }])
   })
 
   it('prepend compensates scrollTop by the height delta; a trailing user node force-scrolls', () => {
@@ -287,7 +344,8 @@ describe('ChatView', () => {
 
   it('pending interactions render placeholder cards', () => {
     const h = makeHarness({
-      pending: [{ kind: 'approval', rpcId: 'r1' as never, approvalId: 'ap1', toolName: 'bash' }],
+      pending: [new PendingWait('approval', RpcId('r1'), SID,
+        { approvalId: 'ap1', toolName: 'bash' } as PendingWait<'approval'>['payload'], vi.fn())],
     })
     const view = render(<h.ChatView {...h.props} />)
     expect(view.getByText(/等待审批/)).toBeTruthy()
diff --git a/packages/client/ui-conversation/tests/coverage-tails.spec.tsx b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
index ee69156729..66ae3e802c 100644
--- a/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
@@ -1,23 +1,22 @@
 // @vitest-environment jsdom
 // Branch tails the acceptance specs do not reach: ToolRow stopped-state dot,
-// PendingCard question arm, bash sample error pill, registry disposer
-// idempotence re-entry, register.ts explicit bashSampleScope override, the
-// node-half empty apply, and AssistantMarkdown reasoning/unknown block arms.
+// PendingCard question arm, bash sample error pill, the node-half empty
+// apply, and AssistantMarkdown reasoning/unknown block arms.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
-import type { ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
-import type { RpcId } from '@deepseek-ai/dsh-client-connection/client'
-import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
-import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type { ConversationService, Translate, ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionListState, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import { PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
+import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import type { ToolRowOwnerProps, ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as nodeApply } from '../src/index.ts'
 import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx'
 import { ToolRow } from '../src/client/chat/ToolRow.tsx'
 import { PendingCard } from '../src/client/chat/PendingCard.tsx'
 import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
 import { BashRow } from '../src/client/toolviews/bash-sample.tsx'
-import { registerChat } from '../src/client/chat/register.ts'
 
 afterEach(cleanup)
 
@@ -36,7 +35,7 @@ describe('tails', () => {
 
   it('PendingCard renders the question arm with its count', () => {
     const view = render(
-      <PendingCard item={{ kind: 'question', rpcId: 'r1' as RpcId, questions: [{}, {}] }} />,
+      <PendingCard item={new PendingWait('question', RpcId('r1'), 's1' as SessionId, { questions: [{}, {}] } as PendingWait<'question'>['payload'], vi.fn())} />,
     )
     expect(view.getByText(/等待回答（2 题）/)).toBeTruthy()
   })
@@ -63,15 +62,13 @@ describe('tails', () => {
 
   it('a settled others-variant row renders the sparkle icon in the leading slot', () => {
     const settled: ToolResultNode = {
-      kind: 'tool-result', seq: 2, callId: 'c5',
+      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: ToolViewProps = {
-      callId: 'c5', toolName: 'todo_write', block: settled,
-      useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
-      actions: { openDetails: vi.fn() },
-      t: ((k: string) => k) as Translate,
+    const props: ToolRowOwnerProps = {
+      callId: 'c5', toolName: 'todo_write', block: settled, openDetails: vi.fn(),
     }
     const view = render(<GenericToolCard {...props} />)
     // Settled ok state keeps the variant icon (sparkle) instead of a StateDot.
@@ -79,49 +76,26 @@ describe('tails', () => {
     expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
   })
 
-  it('BashRow shows the failed pill on error results', () => {
+  it('BashRow shows the failed pill on error results (root session arm)', () => {
     const errorResult: ToolResultNode = {
-      kind: 'tool-result', seq: 1, callId: 'c1',
+      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 props: ToolViewProps = {
-      callId: 'c1', toolName: 'bash', block: errorResult,
-      useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
-      actions: { openDetails: vi.fn() },
-      t: ((k: string) => k) as Translate,
-    }
+    // Root session (no parentId): the global arm renders, error pill visible.
+    const sid = 'root-1' as SessionId
+    const list = createSnapshotStore<SessionListState>({
+      ids: [sid],
+      byId: { [sid]: { id: sid, title: 'r', running: false, updatedAt: 0 } },
+      current: undefined,
+    } as SessionListState)
+    const props = {
+      callId: 'c1', toolName: 'bash', block: errorResult, openDetails: vi.fn(),
+      sessionId: sid, useSessions: bindSnapshotSelector(list),
+    } as unknown as ToolRowProps
     const view = render(<BashRow {...props} />)
+    expect(view.container.querySelector('[data-sample="bash-global"]')).not.toBeNull()
     expect(view.getByText('failed')).toBeTruthy()
   })
-
-  it('registry disposer re-entry is a no-op after the entry was already removed', () => {
-    const registry = new ToolViewRegistry()
-    const off = registry.register('bash', (() => null) as never)
-    const v1 = registry.getVersion()
-    off()
-    const v2 = registry.getVersion()
-    off()
-    expect(registry.getVersion()).toBe(v2)
-    expect(v2).toBeGreaterThan(v1)
-  })
-
-  it('registerChat registers the chat view with the stats footer and disposes cleanly', () => {
-    const disposer = vi.fn()
-    const calls: unknown[] = []
-    const conversation = {
-      registerView: (entry: unknown) => {
-        calls.push(entry)
-        return disposer
-      },
-    } as unknown as ConversationService
-    const toolviews = new ToolViewRegistry()
-    const off = registerChat({ conversation, toolviews, t: ((k: string) => k) as Translate })
-    const entry = calls[0] as { id: string; chrome?: { footer?: unknown } }
-    expect(entry.id).toBe('chat')
-    // footer is a memo exotic component (object, not plain function).
-    expect(entry.chrome?.footer).toBeDefined()
-    off()
-    expect(disposer).toHaveBeenCalledTimes(1)
-  })
 })
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 a9010828c4..c59b1c7527 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -1,18 +1,16 @@
 // @vitest-environment jsdom
-// Final branch tails for the coverage gate, terminal slot form: apply's
-// need() throw, AssistantMarkdown non-final reasoning, StatsLine usage-less
-// node, DetailsPanel titleless selection, registry disposer after a foreign
-// removal emptied the list. (The old cwd WeakMap-cache account retired with
-// the mechanism — derivation lives in EmptyState now, covered by the
-// skeleton specs.)
+// Final branch tails for the coverage gate, terminal slot form:
+// AssistantMarkdown non-final reasoning, StatsLine usage-less node,
+// DetailsPanel titleless selection. (The old cwd WeakMap-cache account
+// retired with the mechanism — derivation lives in EmptyState now, covered
+// by the skeleton specs.)
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
-import { hookOf } from './hook.ts'
+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-ui-slots'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
 import type { ConversationSnapshot, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
-import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { createChatStore } from '../src/client/stores.ts'
 import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
@@ -54,7 +52,7 @@ describe('render branch tails', () => {
     }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
-      <StatsLine sessionId={SID} useSession={hookOf(source) as unknown as UseSession<ConversationSnapshot>} />,
+      <StatsLine useSession={bindSnapshotSelector(source) as unknown as UseSession<ConversationSnapshot>} />,
     )
     expect(view.getByText('cache hit 0% · 15 tokens · 2 turns · 3 steps')).toBeTruthy()
   })
@@ -76,9 +74,9 @@ describe('render branch tails', () => {
     const view = render(
       <DetailsPanel
         sessionId={SID}
-        useSession={hookOf({ getSnapshot: () => snap, subscribe: () => () => {} }) as unknown as UseSession<ConversationSnapshot>}
-        useSessions={hookOf(emptyList)}
-        useStore={hookOf(chat)}
+        useSession={bindSnapshotSelector({ getSnapshot: () => snap, subscribe: () => () => {} }) as unknown as UseSession<ConversationSnapshot>}
+        useSessions={bindSnapshotSelector(emptyList)}
+        useStore={bindSnapshotSelector(chat)}
         actions={chat.actions}
         closeDetails={vi.fn()}
       />,
@@ -86,15 +84,4 @@ describe('render branch tails', () => {
     expect(view.getByText('详情')).toBeTruthy()
     expect(view.getByText('该调用不在当前窗口内')).toBeTruthy()
   })
-
-  it('registry disposer tolerates the list already emptied by a sibling disposer', () => {
-    const registry = new ToolViewRegistry()
-    const offA = registry.register('bash', () => null)
-    const offB = registry.register('bash', () => null)
-    offA()
-    offB()
-    // Both entries gone; a re-register works from a fresh list.
-    registry.register('bash', () => null)
-    expect(registry.resolve('bash', SID)).toBeDefined()
-  })
 })
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index 660127946b..6bf58f7d59 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -19,7 +19,10 @@ function setup(over?: Partial<InputBarProps>) {
   }
   const view = render(<InputBar {...props} />)
   const textarea = view.container.querySelector('textarea')!
-  const button = view.container.querySelector('button')!
+  // aria-label (not role name): title also contains 发送/停止 and would double-match.
+  const button = view.container.querySelector<HTMLButtonElement>(
+    `button[aria-label="${over?.running === true ? '停止' : '发送'}"]`,
+  )!
   return { view, textarea, button, props }
 }
 
@@ -97,7 +100,7 @@ describe('running lock and primary button', () => {
     const textarea = view.container.querySelector('textarea')!
     expect(document.activeElement).toBe(textarea)
     textarea.blur()
-    fireEvent.mouseDown(view.container.querySelector('button')!)
+    fireEvent.mouseDown(view.container.querySelector('button[aria-label="发送"]')!)
     expect(document.activeElement).toBe(textarea)
   })
 
@@ -129,3 +132,38 @@ describe('error strip and variants', () => {
     expect(view.container.querySelector('[class*="hero"]')).not.toBeNull()
   })
 })
+
+describe('placeholder chrome', () => {
+  it('renders attach / Plan / Read-only / model controls', () => {
+    const { view } = setup()
+    expect(view.getByLabelText('添加')).toBeTruthy()
+    expect((view.getByLabelText('Plan mode') as HTMLSelectElement).value).toBe('plan')
+    expect((view.getByLabelText('Access mode') as HTMLSelectElement).value).toBe('readonly')
+    expect((view.getByLabelText('Model') as HTMLSelectElement).value).toBe('v4-pro-high')
+  })
+
+  it('native select change updates the selected option', () => {
+    const { view } = setup()
+    const plan = view.getByLabelText('Plan mode') as HTMLSelectElement
+    fireEvent.change(plan, { target: { value: 'agent' } })
+    expect(plan.value).toBe('agent')
+    const access = view.getByLabelText('Access mode') as HTMLSelectElement
+    fireEvent.change(access, { target: { value: 'readwrite' } })
+    expect(access.value).toBe('readwrite')
+  })
+
+  it('model select can drop the High option', () => {
+    const { view } = setup()
+    const model = view.getByLabelText('Model') as HTMLSelectElement
+    fireEvent.change(model, { target: { value: 'v4-pro' } })
+    expect(model.value).toBe('v4-pro')
+    expect(model.selectedOptions[0]?.textContent).toBe('DeepSeek-V4-Pro')
+  })
+
+  it('running locks the chrome selects and attach control', () => {
+    const { view } = setup({ running: true })
+    expect((view.getByLabelText('添加') as HTMLButtonElement).disabled).toBe(true)
+    expect((view.getByLabelText('Plan mode') as HTMLSelectElement).disabled).toBe(true)
+    expect((view.getByLabelText('Model') as HTMLSelectElement).disabled).toBe(true)
+  })
+})
diff --git a/packages/client/ui-conversation/tests/selection-survival.spec.ts b/packages/client/ui-conversation/tests/selection-survival.spec.ts
index a637b4fa18..3937416030 100644
--- a/packages/client/ui-conversation/tests/selection-survival.spec.ts
+++ b/packages/client/ui-conversation/tests/selection-survival.spec.ts
@@ -123,23 +123,25 @@ describe('selection survives on the store seat', () => {
     expect(two.store.getSnapshot().selection).toEqual({ turnSeq: 9, callId: 'z' })
   })
 
-  it('a title-upgrading list refresh keeps instance identity and the selection value', async () => {
+  it('a display-title-upgrading list refresh keeps instance identity and the selection value', async () => {
     const b = bench()
     // First-send shape: client-side create inserts the row without cwd (title = bare id).
     b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('s1') }))
     const id = await b.sessions.create({})
     await flush()
-    expect(b.sessions.list.getSnapshot().byId[id]?.title).toBe('s1')
+    expect(b.sessions.list.getSnapshot().byId[id]).toMatchObject({ displayTitle: 's1' })
+    expect(b.sessions.list.getSnapshot().byId[id]?.title).toBeUndefined()
 
     const store = storeFor(b, 'conversation', id)
     store.actions.select({ turnSeq: 3, callId: 'c1' })
     store.actions.setDraft('half-typed')
 
-    // The late list refresh lands (host knows the cwd → formal title).
+    // The late list refresh lands (host knows the cwd → better fallback label).
     feed(b, [{ id: 's1', cwd: '/w/proj-a' }])
     await b.sessions.manager.refreshList()
     await flush()
-    expect(b.sessions.list.getSnapshot().byId[id]?.title).toBe('proj-a')
+    expect(b.sessions.list.getSnapshot().byId[id]).toMatchObject({ displayTitle: 'proj-a' })
+    expect(b.sessions.list.getSnapshot().byId[id]?.title).toBeUndefined()
 
     const after = storeFor(b, 'conversation', id)
     expect(after).toBe(store)
diff --git a/packages/client/ui-conversation/tests/service-orchestration.spec.ts b/packages/client/ui-conversation/tests/service-orchestration.spec.ts
index 8b8f4f0dff..2d3be81a4d 100644
--- a/packages/client/ui-conversation/tests/service-orchestration.spec.ts
+++ b/packages/client/ui-conversation/tests/service-orchestration.spec.ts
@@ -2,9 +2,10 @@
 /**
  * ConversationService orchestration half after the store-seat slimming:
  * scope-addressed send/cancel (result folding, root throw), the startSession
- * chain (create → sessions.open → scoped send), views ordering, and the
- * service-unavailable loud failures. Selection/draft state left this service
- * for the declared chat store (chat-store.spec.ts / selection-survival.spec.ts).
+ * chain (create → sessions.open → scoped send), and the service-unavailable
+ * loud failures. Selection/draft state left this service for the declared
+ * chat store (chat-store.spec.ts / selection-survival.spec.ts); the view
+ * registry left for the 'conversation.view' slot (views-type-chain.spec.tsx).
  */
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
@@ -66,9 +67,11 @@ async function bench(opts?: { sessions?: boolean }) {
     create: createMock,
     open: openMock,
     scope: (id: SessionId) => (id === sid('new-1') ? mint(id) : scopes.get(id)),
+    scopeOf,
   } as unknown as SessionsService
   if (opts?.sessions !== false) ctx.provide('sessions', sessionsFake)
-  const fiber = ctx.plugin((pluginCtx) => { void new ConversationService(pluginCtx) })
+  // Class-plugin mount — the same form apply.ts uses in production.
+  const fiber = ctx.plugin(ConversationService)
   await fiber.await()
   const svc = ctx.get('conversation') as ConversationService
   const scopedSvc = (id: SessionId) => mint(id).get('conversation') as ConversationService
@@ -149,17 +152,3 @@ describe('service-unavailable loud failures', () => {
       .rejects.toThrow(/conversation service unavailable through the new scope/)
   })
 })
-
-describe('views ordering', () => {
-  it('orders by explicit order with undefined treated as zero (both comparator arms)', async () => {
-    const b = await bench()
-    const entry = (id: string, order?: number) => ({
-      id, label: id, component: () => null,
-      ...(order !== undefined ? { order } : {}),
-    })
-    b.svc.registerView(entry('z-late', 5) as never)
-    b.svc.registerView(entry('default-zero') as never)
-    b.svc.registerView(entry('first', -1) as never)
-    expect(b.svc.views().map(v => v.id)).toEqual(['first', 'default-zero', 'z-late'])
-  })
-})
diff --git a/packages/client/ui-conversation/tests/skeleton-branches.spec.tsx b/packages/client/ui-conversation/tests/skeleton-branches.spec.tsx
index 52d89d2b19..4eb70ea39f 100644
--- a/packages/client/ui-conversation/tests/skeleton-branches.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton-branches.spec.tsx
@@ -3,7 +3,7 @@
 // acceptance flows), four-share props form: breadcrumb ancestry derivation +
 // error strip in ConversationRoot, DetailsPanel non-JSON args / non-text
 // result blocks / error-only results over the shared store, EmptyState
-// failure surface and custom-directory swap with in-component cwd derivation.
+// failure surface and path-modal confirm with in-component cwd derivation.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, waitFor } from '@testing-library/react'
@@ -11,16 +11,19 @@ import { hookOf } from './hook.ts'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ConversationSnapshot, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SelectionTarget, ViewEntry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SelectionTarget, ViewTab } from '@deepseek-ai/dsh-client-ui-conversation/client'
 // Export discipline: packages/client/AGENTS.md.
 import { createChatStore } from '../src/client/stores.ts'
-import { ConversationRoot } from '../src/client/skeleton/ConversationRoot.tsx'
+import { ConversationRoot, type ConversationRootProps } from '../src/client/skeleton/ConversationRoot.tsx'
 import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
 import { EmptyState } from '../src/client/skeleton/EmptyState.tsx'
 
 afterEach(cleanup)
 
 const SID = 's1' as SessionId
+/** Fallback-only chain stub (no takeover registered in these benches). */
+const fallbackRenderSlotChain: ConversationRootProps['renderSlotChain'] =
+  (_key, _owner, opts) => opts?.fallback ?? null
 
 function snapshotBase(): ConversationSnapshot {
   return {
@@ -43,7 +46,7 @@ function listHook(rows: { id: string; title: string; cwd?: string; parentId?: st
   const store = createSnapshotStore<SessionListState>({
     ids: rows.map(r => r.id as SessionId),
     byId: Object.fromEntries(rows.map(r => [r.id, {
-      id: r.id as SessionId, title: r.title, running: false, updatedAt: 1,
+      id: r.id as SessionId, title: `durable ${r.title}`, displayTitle: r.title, running: false, updatedAt: 1,
       ...(r.cwd !== undefined ? { cwd: r.cwd } : {}),
       ...(r.parentId !== undefined ? { parentId: r.parentId as SessionId } : {}),
     }])),
@@ -53,9 +56,11 @@ function listHook(rows: { id: string; title: string; cwd?: string; parentId?: st
 }
 
 describe('ConversationRoot branches', () => {
-  const chatEntry: ViewEntry = {
-    id: 'chat', label: 'Chat', component: () => <div data-testid="view-body" />,
-  } as unknown as ViewEntry
+  const chatTab: ViewTab = { id: 'chat', label: 'Chat' }
+  /** renderSlot stub in the outlet's baked shape (ring key + only filter marker). */
+  const stubRenderSlot = (() => <div data-testid="view-body" />) as unknown as ConversationRootProps['renderSlot']
+  /** SessionProvider seat stub (render-prop pass-through; ConversationRoot never invokes it). */
+  const SessionProviderStub: ConversationRootProps['SessionProvider'] = ({ children }) => <>{children(SID)}</>
 
   function rootProps(over?: {
     rows?: { id: string; title: string; parentId?: string }[]
@@ -70,11 +75,12 @@ describe('ConversationRoot branches', () => {
         useSessions={listHook(over?.rows ?? [])}
         useStore={hookOf(chat)}
         actions={chat.actions}
-        views={{ list: () => [chatEntry], subscribe: () => () => {}, version: () => 1 }}
+        renderSlot={stubRenderSlot}
+        renderSlotChain={fallbackRenderSlotChain}
+        SessionProvider={SessionProviderStub}
+        views={{ list: () => [chatTab], subscribe: () => () => {}, version: () => 1 }}
         send={vi.fn()}
         stop={vi.fn()}
-        openDetails={vi.fn()}
-        loadOlder={vi.fn()}
         open={open}
       />,
     )
@@ -120,7 +126,7 @@ describe('ConversationRoot branches', () => {
   it('an unknown stored view id falls back to the first registered view', () => {
     const { chat } = rootProps({})
     cleanup()
-    chat.actions.setView('gone' as never)
+    chat.actions.setView('gone')
     const view = render(
       <ConversationRoot
         sessionId={SID}
@@ -128,11 +134,12 @@ describe('ConversationRoot branches', () => {
         useSessions={listHook([])}
         useStore={hookOf(chat)}
         actions={chat.actions}
-        views={{ list: () => [chatEntry], subscribe: () => () => {}, version: () => 1 }}
+        renderSlot={stubRenderSlot}
+        renderSlotChain={fallbackRenderSlotChain}
+        SessionProvider={SessionProviderStub}
+        views={{ list: () => [chatTab], subscribe: () => () => {}, version: () => 1 }}
         send={vi.fn()}
         stop={vi.fn()}
-        openDetails={vi.fn()}
-        loadOlder={vi.fn()}
         open={vi.fn()}
       />,
     )
@@ -158,7 +165,7 @@ describe('DetailsPanel branches', () => {
 
   it('shows non-JSON args verbatim (streaming fragment path)', () => {
     const view = panel({ turnSeq: 1, callId: 'c1', toolName: 'bash' }, {
-      runningCalls: [{ callId: 'c1', name: 'bash', argsRaw: '{"cmd": tru', turn: 1, step: 1, callView: null }],
+      runningCalls: [{ callId: 'c1', name: 'bash', argsRaw: '{"cmd": tru', turn: 1, step: 1, time: 1_000, callView: null }],
     })
     expect(view.getByText('{"cmd": tru')).toBeTruthy()
   })
@@ -169,7 +176,7 @@ describe('DetailsPanel branches', () => {
   })
 
   it('snapshot updates re-run the material selector through the shallow equality arm', () => {
-    let snap = { ...snapshotBase(), runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{"a":1}', turn: 1, step: 1, callView: null }] } as ConversationSnapshot
+    let snap = { ...snapshotBase(), runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{"a":1}', turn: 1, step: 1, time: 1_000, callView: null }] } as ConversationSnapshot
     const subs = new Set<() => void>()
     const source = {
       getSnapshot: () => snap,
@@ -231,10 +238,16 @@ describe('DetailsPanel branches', () => {
 })
 
 describe('EmptyState branches', () => {
+  const noopCreate = () => Promise.resolve()
+
   it('keeps the draft and surfaces a local error strip when startSession rejects', async () => {
     const startSession = vi.fn(() => Promise.reject(new Error('create down')))
     const view = render(
-      <EmptyState useSessions={listHook([{ id: 'a', title: 'a', cwd: '/proj' }])} startSession={startSession} />,
+      <EmptyState
+        useSessions={listHook([{ id: 'a', title: 'a', cwd: '/proj' }])}
+        startSession={startSession}
+        createWorkspaceSession={noopCreate}
+      />,
     )
     const textarea = view.container.querySelector('textarea')!
     fireEvent.change(textarea, { target: { value: 'first task' } })
@@ -246,7 +259,11 @@ describe('EmptyState branches', () => {
   it('non-Error rejection reasons stringify into the error strip', async () => {
     const startSession = vi.fn(() => Promise.reject('plain-string'))
     const view = render(
-      <EmptyState useSessions={listHook([])} startSession={startSession} />,
+      <EmptyState
+        useSessions={listHook([])}
+        startSession={startSession}
+        createWorkspaceSession={noopCreate}
+      />,
     )
     const textarea = view.container.querySelector('textarea')!
     fireEvent.change(textarea, { target: { value: 'go' } })
@@ -254,7 +271,7 @@ describe('EmptyState branches', () => {
     await waitFor(() => expect(view.getByText(/发送失败：plain-string/)).toBeTruthy())
   })
 
-  it('cwd derivation skips blank cwds; select picks, swaps to free-form, submits the typed path', async () => {
+  it('cwd derivation skips blank cwds; menu picks, path modal confirms, submits the typed path', async () => {
     const startSession = vi.fn(() => Promise.resolve())
     const view = render(
       <EmptyState
@@ -263,19 +280,39 @@ describe('EmptyState branches', () => {
           { id: 'b', title: 'b' }, // no cwd: filtered from the option set
         ])}
         startSession={startSession}
+        createWorkspaceSession={noopCreate}
       />,
     )
-    const select = view.container.querySelector('select')!
-    expect([...(select as HTMLSelectElement).options].map(o => o.value))
-      .toEqual(['', '/proj', '::new-directory'])
-    fireEvent.change(select, { target: { value: '/proj' } })
-    expect((select as HTMLSelectElement).value).toBe('/proj')
-    fireEvent.change(select, { target: { value: '::new-directory' } })
-    const custom = view.container.querySelector('input')!
+    fireEvent.click(view.getByRole('button', { name: '项目目录' }))
+    expect([...view.getByRole('menu').querySelectorAll('[role="menuitem"]')].map(el => el.textContent))
+      .toEqual(['proj', 'New Workspace'])
+    fireEvent.click(view.getByRole('menuitem', { name: 'proj' }))
+    expect(view.getByRole('button', { name: '项目目录' }).textContent).toContain('proj')
+    fireEvent.click(view.getByRole('button', { name: '项目目录' }))
+    fireEvent.mouseEnter(view.getByRole('menuitem', { name: 'New Workspace' }).parentElement as HTMLElement)
+    fireEvent.click(view.getByRole('menuitem', { name: 'Use a existing folder' }))
+    const custom = view.getByLabelText('Folder path')
     fireEvent.change(custom, { target: { value: '/typed/dir' } })
+    fireEvent.click(view.getByRole('button', { name: 'Open Folder' }))
     const textarea = view.container.querySelector('textarea')!
     fireEvent.change(textarea, { target: { value: 'task' } })
     fireEvent.keyDown(textarea, { key: 'Enter' })
     await waitFor(() => expect(startSession).toHaveBeenCalledWith({ text: 'task', mode: 'queue', cwd: '/typed/dir' }))
   })
+
+  it('Create modal surfaces inject failures inline', async () => {
+    const createWorkspaceSession = vi.fn(() => Promise.reject(new Error('mkdir blocked')))
+    const view = render(
+      <EmptyState
+        useSessions={listHook([])}
+        startSession={() => Promise.resolve()}
+        createWorkspaceSession={createWorkspaceSession}
+      />,
+    )
+    fireEvent.click(view.getByRole('button', { name: '项目目录' }))
+    fireEvent.mouseEnter(view.getByRole('menuitem', { name: 'New Workspace' }).parentElement as HTMLElement)
+    fireEvent.click(view.getByRole('menuitem', { name: 'Create new' }))
+    fireEvent.click(view.getByRole('button', { name: 'Create' }))
+    await waitFor(() => expect(view.getByRole('alert').textContent).toContain('mkdir blocked'))
+  })
 })
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index 75172dd207..a598803a25 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -10,12 +10,14 @@
  */
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import type { FC } from 'react'
-import { hookOf } from './hook.ts'
+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-ui-slots'
-import type { ConversationSnapshot, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SelectionTarget, ViewEntry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { ConversationSnapshot, PendingInteraction, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
+import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SelectionTarget, ViewTab } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ConversationRootProps } from '../src/client/skeleton/ConversationRoot.tsx'
 // Export discipline: packages/client/AGENTS.md.
 import { createChatStore } from '../src/client/stores.ts'
 import { ConversationRoot } from '../src/client/skeleton/ConversationRoot.tsx'
@@ -26,23 +28,44 @@ const sid = (s: string): SessionId => s as SessionId
 
 afterEach(cleanup)
 beforeEach(() => {
-  localStorage.clear()
+  // jsdom normally provides localStorage; some host Node builds surface it as undefined.
+  globalThis.localStorage?.clear()
 })
 
 /** Minimal conversation snapshot slice the skeleton reads. */
 interface FakeSnapshot {
-  nodes: readonly { kind: string; callId?: string; call?: { name: string; argsRaw: string } | null; content?: readonly { type: string; text?: string }[]; isError?: boolean }[]
-  runningCalls: readonly { callId: string; name: string; argsRaw: string }[]
+  nodes: readonly {
+    kind: string
+    seq?: number
+    time?: number
+    callId?: string
+    call?: { name: string; argsRaw: string } | null
+    callTime?: number | null
+    content?: readonly { type: string; text?: string }[]
+    isError?: boolean
+    callView?: null
+    resultView?: null
+  }[]
+  runningCalls: readonly {
+    callId: string
+    name: string
+    argsRaw: string
+    turn?: number
+    step?: number
+    time?: number
+    callView?: null
+  }[]
   running: boolean
   removed: boolean
   promptError: { op: 'send' | 'stop'; error: { message: string; code: string } } | null
+  pending: readonly PendingInteraction[]
 }
 
 function fakeSession(init: Partial<FakeSnapshot> = {}) {
   const store = createSnapshotStore<FakeSnapshot>({
-    nodes: [], runningCalls: [], running: false, removed: false, promptError: null, ...init,
+    nodes: [], runningCalls: [], running: false, removed: false, promptError: null, pending: [], ...init,
   })
-  return { store, useSession: hookOf(store) as unknown as UseSession<ConversationSnapshot> }
+  return { store, useSession: bindSnapshotSelector(store) as unknown as UseSession<ConversationSnapshot> }
 }
 
 /** Sessions-list stub: the standard useSessions hook over a snapshot store. */
@@ -50,16 +73,21 @@ function fakeSessions(rows: { id: string; title: string; cwd?: string; parentId?
   const store = createSnapshotStore<SessionListState>({
     ids: rows.map(r => sid(r.id)),
     byId: Object.fromEntries(rows.map(r => [r.id, {
-      id: sid(r.id), title: r.title, running: false, updatedAt: 1,
+      id: sid(r.id), title: `durable ${r.title}`, displayTitle: r.title, running: false, updatedAt: 1,
       ...(r.cwd !== undefined ? { cwd: r.cwd } : {}),
       ...(r.parentId !== undefined ? { parentId: sid(r.parentId) } : {}),
     }])),
     current: undefined,
   } as SessionListState)
-  return { store, useSessions: hookOf(store) }
+  return { store, useSessions: bindSnapshotSelector(store) }
 }
 
+/** SessionProvider seat stub (render-prop pass-through; ConversationRoot never invokes it). */
+const SessionProviderStub: ConversationRootProps['SessionProvider'] = ({ children }) => <>{children(sid('s1'))}</>
+
 describe('EmptyState', () => {
+  const noopCreate = () => Promise.resolve()
+
   it('derives cwd options from the sessions list, submits startSession, failure surfaces locally', async () => {
     const { useSessions } = fakeSessions([
       { id: 'a', title: 'a', cwd: '/w/app' },
@@ -68,13 +96,21 @@ describe('EmptyState', () => {
     ])
     let reject!: (e: Error) => void
     const startSession = vi.fn(() => new Promise<void>((_res, rej) => { reject = rej }))
-    render(<EmptyState useSessions={useSessions} startSession={startSession} />)
+    render(
+      <EmptyState
+        useSessions={useSessions}
+        startSession={startSession}
+        createWorkspaceSession={noopCreate}
+      />,
+    )
 
-    const select = screen.getByRole('combobox', { name: '项目目录' })
-    expect([...(select as HTMLSelectElement).options].map(o => o.value))
-      .toEqual(['', '/w/app', '/w/lib', '::new-directory'])
-    fireEvent.change(select, { target: { value: '/w/app' } })
-    const box = screen.getByPlaceholderText('Message to run task, plan and build')
+    const trigger = screen.getByRole('button', { name: '项目目录' })
+    fireEvent.click(trigger)
+    const menu = screen.getByRole('menu')
+    expect([...menu.querySelectorAll('[role="menuitem"]')].map(el => el.textContent))
+      .toEqual(['app', 'lib', 'New Workspace'])
+    fireEvent.click(screen.getByRole('menuitem', { name: 'app' }))
+    const box = screen.getByPlaceholderText('Message to run task, plan and build, enter for / commands')
     fireEvent.change(box, { target: { value: '造一个轮子' } })
     fireEvent.keyDown(box, { key: 'Enter' })
     expect(startSession).toHaveBeenCalledWith({ text: '造一个轮子', mode: 'queue', cwd: '/w/app' })
@@ -85,60 +121,114 @@ describe('EmptyState', () => {
     expect((box as HTMLTextAreaElement).value).toBe('造一个轮子')
   })
 
-  it('new-directory option swaps the select for a free-form input', () => {
+  it('Use a existing folder opens the path modal and Open Folder sets the chip', () => {
     const { useSessions } = fakeSessions([])
-    render(<EmptyState useSessions={useSessions} startSession={() => Promise.resolve()} />)
-    fireEvent.change(screen.getByRole('combobox'), { target: { value: '::new-directory' } })
-    const custom = screen.getByPlaceholderText(/目录路径/)
-    fireEvent.change(custom, { target: { value: '/tmp/fresh' } })
-    expect((custom as HTMLInputElement).value).toBe('/tmp/fresh')
+    render(
+      <EmptyState
+        useSessions={useSessions}
+        startSession={() => Promise.resolve()}
+        createWorkspaceSession={noopCreate}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: '项目目录' }))
+    const newWs = screen.getByRole('menuitem', { name: 'New Workspace' })
+    fireEvent.mouseEnter(newWs.parentElement as HTMLElement)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Use a existing folder' }))
+    expect(screen.getByRole('dialog', { name: 'Enter an existing folder path' })).toBeTruthy()
+    const path = screen.getByLabelText('Folder path') as HTMLInputElement
+    fireEvent.change(path, { target: { value: '/tmp/fresh' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Open Folder' }))
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(screen.getByRole('button', { name: '项目目录' }).textContent).toContain('fresh')
+  })
+
+  it('Create new opens the modal and createWorkspaceSession succeeds', async () => {
+    const { useSessions } = fakeSessions([])
+    const createWorkspaceSession = vi.fn(() => Promise.resolve())
+    render(
+      <EmptyState
+        useSessions={useSessions}
+        startSession={() => Promise.resolve()}
+        createWorkspaceSession={createWorkspaceSession}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: '项目目录' }))
+    fireEvent.mouseEnter(screen.getByRole('menuitem', { name: 'New Workspace' }).parentElement as HTMLElement)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Create new' }))
+    expect(screen.getByRole('dialog', { name: 'Create new workspace' })).toBeTruthy()
+    const name = screen.getByLabelText('Workspace name') as HTMLInputElement
+    expect(name.value).toBe('New WorkSpace')
+    fireEvent.change(name, { target: { value: 'My Proj' } })
+    fireEvent.keyDown(name, { key: 'Enter' })
+    await vi.waitFor(() => expect(createWorkspaceSession).toHaveBeenCalledWith('My Proj'))
+  })
+
+  it('Create modal Cancel dismisses without calling createWorkspaceSession', () => {
+    const { useSessions } = fakeSessions([])
+    const createWorkspaceSession = vi.fn(() => Promise.resolve())
+    render(
+      <EmptyState
+        useSessions={useSessions}
+        startSession={() => Promise.resolve()}
+        createWorkspaceSession={createWorkspaceSession}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: '项目目录' }))
+    fireEvent.mouseEnter(screen.getByRole('menuitem', { name: 'New Workspace' }).parentElement as HTMLElement)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Create new' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }))
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(createWorkspaceSession).not.toHaveBeenCalled()
   })
 })
 
 describe('ConversationRoot', () => {
-  function bench(views: ViewEntry[], activeView?: string) {
-    const { useSession } = fakeSession({ nodes: [{ kind: 'user' }, { kind: 'user' }] })
+  function bench(
+    tabs: ViewTab[], activeView?: string, init: Partial<FakeSnapshot> = {},
+    renderSlotChain?: ConversationRootProps['renderSlotChain'],
+  ) {
+    const { useSession } = fakeSession({ nodes: [{ kind: 'user' }, { kind: 'user' }], ...init })
     const { useSessions } = fakeSessions([
       { id: 'root', title: 'proj' },
       { id: 's1', title: 'child', parentId: 'root' },
     ])
     const chat = createChatStore().create()
-    if (activeView !== undefined) chat.actions.setView(activeView as never)
+    if (activeView !== undefined) chat.actions.setView(activeView)
     const send = vi.fn()
     const stop = vi.fn()
-    const openDetails = vi.fn()
-    const loadOlder = vi.fn()
     const open = vi.fn()
+    // The renderSlot share as the outlet would bake it: renders a marker for
+    // the ring key carrying the active-id filter (a Mock cannot satisfy the
+    // generic method type directly — cast once at the prop seam).
+    const renderSlot = vi.fn((key: string, _owner: object, opts?: { only?: string }) => (
+      <div data-testid={`view-${opts?.only ?? '(all)'}`} data-slot={key} />
+    ))
     const ui = render(
       <ConversationRoot
         sessionId={sid('s1')}
         useSession={useSession}
         useSessions={useSessions}
-        useStore={hookOf(chat)}
+        useStore={bindSnapshotSelector(chat)}
         actions={chat.actions}
+        renderSlot={renderSlot as unknown as ConversationRootProps['renderSlot']}
+        renderSlotChain={renderSlotChain ?? ((_key, _owner, opts) => opts?.fallback ?? null)}
+        SessionProvider={SessionProviderStub}
         views={{
-          list: () => views,
+          list: () => tabs,
           subscribe: () => () => {},
           version: () => 1,
         }}
         send={send}
         stop={stop}
-        openDetails={openDetails}
-        loadOlder={loadOlder}
         open={open}
       />)
-    return { ui, chat, send, stop, open }
+    return { ui, chat, send, stop, open, renderSlot }
   }
 
-  /** View bodies record their mount via testid (renderView is in-component now). */
-  const view = (id: string, label: string): ViewEntry =>
-    ({
-      id, label,
-      component: (() => <div data-testid={`view-${id}`} />) as unknown as FC<never>,
-    }) as unknown as ViewEntry
+  const tab = (id: string, label: string): ViewTab => ({ id, label })
 
   it('renders breadcrumb chain (useSessions-derived), meta turns, and the default chat view', () => {
-    const { open } = bench([view('chat', 'Chat'), view('trajectory', 'Trajectory')])
+    const { open } = bench([tab('chat', 'Chat'), tab('trajectory', 'Trajectory')])
     expect(screen.getByText('proj')).toBeTruthy()
     expect(screen.getByText('child')).toBeTruthy()
     expect(screen.getByText(/2 turns/)).toBeTruthy()
@@ -150,33 +240,25 @@ describe('ConversationRoot', () => {
   })
 
   it('switches views through the store view field and falls back on unknown ids', () => {
-    const { chat } = bench([view('chat', 'Chat'), view('trajectory', 'Trajectory')])
+    const { chat } = bench([tab('chat', 'Chat'), tab('trajectory', 'Trajectory')])
     fireEvent.click(screen.getByRole('tab', { name: 'Trajectory' }))
     expect(chat.store.getSnapshot().view).toBe('trajectory')
     expect(screen.getByTestId('view-trajectory')).toBeTruthy()
     cleanup()
     // A stale persisted id (its view plugin unloaded) falls to the first view.
-    bench([view('chat', 'Chat'), view('trajectory', 'Trajectory')], 'ghost-view')
+    bench([tab('chat', 'Chat'), tab('trajectory', 'Trajectory')], 'ghost-view')
     expect(screen.getByTestId('view-chat')).toBeTruthy()
   })
 
-  it('mounts chrome header/footer around the view body', () => {
-    const entry = {
-      id: 'chat', label: 'Chat',
-      component: () => <div data-testid="body" />,
-      chrome: {
-        header: () => <div data-testid="hd" />,
-        footer: () => <div data-testid="ft" />,
-      },
-    } as unknown as ViewEntry
-    bench([entry])
-    expect(screen.getByTestId('hd')).toBeTruthy()
-    expect(screen.getByTestId('body')).toBeTruthy()
-    expect(screen.getByTestId('ft')).toBeTruthy()
+  it('renders the active view through the declared ring slot with the only filter', () => {
+    const { renderSlot } = bench([tab('chat', 'Chat')])
+    // No owner share: views take everything from the standard kit (contract).
+    expect(renderSlot).toHaveBeenCalledWith('conversation.view', {}, { only: 'chat' })
+    expect(screen.getByTestId('view-chat').getAttribute('data-slot')).toBe('conversation.view')
   })
 
   it('hides the tab strip with a single view; composer writes the store draft and sends it', () => {
-    const { chat, send } = bench([view('chat', 'Chat')])
+    const { chat, send } = bench([tab('chat', 'Chat')])
     expect(screen.queryByRole('tablist')).toBeNull()
     const box = screen.getByPlaceholderText(/输入消息/)
     fireEvent.change(box, { target: { value: 'hi' } })
@@ -185,6 +267,30 @@ describe('ConversationRoot', () => {
     fireEvent.keyDown(box, { key: 'Enter' })
     expect(send).toHaveBeenCalledWith('hi', 'queue')
   })
+
+  it('dispatches the pending list to the composer chain; all-decline falls back to InputBar', () => {
+    const wait = new PendingWait('question', RpcId('rq'), sid('s1'),
+      { questions: [{ id: 'mode', question: 'Choose?', options: [{ label: 'Fast' }] }] } as PendingWait<'question'>['payload'], vi.fn())
+    // A matching entry takes the composer over.
+    const renderSlotChain = vi.fn(() => <div>question takeover</div>) as unknown as ConversationRootProps['renderSlotChain']
+    bench([tab('chat', 'Chat')], undefined, { pending: [wait] }, renderSlotChain)
+    expect(screen.getByText('question takeover')).toBeTruthy()
+    expect(screen.queryByPlaceholderText(/输入消息/)).toBeNull()
+    // The owner dispatches the raw pending list (chain currency); routing
+    // lives in entry selectors, not here.
+    expect(renderSlotChain).toHaveBeenCalledWith(
+      'conversation.composer',
+      expect.objectContaining({
+        interactions: expect.arrayContaining([expect.objectContaining({ key: 'q:rq' })]),
+      }),
+      expect.objectContaining({ fallback: expect.anything() }),
+    )
+    cleanup()
+    // Zero registered entries (default all-decline stub): the fallback IS the
+    // default InputBar — behavior equals the pre-chain composer.
+    bench([tab('chat', 'Chat')], undefined, { pending: [wait] })
+    expect(screen.getByPlaceholderText(/输入消息/)).toBeTruthy()
+  })
 })
 
 describe('DetailsPanel', () => {
@@ -199,7 +305,7 @@ describe('DetailsPanel', () => {
         sessionId={sid('s1')}
         useSession={useSession}
         useSessions={useSessions}
-        useStore={hookOf(chat)}
+        useStore={bindSnapshotSelector(chat)}
         actions={chat.actions}
         closeDetails={closeDetails}
       />)
@@ -209,10 +315,11 @@ describe('DetailsPanel', () => {
   it('renders the selected call args and result off the shared store; close fires the injected callback', () => {
     const { closeDetails } = benchDetails({
       nodes: [{
-        kind: 'tool-result', callId: 'c1',
+        kind: 'tool-result', seq: 1, time: 1_000, callId: 'c1',
         call: { name: 'bash', argsRaw: '{"cmd":"ls"}' },
+        callTime: 500,
         content: [{ type: 'text', text: 'file-a\nfile-b' }],
-        isError: false,
+        isError: false, callView: null, resultView: null,
       }],
     }, { turnSeq: 1, callId: 'c1' })
     expect(screen.getByText('bash')).toBeTruthy()
@@ -223,10 +330,10 @@ describe('DetailsPanel', () => {
   })
 
   it('shows the empty hint without a selection and the running state for open calls', () => {
-    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}' }] }, null)
+    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}', turn: 1, step: 1, time: 1_000, callView: null }] }, null)
     expect(screen.getByText(/点击消息流中的工具行/)).toBeTruthy()
     cleanup()
-    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}' }] }, { turnSeq: 1, callId: 'c9' })
+    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}', turn: 1, step: 1, time: 1_000, callView: null }] }, { turnSeq: 1, callId: 'c9' })
     expect(screen.getByText('运行中…')).toBeTruthy()
   })
 
diff --git a/packages/client/ui-conversation/tests/toolview-entry-types.spec.ts b/packages/client/ui-conversation/tests/toolview-entry-types.spec.ts
deleted file mode 100644
index 62c875687e..0000000000
--- a/packages/client/ui-conversation/tests/toolview-entry-types.spec.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-/**
- * Tool-ring Entry typing (design §7): I inferred from the inject factory at
- * the register site, component must accept ToolViewProps & I, and the resolve
- * read face carries the erased-but-present inject. Compile-time checks via
- * @ts-expect-error pairs; the runtime assertions just keep vitest happy.
- */
-import { describe, expect, it } from 'vitest'
-import type { FC } from 'react'
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type { ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-
-const sid = (s: string): SessionId => s as SessionId
-
-// Positive control: component's own injected share matches the factory's product.
-interface RowInjected { useMyStore: () => number }
-const InjectedRowComp: FC<ToolViewProps & RowInjected> = () => null
-// Plain rows take the shared props only.
-const PlainRowComp: FC<ToolViewProps> = () => null
-
-describe('tool-ring entry typing', () => {
-  it('register infers I from the inject factory and accepts a matching component', () => {
-    const reg = new ToolViewRegistry()
-    const off = reg.register('bash', InjectedRowComp, {
-      inject: () => ({ useMyStore: () => 1 }),
-    })
-    expect(reg.resolve('bash', sid('s'))?.inject).toBeDefined()
-    off()
-  })
-
-  it('injectless registration needs no options and resolves without inject', () => {
-    const reg = new ToolViewRegistry()
-    reg.register('read', PlainRowComp)
-    expect('inject' in (reg.resolve('read', sid('s')) ?? {})).toBe(false)
-  })
-
-  it('compile-time: factory product must cover the component injected share', () => {
-    const reg = new ToolViewRegistry()
-    reg.register('bash', InjectedRowComp, {
-      // @ts-expect-error the factory misses useMyStore, which the component requires
-      inject: () => ({ somethingElse: 1 }),
-    })
-    expect(true).toBe(true)
-  })
-
-  // Known boundary (not asserted): a component demanding an injected share CAN
-  // register bare — with I defaulting to `object`, FC<ToolViewProps & RowInjected>
-  // is structurally assignable to FC<ToolViewProps & object> (parameter
-  // bivariance over a wider props type). The register-site guarantee holds in
-  // the direction that matters: WITH an inject factory, its product must cover
-  // the component's share (previous case). The bare-register gap is the same
-  // one SlotMap's single-kind register has and is accepted by design §7.
-
-  it('compile-time: scope filter receives the branded SessionId', () => {
-    const reg = new ToolViewRegistry()
-    reg.register('bash', PlainRowComp, {
-      // @ts-expect-error number is not assignable to SessionId
-      scope: (id: number) => id > 0,
-    })
-    expect(true).toBe(true)
-  })
-})
diff --git a/packages/client/ui-conversation/tests/toolview-registry.spec.ts b/packages/client/ui-conversation/tests/toolview-registry.spec.ts
deleted file mode 100644
index fad1d7f171..0000000000
--- a/packages/client/ui-conversation/tests/toolview-registry.spec.ts
+++ /dev/null
@@ -1,101 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type { ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-
-const sid = (s: string) => s as SessionId
-const comp = (name: string) => {
-  const fc = () => null
-  fc.displayName = name
-  return fc as unknown as import('react').FC<ToolViewProps>
-}
-
-describe('ToolViewRegistry', () => {
-  it('resolves a global registration for any session', () => {
-    const reg = new ToolViewRegistry()
-    const bash = comp('Bash')
-    reg.register('bash', bash)
-    expect(reg.resolve('bash', sid('a'))?.component).toBe(bash)
-    expect(reg.resolve('bash', sid('b'))?.component).toBe(bash)
-    expect(reg.resolve('read', sid('a'))).toBeUndefined()
-  })
-
-  it('prefers a matching scope filter over the global registration', () => {
-    const reg = new ToolViewRegistry()
-    const global = comp('Global')
-    const swarm = comp('Swarm')
-    reg.register('bash', global)
-    reg.register('bash', swarm, { scope: id => id === sid('swarm-1') })
-    expect(reg.resolve('bash', sid('swarm-1'))?.component).toBe(swarm)
-    expect(reg.resolve('bash', sid('plain'))?.component).toBe(global)
-  })
-
-  it('later registration wins within the same tier, scoped and global', () => {
-    const reg = new ToolViewRegistry()
-    const s1 = comp('S1')
-    const s2 = comp('S2')
-    const g1 = comp('G1')
-    const g2 = comp('G2')
-    reg.register('bash', g1)
-    reg.register('bash', s1, { scope: () => true })
-    reg.register('bash', s2, { scope: () => true })
-    reg.register('bash', g2)
-    expect(reg.resolve('bash', sid('x'))?.component).toBe(s2)
-    const scopeless = new ToolViewRegistry()
-    scopeless.register('bash', g1)
-    scopeless.register('bash', g2)
-    expect(scopeless.resolve('bash', sid('x'))?.component).toBe(g2)
-  })
-
-  it('a non-matching scope filter falls through to global, then undefined', () => {
-    const reg = new ToolViewRegistry()
-    const scoped = comp('Scoped')
-    reg.register('bash', scoped, { scope: () => false })
-    expect(reg.resolve('bash', sid('x'))).toBeUndefined()
-    const global = comp('Global')
-    reg.register('bash', global)
-    expect(reg.resolve('bash', sid('x'))?.component).toBe(global)
-  })
-
-  it('disposer removes exactly its registration and is idempotent', () => {
-    const reg = new ToolViewRegistry()
-    const g = comp('G')
-    const s = comp('S')
-    const off = reg.register('bash', s, { scope: () => true })
-    reg.register('bash', g)
-    off()
-    off()
-    expect(reg.resolve('bash', sid('x'))?.component).toBe(g)
-  })
-
-  it('unregistering the last entry resolves undefined (GenericToolCard fallback)', () => {
-    const reg = new ToolViewRegistry()
-    const off = reg.register('bash', comp('B'))
-    off()
-    expect(reg.resolve('bash', sid('x'))).toBeUndefined()
-  })
-
-  it('carries the inject factory through resolve', () => {
-    const reg = new ToolViewRegistry()
-    const inject = () => ({})
-    reg.register('bash', comp('B'), { inject })
-    expect(reg.resolve('bash', sid('x'))?.inject).toBe(inject)
-    reg.register('read', comp('R'))
-    expect('inject' in reg.resolve('read', sid('x'))!).toBe(false)
-  })
-
-  it('notifies subscribers and bumps the version on register and dispose', () => {
-    const reg = new ToolViewRegistry()
-    const fn = vi.fn()
-    const unsub = reg.subscribe(fn)
-    const v0 = reg.getVersion()
-    const off = reg.register('bash', comp('B'))
-    expect(fn).toHaveBeenCalledTimes(1)
-    expect(reg.getVersion()).toBeGreaterThan(v0)
-    off()
-    expect(fn).toHaveBeenCalledTimes(2)
-    unsub()
-    reg.register('read', comp('R'))
-    expect(fn).toHaveBeenCalledTimes(2)
-  })
-})
diff --git a/packages/client/ui-conversation/tests/toolviews-type-chain.spec.ts b/packages/client/ui-conversation/tests/toolviews-type-chain.spec.ts
deleted file mode 100644
index ea04f23a6d..0000000000
--- a/packages/client/ui-conversation/tests/toolviews-type-chain.spec.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-// Tool-ring type-chain samples (design §9 item 5, toolviews half): the
-// register→inject→resolve chain where `I` is inferred from the inject
-// factory and proved against the component at the register site, plus
-// expect-error duals. Tool names stay an open set (no per-tool props table —
-// design §7); the strong typing under test is Entry-internal. The known
-// bare-register variance edge (FC<Props & I> assignable to FC<Props & object>
-// without an inject factory) is accepted by design §7 and deliberately not
-// pinned here. Follows the slots-ring exemplar's shape.
-import { describe, expect, it } from 'vitest'
-import type { FC, ReactNode } from 'react'
-import type { ToolViewOptions, ToolViewProps } from '../src/client/contract/toolview.ts'
-import { ToolViewRegistry } from '../src/client/toolviews/registry.ts'
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-
-const sid = (s: string): SessionId => s as SessionId
-
-/** Registrant's own injected share (locally declared — ownership rule). */
-interface RowInjected { useRuns: () => number; actions2: { rerun: () => void } }
-
-const InjectedRow: FC<ToolViewProps & RowInjected> = () => null
-const PlainRow: FC<ToolViewProps> = () => null
-
-describe('tool-ring type-chain negatives (compile-time; body never runs)', () => {
-  it('holds the negative samples as expect-error sites', () => {
-    const negatives = (registry: ToolViewRegistry) => {
-      // 1. Inject factory under-produces the component's declared share:
-      //    I infers from the factory, and the component position then fails.
-      registry.register(
-        'bash',
-        // @ts-expect-error component wants actions2, which the factory never produces
-        InjectedRow,
-        { inject: () => ({ useRuns: () => 1 }) },
-      )
-      // 2. Inject factory produces a drifted value type for a declared key
-      //    (I infers from the component position here, so TS flags the factory).
-      registry.register(
-        'bash',
-        InjectedRow,
-        // @ts-expect-error useRuns returns string here, component wants number
-        { inject: () => ({ useRuns: () => 'one', actions2: { rerun: () => {} } }) },
-      )
-      // 3. Options object drifts: scope filter with a wrong parameter shape.
-      const badScope: ToolViewOptions<RowInjected> = {
-        // @ts-expect-error scope takes a SessionId, not a numeric index
-        scope: (index: number) => index > 0,
-      }
-      void badScope
-      // 4. Component demanding props outside ToolViewProps & I (a key neither
-      //    standard nor injected) cannot register even with a full factory.
-      const Overreaching: FC<ToolViewProps & RowInjected & { fromNowhere: boolean }> = () => null
-      registry.register(
-        'bash',
-        // @ts-expect-error fromNowhere is neither a standard prop nor produced by the factory
-        Overreaching,
-        { inject: (): RowInjected => ({ useRuns: () => 1, actions2: { rerun: () => {} } }) },
-      )
-      return null as ReactNode
-    }
-    expect(negatives).toBeTypeOf('function')
-  })
-})
-
-describe('tool-ring full chain (positive dual)', () => {
-  it('registers with an inferred inject share, resolves by scope order, and reads the erased face back', () => {
-    const registry = new ToolViewRegistry()
-    // Registration: I inferred from the factory, component proved ⊇ ToolViewProps & I.
-    const disposeGlobal = registry.register('bash', InjectedRow, {
-      // Terminal channel form: the factory receives the session id only.
-      inject: (sessionId: SessionId): RowInjected => ({
-        useRuns: () => sessionId.length,
-        actions2: { rerun: () => {} },
-      }),
-    })
-    const disposeScoped = registry.register('bash', PlainRow, {
-      scope: id => id === sid('swarm-1'),
-    })
-
-    // Resolve: scope match beats global; elsewhere the global row wins.
-    expect(registry.resolve('bash', sid('swarm-1'))?.component).toBe(PlainRow)
-    const global = registry.resolve('bash', sid('other'))
-    expect(global?.component).toBe(InjectedRow)
-    // Read face: I is erased to object, the factory reference survives; the
-    // outlet-side restoration is the budgeted cast (same boundary as slots).
-    const injected = (global?.inject as (sessionId: SessionId) => RowInjected)(sid('ab'))
-    expect(injected.useRuns()).toBe(2)
-    // Unknown tool → undefined (caller falls back to the generic card).
-    expect(registry.resolve('ghost-tool', sid('other'))).toBeUndefined()
-
-    disposeScoped()
-    expect(registry.resolve('bash', sid('swarm-1'))?.component).toBe(InjectedRow)
-    disposeGlobal()
-    expect(registry.resolve('bash', sid('other'))).toBeUndefined()
-  })
-})
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 621e8a13cc..684a5fdb38 100644
--- a/packages/client/ui-conversation/tests/views-type-chain.spec.tsx
+++ b/packages/client/ui-conversation/tests/views-type-chain.spec.tsx
@@ -1,111 +1,122 @@
-// View-ring type-chain samples (design §9 item 5, views half): the
-// register→inject→render chain composed through ConversationViewMap's
-// per-view extension shapes, plus expect-error duals for each stage.
-// Follows the slots-ring exemplar (ui-slots/tests/type-chain.spec.tsx):
-// negatives live in a never-executed function body; the positive dual runs
-// the real ConversationService view registry.
+// 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.
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
-import type { FC, ReactNode } from 'react'
-import type {
-  ChromePropsOf, ConvViewProps, ConvViewPropsOf, ViewEntry,
-} from '../src/client/contract/views.ts'
-import { ConversationService } from '../src/client/service.ts'
+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'
 
-// Test-only view keys with distinct extension shapes (merged like
-// ui-trajectory does; extension fields are optional per ViewEntryDef).
-declare module '../src/client/contract/views.ts' {
-  interface ConversationViewMap {
-    'vt-extended': { chromeProps: { statLabel: string }; extraProps: { density: 'compact' | 'wide' } }
-    'vt-plain': object
-  }
-}
-
-const ExtendedView: FC<ConvViewPropsOf<'vt-extended'>> = ({ density }) => (density === 'compact' ? null : null)
-const ExtendedChrome: FC<ChromePropsOf<'vt-extended'>> = ({ statLabel }) => (statLabel === '' ? null : null)
-const PlainView: FC<ConvViewPropsOf<'vt-plain'>> = () => null
-
-describe('view-ring type-chain negatives (compile-time; body never runs)', () => {
+describe('view-ring type negatives (compile-time; body never runs)', () => {
   it('holds the negative samples as expect-error sites', () => {
-    const negatives = (service: ConversationService) => {
-      // 1. Registration: a component missing the entry's declared extraProps
-      //    cannot register under that id (props flow from the map entry).
-      const NarrowComp: FC<ConvViewProps & { density: number }> = () => null
-      service.registerView({
-        id: 'vt-extended',
-        label: 'x',
-        // @ts-expect-error density has the wrong value type vs the map entry's extraProps
-        component: NarrowComp,
-      })
-      // 2. Registration: chrome typed for another view's chromeProps drifts.
-      service.registerView({
-        id: 'vt-plain',
-        label: 'x',
-        component: PlainView,
-        // @ts-expect-error vt-plain declares no statLabel chromeProps
-        chrome: { footer: ExtendedChrome },
-      })
-      // 3. Registration: id outside the map is rejected at the entry.
-      service.registerView({
-        // @ts-expect-error unregistered view id
-        id: 'vt-ghost',
-        label: 'x',
-        component: PlainView,
-      })
-      // 4. Render side: per-view props narrow — the extended view's density
-      //    is not accessible under another id's props type.
-      const renderPlain = (props: ConvViewPropsOf<'vt-plain'>): ReactNode => {
-        // @ts-expect-error density belongs to vt-extended's extension, not vt-plain
-        return props.density === 'compact' ? null : null
-      }
-      void renderPlain
-      // 5. Entry-shape drift: ViewEntry<Id> ties chrome and component to the
-      //    SAME id — mixing ids inside one entry fails.
-      const mixed: ViewEntry<'vt-extended'> = {
-        id: 'vt-extended',
-        label: 'x',
-        component: ExtendedView,
-        // @ts-expect-error chrome for vt-plain cannot ride a vt-extended entry
-        chrome: { header: (props: ChromePropsOf<'vt-plain'> & { onlyPlain: true }) => null },
-      }
-      void mixed
-      // 6. Zero-renderSlot inference: the view ring declares no children, so
-      //    view props carry no delegation face (the old hand-written
-      //    ScopedSlots<never> empty surface is retired, not replaced).
-      const renderless = (props: ConvViewPropsOf<'vt-plain'>): ReactNode => {
+    const negatives = (slots: SlotsService) => {
+      // 1. List-kind registration requires the id shape field.
+      // @ts-expect-error missing `id` on a list-slot registration
+      slots.register({ name: 'conversation.view', order: 1 }, (_p: ConvViewProps) => null)
+      // 2. A keyed-kind shape field is rejected on the list slot.
+      slots.register(
+        // @ts-expect-error `key` belongs to keyed slots, not the list ring
+        { name: 'conversation.view', id: 'x', key: 'k' },
+        (_p: ConvViewProps) => null)
+      // 3. Component props must stay within the composed contract: an
+      //    undeclared member cannot be required.
+      // @ts-expect-error component demands a prop no share supplies
+      slots.register(
+        { name: 'conversation.view', id: 'y' },
+        (_p: ConvViewProps & { phantom: number }) => null)
+      // 4. Views receive no renderSlot — the ring's entries declare no children.
+      const renderless = (props: ConvViewProps): ReactNode => {
         // @ts-expect-error views receive no renderSlot — no sub-slot delegation
         void props.renderSlot
-        // @ts-expect-error the legacy slots face is gone from view props
-        void props.slots
         return null
       }
       void renderless
+      // 5. The chat entry's face is its own: openDetails does not exist on the
+      //    base view props (store-less riders never see it).
+      const baseOnly = (props: ConvViewProps): ReactNode => {
+        // @ts-expect-error openDetails lives on ChatViewSlotProps, not the base
+        void props.openDetails
+        return null
+      }
+      void baseOnly
+      // 6. ChatViewSlotProps carries the full composition (standard kit +
+      //    store + inject face) — a handler with a wrong signature is red.
+      const chatProps = (props: ChatViewSlotProps): ReactNode => {
+        // @ts-expect-error openDetails takes a SelectionTarget, not a string
+        props.openDetails('nope')
+        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')
   })
 })
 
-describe('view-ring full chain (positive dual)', () => {
-  it('registers, lists, and renders through the per-view extension shapes', () => {
+describe('view-ring runtime dual (real ledger)', () => {
+  function bench() {
     const ctx = new Context()
-    const service = new ConversationService(ctx)
-    // Registration: extension-typed component + same-id chrome compose cleanly.
-    const dispose = service.registerView({
-      id: 'vt-extended',
-      label: '扩展视图',
-      order: 7,
-      component: ExtendedView,
-      chrome: { footer: ExtendedChrome },
-    })
-    const entry = service.views().find(v => v.id === 'vt-extended')
-    expect(entry?.label).toBe('扩展视图')
-    // Render surface: the listed entry's component accepts the composed props
-    // (base ConvViewProps + the map extension), spelled here as the same type
-    // the runtime hands over.
-    expect(typeof entry?.component).toBe('function')
-    expect(typeof entry?.chrome?.footer).toBe('function')
-    dispose()
-    expect(service.views().some(v => v.id === 'vt-extended')).toBe(false)
+    const slots = new SlotsService(ctx)
+    // The conversation entry's role: declare the ring (declaring is claiming).
+    slots.register({
+      name: 'root',
+      children: { 'conversation.view': { kind: 'list', scope: 'session' } },
+    }, (_p: { renderSlot?: unknown }) => null)
+    return { slots }
+  }
+
+  it('registers, orders, projects tabs, and disposes through the slot ledger', () => {
+    const { slots } = bench()
+    const offLate = slots.register(
+      { name: 'conversation.view', id: 'z-late', order: 20, label: '晚' }, () => null)
+    const offEarly = slots.register(
+      { name: 'conversation.view', id: 'early', order: 0, label: '早' }, () => null)
+    // Order-sorted ledger, label fallback for a labelless rider.
+    const offBare = slots.register(
+      { name: 'conversation.view', id: 'bare', order: 10 }, () => null)
+    const tabs = slots.entries('conversation.view')
+      .map(e => ({ id: e.options.id, label: e.options.label ?? e.options.id }))
+    expect(tabs).toEqual([
+      { id: 'early', label: '早' },
+      { id: 'bare', label: 'bare' },
+      { id: 'z-late', label: '晚' },
+    ])
+    // Duplicate ids fail loud at load (the ring's uniqueness contract).
+    expect(() => slots.register({ name: 'conversation.view', id: 'early' }, () => null))
+      .toThrow(/already has an entry with id "early"/)
+    offEarly()
+    expect(slots.entries('conversation.view').map(e => e.options.id)).toEqual(['bare', 'z-late'])
+    offBare()
+    offLate()
+    expect(slots.entries('conversation.view')).toHaveLength(0)
   })
 })
diff --git a/packages/client/ui-layout/README.md b/packages/client/ui-layout/README.md
index 6cb5fa29a4..9c31e4cc7a 100644
--- a/packages/client/ui-layout/README.md
+++ b/packages/client/ui-layout/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-ui-layout
 
-Shell plugin: three-column AppFrame (drag handles, concession chain) + ctx.layout viewing-state service (nav, panel widths, persist); defines the sidebar/conversation/details/conversation.empty slots. A closed sidebar retains a 56px control rail while details closes to zero width; collapse/expand animates the grid tracks on the deepsuite sider curve. Contract: api-contracts v3 §5.
+Shell plugin: three-column AppFrame (drag handles, concession chain) + ctx.layout viewing-state service (nav, panel widths, persist); defines the sidebar/conversation/details/conversation.empty slots. The sidebar is fixed-width (it never concedes to viewport pressure — only details shrinks, then auto-closes); a closed sidebar retains a 56px control rail while details closes to zero width; collapse/expand animates the grid tracks on the deepsuite sider curve. Contract: api-contracts v3 §5.
 
 Slot declarations use the composed-props entry form (`owner` share, no full `props`): the exported OwnerShare contracts are `SidebarOwnerProps` / `ConvOwnerProps` / `DetailsOwnerProps` / `EmptyOwnerProps` — registrants reference them via `OwnerOf<'sidebar' | ...>` and compose their own injected share locally. No entry declares `children` (declaring it requires the registered component to carry the slots face — reserved for future business slots): delegation authority is the component-side whitelist, i.e. AppFrame's `ScopedSlots<FrameSlotKey>` face over sidebar/conversation/details/conversation.empty. Since the root-slot rework the frame itself registers into 'root' and renders those child slots at its own render sites; the shell only renders 'root'.
 
diff --git a/packages/client/ui-layout/package.json b/packages/client/ui-layout/package.json
index 3448e62f5c..fd3e691375 100644
--- a/packages/client/ui-layout/package.json
+++ b/packages/client/ui-layout/package.json
@@ -33,19 +33,20 @@
     "watch": "tsdown --watch"
   },
   "license": "BSD-3-Clause",
-  "dependencies": {
-    "@deepseek-ai/dsh-client-runtime": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^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"
   },
-  "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
-    "cordis": "^4.0.0-rc.7"
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
   },
   "files": [
     "lib/index.js",
diff --git a/packages/client/ui-layout/src/client/AppFrame.module.css b/packages/client/ui-layout/src/client/AppFrame.module.css
index 631bb929db..b805bb178a 100644
--- a/packages/client/ui-layout/src/client/AppFrame.module.css
+++ b/packages/client/ui-layout/src/client/AppFrame.module.css
@@ -86,11 +86,25 @@
   height: 32px;
   border-radius: 10px;
   box-sizing: border-box;
-  background: var(--dsw-alias-bg-layer-2);
+  background: var(--dsw-alias-button-floating-fill);
   border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  /* Hover affordance: the pill hides until the pointer is over the owning
+     column (data-side pairs handle and column), the strip itself, or a drag. */
+  opacity: 0;
+  transition:
+    opacity var(--ds-transition-duration-slow) var(--ds-ease-in-out),
+    background var(--ds-transition-duration-slow) var(--ds-ease-in-out);
+}
+
+.sidebarCol:hover ~ .handle[data-side='sidebar']::after,
+.detailsCol:hover ~ .handle[data-side='details']::after,
+.handle:hover::after,
+.handle[data-dragging='true']::after {
+  opacity: 1;
 }
 
 .handle:hover::after,
 .handle[data-dragging='true']::after {
+  background: var(--dsw-alias-button-floating-hover);
   border-color: var(--dsw-alias-border-l3);
 }
diff --git a/packages/client/ui-layout/src/client/AppFrame.tsx b/packages/client/ui-layout/src/client/AppFrame.tsx
index e40c94454d..dfa8271075 100644
--- a/packages/client/ui-layout/src/client/AppFrame.tsx
+++ b/packages/client/ui-layout/src/client/AppFrame.tsx
@@ -34,8 +34,8 @@ function DetailsColumn(props: { children?: ReactNode }) {
   return <div className={css.detailsCol}>{props.children}</div>
 }
 
-/** One drag handle: pointer capture, rAF-throttled dx reports against the drag-start origin. */
-function DragHandle(props: { left: number; onStart: () => void; onDrag: (dx: number) => void; onEnd: () => void }) {
+/** One drag handle: pointer capture, rAF-throttled dx reports against the drag-start origin. `side` keys the hover-reveal CSS to the owning column. */
+function DragHandle(props: { side: 'sidebar' | 'details'; left: number; onStart: () => void; onDrag: (dx: number) => void; onEnd: () => void }) {
   const [dragging, setDragging] = useState(false)
   const origin = useRef(0)
   const latest = useRef(0)
@@ -72,6 +72,7 @@ function DragHandle(props: { left: number; onStart: () => void; onDrag: (dx: num
     <div
       className={css.handle}
       style={{ left: props.left }}
+      data-side={props.side}
       data-dragging={dragging || undefined}
       onPointerDown={onPointerDown}
       onPointerMove={onPointerMove}
@@ -161,8 +162,8 @@ export function AppFrame({ useStore, actions, renderSlot, SessionProvider }: App
         )}
       </SessionProvider>
       {/* The collapsed rail is fixed-width: no resize handle while closed. */}
-      {panels.sidebar > 0 && <DragHandle left={cols.sidebar} onStart={onSidebarStart} onDrag={onSidebarDrag} onEnd={onDragEnd} />}
-      {cols.details > 0 && <DragHandle left={viewport - cols.details} onStart={onDetailsStart} onDrag={onDetailsDrag} onEnd={onDragEnd} />}
+      {panels.sidebar > 0 && <DragHandle side="sidebar" left={cols.sidebar} onStart={onSidebarStart} onDrag={onSidebarDrag} onEnd={onDragEnd} />}
+      {cols.details > 0 && <DragHandle side="details" left={viewport - cols.details} onStart={onDetailsStart} onDrag={onDetailsDrag} onEnd={onDragEnd} />}
     </div>
   )
 }
diff --git a/packages/client/ui-layout/src/client/columns.ts b/packages/client/ui-layout/src/client/columns.ts
index d7a63aafa2..7cd5f8c2d8 100644
--- a/packages/client/ui-layout/src/client/columns.ts
+++ b/packages/client/ui-layout/src/client/columns.ts
@@ -1,12 +1,13 @@
 /**
  * Pure concession-chain column solver for the three-column AppFrame.
  * Chain order is fixed by contract: keep center >= CENTER_MIN by shrinking
- * details first, then sidebar, then auto-closing details (derived zero width —
- * persisted width preferences are never rewritten, so widening the window
- * restores them). Center absorbs any remaining deficit as the last resort.
- * Inputs are the layout store's plain width preferences (0 = closed); a
- * closed sidebar resolves to the fixed SIDEBAR_COLLAPSED control rail while
- * closed details resolve to zero width.
+ * details, then auto-closing it (derived zero width — persisted width
+ * preferences are never rewritten, so widening the window restores them).
+ * The sidebar never concedes: its rendered width is always the drag
+ * preference (or the collapsed rail), and center absorbs any remaining
+ * deficit as the last resort. Inputs are the layout store's plain width
+ * preferences (0 = closed); a closed sidebar resolves to the fixed
+ * SIDEBAR_COLLAPSED control rail while closed details resolve to zero width.
  */
 
 /** Resolved widths for one frame; center may drop below CENTER_MIN only at the final fallback. */
@@ -16,11 +17,11 @@ export interface Columns { sidebar: number; center: number; details: number }
 /** Center column floor; only the final fallback may go below it. */
 export const CENTER_MIN = 640
 /** Sidebar drag clamp floor. */
-export const SIDEBAR_MIN = 240
+export const SIDEBAR_MIN = 280
 /** Sidebar drag clamp ceiling. */
 export const SIDEBAR_MAX = 420
-/** Sidebar width before any user drag. */
-export const SIDEBAR_DEFAULT = 300
+/** Sidebar width before any user drag (= the drag floor). */
+export const SIDEBAR_DEFAULT = 280
 /** Closed-sidebar rail: a 24px icon column between 16px horizontal paddings. */
 export const SIDEBAR_COLLAPSED = 56
 /** Details drag clamp floor. */
@@ -44,38 +45,26 @@ export function clampWidth(px: number, min: number, max: number): number {
 /**
  * Solve the three column widths for one viewport frame. Pure: no hysteresis —
  * the output is a function of (viewport, preferences) only, so recovery on
- * re-widening is automatic. After the auto-close step the details pressure is
- * gone, so the sidebar returns to its preferred width when it fits.
- * Preferences re-clamp here because they cross a durable boundary
- * (localStorage rehydration may carry stale ranges).
+ * re-widening is automatic. Preferences re-clamp here because they cross a
+ * durable boundary (localStorage rehydration may carry stale ranges).
  * @param viewport - available frame width in px.
  * @param sidebar - sidebar width preference in px (0 = closed).
  * @param details - details width preference in px (0 = closed).
  * @returns resolved widths; details 0 means visually closed (never unmounted), while a closed sidebar keeps its compact rail.
  */
 export function computeColumns(viewport: number, sidebar: number, details: number): Columns {
-  const s0 = sidebar === 0 ? SIDEBAR_COLLAPSED : clampWidth(sidebar, SIDEBAR_MIN, SIDEBAR_MAX)
+  // The sidebar is fixed at its preference (or the rail) — it never concedes.
+  const s = sidebar === 0 ? SIDEBAR_COLLAPSED : clampWidth(sidebar, SIDEBAR_MIN, SIDEBAR_MAX)
   const d0 = details === 0 ? 0 : clampWidth(details, DETAILS_MIN, DETAILS_MAX)
 
   // Step 1: everything fits at preferred widths.
-  if (s0 + d0 + CENTER_MIN <= viewport) return { sidebar: s0, center: viewport - s0 - d0, details: d0 }
+  if (s + d0 + CENTER_MIN <= viewport) return { sidebar: s, center: viewport - s - d0, details: d0 }
 
   // Step 2: shrink details toward its minimum.
-  const d1 = d0 === 0 ? 0 : Math.max(DETAILS_MIN, viewport - s0 - CENTER_MIN)
-  if (s0 + d1 + CENTER_MIN <= viewport) return { sidebar: s0, center: CENTER_MIN, details: d1 }
+  const d1 = d0 === 0 ? 0 : Math.max(DETAILS_MIN, viewport - s - CENTER_MIN)
+  if (s + d1 + CENTER_MIN <= viewport) return { sidebar: s, center: CENTER_MIN, details: d1 }
 
-  // Step 3: shrink sidebar toward its minimum (the collapsed rail never shrinks).
-  const s1 = sidebar === 0 ? SIDEBAR_COLLAPSED : Math.max(SIDEBAR_MIN, viewport - d1 - CENTER_MIN)
-  if (s1 + d1 + CENTER_MIN <= viewport) return { sidebar: s1, center: CENTER_MIN, details: d1 }
-
-  // Step 4: auto-close details (derived — preferences untouched). With the
-  // details pressure gone the sidebar concession is re-solved from preference.
-  if (d1 > 0) {
-    if (s0 + CENTER_MIN <= viewport) return { sidebar: s0, center: viewport - s0, details: 0 }
-    const s2 = sidebar === 0 ? SIDEBAR_COLLAPSED : Math.max(SIDEBAR_MIN, viewport - CENTER_MIN)
-    return { sidebar: s2, center: Math.max(0, viewport - s2), details: 0 }
-  }
-
-  // Step 5: center absorbs the deficit (may drop below CENTER_MIN).
-  return { sidebar: s1, center: Math.max(0, viewport - s1 - d1), details: d1 }
+  // Step 3: auto-close details (derived — preferences untouched); center
+  // absorbs any remaining deficit (may drop below CENTER_MIN).
+  return { sidebar: s, center: Math.max(0, viewport - s), details: 0 }
 }
diff --git a/packages/client/ui-layout/tests/app-frame.spec.tsx b/packages/client/ui-layout/tests/app-frame.spec.tsx
index 120197d531..841e90fc18 100644
--- a/packages/client/ui-layout/tests/app-frame.spec.tsx
+++ b/packages/client/ui-layout/tests/app-frame.spec.tsx
@@ -50,7 +50,7 @@ function hookOf<T>(inst: { subscribe: (fn: () => void) => () => void; getSnapsho
 function mountFrame() {
   window.innerWidth = frameWidth // first-render viewport source before the observer fires
   const instance = createLayoutStore().create()
-  instance.actions.openDetails() // seed: sidebar at default 300, details open at default 360
+  instance.actions.openDetails() // seed: sidebar at default 280, details open at default 360
   const slotCalls: { key: string; props: unknown }[] = []
   const renderSlot = ((key: string, owner: object) => {
     slotCalls.push({ key, props: owner })
@@ -116,7 +116,7 @@ afterEach(() => {
 describe('AppFrame', () => {
   it('renders three tracks from store state', () => {
     const { frame } = mountFrame()
-    expect(tracks(frame)).toEqual([300, 360])
+    expect(tracks(frame)).toEqual([280, 360])
   })
 
   it('renders the session pair with empty owner shares (sessionId is framework-standard)', () => {
@@ -142,13 +142,13 @@ describe('AppFrame', () => {
 
   it('sidebar slot receives live concession output as owner props', () => {
     const { slotCalls } = mountFrame()
-    expect(slotCalls.find((c) => c.key === 'sidebar')!.props).toEqual({ collapsed: false, width: 300 })
+    expect(slotCalls.find((c) => c.key === 'sidebar')!.props).toEqual({ collapsed: false, width: 280 })
   })
 
   it('sidebar drag widens through rAF-batched pointer moves', () => {
     const { frame } = mountFrame()
     const handles = frame.querySelectorAll('[class*="handle"]')
-    drag(handles[0]!, 300, 350)
+    drag(handles[0]!, 280, 350)
     expect(tracks(frame)[0]).toBe(350)
   })
 
@@ -160,18 +160,18 @@ describe('AppFrame', () => {
   })
 
   it('drag base is the rendered (concession-clamped) width, not the preference', () => {
-    frameWidth = 1250 // step-2 squeeze: details renders 310 while preference is 360
+    frameWidth = 1250 // step-2 squeeze: details renders 330 while preference is 360
     const { frame, instance } = mountFrame()
-    expect(tracks(frame)).toEqual([300, 310])
+    expect(tracks(frame)).toEqual([280, 330])
     const handles = frame.querySelectorAll('[class*="handle"]')
-    drag(handles[1]!, 940, 950) // shrink by 10 from the rendered width
-    expect(instance.getSnapshot().details).toBe(300)
+    drag(handles[1]!, 920, 930) // shrink by 10 from the rendered width
+    expect(instance.getSnapshot().details).toBe(320)
   })
 
   it('details column stays mounted at zero width', () => {
     const { frame, instance, getByTestId } = mountFrame()
     act(() => { instance.actions.closeDetails() })
-    expect(tracks(frame)).toEqual([300, 0])
+    expect(tracks(frame)).toEqual([280, 0])
     expect(getByTestId('details-content')).toBeTruthy()
     expect(frame.hasAttribute('data-details-collapsed')).toBe(true)
   })
@@ -190,10 +190,10 @@ describe('AppFrame', () => {
     const { frame } = mountFrame()
     frameWidth = 1250
     act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
-    expect(tracks(frame)).toEqual([300, 310])
+    expect(tracks(frame)).toEqual([280, 330])
     frameWidth = 1920
     act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
-    expect(tracks(frame)).toEqual([300, 360])
+    expect(tracks(frame)).toEqual([280, 360])
   })
 
   it('drag handles disappear for collapsed columns', () => {
@@ -223,7 +223,7 @@ describe('AppFrame — guard branches', () => {
   it('two moves inside one frame coalesce through the pending rAF', () => {
     const { frame, instance } = mountFrame()
     const handle = frame.querySelectorAll('[class*="handle"]')[0]!
-    act(() => { handle.dispatchEvent(new PointerEvent('pointerdown', { pointerId: 1, clientX: 300, bubbles: true })) })
+    act(() => { handle.dispatchEvent(new PointerEvent('pointerdown', { pointerId: 1, clientX: 280, bubbles: true })) })
     act(() => {
       // Two moves before the frame flushes: the second must ride the pending
       // rAF (frame.current ??= guard), and the flush sees the latest x.
@@ -238,7 +238,7 @@ describe('AppFrame — guard branches', () => {
   it('pointerup with a pending rAF cancels it and commits the final position', () => {
     const { frame, instance } = mountFrame()
     const handle = frame.querySelectorAll('[class*="handle"]')[0]!
-    act(() => { handle.dispatchEvent(new PointerEvent('pointerdown', { pointerId: 1, clientX: 300, bubbles: true })) })
+    act(() => { handle.dispatchEvent(new PointerEvent('pointerdown', { pointerId: 1, clientX: 280, bubbles: true })) })
     act(() => {
       handle.dispatchEvent(new PointerEvent('pointermove', { pointerId: 1, clientX: 360, bubbles: true }))
       // No timer advance: the rAF is still pending when pointerup arrives.
@@ -252,7 +252,7 @@ describe('AppFrame — guard branches', () => {
     frameWidth = 0
     act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
     // Track template still reflects the last non-zero viewport.
-    expect(tracks(frame)).toEqual([300, 360])
+    expect(tracks(frame)).toEqual([280, 360])
   })
 })
 
@@ -270,6 +270,6 @@ describe('AppFrame — unmount with an in-flight resize frame', () => {
     const { frame } = mountFrame()
     frameWidth = 1250
     act(() => { fireResize?.(); fireResize?.(); vi.advanceTimersByTime(20) })
-    expect(tracks(frame)).toEqual([300, 310])
+    expect(tracks(frame)).toEqual([280, 330])
   })
 })
diff --git a/packages/client/ui-layout/tests/columns.spec.ts b/packages/client/ui-layout/tests/columns.spec.ts
index 6358c45076..ae8c39a117 100644
--- a/packages/client/ui-layout/tests/columns.spec.ts
+++ b/packages/client/ui-layout/tests/columns.spec.ts
@@ -19,7 +19,7 @@ describe('clampWidth', () => {
 describe('computeColumns', () => {
   it('step 1: everything fits at preferred widths', () => {
     const cols = computeColumns(1920, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: 300, center: 1920 - 300 - 360, details: 360 })
+    expect(cols).toEqual({ sidebar: 280, center: 1920 - 280 - 360, details: 360 })
   })
 
   it('closed sidebar keeps its compact rail while closed details contribute zero width', () => {
@@ -31,12 +31,13 @@ describe('computeColumns', () => {
     const cols = computeColumns(1920, open(9999), open(1))
     expect(cols.sidebar).toBe(420)
     expect(cols.details).toBe(300)
+    expect(computeColumns(1920, open(1), open(DETAILS_DEFAULT)).sidebar).toBe(SIDEBAR_MIN)
   })
 
   it('step 2: details shrinks first, center pinned at min', () => {
-    // 300 + 360 + 640 = 1300 > 1250; details concedes to 1250-300-640 = 310.
+    // 280 + 360 + 640 = 1280 > 1250; details concedes to 1250-280-640 = 330.
     const cols = computeColumns(1250, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: 300, center: CENTER_MIN, details: 310 })
+    expect(cols).toEqual({ sidebar: 280, center: CENTER_MIN, details: 330 })
   })
 
   it('boundary: exactly at the step-1/step-2 seam', () => {
@@ -46,28 +47,16 @@ describe('computeColumns', () => {
     expect(one).toEqual({ sidebar: 300, center: CENTER_MIN, details: 359 })
   })
 
-  it('step 3: sidebar concedes after details hits its min', () => {
-    // details floor 300: sidebar = 1220-300-640 = 280.
-    const cols = computeColumns(1220, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: 280, center: CENTER_MIN, details: DETAILS_MIN })
+  it('step 3: details auto-closes when its min still starves center — sidebar holds its preference', () => {
+    // 280 + 300 + 640 = 1220 > 1210 → details 0; sidebar untouched: center = 1210-280 = 930.
+    const cols = computeColumns(1210, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(cols).toEqual({ sidebar: 280, center: 930, details: 0 })
   })
 
-  it('step 4: details auto-closes when both panels are at min and center still starves', () => {
-    // 240 + 300 + 640 = 1180 > 1100 → details 0; sidebar preference (300) fits: 1100-300 = 800 center.
-    const cols = computeColumns(1100, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: 300, center: 800, details: 0 })
-  })
-
-  it('step 4 keeps squeezing sidebar when preference no longer fits', () => {
-    // 900 < 300+640: sidebar = max(240, 900-640) = 260.
-    const cols = computeColumns(900, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: 260, center: CENTER_MIN, details: 0 })
-  })
-
-  it('step 5: center absorbs the deficit as last resort (details closed)', () => {
-    // 700 < 240+640: sidebar floors at 240, center takes 460 < CENTER_MIN.
+  it('the sidebar never concedes: center absorbs the deficit below CENTER_MIN', () => {
+    // 700 < 280+640: sidebar keeps 280, center takes 420 < CENTER_MIN.
     const cols = computeColumns(700, open(SIDEBAR_DEFAULT), closed(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: SIDEBAR_MIN, center: 460, details: 0 })
+    expect(cols).toEqual({ sidebar: SIDEBAR_DEFAULT, center: 420, details: 0 })
   })
 
   it('sidebar-closed narrow window: details concedes then auto-closes', () => {
@@ -81,11 +70,11 @@ describe('computeColumns', () => {
     })
   })
 
-  it('tiny viewport: both panels yield everything to center', () => {
+  it('tiny viewport: details closes, sidebar holds, center takes the remainder', () => {
     const cols = computeColumns(400, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
     expect(cols.details).toBe(0)
-    expect(cols.sidebar).toBe(SIDEBAR_MIN)
-    expect(cols.center).toBe(Math.max(0, 400 - SIDEBAR_MIN))
+    expect(cols.sidebar).toBe(SIDEBAR_DEFAULT)
+    expect(cols.center).toBe(Math.max(0, 400 - SIDEBAR_DEFAULT))
   })
 
   it('recovery is pure: re-widening restores preferred widths untouched', () => {
@@ -99,7 +88,7 @@ describe('computeColumns', () => {
 
 describe('computeColumns — degenerate viewports', () => {
   it('sidebar closed and viewport below CENTER_MIN: details auto-closes, center takes the rest', () => {
-    // Reaches step 4's re-solve with the compact rail as the sidebar floor.
+    // Reaches step 3's auto-close with the compact rail sidebar.
     expect(computeColumns(500, closed(300), open(DETAILS_DEFAULT)))
       .toEqual({ sidebar: SIDEBAR_COLLAPSED, center: 500 - SIDEBAR_COLLAPSED, details: 0 })
   })
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 29883df236..5b158c453a 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -1,6 +1,10 @@
 # @deepseek-ai/dsh-client-ui-primitives
 
-Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Input, markdown family (MessageText/JsonBlock). Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, markdown family (MessageText/MarkdownText/JsonBlock). Contract: api-contracts v3 §8.
+
+## Markdown rendering
+
+`MarkdownText` renders GFM from untrusted assistant output through React elements. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders image alt text without loading remote resources; `MessageText` remains the literal-text primitive for user-authored content.
 
 ## Model Experience
 
@@ -15,4 +19,3 @@ 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.
 - **StateDot `Active` variant is a hidden placeholder in the design** — not implemented; the four shipped states (done/warning/ongoing/error) are the complete P-I surface.
-- **MessageText renders plain text** — markdown support swaps this component's internals later; consumers must not assume block structure.
diff --git a/packages/client/ui-primitives/package.json b/packages/client/ui-primitives/package.json
index 2d23ecd330..44c35eb517 100644
--- a/packages/client/ui-primitives/package.json
+++ b/packages/client/ui-primitives/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-primitives",
-  "description": "Pure React atoms for the dsh web UI: StateDot, ic_ds_* icon set, Button/Pill/Menu/Input, markdown family (zero cordis)",
+  "description": "Pure React atoms for the dsh web UI: StateDot, ic_ds_* icon set, Button/Pill/Menu/Modal/Input, markdown family (zero cordis)",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -21,7 +21,9 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "clsx": "^2.0.0",
-    "react": "^18.2.0"
+    "react": "^18.2.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
diff --git a/packages/client/ui-primitives/src/BrandWordmark.tsx b/packages/client/ui-primitives/src/BrandWordmark.tsx
new file mode 100644
index 0000000000..aa45d046f0
--- /dev/null
+++ b/packages/client/ui-primitives/src/BrandWordmark.tsx
@@ -0,0 +1,56 @@
+// DeepSeek Harness brand wordmark (figma 356:14644, exact extract): whale +
+// "deepseek" letterforms + HARNESS badge plate in one svg. Native 182x24.
+// Ink rides currentColor; the badge text is knocked out in the inverted
+// label color so the plate stays legible in both themes.
+
+import type { IconProps } from './icons/props.ts'
+
+/**
+ * Render the full brand wordmark.
+ * @param props.size - height in px (default 24; width keeps the 182:24 ratio).
+ * @param props.className - extra class for layout placement.
+ * @returns the wordmark svg (aria-hidden decorative brand art).
+ */
+export function BrandWordmark({ size = 24, className }: IconProps) {
+  return (
+    <svg
+      width={(size * 182) / 24}
+      height={size}
+      className={className}
+      viewBox="0 0 182 24"
+      fill="none"
+      aria-hidden="true"
+    >
+      <path d="M68.416 18.2447H67.0501V16.1272H68.416C69.2619 16.1272 70.1166 15.9163 70.6671 15.3304C71.2181 14.7444 71.426 13.8455 71.426 12.9471C71.426 12.0487 71.2268 11.1498 70.6671 10.5643C70.1083 9.97831 69.2619 9.76744 68.416 9.76744C67.5701 9.76744 66.7154 9.97831 66.1639 10.5643C65.6129 11.1503 65.4049 12.0487 65.4049 12.9471V21.6435H63.009V7.6582H65.4049V8.54883H65.8442C65.8918 8.49393 65.9394 8.44728 65.9875 8.40064C66.5871 7.85353 67.5049 7.6582 68.4072 7.6582C69.8212 7.6582 71.2341 8.00998 72.1607 8.98662C73.0868 9.96325 73.4143 11.4632 73.4143 12.9558C73.4143 14.4485 73.0785 15.9406 72.1607 16.925C71.2424 17.9094 69.8212 18.2457 68.416 18.2457V18.2447Z" fill="currentColor"/>
+      <path d="M31.9551 8.03497H33.3204V10.1525H31.9551C31.1087 10.1525 30.2545 10.3633 29.7035 10.9493C29.1525 11.5353 28.945 12.4342 28.945 13.3326C28.945 14.231 29.1447 15.1294 29.7035 15.7154C30.2623 16.3014 31.1087 16.5122 31.9551 16.5122C32.8015 16.5122 33.6562 16.3014 34.2072 15.7154C34.7582 15.1294 34.9657 14.231 34.9657 13.3326V4.62842H37.3611V18.6219H34.9657V17.7313H34.5264C34.4783 17.7857 34.4307 17.8329 34.3826 17.8795C33.7835 18.4261 32.8652 18.6219 31.9629 18.6219C30.5494 18.6219 29.136 18.2707 28.2099 17.294C27.2838 16.3174 26.9563 14.817 26.9563 13.3248C26.9563 11.8327 27.2916 10.34 28.2099 9.35561C29.136 8.37898 30.5494 8.03497 31.9551 8.03497Z" fill="currentColor"/>
+      <path d="M49.3786 13.1431V13.9948H42.9984V12.2996H47.2305C47.1348 11.6825 46.9113 11.1043 46.5119 10.682C45.9371 10.0727 45.0503 9.85409 44.1723 9.85409C43.2943 9.85409 42.4076 10.0727 41.8328 10.682C41.258 11.2913 41.05 12.2213 41.05 13.1435C41.05 14.0658 41.2575 15.003 41.8328 15.6046C42.4076 16.2061 43.2939 16.433 44.1723 16.433C45.0508 16.433 45.9371 16.2143 46.5119 15.6046C46.5916 15.5186 46.6635 15.4248 46.7354 15.331H49.0992C48.8918 16.0657 48.5643 16.7299 48.0691 17.2454C47.111 18.2531 45.6339 18.6205 44.1723 18.6205C42.7108 18.6205 41.2337 18.2609 40.2755 17.2454C39.3174 16.2299 38.9661 14.6828 38.9661 13.1435C38.9661 11.6043 39.3096 10.0494 40.2755 9.04168C41.242 8.03396 42.7108 7.66663 44.1723 7.66663C45.6339 7.66663 47.111 8.02618 48.0691 9.04168C49.0351 10.0572 49.3786 11.6043 49.3786 13.1435V13.1431Z" fill="currentColor"/>
+      <path d="M61.4045 13.1431V13.9948H55.0243V12.2996H59.2564C59.1602 11.6825 58.9372 11.1043 58.5378 10.682C57.963 10.0727 57.0762 9.85409 56.1982 9.85409C55.3202 9.85409 54.4335 10.0727 53.8587 10.682C53.2839 11.2913 53.0759 12.2213 53.0759 13.1435C53.0759 14.0658 53.2834 15.003 53.8587 15.6046C54.4335 16.2061 55.3202 16.433 56.1982 16.433C57.0762 16.433 57.963 16.2143 58.5378 15.6046C58.6179 15.5186 58.6894 15.4248 58.7608 15.331H61.1251C60.9171 16.0657 60.5897 16.7299 60.0945 17.2454C59.1364 18.2531 57.6593 18.6205 56.1982 18.6205C54.7372 18.6205 53.2596 18.2609 52.3014 17.2454C51.3432 16.2299 50.9919 14.6828 50.9919 13.1435C50.9919 11.6043 51.3355 10.0494 52.3014 9.04168C53.2678 8.03396 54.7367 7.66663 56.1982 7.66663C57.6598 7.66663 59.1364 8.02618 60.0945 9.04168C61.061 10.0572 61.4045 11.6043 61.4045 13.1435V13.1431Z" fill="currentColor"/>
+      <path d="M80.242 18.6214C81.7035 18.6214 83.1801 18.4105 84.1383 17.809C85.0965 17.2075 85.4482 16.2931 85.4482 15.3869C85.4482 14.4807 85.1042 13.5585 84.1383 12.9647C83.1801 12.371 81.703 12.1518 80.242 12.1518C79.6186 12.1518 79.0438 12.0658 78.6366 11.8394C78.2294 11.6047 78.0778 11.2534 78.0778 10.9017C78.0778 10.5499 78.2216 10.1908 78.6366 9.9639C79.0438 9.72921 79.6749 9.65147 80.2973 9.65147C80.9198 9.65147 81.5509 9.73747 81.9591 9.9639C82.3663 10.1986 82.5179 10.5499 82.5179 10.9017H84.9531C84.9531 9.99499 84.6421 9.07327 83.7719 8.47951C82.9017 7.88576 81.5679 7.66663 80.2424 7.66663C78.9169 7.66663 77.5837 7.8775 76.713 8.47951C75.8427 9.08104 75.5308 9.99499 75.5308 10.9017C75.5308 11.8083 75.8423 12.73 76.713 13.3238C77.5832 13.9176 78.9165 14.1367 80.2424 14.1367C80.929 14.1367 81.688 14.2227 82.1428 14.4491C82.5985 14.676 82.7579 15.0351 82.7579 15.3869C82.7579 15.7387 82.5985 16.0977 82.1428 16.3246C81.688 16.5511 80.9931 16.6371 80.3066 16.6371C79.62 16.6371 78.9169 16.5511 78.4694 16.3246C78.0224 16.0982 77.8543 15.7387 77.8543 15.3869H75.0435C75.0435 16.2935 75.3865 17.2153 76.3534 17.809C77.3194 18.4028 78.7809 18.6214 80.2424 18.6214H80.242Z" fill="currentColor"/>
+      <path d="M97.4733 13.1431V13.9948H91.0932V12.2996H95.3252C95.23 11.6825 95.006 11.1043 94.6071 10.682C94.0313 10.0727 93.1456 9.85409 92.2666 9.85409C91.3876 9.85409 90.5018 10.0727 89.927 10.682C89.3522 11.2913 89.1452 12.2213 89.1452 13.1435C89.1452 14.0658 89.3522 15.003 89.927 15.6046C90.5018 16.2061 91.3886 16.433 92.2666 16.433C93.1446 16.433 94.0313 16.2143 94.6071 15.6046C94.6863 15.5186 94.7587 15.4248 94.8301 15.331H97.1935C96.9855 16.0657 96.6585 16.7299 96.1639 17.2454C95.2057 18.2531 93.7281 18.6205 92.2666 18.6205C90.805 18.6205 89.3284 18.2609 88.3703 17.2454C87.4121 16.2299 87.0613 14.6828 87.0613 13.1435C87.0613 11.6043 87.4043 10.0494 88.3703 9.04168C89.3367 8.03396 90.806 7.66663 92.2666 7.66663C93.7272 7.66663 95.2057 8.02618 96.1639 9.04168C97.1298 10.0572 97.4729 11.6043 97.4729 13.1435L97.4733 13.1431Z" fill="currentColor"/>
+      <path d="M109.499 13.1431V13.9948H103.119V12.2996H107.351C107.256 11.6825 107.032 11.1043 106.632 10.682C106.057 10.0727 105.172 9.85409 104.293 9.85409C103.414 9.85409 102.528 10.0727 101.953 10.682C101.378 11.2913 101.17 12.2213 101.17 13.1435C101.17 14.0658 101.378 15.003 101.953 15.6046C102.528 16.2061 103.415 16.433 104.293 16.433C105.171 16.433 106.057 16.2143 106.632 15.6046C106.712 15.5186 106.784 15.4248 106.856 15.331H109.22C109.012 16.0657 108.685 16.7299 108.19 17.2454C107.231 18.2531 105.754 18.6205 104.293 18.6205C102.831 18.6205 101.355 18.2609 100.396 17.2454C99.4382 16.2299 99.0864 14.6828 99.0864 13.1435C99.0864 11.6043 99.4295 10.0494 100.396 9.04168C101.362 8.03396 102.832 7.66663 104.293 7.66663C105.754 7.66663 107.231 8.02618 108.19 9.04168C109.156 10.0572 109.499 11.6043 109.499 13.1435V13.1431Z" fill="currentColor"/>
+      <path d="M113.5 4.62817H111.104V18.6217H113.5V4.62817Z" fill="currentColor"/>
+      <path d="M117.589 12.8154L121.517 18.6208H118.554L114.625 12.8154L118.554 8.15088H121.517L117.589 12.8154Z" fill="currentColor"/>
+      <g clipPath="url(#dsh-wordmark-whale-clip)">
+        <path d="M23.0584 4.95203C22.8129 4.83203 22.7074 5.06103 22.5639 5.17704C22.5149 5.21454 22.4734 5.26354 22.4319 5.30854C22.0734 5.69155 21.6543 5.94306 21.1073 5.91306C20.3073 5.86806 19.6243 6.11957 19.0203 6.73158C18.8918 5.97706 18.4652 5.52655 17.8162 5.23754C17.4767 5.08753 17.1332 4.93703 16.8952 4.61052C16.7292 4.37801 16.6837 4.11901 16.6007 3.8635C16.5477 3.70949 16.4952 3.55199 16.3177 3.52549C16.1252 3.49549 16.0497 3.65699 15.9742 3.792C15.6722 4.34401 15.5552 4.95203 15.5667 5.56805C15.5932 6.95359 16.1782 8.05712 17.3407 8.84215C17.4727 8.93215 17.5067 9.02215 17.4652 9.15366C17.3857 9.42416 17.2917 9.68667 17.2087 9.95718C17.1557 10.1297 17.0767 10.1677 16.8917 10.0922C16.2537 9.82568 15.7027 9.43117 15.2156 8.95465C14.3891 8.15513 13.6416 7.2726 12.7096 6.58158C12.4906 6.42007 12.2716 6.27007 12.045 6.12707C11.094 5.20354 12.1696 4.44502 12.4186 4.35501C12.6791 4.26101 12.5091 3.938 11.6675 3.942C10.826 3.9455 10.056 4.22751 9.07446 4.60302C8.93096 4.65952 8.77995 4.70052 8.62545 4.73452C7.73492 4.56552 6.80989 4.52802 5.84386 4.63702C4.02481 4.83953 2.57177 5.69955 1.50373 7.1676C0.220694 8.93215 -0.0813148 10.9372 0.288196 13.0283C0.676708 15.2323 1.80174 17.0569 3.53029 18.4834C5.32285 19.9625 7.38741 20.6875 9.74298 20.5485C11.1735 20.466 12.7661 20.2745 14.5626 18.7539C15.0156 18.9795 15.4912 19.0695 16.2797 19.137C16.8872 19.1935 17.4722 19.107 17.9252 19.013C18.6347 18.8629 18.5857 18.2059 18.3292 18.0854C16.2497 17.1169 16.7062 17.5109 16.2912 17.1919C17.3477 15.9419 18.9618 13.7198 19.4598 10.6942C19.5088 10.3602 19.5713 9.88968 19.5638 9.61917C19.5598 9.45417 19.5978 9.39016 19.7863 9.37116C20.3073 9.31116 20.8128 9.16866 21.2773 8.91315C22.6249 8.17713 23.1684 6.96809 23.2964 5.51905C23.3154 5.29754 23.2924 5.06853 23.0584 4.95203ZM11.3165 17.9954C9.30097 16.4109 8.32344 15.8894 7.91992 15.9119C7.54241 15.9344 7.61042 16.3664 7.69342 16.6479C7.78042 16.9259 7.89342 17.1174 8.05193 17.3614C8.16143 17.5229 8.23694 17.7629 7.94243 17.9434C7.29341 18.3449 6.16487 17.8084 6.11187 17.7819C4.79833 17.0084 3.7003 15.9874 2.92628 14.5908C2.17875 13.2468 1.74474 11.8047 1.67324 10.2657C1.65424 9.89418 1.76374 9.76267 2.13375 9.69517C2.62077 9.60517 3.12278 9.58617 3.6093 9.65767C5.66636 9.95818 7.41741 10.8777 8.88545 12.3348C9.72348 13.1643 10.3575 14.1558 11.0105 15.1243C11.705 16.1529 12.4521 17.1329 13.4036 17.9364C13.7396 18.2179 14.0076 18.4319 14.2641 18.5899C13.4906 18.6764 12.1996 18.6949 11.3165 17.9964V17.9954ZM12.2826 11.7817C12.2826 11.6167 12.4146 11.4852 12.5806 11.4852C12.6181 11.4852 12.6521 11.4927 12.6826 11.5037C12.7241 11.5187 12.7621 11.5412 12.7921 11.5752C12.8451 11.6277 12.8751 11.7027 12.8751 11.7817C12.8751 11.9467 12.7431 12.0782 12.5771 12.0782C12.4111 12.0782 12.2826 11.9467 12.2826 11.7817ZM15.2831 13.3208C15.0906 13.3998 14.8981 13.4673 14.7131 13.4748C14.4261 13.4898 14.1131 13.3733 13.9431 13.2308C13.6791 13.0093 13.4901 12.8853 13.4111 12.4988C13.3771 12.3338 13.3961 12.0782 13.4261 11.9317C13.4941 11.6162 13.4186 11.4137 13.1961 11.2297C13.0151 11.0797 12.7846 11.0382 12.5316 11.0382C12.4371 11.0382 12.3506 10.9967 12.2861 10.9632C12.1806 10.9107 12.0936 10.7792 12.1766 10.6177C12.2031 10.5652 12.3316 10.4377 12.3616 10.4152C12.7051 10.2197 13.1011 10.2837 13.4676 10.4302C13.8071 10.5692 14.0641 10.8242 14.4336 11.1847C14.8111 11.6202 14.8791 11.7402 15.0941 12.0672C15.2641 12.3228 15.4186 12.5853 15.5247 12.8858C15.5887 13.0733 15.5057 13.2268 15.2831 13.3208Z" fill="currentColor"/>
+      </g>
+      <rect x="129.348" y="5.5" width="52" height="14" rx="2" fill="currentColor"/>
+      <g clipPath="url(#dsh-wordmark-badge-clip)">
+        <path d="M132.848 8.93205H134.08V16.137H132.848V8.93205ZM136.5 8.93205H137.732V16.137H136.5V8.93205ZM133.365 13.024V11.99H137.193V13.024H133.365Z" fill="var(--dsw-alias-label-primary-inverted)"/>
+        <path d="M140.397 14.432L140.672 13.453H143.202L143.532 14.432H140.397ZM140.287 16.137H139.055L141.277 8.93205H142.201L142.146 9.74605L140.947 13.915H140.969L140.287 16.137ZM145.039 16.137H143.741L143.07 13.948L143.081 13.937L141.871 9.74605L141.926 8.93205H142.817L145.039 16.137Z" fill="var(--dsw-alias-label-primary-inverted)"/>
+        <path d="M146.846 8.93205H149.068C149.852 8.93205 150.443 9.11538 150.839 9.48205C151.235 9.84138 151.433 10.3327 151.433 10.956C151.433 11.22 151.396 11.4657 151.323 11.693C151.249 11.9204 151.125 12.1257 150.949 12.309C150.773 12.4924 150.531 12.65 150.223 12.782C149.922 12.9067 149.541 13.0057 149.079 13.079V13.321H146.846V12.639L148.023 12.485C148.631 12.4044 149.09 12.298 149.398 12.166C149.706 12.034 149.915 11.8764 150.025 11.693C150.135 11.5024 150.19 11.2934 150.19 11.066C150.19 10.6994 150.083 10.417 149.871 10.219C149.658 10.021 149.324 9.92205 148.87 9.92205H146.846V8.93205ZM146.395 8.93205H147.627V16.137H146.395V8.93205ZM151.917 16.093V16.137H150.366L149.024 14.322C148.87 14.1094 148.73 13.9407 148.606 13.816C148.481 13.684 148.345 13.5887 148.199 13.53C148.052 13.464 147.872 13.42 147.66 13.398C147.447 13.3687 147.176 13.3504 146.846 13.343V13.145H149.079C149.233 13.211 149.368 13.2844 149.486 13.365C149.61 13.4457 149.735 13.5447 149.86 13.662C149.992 13.7794 150.138 13.937 150.3 14.135L151.917 16.093Z" fill="var(--dsw-alias-label-primary-inverted)"/>
+        <path d="M153.58 9.57005L153.591 8.93205H154.46L157.584 15.51V16.137H156.704L153.58 9.57005ZM158.024 16.137H156.968L156.88 8.93205H158.024V16.137ZM154.24 16.137H153.096V8.93205H154.152L154.24 16.137Z" fill="var(--dsw-alias-label-primary-inverted)"/>
+        <path d="M159.963 8.93205H161.206V16.137H159.963V8.93205ZM160.095 9.96605V8.93205H164.858V9.96605H160.095ZM160.095 16.137V15.103H164.902V16.137H160.095ZM160.095 13.013V11.99H164.374V13.013H160.095Z" fill="var(--dsw-alias-label-primary-inverted)"/>
+        <path d="M169.052 15.257C169.543 15.257 169.895 15.1654 170.108 14.982C170.328 14.7987 170.438 14.5457 170.438 14.223C170.438 14.047 170.405 13.8967 170.339 13.772C170.273 13.6474 170.152 13.5337 169.976 13.431C169.807 13.321 169.558 13.2147 169.228 13.112L168.491 12.881C167.846 12.6757 167.38 12.4044 167.094 12.067C166.808 11.7297 166.665 11.3007 166.665 10.78C166.665 10.428 166.76 10.1017 166.951 9.80105C167.142 9.50038 167.428 9.25838 167.809 9.07505C168.19 8.89172 168.663 8.80005 169.228 8.80005C169.631 8.80005 169.998 8.82938 170.328 8.88805C170.665 8.93938 171.039 9.01638 171.45 9.11905L171.274 10.175C170.834 10.0504 170.442 9.96238 170.097 9.91105C169.76 9.85238 169.463 9.82305 169.206 9.82305C168.737 9.82305 168.403 9.90738 168.205 10.076C168.007 10.2374 167.908 10.439 167.908 10.681C167.908 10.857 167.941 11.0147 168.007 11.154C168.073 11.286 168.19 11.407 168.359 11.517C168.535 11.627 168.784 11.7334 169.107 11.836L169.866 12.078C170.526 12.276 170.995 12.5327 171.274 12.848C171.553 13.156 171.692 13.585 171.692 14.135C171.692 14.5604 171.589 14.9344 171.384 15.257C171.179 15.5797 170.878 15.8327 170.482 16.016C170.093 16.1994 169.609 16.291 169.03 16.291C168.627 16.291 168.212 16.247 167.787 16.159C167.362 16.071 166.9 15.9427 166.401 15.774L166.665 14.718C167.156 14.894 167.6 15.0297 167.996 15.125C168.399 15.213 168.751 15.257 169.052 15.257Z" fill="var(--dsw-alias-label-primary-inverted)"/>
+        <path d="M175.809 15.257C176.3 15.257 176.652 15.1654 176.865 14.982C177.085 14.7987 177.195 14.5457 177.195 14.223C177.195 14.047 177.162 13.8967 177.096 13.772C177.03 13.6474 176.909 13.5337 176.733 13.431C176.564 13.321 176.315 13.2147 175.985 13.112L175.248 12.881C174.603 12.6757 174.137 12.4044 173.851 12.067C173.565 11.7297 173.422 11.3007 173.422 10.78C173.422 10.428 173.517 10.1017 173.708 9.80105C173.899 9.50038 174.185 9.25838 174.566 9.07505C174.947 8.89172 175.42 8.80005 175.985 8.80005C176.388 8.80005 176.755 8.82938 177.085 8.88805C177.422 8.93938 177.796 9.01638 178.207 9.11905L178.031 10.175C177.591 10.0504 177.199 9.96238 176.854 9.91105C176.517 9.85238 176.22 9.82305 175.963 9.82305C175.494 9.82305 175.16 9.90738 174.962 10.076C174.764 10.2374 174.665 10.439 174.665 10.681C174.665 10.857 174.698 11.0147 174.764 11.154C174.83 11.286 174.947 11.407 175.116 11.517C175.292 11.627 175.541 11.7334 175.864 11.836L176.623 12.078C177.283 12.276 177.752 12.5327 178.031 12.848C178.31 13.156 178.449 13.585 178.449 14.135C178.449 14.5604 178.346 14.9344 178.141 15.257C177.936 15.5797 177.635 15.8327 177.239 16.016C176.85 16.1994 176.366 16.291 175.787 16.291C175.384 16.291 174.969 16.247 174.544 16.159C174.119 16.071 173.657 15.9427 173.158 15.774L173.422 14.718C173.913 14.894 174.357 15.0297 174.753 15.125C175.156 15.213 175.508 15.257 175.809 15.257Z" fill="var(--dsw-alias-label-primary-inverted)"/>
+      </g>
+      <defs>
+        <clipPath id="dsh-wordmark-whale-clip">
+          <rect width="23.16" height="17.0435" fill="white" transform="translate(0.141602 3.52185)"/>
+        </clipPath>
+        <clipPath id="dsh-wordmark-badge-clip">
+          <rect width="46" height="14" fill="white" transform="translate(132.348 5.5)"/>
+        </clipPath>
+      </defs>
+    </svg>
+  )
+}
diff --git a/packages/client/ui-primitives/src/Button.module.css b/packages/client/ui-primitives/src/Button.module.css
index 1cb3b18194..3f415b5d15 100644
--- a/packages/client/ui-primitives/src/Button.module.css
+++ b/packages/client/ui-primitives/src/Button.module.css
@@ -56,6 +56,20 @@
   background: var(--dsw-alias-interactive-bg-active);
 }
 
+/* Dialog Cancel (figma 451:18655): bordered capsule on transparent fill. */
+.outline {
+  border: 1px solid var(--dsw-alias-border-l2);
+  background: transparent;
+}
+
+.outline:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.outline:disabled {
+  border-color: var(--dsw-alias-border-l1);
+}
+
 .toolbar {
   background: var(--dsw-alias-button-tool-bar-fill);
 }
diff --git a/packages/client/ui-primitives/src/Button.tsx b/packages/client/ui-primitives/src/Button.tsx
index 028c1fc266..642372868a 100644
--- a/packages/client/ui-primitives/src/Button.tsx
+++ b/packages/client/ui-primitives/src/Button.tsx
@@ -6,7 +6,7 @@ import clsx from 'clsx'
 import css from './Button.module.css'
 
 /** Visual variant, each backed by its --dsw-alias-button-* token family. */
-export type ButtonVariant = 'primary' | 'ghost' | 'toolbar'
+export type ButtonVariant = 'primary' | 'ghost' | 'outline' | 'toolbar'
 
 /**
  * Render a button.
diff --git a/packages/client/ui-primitives/src/Menu.module.css b/packages/client/ui-primitives/src/Menu.module.css
index 3e3bf85299..3cbcb62d29 100644
--- a/packages/client/ui-primitives/src/Menu.module.css
+++ b/packages/client/ui-primitives/src/Menu.module.css
@@ -3,21 +3,32 @@
   display: inline-flex;
 }
 
-/* Dropdown card (figma MenuDropdown 122:10096): white card, r12, no border,
- * layered drop shadows via the shadow token, 4px inset padding. */
+/* Dropdown card (figma MenuDropdown 122:9481 / 419:16920): menu surface,
+ * r12, inverted hairline border, shadow-lv3, 4px inset padding. */
+.list,
+.submenu {
+  padding: 4px;
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 12px;
+  background: var(--dsw-specific-menu);
+  box-shadow: var(--dsw-shadow-lv3);
+}
+
 .list {
   position: absolute;
   top: calc(100% + 4px);
   left: 0;
   z-index: 100;
   min-width: 130px;
-  padding: 4px;
-  display: flex;
-  flex-direction: column;
-  gap: 0;
-  border-radius: 12px;
-  background: var(--dsw-alias-bg-layer-1);
-  box-shadow: var(--dsw-shadow-lv2);
+}
+
+/* Open above the anchor (empty-state workspace chip: figma 122:9481). */
+.sideTop {
+  top: auto;
+  bottom: calc(100% + 4px);
 }
 
 .alignEnd {
@@ -25,12 +36,18 @@
   right: 0;
 }
 
-/* Menu cell (figma .Menu_cell 27:5169): r10, pad 10/8, 14/22 primary text,
+.itemWrap {
+  position: relative;
+}
+
+/* Menu cell (figma .Menu_cell): min-h 40, r10, pad 10/8, 14/22 primary,
  * gap 8 between leading icon / label / trailing check. */
 .item {
   display: flex;
   align-items: center;
   gap: 8px;
+  width: 100%;
+  min-height: 40px;
   padding: 8px 10px;
   border: none;
   border-radius: 10px;
@@ -51,9 +68,22 @@
   cursor: not-allowed;
 }
 
+.itemIcon {
+  display: inline-flex;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  align-items: center;
+  justify-content: center;
+  color: var(--dsw-alias-label-tertiary);
+}
+
 .itemLabel {
   flex: 1;
   min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 .check {
@@ -66,3 +96,34 @@
 .selected {
   background: transparent;
 }
+
+/* Separator cell (figma 122:9481): py 4 / px 2 around the hairline. */
+.separator {
+  height: 1px;
+  margin: 4px 2px;
+  background: var(--dsw-alias-border-l1);
+}
+
+/* Nested card to the right of the parent row (figma 419:16920).
+ * Bottom-aligned with the parent menu card (grows upward): itemWrap sits in
+ * .list's 4px pad, so bottom: -4px matches the list's outer bottom edge.
+ * Horizontal: list pad (4px) + 6px card gap = 10px past itemWrap — plain
+ * `100% + 6px` collapses to ~2px between outer card edges.
+ * ::before bridges the full gap so the pointer can cross without mouseLeave. */
+.submenu {
+  position: absolute;
+  top: auto;
+  bottom: -4px;
+  left: calc(100% + 10px);
+  z-index: 101;
+  min-width: 160px;
+}
+
+.submenu::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: -10px;
+  width: 10px;
+}
diff --git a/packages/client/ui-primitives/src/Menu.tsx b/packages/client/ui-primitives/src/Menu.tsx
index ad45acc221..0b07c26357 100644
--- a/packages/client/ui-primitives/src/Menu.tsx
+++ b/packages/client/ui-primitives/src/Menu.tsx
@@ -1,46 +1,69 @@
 // Menu: minimal controlled dropdown (group-by pickers, project selectors).
 // Pure CSS positioning relative to the anchor wrapper — no portal, no popper.
 // The owner controls `open`; outside-click closing uses one document listener
-// active only while open.
+// active only while open. Submenus open on hover/focus inside the same root.
 
-import { useEffect, useRef } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import clsx from 'clsx'
 import { IconCheckOutline16 } from './icons/index.tsx'
 import css from './Menu.module.css'
 
-/** One selectable menu row. */
+/** Selectable row (optionally with a nested submenu). */
 export interface MenuItem {
   id: string
   label: ReactNode
   disabled?: boolean
+  /** Leading icon (figma .Menu_cell gap 8). */
+  icon?: ReactNode
+  /** Nested card opened to the right on hover/focus. */
+  submenu?: readonly MenuItem[]
+}
+
+/** Hairline between item groups (not selectable). */
+export interface MenuSeparator {
+  type: 'separator'
+  id: string
+}
+
+/** One primary-menu entry: a row or a separator. */
+export type MenuEntry = MenuItem | MenuSeparator
+
+function isSeparator(entry: MenuEntry): entry is MenuSeparator {
+  return 'type' in entry && entry.type === 'separator'
 }
 
 /**
  * Render an anchored dropdown menu.
  * @param props.open - whether the list is showing (owner-controlled).
  * @param props.anchor - the trigger element (rendered in place).
- * @param props.items - selectable rows.
+ * @param props.items - selectable rows and optional separators.
  * @param props.selectedId - row shown as selected.
- * @param props.onSelect - row click callback (not called for disabled rows).
+ * @param props.onSelect - row click callback (not called for disabled rows or submenu parents that only open children).
  * @param props.onClose - invoked on outside click or Escape.
  * @param props.align - list alignment against the anchor (default 'start').
+ * @param props.side - open below (`bottom`, default) or above (`top`) the anchor.
  * @returns anchor wrapper with the conditional list.
  */
-export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align = 'start', className }: {
+export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align = 'start', side = 'bottom', className }: {
   open: boolean
   anchor: ReactNode
-  items: readonly MenuItem[]
+  items: readonly MenuEntry[]
   selectedId?: string
   onSelect: (id: string) => void
   onClose: () => void
   align?: 'start' | 'end'
+  side?: 'bottom' | 'top'
   className?: string
 }) {
   const rootRef = useRef<HTMLSpanElement>(null)
+  const [openSubmenuId, setOpenSubmenuId] = useState<string | null>(null)
 
   useEffect(() => {
-    if (!open) return
+    if (!open) {
+      setOpenSubmenuId(null)
+      return
+    }
     const onPointerDown = (e: PointerEvent) => {
       if (rootRef.current && e.target instanceof Node && !rootRef.current.contains(e.target)) onClose()
     }
@@ -59,21 +82,61 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align
     <span ref={rootRef} className={clsx(css.root, className)}>
       {anchor}
       {open && (
-        <div className={clsx(css.list, align === 'end' && css.alignEnd)} role="menu">
-          {items.map(item => (
-            <button
-              key={item.id}
-              type="button"
-              role="menuitem"
-              className={clsx(css.item, item.id === selectedId && css.selected)}
-              disabled={item.disabled}
-              onClick={() => onSelect(item.id)}
-            >
-              <span className={css.itemLabel}>{item.label}</span>
-              {/* Selection marker is a trailing check (figma .Menu_cell), not a fill. */}
-              {item.id === selectedId && <IconCheckOutline16 className={css.check} />}
-            </button>
-          ))}
+        <div className={clsx(css.list, side === 'top' && css.sideTop, align === 'end' && css.alignEnd)} role="menu">
+          {items.map(entry => {
+            if (isSeparator(entry)) {
+              return <div key={entry.id} className={css.separator} role="separator" />
+            }
+            const hasSub = entry.submenu !== undefined && entry.submenu.length > 0
+            const subOpen = hasSub && openSubmenuId === entry.id
+            return (
+              <div
+                key={entry.id}
+                className={css.itemWrap}
+                onMouseEnter={() => { setOpenSubmenuId(hasSub ? entry.id : null) }}
+                onMouseLeave={() => { setOpenSubmenuId(null) }}
+              >
+                <button
+                  type="button"
+                  role="menuitem"
+                  className={clsx(css.item, entry.id === selectedId && css.selected)}
+                  disabled={entry.disabled}
+                  aria-haspopup={hasSub ? 'menu' : undefined}
+                  aria-expanded={hasSub ? subOpen : undefined}
+                  onFocus={() => { setOpenSubmenuId(hasSub ? entry.id : null) }}
+                  onClick={() => {
+                    if (hasSub) {
+                      setOpenSubmenuId(entry.id)
+                      return
+                    }
+                    onSelect(entry.id)
+                  }}
+                >
+                  {entry.icon !== undefined && <span className={css.itemIcon}>{entry.icon}</span>}
+                  <span className={css.itemLabel}>{entry.label}</span>
+                  {/* Selection marker is a trailing check (figma .Menu_cell), not a fill. */}
+                  {entry.id === selectedId && <IconCheckOutline16 className={css.check} />}
+                </button>
+                {subOpen && entry.submenu !== undefined && (
+                  <div className={css.submenu} role="menu">
+                    {entry.submenu.map(sub => (
+                      <button
+                        key={sub.id}
+                        type="button"
+                        role="menuitem"
+                        className={css.item}
+                        disabled={sub.disabled}
+                        onClick={() => { onSelect(sub.id) }}
+                      >
+                        {sub.icon !== undefined && <span className={css.itemIcon}>{sub.icon}</span>}
+                        <span className={css.itemLabel}>{sub.label}</span>
+                      </button>
+                    ))}
+                  </div>
+                )}
+              </div>
+            )
+          })}
         </div>
       )}
     </span>
diff --git a/packages/client/ui-primitives/src/Modal.module.css b/packages/client/ui-primitives/src/Modal.module.css
new file mode 100644
index 0000000000..49026f7a5f
--- /dev/null
+++ b/packages/client/ui-primitives/src/Modal.module.css
@@ -0,0 +1,79 @@
+/* Full-viewport layer (figma Mask + Dialog 451:18655): mask + centered card. */
+.root {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+}
+
+/* User/spec mask: rgba(0,0,0,0.24) + blur(2px) via --dsw-alias-bg-mask-1 /
+   --dsw-mask-blur (light); dark theme raises mask opacity. */
+.mask {
+  position: absolute;
+  inset: 0;
+  background: var(--dsw-alias-bg-mask-1);
+  backdrop-filter: var(--dsw-mask-blur);
+}
+
+/* Dialog card: r24, shadow-lv3, layer-2 fill, inverted border, pb 24. */
+.dialog {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  width: min(380px, 100%);
+  padding: 0 0 24px;
+  overflow: hidden;
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 24px;
+  background: var(--dsw-alias-bg-layer-2);
+  box-shadow: var(--dsw-shadow-lv3);
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+/* Header pad (figma Title row): pt 22 / pl 24 / pr 14 / pb 12. */
+.header {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 22px 14px 12px 24px;
+}
+
+.title {
+  margin: 0;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+.description {
+  margin: 0;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  padding: 0 24px;
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  padding: 0 24px;
+}
diff --git a/packages/client/ui-primitives/src/Modal.tsx b/packages/client/ui-primitives/src/Modal.tsx
new file mode 100644
index 0000000000..cdbe1060bf
--- /dev/null
+++ b/packages/client/ui-primitives/src/Modal.tsx
@@ -0,0 +1,62 @@
+// Modal: controlled full-viewport dialog (create-workspace and similar).
+// Fixed overlay in the React tree (no react-dom portal) so ui-primitives
+// stays free of a react-dom dependency; mask tokens match figma 451:18655.
+
+import { useEffect } from 'react'
+import type { ReactNode } from 'react'
+import clsx from 'clsx'
+import css from './Modal.module.css'
+
+/**
+ * Render a centered modal over a blurred page mask.
+ * @param props.open - whether the dialog is showing.
+ * @param props.onClose - Escape or mask click.
+ * @param props.title - dialog heading.
+ * @param props.description - optional supporting sentence under the title.
+ * @param props.children - body (inputs, etc.).
+ * @param props.footer - action row (Cancel / Create).
+ * @returns null when closed; otherwise the overlay tree.
+ */
+export function Modal({ open, onClose, title, description, children, footer, className }: {
+  open: boolean
+  onClose: () => void
+  title: string
+  description?: string
+  children?: ReactNode
+  footer?: ReactNode
+  className?: string
+}) {
+  useEffect(() => {
+    if (!open) return
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', onKeyDown)
+    return () => { document.removeEventListener('keydown', onKeyDown) }
+  }, [open, onClose])
+
+  if (!open) return null
+
+  return (
+    <div className={css.root} role="presentation">
+      <div className={css.mask} aria-hidden="true" onClick={onClose} />
+      <div
+        className={clsx(css.dialog, className)}
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+      >
+        <div className={css.content}>
+          <div className={css.header}>
+            <h2 className={css.title}>{title}</h2>
+            {description !== undefined && description !== '' && (
+              <p className={css.description}>{description}</p>
+            )}
+          </div>
+          {children !== undefined && <div className={css.body}>{children}</div>}
+        </div>
+        {footer !== undefined && <div className={css.footer}>{footer}</div>}
+      </div>
+    </div>
+  )
+}
diff --git a/packages/client/ui-primitives/src/Tooltip.module.css b/packages/client/ui-primitives/src/Tooltip.module.css
new file mode 100644
index 0000000000..5853531bd4
--- /dev/null
+++ b/packages/client/ui-primitives/src/Tooltip.module.css
@@ -0,0 +1,38 @@
+/* Visual spec mirrors deepsuite @deepseek/ui Tooltip.css (size m, no arrow),
+   except padding tightened 6/12 -> 4/8 and radius 10 -> 8 by product ruling:
+   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. */
+
+.bubble {
+  position: fixed;
+  z-index: 100;
+  padding: 4px 8px;
+  border-radius: 8px;
+  background: var(--dsw-alias-tooltip-bg);
+  color: var(--dsw-static-neutral-bluish-00);
+  font-size: 14px;
+  line-height: 22px;
+  white-space: nowrap;
+  pointer-events: none;
+  animation: tooltip-in 150ms var(--ds-ease-in-out);
+}
+
+.bubble[data-side='right'] {
+  transform: translateY(-50%);
+}
+
+.bubble[data-side='bottom'] {
+  transform: translateX(-50%);
+}
+
+@keyframes tooltip-in {
+  from { opacity: 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bubble {
+    animation: none;
+  }
+}
diff --git a/packages/client/ui-primitives/src/Tooltip.tsx b/packages/client/ui-primitives/src/Tooltip.tsx
new file mode 100644
index 0000000000..f62a397535
--- /dev/null
+++ b/packages/client/ui-primitives/src/Tooltip.tsx
@@ -0,0 +1,77 @@
+// Hover/focus label bubble (figma tooltip pill: dark plate, white text).
+// TODO: interaction is a placeholder (no show delay, no flip on viewport
+// collision, no arrow) — visuals and behavior get a proper pass later.
+// The anchor is the child element itself (cloneElement, no wrapper node), so
+// attaching a tooltip never changes the anchor's layout context. The bubble is
+// position:fixed and coordinates come from the anchor's rect at show time, so
+// it escapes ancestor overflow clipping (the sidebar rail clips its column)
+// without a portal.
+
+import { cloneElement, useEffect, useRef, useState } from 'react'
+import type { FocusEventHandler, MouseEventHandler, ReactElement, Ref } from 'react'
+import css from './Tooltip.module.css'
+
+/** Bubble placement relative to the anchor. */
+export type TooltipSide = 'right' | 'bottom'
+
+/** Props Tooltip injects into its anchor child; the child's own handlers are chained ahead of the tooltip's. */
+interface AnchorProps {
+  ref?: Ref<HTMLElement> | undefined
+  onMouseEnter?: MouseEventHandler | undefined
+  onMouseLeave?: MouseEventHandler | undefined
+  onFocus?: FocusEventHandler | undefined
+  onBlur?: FocusEventHandler | undefined
+}
+
+/**
+ * Attach a hover/focus tooltip to an anchor element.
+ * @param props.label - bubble text.
+ * @param props.side - placement relative to the anchor (default 'right').
+ * @param props.disabled - suppress the bubble while true; the anchor renders identically so toggling never remounts it (which would cut its CSS transitions).
+ * @param props.children - a single anchor element. Tooltip owns its ref (no current consumer passes one).
+ * @returns the cloned anchor plus a fixed-position bubble while hovered/focused.
+ */
+export function Tooltip({ label, side = 'right', disabled = false, children }: { label: string; side?: TooltipSide; disabled?: boolean; children: ReactElement<AnchorProps> }) {
+  const anchor = useRef<HTMLElement | null>(null)
+  const [pos, setPos] = useState<{ x: number; y: number } | null>(null)
+  // Hover and focus are independent triggers: the bubble hides only after
+  // BOTH clear (hovering away from a focused anchor must not drop it).
+  const triggers = useRef({ hover: false, focus: false })
+
+  // Disabling mid-hover (e.g. clicking a rail control expands the sidebar)
+  // must drop an already-visible bubble: no mouseleave fires.
+  useEffect(() => {
+    if (disabled) { triggers.current = { hover: false, focus: false }; setPos(null) }
+  }, [disabled])
+
+  const show = () => {
+    if (disabled) return
+    const el = anchor.current
+    /* v8 ignore next -- the ref is attached by event time: events fire on the cloned anchor. */
+    if (el === null) return
+    const r = el.getBoundingClientRect()
+    setPos(side === 'right'
+      ? { x: r.right + 10, y: r.top + r.height / 2 }
+      : { x: r.left + r.width / 2, y: r.bottom + 8 })
+  }
+  const hide = () => {
+    if (!triggers.current.hover && !triggers.current.focus) setPos(null)
+  }
+
+  return (
+    <>
+      {cloneElement(children, {
+        ref: anchor,
+        onMouseEnter: (e) => { children.props.onMouseEnter?.(e); triggers.current.hover = true; show() },
+        onMouseLeave: (e) => { children.props.onMouseLeave?.(e); triggers.current.hover = false; hide() },
+        onFocus: (e) => { children.props.onFocus?.(e); triggers.current.focus = true; show() },
+        onBlur: (e) => { children.props.onBlur?.(e); triggers.current.focus = false; hide() },
+      })}
+      {pos !== null && (
+        <span className={css.bubble} data-side={side} style={{ left: pos.x, top: pos.y }} role="tooltip">
+          {label}
+        </span>
+      )}
+    </>
+  )
+}
diff --git a/packages/client/ui-primitives/src/icons/index.tsx b/packages/client/ui-primitives/src/icons/index.tsx
index 4f35833fb6..80bb3848dd 100644
--- a/packages/client/ui-primitives/src/icons/index.tsx
+++ b/packages/client/ui-primitives/src/icons/index.tsx
@@ -165,6 +165,16 @@ export const IconChevronRightOutline14 = ({ size = 14, className }: IconProps) =
   </svg>
 )
 
+/** ic_ds_triangle_right_fill_14 — tree expand arrow; points right, consumers rotate it 90° for the open state. */
+export const IconTriangleRightFill14 = ({ 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">
+    <path
+      d="M4.25 2.82782L4.25 11.1722C4.25 11.6622 4.84243 11.9076 5.18891 11.5611L9.36109 7.38891C9.57588 7.17412 9.57588 6.82588 9.36109 6.61109L5.18891 2.43891C4.84243 2.09243 4.25 2.33782 4.25 2.82782Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
 /** ic_ds_chevron_up_outline_14 */
 export const IconChevronUpOutline14 = ({ 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">
@@ -552,11 +562,11 @@ export const IconProjectAddOutline16 = ({ size = 16, className }: IconProps) =>
     </svg>
 )
 
-/** folder_open_16 (figma extract) */
+/** folder_open_16 (figma extract): outline at full ink + 20%-opacity inner fill riding the same currentColor. */
 export const IconFolderOpen16 = ({ size = 16, className }: IconProps) => (
   <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none">
-    <path transform="translate(0.5996 1.645)" d="M4.69624 0C5.3113 0.000140941 5.88623 0.307626 6.22749 0.819336L6.69917 1.52734C6.78449 1.65523 6.92823 1.7324 7.08198 1.73242L11.6699 1.73242C13.0038 1.73257 14.0859 2.81452 14.0859 4.14844L14.0859 5.05566C14.7693 5.4559 15.1595 6.2791 14.9374 7.11621L13.8837 11.0869C13.6026 12.1454 12.644 12.8818 11.5488 12.8818L2.41596 12.8818C1.01395 12.8816 -0.0511855 11.7074 0.00190073 10.376L0.00190073 2.41602C0.00190073 1.08201 1.08391 0 2.41792 0L4.69624 0ZM3.27827 6.18457C2.80902 6.18474 2.39772 6.50054 2.27729 6.9541L1.41499 10.2012C1.2407 10.8579 1.73653 11.5017 2.41596 11.502L11.5488 11.502C12.0182 11.502 12.4293 11.1861 12.5498 10.7324L13.6035 6.7627C13.681 6.47081 13.4611 6.18474 13.1591 6.18457L3.27827 6.18457ZM2.41792 1.38086C1.8462 1.38086 1.38276 1.8443 1.38276 2.41602L1.38276 5.72266C1.83056 5.15603 2.52166 4.80383 3.27827 4.80371L12.705 4.80371L12.705 4.14844C12.705 3.57681 12.2415 3.11342 11.6699 3.11328L7.08198 3.11328C6.46674 3.11326 5.89205 2.80484 5.55073 2.29297L5.07905 1.58496C4.99378 1.45723 4.84981 1.381 4.69624 1.38086L2.41792 1.38086Z" fill="currentColor"/>
-    <path transform="translate(1.979 3.026)" d="M11.7793 4.80371C12.0811 4.80388 12.3008 5.09009 12.2236 5.38184L11.1699 9.35156C11.0494 9.80525 10.6383 10.1211 10.1689 10.1211L1.03612 10.1211C0.356864 10.1206 -0.139141 9.47695 0.0351403 8.82031L0.897445 5.57324C1.01797 5.12 1.42946 4.80406 1.89842 4.80371L11.7793 4.80371ZM3.31639 0C3.46985 0.000107244 3.61388 0.0765707 3.6992 0.204102L4.17088 0.912109C4.51213 1.42391 5.08701 1.73228 5.70213 1.73242L10.29 1.73242C10.8616 1.73251 11.325 2.19605 11.3252 2.76758L11.3252 3.42285L1.89842 3.42285C1.14203 3.42309 0.450638 3.77535 0.00291371 4.3418L0.00291371 1.03516C0.00307753 0.463694 0.466614 0.000188756 1.03807 0L3.31639 0Z" fill="currentColor"/>
+    <path d="M5.19629 1.57104C5.81144 1.5711 6.38623 1.8786 6.72754 2.39038L7.19922 3.09839C7.28454 3.22635 7.42824 3.30344 7.58203 3.30347H12.1699C13.5039 3.30348 14.5859 4.38548 14.5859 5.71948V6.62671C15.2694 7.02689 15.6605 7.85012 15.4385 8.68726L14.3848 12.658C14.1037 13.7164 13.1449 14.4527 12.0498 14.4529H2.91699C1.51651 14.4529 0.451662 13.2814 0.501954 11.9519V3.98706C0.501954 2.65305 1.58396 1.57104 2.91797 1.57104H5.19629ZM3.7793 7.75562C3.30994 7.75562 2.89883 8.07153 2.77832 8.52515L1.91602 11.7722C1.74167 12.4291 2.23734 13.073 2.91699 13.073H12.0498C12.5191 13.0728 12.9304 12.757 13.0508 12.3035L14.1045 8.33374C14.1819 8.04202 13.9619 7.756 13.6602 7.75562H3.7793ZM2.91797 2.9519C2.34625 2.9519 1.88281 3.41534 1.88281 3.98706V7.2937C2.33068 6.7269 3.02249 6.37476 3.7793 6.37476H13.2051V5.71948C13.2051 5.14777 12.7416 4.68434 12.1699 4.68433H7.58203C6.96675 4.6843 6.39209 4.37595 6.05078 3.86401L5.5791 3.15601C5.49379 3.02821 5.34995 2.95196 5.19629 2.9519H2.91797Z" fill="currentColor"/>
+    <path opacity="0.2" d="M13.6602 7.75525C13.9618 7.7556 14.1815 8.04179 14.1045 8.33337L13.0508 12.3031C12.9304 12.7567 12.5191 13.0725 12.0498 13.0726H2.91701C2.23744 13.0725 1.7417 12.4287 1.91603 11.7719L2.77834 8.52478C2.89898 8.07146 3.31018 7.75532 3.77931 7.75525H13.6602ZM5.1963 2.95154C5.34985 2.95159 5.49377 3.02803 5.57912 3.15564L6.0508 3.86365C6.39205 4.37553 6.96685 4.68385 7.58205 4.68396H12.1699C12.7416 4.68396 13.2049 5.14754 13.2051 5.71912V6.37439H3.77931C3.02267 6.37444 2.33067 6.72671 1.88283 7.29333V3.98669C1.88299 3.4152 2.34649 2.95168 2.91798 2.95154H5.1963Z" fill="currentColor"/>
     </svg>
 )
 
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index daea4202b3..0d6cde4ed0 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Pure React atoms (zero cordis): StateDot, icons, Button/Pill/Menu/Input,
+ * Pure React atoms (zero cordis): StateDot, icons, Button/Pill/Menu/Modal/Input,
  * markdown family, ConnectionBanner. Everything consumes props plus --dsw-*
  * token vars only. Contract: api-contracts v3 section 8.
  */
@@ -11,9 +11,14 @@ export type { ButtonVariant } from './Button.tsx'
 export { Pill } from './Pill.tsx'
 export { Input } from './Input.tsx'
 export { Menu } from './Menu.tsx'
-export type { MenuItem } from './Menu.tsx'
+export type { MenuEntry, MenuItem, MenuSeparator } from './Menu.tsx'
+export { Modal } from './Modal.tsx'
 export { ConnectionBanner } from './ConnectionBanner.tsx'
 export { FishLogo } from './FishLogo.tsx'
+export { BrandWordmark } from './BrandWordmark.tsx'
+export { Tooltip } from './Tooltip.tsx'
+export type { TooltipSide } from './Tooltip.tsx'
 export { JsonBlock } from './markdown/JsonBlock.tsx'
+export { MarkdownText } from './markdown/MarkdownText.tsx'
 export { MessageText } from './markdown/MessageText.tsx'
 export * from './icons/index.tsx'
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
new file mode 100644
index 0000000000..36b1dc2b55
--- /dev/null
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -0,0 +1,123 @@
+.markdown {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 12px;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-markdown-base);
+}
+
+.markdown :where(h1, h2, h3, h4, h5, h6, p, ul, ol, blockquote, pre, hr) {
+  margin: 0;
+}
+
+.markdown h1 {
+  font: var(--dsw-font-markdown-h1);
+}
+
+.markdown h2 {
+  font: var(--dsw-font-markdown-h2);
+}
+
+.markdown h3 {
+  font: var(--dsw-font-markdown-h3);
+}
+
+.markdown :where(h4, h5, h6) {
+  font: var(--dsw-font-markdown-h4);
+}
+
+.markdown :where(strong, th) {
+  font-weight: var(--dsw-font-markdown-base-strong-font-weight);
+}
+
+.markdown :where(ul, ol) {
+  padding-inline-start: 24px;
+}
+
+.markdown li + li {
+  margin-block-start: 4px;
+}
+
+.markdown li > :where(ul, ol) {
+  margin-block-start: 4px;
+}
+
+.markdown blockquote {
+  padding-inline-start: 12px;
+  border-inline-start: 3px solid var(--dsw-alias-markdown-citation);
+  color: var(--dsw-alias-label-secondary);
+}
+
+.markdown a {
+  color: var(--dsw-alias-state-business-primary);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.markdown :not(pre) > code {
+  padding: 2px 4px;
+  border-radius: 4px;
+  background: var(--dsw-alias-markdown-inline-code);
+  font: var(--dsw-font-markdown-code);
+}
+
+.markdown pre {
+  max-width: 100%;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  padding: 12px 16px;
+  border-radius: 8px;
+  background: var(--dsw-alias-markdown-code-block);
+  font: var(--dsw-font-markdown-code-block);
+}
+
+.markdown pre code {
+  padding: 0;
+  background: transparent;
+  font: inherit;
+  overflow-wrap: normal;
+  word-break: normal;
+  white-space: pre;
+}
+
+.markdown hr {
+  width: 100%;
+  border: 0;
+  border-block-start: 1px solid var(--dsw-alias-markdown-citation);
+}
+
+.markdown input[type='checkbox'] {
+  margin: 0 8px 0 0;
+  accent-color: var(--dsw-alias-state-business-primary);
+}
+
+.tableScroll {
+  max-width: 100%;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+}
+
+.tableScroll table {
+  width: max-content;
+  min-width: 100%;
+  border-collapse: collapse;
+  font: var(--dsw-font-markdown-table);
+}
+
+.tableScroll :where(th, td) {
+  padding: 6px 12px;
+  border: 1px solid var(--dsw-alias-markdown-citation);
+  text-align: start;
+  white-space: nowrap;
+}
+
+.tableScroll th {
+  background: var(--dsw-alias-markdown-code-block-banner);
+  font: var(--dsw-font-markdown-table-head);
+}
+
+.imageAlt {
+  color: var(--dsw-alias-label-tertiary);
+  font-style: italic;
+}
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
new file mode 100644
index 0000000000..425e3969ab
--- /dev/null
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
@@ -0,0 +1,64 @@
+import ReactMarkdown from 'react-markdown'
+import type { Components, UrlTransform } from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+import css from './MarkdownText.module.css'
+
+const remarkPlugins = [remarkGfm]
+
+function sanitizeUrl(url: string): string {
+  try {
+    switch (new URL(url).protocol) {
+      case 'http:':
+      case 'https:':
+      case 'mailto:':
+        return url
+      default:
+        return ''
+    }
+  } catch {
+    return ''
+  }
+}
+
+const safeUrl: UrlTransform = url => sanitizeUrl(url)
+
+const components: Components = {
+  a: ({ href = '', children }) => {
+    const safeHref = sanitizeUrl(href)
+    if (safeHref === '') return <>{children}</>
+    const external = ['http:', 'https:'].includes(new URL(safeHref).protocol)
+    return (
+      <a
+        href={safeHref}
+        {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+      >
+        {children}
+      </a>
+    )
+  },
+  img: ({ alt = '' }) => <span className={css.imageAlt}>{alt}</span>,
+  table: ({ children }) => (
+    <div className={css.tableScroll}>
+      <table>{children}</table>
+    </div>
+  ),
+}
+
+/**
+ * Render untrusted assistant-authored Markdown as semantic React elements.
+ * @param props - Markdown source text preserved by the session projection.
+ * @returns A GFM document with raw HTML, relative links, unsafe protocols, and remote images disabled.
+ */
+export function MarkdownText({ text }: { text: string }) {
+  return (
+    <div className={css.markdown}>
+      <ReactMarkdown
+        remarkPlugins={remarkPlugins}
+        components={components}
+        urlTransform={safeUrl}
+      >
+        {text}
+      </ReactMarkdown>
+    </div>
+  )
+}
diff --git a/packages/client/ui-primitives/src/markdown/MessageText.tsx b/packages/client/ui-primitives/src/markdown/MessageText.tsx
index e9fa76d823..cafe9ab3c0 100644
--- a/packages/client/ui-primitives/src/markdown/MessageText.tsx
+++ b/packages/client/ui-primitives/src/markdown/MessageText.tsx
@@ -1,4 +1,4 @@
-// MessageText: the single text-block rendering point (Markdown support later = swap this component's internals, zero card-structure changes).
+// MessageText is the literal-text primitive for user and steering content; assistant output uses MarkdownText.
 
 import css from './MessageText.module.css'
 
diff --git a/packages/client/ui-primitives/tests/atoms.spec.tsx b/packages/client/ui-primitives/tests/atoms.spec.tsx
index f259cb334a..a4b286ced7 100644
--- a/packages/client/ui-primitives/tests/atoms.spec.tsx
+++ b/packages/client/ui-primitives/tests/atoms.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { Button, ConnectionBanner, Input, Menu, Pill } from '@deepseek-ai/dsh-client-ui-primitives'
+import { Button, ConnectionBanner, Input, Menu, Modal, Pill } from '@deepseek-ai/dsh-client-ui-primitives'
 
 afterEach(cleanup)
 
@@ -21,6 +21,11 @@ describe('Button', () => {
     fireEvent.click(screen.getByRole('button'))
     expect(onClick).not.toHaveBeenCalled()
   })
+
+  it('outline variant renders a bordered cancel-style button', () => {
+    render(<Button variant="outline">Cancel</Button>)
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeDefined()
+  })
 })
 
 describe('Pill', () => {
@@ -91,11 +96,12 @@ describe('Menu', () => {
     expect(onClose).not.toHaveBeenCalled()
   })
 
-  it('selected item shows the trailing check; align=end and className apply', () => {
+  it('selected item shows the trailing check; align=end, side=top, and className apply', () => {
     const { container } = render(
       <Menu
         open
         align="end"
+        side="top"
         className="x"
         anchor={<span>trigger</span>}
         items={items}
@@ -104,12 +110,89 @@ describe('Menu', () => {
         onClose={() => {}}
       />)
     expect((container.firstElementChild as HTMLElement).classList.contains('x')).toBe(true)
+    const menu = screen.getByRole('menu')
+    expect(menu.className).toMatch(/sideTop|alignEnd/)
     const selected = screen.getByRole('menuitem', { name: 'Alpha' })
     expect(selected.querySelector('svg')).not.toBeNull()
     const other = screen.getByRole('menuitem', { name: 'Beta' })
     expect(other.querySelector('svg')).toBeNull()
     fireEvent.keyDown(document, { key: 'a' })
   })
+
+  it('renders a leading icon and a separator between groups', () => {
+    render(
+      <Menu
+        open
+        anchor={<span>trigger</span>}
+        items={[
+          { id: 'a', label: 'Alpha', icon: <svg data-testid="ic" /> },
+          { type: 'separator', id: 's1' },
+          { id: 'c', label: 'Create' },
+        ]}
+        onSelect={() => {}}
+        onClose={() => {}}
+      />)
+    expect(screen.getByTestId('ic')).toBeDefined()
+    expect(screen.getByRole('separator')).toBeDefined()
+  })
+
+  it('opens a submenu on hover and selects a nested item', () => {
+    const onSelect = vi.fn()
+    render(
+      <Menu
+        open
+        anchor={<span>trigger</span>}
+        items={[
+          { id: 'plain', label: 'Plain' },
+          {
+            id: 'new',
+            label: 'New Workspace',
+            submenu: [
+              { id: 'ok', label: 'Create ok', icon: <svg data-testid="sub-ic" /> },
+            ],
+          },
+        ]}
+        onSelect={onSelect}
+        onClose={() => {}}
+      />)
+    const plain = screen.getByRole('menuitem', { name: 'Plain' })
+    fireEvent.mouseEnter(plain.parentElement as HTMLElement)
+    fireEvent.focus(plain)
+    const parent = screen.getByRole('menuitem', { name: 'New Workspace' })
+    const wrap = parent.parentElement as HTMLElement
+    fireEvent.click(parent)
+    expect(onSelect).not.toHaveBeenCalled()
+    fireEvent.focus(parent)
+    fireEvent.mouseEnter(wrap)
+    expect(screen.getByTestId('sub-ic')).toBeDefined()
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Create ok' }))
+    expect(onSelect).toHaveBeenCalledWith('ok')
+    fireEvent.mouseLeave(wrap)
+    expect(screen.queryByRole('menuitem', { name: 'Create ok' })).toBeNull()
+  })
+})
+
+describe('Modal', () => {
+  it('is absent while closed; Escape and mask click call onClose', () => {
+    const onClose = vi.fn()
+    const { rerender } = render(
+      <Modal open={false} onClose={onClose} title="Create new workspace">body</Modal>)
+    expect(screen.queryByRole('dialog')).toBeNull()
+    rerender(
+      <Modal open onClose={onClose} title="Create new workspace" description="Name it." footer={<button type="button">Create</button>}>
+        <input aria-label="name" />
+      </Modal>)
+    expect(screen.getByRole('dialog', { name: 'Create new workspace' })).toBeDefined()
+    expect(screen.getByText('Name it.')).toBeDefined()
+    fireEvent.keyDown(document, { key: 'a' })
+    expect(onClose).not.toHaveBeenCalled()
+    fireEvent.keyDown(document, { key: 'Escape' })
+    expect(onClose).toHaveBeenCalledTimes(1)
+    // Mask is the presentation sibling behind the dialog.
+    const mask = document.querySelector('[aria-hidden="true"]') as HTMLElement
+    fireEvent.click(mask)
+    expect(onClose).toHaveBeenCalledTimes(2)
+  })
 })
 
 describe('ConnectionBanner', () => {
diff --git a/packages/client/ui-primitives/tests/icons.spec.tsx b/packages/client/ui-primitives/tests/icons.spec.tsx
index ee396af4f5..74bf5a9678 100644
--- a/packages/client/ui-primitives/tests/icons.spec.tsx
+++ b/packages/client/ui-primitives/tests/icons.spec.tsx
@@ -14,8 +14,8 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('ic_ds_ icon set', () => {
-  it('exports the full P-I set (43 deepsuite + 6 figma extracts)', () => {
-    expect(iconNames.length).toBe(49)
+  it('exports the full P-I set (43 deepsuite + 7 figma extracts)', () => {
+    expect(iconNames.length).toBe(50)
   })
 
   it.each(iconNames)('%s renders an svg with currentColor fills and no hardcoded palette', name => {
diff --git a/packages/client/ui-primitives/tests/markdown.spec.tsx b/packages/client/ui-primitives/tests/markdown.spec.tsx
index 6cfb5f4e8e..4e1dc292d4 100644
--- a/packages/client/ui-primitives/tests/markdown.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown.spec.tsx
@@ -1,14 +1,93 @@
 // @vitest-environment jsdom
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it } from 'vitest'
-import { JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
+import { JsonBlock, MarkdownText, MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
 
 afterEach(cleanup)
 
 describe('MessageText', () => {
   it('renders the text verbatim', () => {
-    const { container } = render(<MessageText text={'line1\nline2'} />)
-    expect(container.textContent).toBe('line1\nline2')
+    const { container } = render(<MessageText text={'# line1\n`line2`'} />)
+    expect(container.textContent).toBe('# line1\n`line2`')
+    expect(container.querySelector('h1')).toBeNull()
+  })
+})
+
+describe('MarkdownText', () => {
+  it('renders CommonMark and GFM elements as semantic DOM', () => {
+    const markdown = [
+      '# Heading',
+      '',
+      'Paragraph with **strong**, *emphasis*, ~~deleted~~, `inline`, and [safe](https://example.com).  ',
+      'Hard break.',
+      '',
+      '> Quote',
+      '',
+      '- parent',
+      '  - child',
+      '',
+      '1. first',
+      '2. second',
+      '',
+      '- [x] done',
+      '- [ ] pending',
+      '',
+      '| Name | Value |',
+      '| --- | --- |',
+      '| alpha | beta |',
+      '',
+      '---',
+      '',
+      '```ts',
+      'const answer = 42',
+      '```',
+      '',
+      '<https://deepseek.com>',
+    ].join('\n')
+    const { container } = render(<MarkdownText text={markdown} />)
+
+    expect(screen.getByRole('heading', { level: 1, name: 'Heading' })).toBeTruthy()
+    expect(container.querySelector('strong')?.textContent).toBe('strong')
+    expect(container.querySelector('em')?.textContent).toBe('emphasis')
+    expect(container.querySelector('del')?.textContent).toBe('deleted')
+    expect(container.querySelector('blockquote')?.textContent?.trim()).toBe('Quote')
+    expect(container.querySelectorAll('ul')).toHaveLength(3)
+    expect(container.querySelector('ol')).not.toBeNull()
+    expect(container.querySelectorAll('input[type="checkbox"]')).toHaveLength(2)
+    expect(container.querySelector('table')?.textContent).toContain('alphabeta')
+    expect(container.querySelector('hr')).not.toBeNull()
+    expect(container.querySelector('pre code')?.textContent).toContain('const answer = 42')
+    expect(container.querySelector('br')).not.toBeNull()
+    expect(screen.getByRole('link', { name: 'safe' }).getAttribute('target')).toBe('_blank')
+    expect(screen.getByRole('link', { name: 'https://deepseek.com' })).toBeTruthy()
+  })
+
+  it('neutralizes raw HTML, unsafe or relative links, and remote images', () => {
+    const markdown = [
+      '<script>globalThis.compromised = true</script>',
+      '<img src="x" onerror="globalThis.compromised = true">',
+      '[script](javascript:alert(1)) [relative](/settings)',
+      '[mail](mailto:dev@example.com) [web](http://example.com) [upper](HTTPS://example.com)',
+      '![remote diagram](https://example.com/private.png)',
+    ].join('\n\n')
+    const { container } = render(<MarkdownText text={markdown} />)
+
+    expect(container.querySelector('script')).toBeNull()
+    expect(container.querySelector('img')).toBeNull()
+    const neutralized = [...container.querySelectorAll('p')]
+      .find(paragraph => paragraph.textContent === 'script relative')
+    expect(neutralized?.querySelector('a')).toBeNull()
+    expect(screen.getByRole('link', { name: 'mail' }).getAttribute('target')).toBeNull()
+    expect(screen.getByRole('link', { name: 'web' }).getAttribute('rel')).toBe('noopener noreferrer')
+    expect(screen.getByRole('link', { name: 'upper' }).getAttribute('target')).toBe('_blank')
+    expect(screen.getByText('remote diagram')).toBeTruthy()
+  })
+
+  it('keeps incomplete streaming Markdown renderable', () => {
+    const { container } = render(<MarkdownText text={'## Streaming\n\n- first\n- **unfinished'} />)
+    expect(screen.getByRole('heading', { level: 2, name: 'Streaming' })).toBeTruthy()
+    expect(container.querySelectorAll('li')).toHaveLength(2)
+    expect(screen.getByText('**unfinished')).toBeTruthy()
   })
 })
 
diff --git a/packages/client/ui-primitives/tests/tooltip.spec.tsx b/packages/client/ui-primitives/tests/tooltip.spec.tsx
new file mode 100644
index 0000000000..3b3af8373c
--- /dev/null
+++ b/packages/client/ui-primitives/tests/tooltip.spec.tsx
@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
+
+afterEach(cleanup)
+
+describe('Tooltip', () => {
+  it('shows the bubble to the right on hover and hides it on leave', () => {
+    render(
+      <Tooltip label="Open sidebar">
+        <button type="button">anchor</button>
+      </Tooltip>,
+    )
+    const anchor = screen.getByText('anchor')
+    fireEvent.mouseEnter(anchor)
+    const bubble = screen.getByRole('tooltip')
+    expect(bubble.textContent).toBe('Open sidebar')
+    expect(bubble.getAttribute('data-side')).toBe('right')
+    // jsdom rects are all-zero: right placement lands at the +10 gutter.
+    expect(bubble.style.left).toBe('10px')
+    expect(bubble.style.top).toBe('0px')
+    fireEvent.mouseLeave(anchor)
+    expect(screen.queryByRole('tooltip')).toBeNull()
+  })
+
+  it('supports bottom placement and the focus/blur channel', () => {
+    render(
+      <Tooltip label="Below" side="bottom">
+        <button type="button">anchor</button>
+      </Tooltip>,
+    )
+    const anchor = screen.getByText('anchor')
+    fireEvent.focus(anchor)
+    const bubble = screen.getByRole('tooltip')
+    expect(bubble.getAttribute('data-side')).toBe('bottom')
+    expect(bubble.style.left).toBe('0px')
+    expect(bubble.style.top).toBe('8px')
+    fireEvent.blur(anchor)
+    expect(screen.queryByRole('tooltip')).toBeNull()
+  })
+
+  it('chains the anchor\'s own handlers ahead of the tooltip\'s', () => {
+    const onMouseEnter = vi.fn()
+    const onMouseLeave = vi.fn()
+    const onFocus = vi.fn()
+    const onBlur = vi.fn()
+    render(
+      <Tooltip label="Chained">
+        <button type="button" onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave} onFocus={onFocus} onBlur={onBlur}>anchor</button>
+      </Tooltip>,
+    )
+    const anchor = screen.getByText('anchor')
+    fireEvent.mouseEnter(anchor)
+    fireEvent.mouseLeave(anchor)
+    fireEvent.focus(anchor)
+    fireEvent.blur(anchor)
+    expect(onMouseEnter).toHaveBeenCalledOnce()
+    expect(onMouseLeave).toHaveBeenCalledOnce()
+    expect(onFocus).toHaveBeenCalledOnce()
+    expect(onBlur).toHaveBeenCalledOnce()
+  })
+
+  it('suppresses the bubble while disabled without remounting the anchor', () => {
+    const { rerender } = render(
+      <Tooltip label="Rail" disabled>
+        <button type="button">anchor</button>
+      </Tooltip>,
+    )
+    const anchor = screen.getByText('anchor')
+    fireEvent.mouseEnter(anchor)
+    expect(screen.queryByRole('tooltip')).toBeNull()
+    rerender(
+      <Tooltip label="Rail">
+        <button type="button">anchor</button>
+      </Tooltip>,
+    )
+    // Same DOM node: toggling disabled never remounted the anchor.
+    expect(screen.getByText('anchor')).toBe(anchor)
+    fireEvent.mouseEnter(anchor)
+    expect(screen.getByRole('tooltip')).toBeTruthy()
+  })
+
+  it('keeps the bubble while either hover or focus is still active', () => {
+    render(
+      <Tooltip label="Sticky">
+        <button type="button">anchor</button>
+      </Tooltip>,
+    )
+    const anchor = screen.getByText('anchor')
+    // Focused AND hovered: leaving with the mouse must not drop the bubble.
+    fireEvent.focus(anchor)
+    fireEvent.mouseEnter(anchor)
+    fireEvent.mouseLeave(anchor)
+    expect(screen.getByRole('tooltip')).toBeTruthy()
+    fireEvent.blur(anchor)
+    expect(screen.queryByRole('tooltip')).toBeNull()
+    // Symmetric: blurring while still hovered keeps it, mouseleave ends it.
+    fireEvent.mouseEnter(anchor)
+    fireEvent.focus(anchor)
+    fireEvent.blur(anchor)
+    expect(screen.getByRole('tooltip')).toBeTruthy()
+    fireEvent.mouseLeave(anchor)
+    expect(screen.queryByRole('tooltip')).toBeNull()
+  })
+
+  it('drops an already-visible bubble when disabled flips mid-hover', () => {
+    const { rerender } = render(
+      <Tooltip label="Rail">
+        <button type="button">anchor</button>
+      </Tooltip>,
+    )
+    fireEvent.mouseEnter(screen.getByText('anchor'))
+    expect(screen.getByRole('tooltip')).toBeTruthy()
+    // e.g. clicking a rail control expands the sidebar: no mouseleave fires.
+    rerender(
+      <Tooltip label="Rail" disabled>
+        <button type="button">anchor</button>
+      </Tooltip>,
+    )
+    expect(screen.queryByRole('tooltip')).toBeNull()
+  })
+})
diff --git a/packages/client/ui-question/README.md b/packages/client/ui-question/README.md
new file mode 100644
index 0000000000..a02c85d54c
--- /dev/null
+++ b/packages/client/ui-question/README.md
@@ -0,0 +1,20 @@
+# @deepseek-ai/dsh-client-ui-question
+
+Web `ask_user_question` feature plugin. Its host half mounts `dsh-tool-ask-user` only when the Web feature is selected; its browser half registers the `question` entry in the conversation-owned `conversation.composer` keyed slot.
+
+The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`.
+
+Selection state is local to a component keyed by the request rpcId. A replay with the same id preserves a still-mounted draft, while `question/resolved` from the host removes the composer. The host remains authoritative: successful HTTP delivery does not remove pending state locally.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-ask-user`; that package owns the model-visible tool schema and structured result.
+
+#### KV Cache effect
+
+No direct invalidation; `dsh-tool-ask-user` owns the model-visible tool call and result.
+
+## Known Limitations and Deferred Work
+
+- **Unsubmitted drafts are not durable** — reconnect resync or a full page reload restores the host-owned pending request with the same rpcId, but a composer unmount resets local option and custom-text drafts.
+- **One request owns the composer at a time** — later pending requests remain in the session snapshot and become visible after the earlier request resolves.
diff --git a/packages/client/ui-question/package.json b/packages/client/ui-question/package.json
new file mode 100644
index 0000000000..e40deeb248
--- /dev/null
+++ b/packages/client/ui-question/package.json
@@ -0,0 +1,67 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-question",
+  "description": "Web ask_user_question feature: host tool mount plus composer-takeover question UI",
+  "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-ui-conversation"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-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-tool-ask-user": "workspace:^",
+    "clsx": "^2.0.0",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "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",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/ui-question/src/client/QuestionComposer.module.css b/packages/client/ui-question/src/client/QuestionComposer.module.css
new file mode 100644
index 0000000000..6c0c1b854c
--- /dev/null
+++ b/packages/client/ui-question/src/client/QuestionComposer.module.css
@@ -0,0 +1,348 @@
+.frame {
+  display: flex;
+  justify-content: center;
+  padding: 6px 24px 10px;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  max-width: 720px;
+  /* Composer seat sits in a fixed-height conversation column (overflow
+     hidden): cap the card against the viewport and scroll the option list
+     so header and footer actions stay reachable on long batches. */
+  max-height: min(60vh, 520px);
+  padding: 14px 16px 12px;
+  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border-radius: 18px;
+  background: var(--dsw-specific-input-major);
+  box-shadow: var(--dsw-shadow-lv1-blur);
+  color: var(--dsw-alias-label-primary);
+}
+
+.card,
+.card * {
+  box-sizing: border-box;
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  flex-shrink: 0;
+  margin-bottom: 8px;
+}
+
+.headingBlock {
+  min-width: 0;
+  padding: 1px 2px;
+}
+
+.eyebrow {
+  margin-bottom: 2px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+.title {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin: 0;
+  font-size: 16px;
+  line-height: 22px;
+  font-weight: 600;
+}
+
+.multiSelectHint {
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 400;
+  white-space: nowrap;
+}
+
+.detail {
+  margin: 2px 0 0;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 400;
+}
+
+.headerActions,
+.footerActions {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex-shrink: 0;
+}
+
+.progress {
+  padding: 0 6px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 24px;
+  white-space: nowrap;
+}
+
+.iconButton {
+  display: grid;
+  place-items: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+}
+
+.iconButton:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-primary);
+}
+
+.iconButton:disabled {
+  color: var(--dsw-alias-label-dimmed);
+  cursor: default;
+}
+
+.options {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  /* The scrollable region of the capped card (ChatView list pattern). */
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.option {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-height: 42px;
+  padding: 5px 8px;
+  border: 1px solid transparent;
+  border-radius: 12px;
+  background: transparent;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+  transition: background-color 120ms ease, border-color 120ms ease;
+}
+
+.option:hover:not(:disabled),
+.optionSelected {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.optionSelected {
+  border-color: var(--dsw-alias-border-l2);
+}
+
+.option:disabled,
+.customTrigger:disabled {
+  cursor: default;
+}
+
+.number {
+  display: grid;
+  place-items: center;
+  flex: 0 0 28px;
+  width: 28px;
+  height: 28px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 999px;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.optionCopy {
+  min-width: 0;
+  flex: 1;
+}
+
+.optionLine {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 2px 6px;
+}
+
+.optionLabel {
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 600;
+}
+
+.badge {
+  padding: 0 6px;
+  border-radius: 999px;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-secondary);
+  font-size: 11px;
+  line-height: 18px;
+}
+
+.description {
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 400;
+}
+
+.choiceIcon {
+  display: grid;
+  place-items: center;
+  width: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.custom {
+  border: 1px solid transparent;
+  border-radius: 12px;
+}
+
+.customOpen {
+  border-color: var(--dsw-alias-border-l2);
+  background: var(--dsw-alias-bg-module-platform);
+}
+
+.customOptionless {
+  border: none;
+  background: transparent;
+}
+
+.customTrigger {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-height: 42px;
+  padding: 5px 8px;
+  border: none;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 14px;
+  line-height: 20px;
+  text-align: left;
+  cursor: pointer;
+}
+
+.customTrigger:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+}
+
+.customInput {
+  display: block;
+  width: calc(100% - 20px);
+  min-height: 54px;
+  max-height: 140px;
+  margin: 0 10px 10px;
+  padding: 7px 10px;
+  resize: vertical;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 10px;
+  outline: none;
+  background: var(--dsw-specific-input-major);
+  color: var(--dsw-alias-label-primary);
+  caret-color: var(--dsw-alias-state-business-primary);
+  font: inherit;
+  font-size: 13px;
+  line-height: 20px;
+}
+
+.customInput:focus {
+  border-color: var(--dsw-alias-state-business-primary);
+}
+
+.customInput::placeholder {
+  color: var(--dsw-alias-label-caption);
+}
+
+.customOptionless .customInput {
+  width: 100%;
+  min-height: 58px;
+  margin: 0;
+  background: var(--dsw-alias-bg-module-platform);
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-shrink: 0;
+  margin-top: 8px;
+  padding: 0 2px;
+}
+
+.feedback {
+  min-height: 16px;
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+@media (max-width: 720px) {
+  .frame {
+    padding: 6px 10px 10px;
+  }
+
+  .card {
+    padding: 12px 10px 10px;
+    border-radius: 16px;
+  }
+
+  .header {
+    display: block;
+  }
+
+  .headerActions {
+    justify-content: flex-end;
+    margin-top: 8px;
+  }
+
+  .headingBlock {
+    padding: 0 2px;
+  }
+
+  .title {
+    font-size: 15px;
+    line-height: 21px;
+  }
+
+  .option,
+  .customTrigger {
+    align-items: flex-start;
+    gap: 8px;
+    padding: 6px;
+  }
+
+  .choiceIcon {
+    margin-top: 3px;
+  }
+
+  .footer {
+    align-items: flex-end;
+  }
+
+  .footerActions {
+    flex-shrink: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .option {
+    transition: none;
+  }
+}
diff --git a/packages/client/ui-question/src/client/QuestionComposer.tsx b/packages/client/ui-question/src/client/QuestionComposer.tsx
new file mode 100644
index 0000000000..3571263f61
--- /dev/null
+++ b/packages/client/ui-question/src/client/QuestionComposer.tsx
@@ -0,0 +1,297 @@
+import { useMemo, useState, type KeyboardEvent } from 'react'
+import clsx from 'clsx'
+import {
+  Button, IconCheckOutline16, IconChevronLeftOutline14, IconChevronRightOutline14,
+  IconCloseOutline16, IconEditOutline16,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import { PendingQuestion, type QuestionAnswer, type QuestionComposerProps } from './contract/slots.ts'
+import css from './QuestionComposer.module.css'
+
+interface DraftAnswer {
+  selected: string[]
+  custom: string
+  customOpen: boolean
+  skipped: boolean
+}
+
+/**
+ * Split the conventional recommendation suffix without changing the answer value.
+ * @param label - Original option label returned if selected.
+ * @returns Display label plus recommendation state.
+ */
+export function parseRecommendedLabel(label: string): { label: string; recommended: boolean } {
+  const suffix = /\s*(?:\((?:recommended|推荐)\)|（(?:recommended|推荐)）)\s*$/i
+  return suffix.test(label)
+    ? { label: label.replace(suffix, ''), recommended: true }
+    : { label, recommended: false }
+}
+
+/**
+ * Remove a conventional multi-select suffix so the hint can be styled separately.
+ * @param title - Question title supplied by the interaction request.
+ * @returns Question title without a trailing multi-select marker.
+ */
+export function parseQuestionTitle(title: string): string {
+  return title.replace(/\s*[（(]可多选[）)]\s*$/, '')
+}
+
+/** Return whether a textarea key event belongs to an active IME composition. */
+function isComposing(event: KeyboardEvent<HTMLTextAreaElement>): boolean {
+  return event.nativeEvent.isComposing || event.nativeEvent.keyCode === 229
+}
+
+/**
+ * Composer takeover boundary; the carrier key keys local drafts, so a
+ * same-request replay (same key, new carrier object) preserves them.
+ * @param props - the selector-matched pending question carrier plus the framework standard kit.
+ * @returns The question flow for this request.
+ */
+export function QuestionComposer(props: QuestionComposerProps) {
+  // Domain-face mint rides the carrier's stable identity (never minted in a
+  // select/render dispatch — per-dispatch minting would churn memo identity).
+  const question = useMemo(() => new PendingQuestion(props.matched), [props.matched])
+  return <QuestionFlow key={question.key} pending={question} />
+}
+
+function QuestionFlow({ pending }: { pending: PendingQuestion }) {
+  const questions = pending.questions
+  const [index, setIndex] = useState(0)
+  const [drafts, setDrafts] = useState<DraftAnswer[]>(() => questions.map(question => ({
+    selected: [], custom: '', customOpen: (question.options?.length ?? 0) === 0, skipped: false,
+  })))
+  const [busy, setBusy] = useState<'answer' | 'cancel' | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const question = questions[index]!
+  const draft = drafts[index]!
+  const hasOptions = (question.options?.length ?? 0) > 0
+
+  const cancelFlow = (): void => {
+    setBusy('cancel')
+    setError(null)
+    void pending.cancel().catch((cause: unknown) => {
+      setBusy(null)
+      setError(cause instanceof Error ? cause.message : String(cause))
+    })
+  }
+
+  const updateDraft = (update: (current: DraftAnswer) => DraftAnswer): void => {
+    setDrafts(current => current.map((item, itemIndex) => itemIndex === index ? update(item) : item))
+    setError(null)
+  }
+
+  const choose = (label: string): void => {
+    updateDraft((current) => {
+      const selected = question.multiSelect === true
+        ? current.selected.includes(label)
+          ? current.selected.filter(item => item !== label)
+          : [...current.selected, label]
+        : [label]
+      return { selected, custom: '', customOpen: false, skipped: false }
+    })
+    if (question.multiSelect !== true && index < questions.length - 1) {
+      setIndex(current => current + 1)
+    }
+  }
+
+  const openCustom = (): void => {
+    updateDraft(current => ({ ...current, selected: [], customOpen: true, skipped: false }))
+  }
+
+  const answered = (item: DraftAnswer): boolean =>
+    item.selected.length > 0 || item.custom.trim() !== ''
+
+  const completed = (item: DraftAnswer): boolean => answered(item) || item.skipped
+
+  const submitDrafts = (values: DraftAnswer[]): void => {
+    const missing = values.findIndex(item => !completed(item))
+    if (missing >= 0) {
+      setIndex(missing)
+      setError('请先完成这道问题。')
+      return
+    }
+    const answer: QuestionAnswer = {
+      answers: questions.map((item, itemIndex) => {
+        const value = values[itemIndex] as DraftAnswer
+        if (value.skipped) return { id: item.id, selected: [] }
+        const custom = value.custom.trim()
+        return {
+          id: item.id,
+          selected: custom === '' ? value.selected : [],
+          ...(custom === '' ? {} : { custom }),
+        }
+      }),
+    }
+    setBusy('answer')
+    setError(null)
+    void pending.answer(answer).catch((cause: unknown) => {
+      setBusy(null)
+      setError(cause instanceof Error ? cause.message : String(cause))
+    })
+  }
+
+  const continueFlow = (): void => {
+    if (!answered(draft)) {
+      setError('请选择一个选项或填写自定义答案。')
+      return
+    }
+    if (index < questions.length - 1) {
+      setIndex(current => current + 1)
+      setError(null)
+      return
+    }
+    submitDrafts(drafts)
+  }
+
+  const skipQuestion = (): void => {
+    const nextDrafts = drafts.map((item, itemIndex) => itemIndex === index
+      ? {
+          selected: [], custom: '',
+          customOpen: (question.options?.length ?? 0) === 0,
+          skipped: true,
+        }
+      : item)
+    setDrafts(nextDrafts)
+    setError(null)
+    if (index < questions.length - 1) {
+      setIndex(current => current + 1)
+      return
+    }
+    submitDrafts(nextDrafts)
+  }
+
+  return (
+    <div className={css.frame} data-question-key={pending.key}>
+      <section className={css.card} aria-labelledby={`question-${pending.key}-${String(index)}`}>
+        <header className={css.header}>
+          <div className={css.headingBlock}>
+            {question.header !== undefined && <div className={css.eyebrow}>{question.header}</div>}
+            <h2 className={css.title} id={`question-${pending.key}-${String(index)}`}>
+              <span>{question.multiSelect === true
+                ? parseQuestionTitle(question.question)
+                : question.question}</span>
+              {question.multiSelect === true && <span className={css.multiSelectHint}>可多选</span>}
+            </h2>
+            {question.detail !== undefined && <p className={css.detail}>{question.detail}</p>}
+          </div>
+          <div className={css.headerActions}>
+            <span className={css.progress}>{index + 1} / {questions.length}</span>
+            <button
+              type="button" className={css.iconButton} aria-label="上一题"
+              disabled={index === 0 || busy !== null}
+              onClick={() => { setIndex(index - 1); setError(null) }}
+            >
+              <IconChevronLeftOutline14 />
+            </button>
+            <button
+              type="button" className={css.iconButton} aria-label="下一题"
+              disabled={index === questions.length - 1 || busy !== null}
+              onClick={() => { setIndex(index + 1); setError(null) }}
+            >
+              <IconChevronRightOutline14 />
+            </button>
+            <button
+              type="button" className={css.iconButton} aria-label="放弃整组问题"
+              title="放弃整组问题"
+              disabled={busy !== null} onClick={cancelFlow}
+            >
+              <IconCloseOutline16 />
+            </button>
+          </div>
+        </header>
+
+        <div className={css.options} role={question.multiSelect === true ? 'group' : 'radiogroup'}>
+          {(question.options ?? []).map((option, optionIndex) => {
+            const selected = draft.selected.includes(option.label)
+            const display = parseRecommendedLabel(option.label)
+            return (
+              <button
+                type="button" key={`${option.label}-${String(optionIndex)}`}
+                className={clsx(css.option, selected && css.optionSelected)}
+                role={question.multiSelect === true ? 'checkbox' : 'radio'}
+                aria-checked={selected}
+                aria-label={display.label}
+                disabled={busy !== null}
+                onClick={() => { choose(option.label) }}
+                onKeyDown={(event) => {
+                  if (event.key !== 'Enter' || !drafts.every(completed)) return
+                  event.preventDefault()
+                  submitDrafts(drafts)
+                }}
+              >
+                <span className={css.number}>{optionIndex + 1}</span>
+                <span className={css.optionCopy}>
+                  <span className={css.optionLine}>
+                    <span className={css.optionLabel}>{display.label}</span>
+                    {display.recommended && <span className={css.badge}>推荐</span>}
+                    {option.description !== undefined && (
+                      <span className={css.description}>{option.description}</span>
+                    )}
+                  </span>
+                </span>
+                <span className={css.choiceIcon}>
+                  {selected ? <IconCheckOutline16 /> : <IconChevronRightOutline14 />}
+                </span>
+              </button>
+            )
+          })}
+
+          <div className={clsx(
+            css.custom,
+            draft.customOpen && css.customOpen,
+            !hasOptions && css.customOptionless,
+          )}>
+            {hasOptions && (
+              <button
+                type="button" className={css.customTrigger}
+                disabled={busy !== null} onClick={openCustom}
+                aria-expanded={draft.customOpen}
+              >
+                <span className={css.number}><IconEditOutline16 /></span>
+                <span>其他，请填写自定义答案</span>
+              </button>
+            )}
+            {draft.customOpen && (
+              <textarea
+                autoFocus
+                className={css.customInput}
+                value={draft.custom}
+                disabled={busy !== null}
+                rows={2}
+                placeholder="输入你的答案"
+                onChange={(event) => {
+                  const value = event.target.value
+                  updateDraft(current => ({
+                    ...current, selected: [], custom: value, customOpen: true, skipped: false,
+                  }))
+                }}
+                onKeyDown={(event) => {
+                  if (event.key === 'Enter' && !event.shiftKey && !isComposing(event)) {
+                    event.preventDefault()
+                    continueFlow()
+                  }
+                }}
+              />
+            )}
+          </div>
+        </div>
+
+        <footer className={css.footer}>
+          <div className={css.feedback} role="status">{error}</div>
+          <div className={css.footerActions}>
+            <Button variant="ghost" size="sm" disabled={busy !== null} onClick={skipQuestion}>
+              跳过本题
+            </Button>
+            <Button
+              variant="primary" size="sm"
+              disabled={busy !== null || !answered(draft)} onClick={continueFlow}
+            >
+              {busy === 'answer'
+                ? '正在提交…'
+                : index === questions.length - 1 ? '提交' : '下一题'}
+            </Button>
+          </div>
+        </footer>
+      </section>
+    </div>
+  )
+}
diff --git a/packages/client/ui-question/src/client/contract/slots.ts b/packages/client/ui-question/src/client/contract/slots.ts
new file mode 100644
index 0000000000..e3c3e815bf
--- /dev/null
+++ b/packages/client/ui-question/src/client/contract/slots.ts
@@ -0,0 +1,77 @@
+/**
+ * Question-composer slot contract: the registrant-side props composition for
+ * the conversation-owned `conversation.composer` slot, plus the question
+ * domain face over the runtime's carrier object. The carrier (PendingWait)
+ * owns envelope transport only; the question protocol — answer value shape,
+ * cancelled error encoding, receipt checks — lives HERE, with the package
+ * that consumes it.
+ */
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+// Also pulls ui-conversation's SlotMap merge (the 'conversation.composer'
+// entry) into every program that sees this contract, so PropsRuntime resolves.
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
+import type { QuestionResponsePayload } from '@deepseek-ai/dsh-client-connection/client'
+
+/** The pending question carrier the owner dispatches into the composer slot. */
+export type QuestionWait = PendingWait<'question'>
+
+/** One structured answer batch covering every question of the request. */
+export type QuestionAnswer = QuestionResponsePayload['answer']
+
+/**
+ * Question domain face over the carrier: render identity and questions
+ * transparently forwarded; answer/cancel own the wire encoding (the ok value
+ * shape and the cancelled error) and turn a rejected carrier receipt into a
+ * thrown error. Components mint one per carrier via useMemo (never inside a
+ * select — a per-dispatch mint would churn identity and break memoization).
+ */
+export class PendingQuestion {
+  /**
+   * @param wait - the runtime carrier for one pending question request.
+   */
+  constructor(private readonly wait: QuestionWait) {}
+
+  /** Opaque render identity (React key / draft remount axis), forwarded from the carrier. */
+  get key(): string {
+    return this.wait.key
+  }
+
+  /** The request's question list, forwarded from the carrier payload. */
+  get questions(): QuestionWait['payload']['questions'] {
+    return this.wait.payload.questions
+  }
+
+  /**
+   * Deliver the whole answer batch; a rejected carrier receipt throws.
+   * @param answer - complete structured answer batch.
+   */
+  async answer(answer: QuestionAnswer): Promise<void> {
+    const receipt = await this.wait.respond({
+      ok: true, value: { sessionId: this.wait.sessionId, answer },
+    })
+    if (!receipt.accepted) {
+      throw new Error(`question response rejected: ${receipt.reason}`)
+    }
+  }
+
+  /** Reject the whole wait (the host resolves the tool call as cancelled); a rejected receipt throws. */
+  async cancel(): Promise<void> {
+    const receipt = await this.wait.respond({
+      ok: false,
+      error: { code: 'cancelled', message: 'the user closed this question request', details: {} },
+    })
+    if (!receipt.accepted) {
+      throw new Error(`question cancellation rejected: ${receipt.reason}`)
+    }
+  }
+}
+
+/**
+ * Full component props: the framework runtime share (chain currency +
+ * session/global standard kit) plus the chain `matched` share — the entry's
+ * selector result, already narrowed to the question carrier. No injected
+ * share: the carrier plus the domain face above carry the whole behavior
+ * surface.
+ */
+export type QuestionComposerProps = PropsRuntime<'conversation.composer'> & { matched: QuestionWait }
diff --git a/packages/client/ui-question/src/client/index.ts b/packages/client/ui-question/src/client/index.ts
new file mode 100644
index 0000000000..328fa6c6ce
--- /dev/null
+++ b/packages/client/ui-question/src/client/index.ts
@@ -0,0 +1,41 @@
+/**
+ * Web question plugin, browser half: QuestionComposer registered as a
+ * selector-routed entry of the conversation-declared composer chain. Pure
+ * consumer — the selector narrows the owner's currency to the question
+ * carrier (matched prop), and the whole behavior surface rides the carrier
+ * (domain encoding in contract/slots.ts PendingQuestion); no inject face, no
+ * service dependency beyond slots. Export discipline: packages/client/AGENTS.md.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ComposerChainProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { QuestionWait } from './contract/slots.ts'
+import { QuestionComposer } from './QuestionComposer.tsx'
+
+export { PendingQuestion } from './contract/slots.ts'
+export type { QuestionAnswer, QuestionComposerProps, QuestionWait } from './contract/slots.ts'
+
+/**
+ * Required services (cordis fiber inject). 'conversation' is an ordering
+ * edge, not a call dependency: the 'conversation.composer' chain slot is
+ * declared by ui-conversation's apply, and register() into an undeclared
+ * slot throws — service waiting orders this apply after the declaring one.
+ */
+export const inject = ['slots', 'conversation']
+
+/** Chain routing: claim the composer while a question wait is pending (pure — owner props only). */
+function selectQuestion({ interactions }: ComposerChainProps): QuestionWait | null {
+  return interactions.find((i): i is QuestionWait => i.kind === 'question') ?? null
+}
+
+/**
+ * Client plugin body: register the question composer into the composer chain.
+ * Zero business face — data and verbs both live on the matched carrier.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  const slots = ctx.slots
+  ctx.effect(
+    () => slots.register({ name: 'conversation.composer', select: selectQuestion }, QuestionComposer),
+    'ui-question: composer chain registration',
+  )
+}
diff --git a/packages/client/ui-question/src/css-modules.d.ts b/packages/client/ui-question/src/css-modules.d.ts
new file mode 100644
index 0000000000..24a27bda3f
--- /dev/null
+++ b/packages/client/ui-question/src/css-modules.d.ts
@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: Readonly<Record<string, string>>
+  export default classes
+}
diff --git a/packages/client/ui-question/src/index.ts b/packages/client/ui-question/src/index.ts
new file mode 100644
index 0000000000..901e832c14
--- /dev/null
+++ b/packages/client/ui-question/src/index.ts
@@ -0,0 +1,17 @@
+/**
+ * Web question plugin, node half: enabling this UI feature also exposes the
+ * model-facing ask_user_question tool on the host composition.
+ */
+import type { Context } from 'cordis'
+import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
+
+/** Host services required by the model-facing tool. */
+export const inject = ['tools', 'userInteraction']
+
+/**
+ * Mount ask_user_question for hosts that selected the Web question plugin.
+ * @param ctx - Host plugin context carrying tools and userInteraction.
+ */
+export function apply(ctx: Context): void {
+  toolAskUser.apply(ctx)
+}
diff --git a/packages/client/ui-question/src/invariant.ts b/packages/client/ui-question/src/invariant.ts
new file mode 100644
index 0000000000..6a6e7ebb90
--- /dev/null
+++ b/packages/client/ui-question/src/invariant.ts
@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-question`.
+ * @module @deepseek-ai/dsh-client-ui-question/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-question'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-question-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: tool and slot registrations are effects
+ * owned and observed by their respective registries; the host pending table is
+ * exercised through the public wire protocol.
+ */
+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-question/tests/browser-plugin.spec.ts b/packages/client/ui-question/tests/browser-plugin.spec.ts
new file mode 100644
index 0000000000..09f71c9b5f
--- /dev/null
+++ b/packages/client/ui-question/tests/browser-plugin.spec.ts
@@ -0,0 +1,70 @@
+/**
+ * apply wiring on a real cordis Context + SlotsService: QuestionComposer
+ * registered as the `question` entry of the conversation-declared composer
+ * slot with ZERO business face (data and verbs ride the dispatched carrier),
+ * load-order fail-loud, and fiber-teardown unregistration. Component and
+ * domain-face behavior is covered props-direct in question-composer.spec.tsx;
+ * no renderer machinery here.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { QuestionComposer } from '../src/client/QuestionComposer.tsx'
+import { apply, inject } from '../src/client/index.ts'
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const slots = ctx.get('slots') as SlotsService
+  // Stand-in for ui-conversation's conversation entry: the composer slot only
+  // exists while a live entry declares it in children (declaration account:
+  // design §2.2).
+  slots.register(
+    { name: 'root', children: { 'conversation.composer': { kind: 'chain', scope: 'session' } } } as never,
+    () => null,
+  )
+  // 'conversation' inject is an ordering edge (the declaring plugin provides
+  // it after declaring the chain); the bench declares the chain itself.
+  ctx.provide('conversation', {})
+  return { ctx, slots }
+}
+
+describe('apply', () => {
+  it('declares the services it binds', () => {
+    expect(inject).toEqual(['slots', 'conversation'])
+  })
+
+  it('fails loud when no live entry has declared the composer slot', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SlotsService).await()
+    // Satisfy the ordering inject without declaring the chain: apply must
+    // then hit the undeclared-slot throw, not sit waiting on the service.
+    ctx.provide('conversation', {})
+    await expect(ctx.plugin({ inject: [...inject], apply }))
+      .rejects.toThrow(/slot "conversation.composer" is not declared/)
+  })
+
+  it('registers the question entry: routing selector, no inject face', async () => {
+    const { ctx, slots } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    const entry = slots.entries('conversation.composer')[0]!
+    expect(entry.component).toBe(QuestionComposer)
+    // The whole behavior surface rides the matched carrier: no business face.
+    expect(entry.inject).toBeUndefined()
+    // The selector narrows the chain currency: question wait in → that wait; none → null.
+    const select = entry.select as (owner: { interactions: readonly { kind: string }[] }) => unknown
+    const question = { kind: 'question' }
+    expect(select({ interactions: [{ kind: 'approval' }, question] })).toBe(question)
+    expect(select({ interactions: [{ kind: 'approval' }] })).toBeNull()
+    expect(select({ interactions: [] })).toBeNull()
+  })
+
+  it('teardown unregisters the slot entry', async () => {
+    const { ctx, slots } = await bench()
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(slots.entries('conversation.composer')).toHaveLength(1)
+    await fiber.dispose()
+    expect(slots.entries('conversation.composer')).toHaveLength(0)
+  })
+})
diff --git a/packages/client/ui-question/tests/node-plugin.spec.ts b/packages/client/ui-question/tests/node-plugin.spec.ts
new file mode 100644
index 0000000000..9bc34e9599
--- /dev/null
+++ b/packages/client/ui-question/tests/node-plugin.spec.ts
@@ -0,0 +1,28 @@
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import { apply, inject } from '../src/index.ts'
+
+let ctx: Context | undefined
+
+afterEach(async () => {
+  await ctx?.fiber.dispose()
+  ctx = undefined
+})
+
+describe('ui-question node plugin', () => {
+  it('exposes ask_user_question only for the selected Web feature lifecycle', async () => {
+    ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(UserInteractionService)
+    const feature = ctx.plugin({ inject: [...inject], apply })
+    await feature.await()
+    expect(ctx.tools.get('ask_user_question')).toBeDefined()
+
+    await feature.dispose()
+    expect(ctx.tools.get('ask_user_question')).toBeUndefined()
+  })
+})
diff --git a/packages/client/ui-question/tests/question-composer.spec.tsx b/packages/client/ui-question/tests/question-composer.spec.tsx
new file mode 100644
index 0000000000..9a8ac9bb57
--- /dev/null
+++ b/packages/client/ui-question/tests/question-composer.spec.tsx
@@ -0,0 +1,265 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import type { ConversationSnapshot, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
+import type { RpcReceipt } from '@deepseek-ai/dsh-client-connection/client'
+import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+import { PendingQuestion } from '../src/client/contract/slots.ts'
+import {
+  QuestionComposer, parseQuestionTitle, parseRecommendedLabel,
+} from '../src/client/QuestionComposer.tsx'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+/** Framework standard-kit stubs: the composer consumes none of them, the
+ *  composed props type mandates their delivery (framework hooks are plain
+ *  stubs per the client testing discipline). */
+const kit = {
+  sessionId: SID,
+  useSession: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook<ConversationSnapshot>,
+  useSessions: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook<SessionListState>,
+}
+
+const QUESTIONS = [
+  {
+    id: 'profile', header: '偏好', question: '选择候选人类型',
+    detail: '按当前空缺岗位的优先级选择。',
+    options: [
+      { label: '工程落地型 (Recommended)', description: '优先工程交付。' },
+      { label: '研究潜力型', description: '优先研究能力。' },
+    ],
+  },
+  {
+    id: 'detail', question: '补充你的要求',
+  },
+  {
+    id: 'signals', question: '选择重要信号（可多选）', multiSelect: true,
+    options: [{ label: '系统设计' }, { label: '代码质量' }, { label: '产品判断' }],
+  },
+]
+
+/** Carrier fixture: a real PendingWait over a scripted respond carrier. */
+function wait(rpcId = 'question-1', respond = vi.fn(() => Promise.resolve<RpcReceipt>({ accepted: true }))) {
+  const carrier = new PendingWait(
+    'question', RpcId(rpcId), SID, { questions: QUESTIONS } as PendingWait<'question'>['payload'], respond)
+  return { carrier, respond }
+}
+
+/** The client-response envelope respond must have received for an answer batch. */
+function answeredEnvelope(rpcId: string, answers: object[]) {
+  return {
+    type: 'client-response', rpcId: RpcId(rpcId),
+    result: { ok: true, value: { sessionId: SID, answer: { answers } } },
+  }
+}
+
+describe('QuestionComposer', () => {
+  it('collects single, custom, and multi-select answers before one batch submit', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    expect(screen.getByText('1 / 3')).toBeTruthy()
+    expect(screen.getByText('推荐')).toBeTruthy()
+    expect(screen.getByText('工程落地型')).toBeTruthy()
+    expect(screen.getByText('按当前空缺岗位的优先级选择。')).toBeTruthy()
+    fireEvent.keyDown(screen.getByRole('radio', { name: /工程落地型/ }), { key: 'Enter' })
+    expect(respond).not.toHaveBeenCalled()
+    fireEvent.click(screen.getByRole('radio', { name: /工程落地型/ }))
+
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    // detail is per-question: the second question carries none.
+    expect(screen.queryByText('按当前空缺岗位的优先级选择。')).toBeNull()
+    expect(screen.queryByRole('button', { name: '填写答案' })).toBeNull()
+    const custom = screen.getByPlaceholderText('输入你的答案')
+    fireEvent.change(custom, { target: { value: '要能独立排查线上问题' } })
+    fireEvent.keyDown(custom, { key: 'Enter' })
+
+    expect(screen.getByText('3 / 3')).toBeTruthy()
+    expect(screen.getByText('选择重要信号')).toBeTruthy()
+    expect(screen.getByText('可多选')).toBeTruthy()
+    expect(screen.queryByText('（可多选）')).toBeNull()
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: '代码质量' }))
+    fireEvent.keyDown(screen.getByRole('checkbox', { name: '代码质量' }), { key: 'Enter' })
+
+    // The domain face encoded the whole batch into one carrier envelope.
+    expect(respond).toHaveBeenCalledWith(answeredEnvelope('question-1', [
+      { id: 'profile', selected: ['工程落地型 (Recommended)'] },
+      { id: 'detail', selected: [], custom: '要能独立排查线上问题' },
+      { id: 'signals', selected: ['系统设计', '代码质量'] },
+    ]))
+    expect((screen.getByRole('button', { name: '正在提交…' }) as HTMLButtonElement).disabled).toBe(true)
+  })
+
+  it('skips individual questions without discarding earlier answers', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    expect((screen.getByText('下一题').closest('button') as HTMLButtonElement).disabled).toBe(true)
+    fireEvent.click(screen.getByRole('radio', { name: '研究潜力型' }))
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '跳过本题' }))
+    expect(screen.getByText('3 / 3')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '跳过本题' }))
+
+    expect(respond).toHaveBeenCalledWith(answeredEnvelope('question-1', [
+      { id: 'profile', selected: ['研究潜力型'] },
+      { id: 'detail', selected: [] },
+      { id: 'signals', selected: [] },
+    ]))
+  })
+
+  it('keeps IME Enter inside the custom input until composition finishes', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('radio', { name: '研究潜力型' }))
+    const custom = screen.getByPlaceholderText('输入你的答案')
+    fireEvent.change(custom, { target: { value: '中文输入' } })
+
+    fireEvent.keyDown(custom, { key: 'Enter', isComposing: true })
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    expect(respond).not.toHaveBeenCalled()
+
+    fireEvent.keyDown(custom, { key: 'Enter', keyCode: 229 })
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    expect(respond).not.toHaveBeenCalled()
+
+    fireEvent.keyDown(custom, { key: 'Enter' })
+    expect(screen.getByText('3 / 3')).toBeTruthy()
+  })
+
+  it('opens custom input, reports missing skipped answers, and supports header navigation', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('button', { name: '其他，请填写自定义答案' }))
+    expect(screen.getByPlaceholderText('输入你的答案')).toBeTruthy()
+    fireEvent.click(screen.getByRole('radio', { name: '工程落地型' }))
+    const emptyCustom = screen.getByPlaceholderText('输入你的答案')
+    fireEvent.keyDown(emptyCustom, { key: 'Enter', shiftKey: true })
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    fireEvent.keyDown(emptyCustom, { key: 'Enter' })
+    expect(screen.getByText('请选择一个选项或填写自定义答案。')).toBeTruthy()
+
+    fireEvent.click(screen.getByLabelText('下一题'))
+    fireEvent.click(screen.getByRole('checkbox', { name: '产品判断' }))
+    fireEvent.click(screen.getByRole('button', { name: '提交' }))
+    expect(screen.getByText('请先完成这道问题。')).toBeTruthy()
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    fireEvent.click(screen.getByLabelText('上一题'))
+    expect(screen.getByText('1 / 3')).toBeTruthy()
+    expect(respond).not.toHaveBeenCalled()
+  })
+
+  it('surfaces cancellation failures: rejected receipt text and raw transport reasons', async () => {
+    const respond = vi.fn()
+      .mockResolvedValueOnce({ accepted: false, reason: 'bad-response' })
+      .mockRejectedValueOnce(new Error('第二次取消失败'))
+    const { carrier } = wait('question-1', respond)
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    // Receipt rejection surfaces through the domain face's thrown message.
+    fireEvent.click(screen.getByRole('button', { name: '放弃整组问题' }))
+    expect(await screen.findByText('question cancellation rejected: bad-response')).toBeTruthy()
+    expect((screen.getByRole('button', { name: '跳过本题' }) as HTMLButtonElement).disabled).toBe(false)
+
+    fireEvent.click(screen.getByRole('button', { name: '放弃整组问题' }))
+    expect(await screen.findByText('第二次取消失败')).toBeTruthy()
+  })
+
+  it('surfaces transport rejection and resets local drafts for a different request', async () => {
+    const respond = vi.fn()
+      .mockRejectedValueOnce(new Error('网络中断'))
+      .mockRejectedValueOnce('字符串错误')
+    const first = wait('first', respond)
+    const view = render(<QuestionComposer matched={first.carrier} interactions={[first.carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('radio', { name: /研究潜力型/ }))
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    const second = wait('second', respond)
+    view.rerender(<QuestionComposer matched={second.carrier} interactions={[second.carrier]} {...kit} />)
+    expect(screen.getByRole('radio', { name: /研究潜力型/ }).getAttribute('aria-checked')).toBe('false')
+
+    fireEvent.click(screen.getByRole('radio', { name: /工程落地型/ }))
+    const custom = screen.getByPlaceholderText('输入你的答案')
+    fireEvent.change(custom, { target: { value: 'x' } })
+    fireEvent.keyDown(custom, { key: 'Enter' })
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('button', { name: '提交' }))
+    expect(await screen.findByText('网络中断')).toBeTruthy()
+    expect((screen.getByRole('button', { name: '提交' }) as HTMLButtonElement).disabled).toBe(false)
+
+    fireEvent.click(screen.getByRole('button', { name: '提交' }))
+    expect(await screen.findByText('字符串错误')).toBeTruthy()
+  })
+
+  it('same-key carrier replacement (baseline replay) keeps drafts', () => {
+    const first = wait('same-id')
+    const view = render(<QuestionComposer matched={first.carrier} interactions={[first.carrier]} {...kit} />)
+    fireEvent.click(screen.getByRole('radio', { name: /研究潜力型/ }))
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+    // Replay mints a NEW carrier for the same request; same key = no remount.
+    const replayed = wait('same-id')
+    view.rerender(<QuestionComposer matched={replayed.carrier} interactions={[replayed.carrier]} {...kit} />)
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+  })
+})
+
+describe('PendingQuestion domain face', () => {
+  it('encodes the answer batch into the ok envelope and throws on a rejected receipt', async () => {
+    const respond = vi.fn()
+      .mockResolvedValueOnce({ accepted: true })
+      .mockResolvedValueOnce({ accepted: false, reason: 'not-pending' })
+    const question = new PendingQuestion(wait('rq', respond).carrier)
+    const batch = { answers: [{ id: 'mode', selected: ['Fast'] }] }
+    await expect(question.answer(batch)).resolves.toBeUndefined()
+    expect(respond).toHaveBeenCalledWith(answeredEnvelope('rq', batch.answers))
+    await expect(question.answer(batch)).rejects.toThrow(/question response rejected: not-pending/)
+  })
+
+  it('encodes cancellation as the cancelled error envelope and throws on a rejected receipt', async () => {
+    const respond = vi.fn()
+      .mockResolvedValueOnce({ accepted: true })
+      .mockResolvedValueOnce({ accepted: false, reason: 'bad-response' })
+    const question = new PendingQuestion(wait('rc', respond).carrier)
+    await expect(question.cancel()).resolves.toBeUndefined()
+    expect(respond).toHaveBeenCalledWith({
+      type: 'client-response', rpcId: RpcId('rc'),
+      result: {
+        ok: false,
+        error: { code: 'cancelled', message: 'the user closed this question request', details: {} },
+      },
+    })
+    await expect(question.cancel()).rejects.toThrow(/question cancellation rejected: bad-response/)
+  })
+
+  it('forwards key and questions from the carrier', () => {
+    const question = new PendingQuestion(wait('rk').carrier)
+    expect(question.key).toBe('q:rk')
+    expect(question.questions).toBe(wait('rk').carrier.payload.questions)
+  })
+})
+
+describe('parseRecommendedLabel', () => {
+  it('recognizes English and Chinese suffixes without changing ordinary labels', () => {
+    expect(parseRecommendedLabel('Fast (Recommended)')).toEqual({ label: 'Fast', recommended: true })
+    expect(parseRecommendedLabel('稳妥（推荐）')).toEqual({ label: '稳妥', recommended: true })
+    expect(parseRecommendedLabel('稳妥 (推荐)')).toEqual({ label: '稳妥', recommended: true })
+    expect(parseRecommendedLabel('Plain')).toEqual({ label: 'Plain', recommended: false })
+  })
+})
+
+describe('parseQuestionTitle', () => {
+  it('removes Chinese and ASCII multi-select suffixes', () => {
+    expect(parseQuestionTitle('选择信号（可多选）')).toBe('选择信号')
+    expect(parseQuestionTitle('选择信号 (可多选)')).toBe('选择信号')
+    expect(parseQuestionTitle('选择信号')).toBe('选择信号')
+  })
+})
diff --git a/packages/client/ui-question/tsconfig.json b/packages/client/ui-question/tsconfig.json
new file mode 100644
index 0000000000..4c4138b80d
--- /dev/null
+++ b/packages/client/ui-question/tsconfig.json
@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../connection"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../ui/tool-ask-user"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-question/tsdown.config.ts b/packages/client/ui-question/tsdown.config.ts
new file mode 100644
index 0000000000..0af4afb3ed
--- /dev/null
+++ b/packages/client/ui-question/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-question', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md
index 33cdeb756d..c165455b1a 100644
--- a/packages/client/ui-sidebar/README.md
+++ b/packages/client/ui-sidebar/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-ui-sidebar
 
-Sidebar plugin: session multi-level tree (cwd grouping + parentId nesting), search, by-workspace grouping, state dots, three creation entries. Collapse morphs the four control rows into the layout-owned 56px rail (expand / new session / new workspace / search — search expands and focuses the search box) plus the settings foot: geometry animates on the deepsuite curve while wide-only content cross-fades and unmounts at settle. Contract: the [slot system standard](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md).
+Sidebar plugin: session multi-level tree (cwd grouping + parentId nesting), search, by-workspace grouping, state dots, three creation entries. Top-level New Session / New Workspace clear the selection onto `conversation.empty`; per-project "+" still create-then-opens. Collapse is a slide + crossfade into the layout-owned 56px rail (open / new session / new workspace / search — search expands and focuses the search box — plus the settings foot): the expanded content freezes at its width and fades in place while the column slides over it, then the rail — whale mark resting, panel icon on hover, tooltips on every control — crossfades in at settle as the wide content unmounts. Contract: the [slot system standard](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md).
 
 `src/client/contract/slots.ts` is the single-domain contract file: `SidebarRootInjected` (the registrant's own injected share — plain service callbacks: onOpen/onCreate/onToggleSidebar) and `SidebarRootComponentProps = PropsRuntime<'sidebar'> & SidebarRootInjected` (owner `{collapsed,width}` plus the standard `useSessions` hook, resolved off ui-layout's SlotMap declaration, never re-stated). `apply` registers SidebarRoot cast-free against that composition; the inject factory closes over the plugin's own ctx.
 
diff --git a/packages/client/ui-sidebar/package.json b/packages/client/ui-sidebar/package.json
index b188841b43..5f7b4d0f23 100644
--- a/packages/client/ui-sidebar/package.json
+++ b/packages/client/ui-sidebar/package.json
@@ -24,6 +24,7 @@
   },
   "dshClient": {
     "inject": [
+      "@deepseek-ai/dsh-client-runtime",
       "@deepseek-ai/dsh-client-ui-layout"
     ],
     "platform": "web"
@@ -34,21 +35,25 @@
   },
   "license": "BSD-3-Clause",
   "dependencies": {
+    "clsx": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^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-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
-    "clsx": "^2.0.0",
-    "react": "^18.2.0"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
-  "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
-    "cordis": "^4.0.0-rc.7"
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
   },
   "files": [
     "lib/index.js",
diff --git a/packages/client/ui-sidebar/src/client/Rows.module.css b/packages/client/ui-sidebar/src/client/Rows.module.css
index 65b6f0fa5e..18539a5f61 100644
--- a/packages/client/ui-sidebar/src/client/Rows.module.css
+++ b/packages/client/ui-sidebar/src/client/Rows.module.css
@@ -24,12 +24,38 @@
   background: var(--dsw-alias-interactive-bg-active);
 }
 
+/* Two-line row: the leading slot (folder/chevron), title, and trailing
+   actions all top-align on the 20px first text line (figma cell) — content
+   is 42px (20 + 2 + 20), so 6px vertical padding centers the block. */
 .projectRow {
   height: 54px;
+  align-items: flex-start;
+  padding-top: 6px;
+  padding-bottom: 6px;
+  box-sizing: border-box;
 }
 
+.projectRow .rowActions {
+  height: 20px;
+}
+
+/* Session cell (figma): pad 8, adjacent 16px twist + status slots, then a 4px
+   gap to the title — the slots butt together, so the row gap is zeroed and
+   the title carries its own margins. */
 .sessionRow {
   height: 34px;
+  gap: 0;
+  /* Mount fade: session rows appear by unfolding a group (or the tree
+     mounting). Stable row keys keep already-visible rows from replaying it. */
+  animation: row-in 150ms var(--ds-ease-in-out);
+}
+
+.sessionRow .title {
+  margin: 0 6px 0 4px;
+}
+
+@keyframes row-in {
+  from { opacity: 0; }
 }
 
 .slot {
@@ -47,11 +73,20 @@
   color: var(--dsw-alias-state-business-primary);
 }
 
-/* Project leading slot: folder by default, chevron on row hover. */
+/* Project leading slot: folder by default, expand arrow on row hover. */
 .projectRow .chevron { display: none; }
 .projectRow:hover .chevron { display: inline-flex; }
 .projectRow:hover .folder { display: none; }
 
+/* Expand arrow (filled triangle): points right closed, rotates to point down open. */
+.arrow {
+  transition: transform 150ms var(--ds-ease-in-out);
+}
+
+.arrowOpen {
+  transform: rotate(90deg);
+}
+
 .projectText {
   flex: 1;
   min-width: 0;
@@ -131,22 +166,25 @@
 }
 
 /* Session expand twist occupies the leading 16px slot; keep a spacer when absent
-   so titles align across sibling rows. */
+   so titles align across sibling rows. Duplicates the .iconButton reset instead
+   of `composes:` — the tsdown CSS-modules pipeline drops composes mappings, which
+   left the raw UA button box showing. */
 .twist {
-  composes: iconButton;
-  width: 16px;
-  height: 20px;
-}
-
-/* "L" connector slot (figma arrow 14:3071): 16x16, glyph right-aligned. */
-.cornerSlot {
   flex: none;
-  width: 16px;
-  height: 16px;
   display: inline-flex;
   align-items: center;
-  justify-content: flex-end;
-  color: var(--dsw-alias-label-caption);
+  justify-content: center;
+  width: 16px;
+  height: 20px;
+  border: none;
+  border-radius: 4px;
+  padding: 0;
+  background: transparent;
+  cursor: pointer;
+}
+
+.twist:hover {
+  color: var(--dsw-alias-label-primary);
 }
 
 /* Chevrons and tree twists ride the caption grey (#ADB2B8); the folder glyph
@@ -156,3 +194,11 @@
 .twist {
   color: var(--dsw-alias-label-caption);
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .sessionRow,
+  .arrow {
+    animation: none;
+    transition: none;
+  }
+}
diff --git a/packages/client/ui-sidebar/src/client/Rows.tsx b/packages/client/ui-sidebar/src/client/Rows.tsx
index c24f6b9fb5..53f8bbe14f 100644
--- a/packages/client/ui-sidebar/src/client/Rows.tsx
+++ b/packages/client/ui-sidebar/src/client/Rows.tsx
@@ -5,16 +5,15 @@
  */
 import clsx from 'clsx'
 import {
-  IconChevronDownOutline14, IconChevronRightOutline14,
   IconEllipsisOutline16, IconFolderClose16, IconFolderOpen16, IconPlusOutline16,
-  IconTreeCorner8x10, StateDot,
+  IconTriangleRightFill14, StateDot,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ProjectRow, SessionRow } from './tree.ts'
 import { formatRelativeTime } from './tree.ts'
 import css from './Rows.module.css'
 
-/** Indent step per tree level: 16px slot + 6px gap (figma). */
-const INDENT_STEP = 22
+/** Indent step per tree level: one 16px slot (figma session cell). */
+const INDENT_STEP = 16
 
 /**
  * Project (workspace) row: 54px, folder + title + session count; hover
@@ -38,7 +37,7 @@ export function ProjectRowItem({ row, active, onToggle, onCreate }: {
         {row.expanded ? <IconFolderOpen16 /> : <IconFolderClose16 />}
       </span>
       <span className={clsx(css.slot, css.chevron)}>
-        {row.expanded ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+        <IconTriangleRightFill14 className={clsx(css.arrow, row.expanded && css.arrowOpen)} />
       </span>
       <span className={css.projectText}>
         <span className={css.title}>{row.label}</span>
@@ -79,17 +78,16 @@ export function SessionRowItem({ row, selected, now, onOpen, onToggle }: {
   onOpen: () => void
   onToggle: () => void
 }) {
-  // Rail (figma sub-cell slot sequence): twist slot, always-reserved state
-  // slot (opacity-0 slots keep their 22px in figma, so titles align whether
-  // or not the dot is lit), then the L connector on child rows. Extra depth
-  // rides the left padding: indent spacers = depth - 1.
+  // Rail (figma session cell: pad 8, twist slot 16, status slot 16, gap 4 to
+  // the title): both slots are always reserved so titles align whether or not
+  // the twist/dot is lit. Extra depth rides the left padding.
   return (
     <div
       className={clsx(css.sessionRow, selected && css.selected)}
       role="treeitem"
       aria-selected={selected}
       {...(row.hasChildren ? { 'aria-expanded': row.expanded } : {})}
-      style={{ paddingLeft: 8 + Math.max(0, row.depth - 1) * INDENT_STEP }}
+      style={{ paddingLeft: 8 + row.depth * INDENT_STEP }}
       onClick={onOpen}
     >
       {row.hasChildren
@@ -100,16 +98,11 @@ export function SessionRowItem({ row, selected, now, onOpen, onToggle }: {
               aria-label={row.expanded ? 'Collapse' : 'Expand'}
               onClick={(e) => { e.stopPropagation(); onToggle() }}
             >
-              {row.expanded ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+              <IconTriangleRightFill14 className={clsx(css.arrow, row.expanded && css.arrowOpen)} />
             </button>
           )
         : <span className={css.slot} />}
       <span className={css.slot}>{row.running && <StateDot state="ongoing" />}</span>
-      {row.depth > 0 && (
-        <span className={css.cornerSlot} data-tree-corner="">
-          <IconTreeCorner8x10 />
-        </span>
-      )}
       <span className={css.title}>{row.title}</span>
       <span className={css.time}>{formatRelativeTime(row.updatedAt, now)}</span>
       <span className={css.rowActions}>
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
index c580d47b75..621b33fc66 100644
--- a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
@@ -1,41 +1,62 @@
-/* Sidebar column (figma 133:7629): vertical stack, padding 16/6, sidebar
-   fill + 1px right border painted by the layout column. Collapse morphs in
-   place: the four control rows persist into the 56px rail (one icon each,
-   x-converged by the shrinking column), geometry rides the deepsuite curve
-   while wide-only content cross-fades 200ms; explicit margins own the
-   vertical rhythm in both states so every gap can transition. */
+/* Sidebar column (figma 133:7629): vertical stack, padding 12/6, sidebar
+   fill + 1px right border painted by the layout column. Collapse is a
+   slide + crossfade, not a morph: the content holds its frozen expanded
+   layout (inline width set by the component) and fades in place (.fading)
+   while the sliding column (AppFrame grid tracks) clips it; the rail layout
+   (.collapsed) only applies after the fade settles, so nothing reflows
+   mid-slide. */
 
 .root {
   display: flex;
   flex-direction: column;
   height: 100%;
-  padding: 6px 16px;
+  padding: 6px 12px;
   box-sizing: border-box;
   background: var(--dsw-specific-sidebar-fill);
   color: var(--dsw-alias-label-primary);
   font-size: 14px;
-  transition: padding var(--ds-transition-duration-slow) var(--ds-ease-in-out);
 }
 
+/* Rail geometry (figma rail spec): 36x36 control boxes centered in the 56px
+   rail (10px side padding), 12px vertical rhythm, 18px from the rail top to
+   the whale's box (24px to the 24-wide whale glyph itself). */
 .root.collapsed {
-  padding-top: 14px;
+  padding: 18px 10px 6px;
 }
 
-/* Wide-only content: fades ahead of the geometry (200ms vs 300ms) and
-   unmounts once the collapse settles; remounts fade back in. */
+/* Collapse phase 1: the whole frozen-width content fades out in place over
+   150ms; at settle the children unmount/snap to the rail layout. */
+.fading > * {
+  opacity: 0;
+  transition: opacity 150ms var(--ds-ease-in-out);
+}
+
+/* Wide-only content fades back in on expand remount. */
 .wide {
   animation: wide-in 200ms var(--ds-ease-in-out);
-  transition: opacity 200ms var(--ds-ease-in-out);
-}
-
-.collapsed .wide {
-  opacity: 0;
 }
 
 @keyframes wide-in {
   from { opacity: 0; }
 }
 
+/* Rail controls hold hidden while the column slides shut, then fade in over
+   the slide's tail: .railIn applies at settle (150ms into the 0.3s AppFrame
+   track transition), so a 100ms delay + 150ms fade starts just before the
+   slide ends (250ms) and finishes at 400ms; `backwards` keeps them at
+   opacity 0 through the delay. Only a live collapse gets .railIn — a
+   refresh straight into the collapsed state renders statically. */
+.railIn .iconButton,
+.railIn .newSession,
+.railIn .searchButton,
+.railIn .foot {
+  animation: rail-in 150ms var(--ds-ease-in-out) 100ms backwards;
+}
+
+@keyframes rail-in {
+  from { opacity: 0; }
+}
+
 /* Logo row (figma pad (4,8,4,8)): brand left, panel toggle right-anchored —
    the toggle is the rail's expand control and slides in with the right edge. */
 .logoRow {
@@ -45,23 +66,19 @@
   justify-content: flex-end;
   gap: 8px;
   height: 60px;
-  padding: 8px 4px;
+  padding: 8px 0 8px 4px;
   margin-bottom: 16px;
   box-sizing: border-box;
   overflow: hidden;
-  transition:
-    height var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    padding var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    margin var(--ds-transition-duration-slow) var(--ds-ease-in-out);
 }
 
 .collapsed .logoRow {
-  height: 24px;
+  height: 36px;
   padding: 0;
-  margin-bottom: 8px;
+  margin-bottom: 12px;
 }
 
-/* Brand group (figma I133:7632): fish + wordmark ride the text ink
+/* Brand group (figma I133:7632): the full wordmark rides the text ink
    (figma-flows ruling: main-screen instance is black; blue is brand
    emphasis only). */
 .brand {
@@ -69,28 +86,9 @@
   min-width: 0;
   display: inline-flex;
   align-items: center;
-  gap: 7px;
   overflow: hidden;
 }
 
-.wordmark {
-  font-weight: 600;
-  white-space: nowrap;
-}
-
-/* HARNESS badge (figma 34:10358): 14px tall, mono 11/500 on primary fill. */
-.badge {
-  flex: none;
-  padding: 0 3px;
-  border-radius: 2px;
-  background: var(--dsw-alias-label-primary);
-  color: var(--dsw-alias-label-primary-inverted);
-  font-family: var(--ds-font-family-code);
-  font-size: 11px;
-  font-weight: 500;
-  line-height: 14px;
-}
-
 .iconButton {
   flex: none;
   display: inline-flex;
@@ -104,9 +102,6 @@
   background: transparent;
   cursor: pointer;
   color: var(--dsw-alias-label-secondary);
-  transition:
-    width var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    height var(--ds-transition-duration-slow) var(--ds-ease-in-out);
 }
 
 .iconButton:hover {
@@ -114,12 +109,33 @@
 }
 
 .collapsed .iconButton {
-  width: 24px;
-  height: 24px;
+  width: 36px;
+  height: 36px;
 }
 
-/* New Session: 38px capsule (figma 133:7634) morphing into the rail's plain
-   icon control — border and fill fade with the label. */
+/* Rail logo swap: collapsed, the toggle rests as the whale mark (brand ink,
+   no hover circle) and hovering reveals the panel icon — the expand
+   affordance (figma sidebar-hover flow). Expanded it is a plain panel icon. */
+.collapsed .toggle .panelIcon {
+  display: none;
+}
+
+.collapsed .toggle:hover .panelIcon {
+  display: inline;
+}
+
+.collapsed .toggle:hover .railFish {
+  display: none;
+}
+
+/* Rail icons ride the primary ink (figma rail spec); expanded keeps the
+   secondary icon-button ink. */
+.collapsed .iconButton {
+  color: var(--dsw-alias-label-primary);
+}
+
+/* New Session: 38px capsule (figma 133:7634); collapsed it renders as the
+   rail's plain icon control. */
 .newSession {
   flex: none;
   display: flex;
@@ -128,24 +144,17 @@
   gap: 6px;
   height: 38px;
   padding: 8px 16px;
-  margin-bottom: 20px; /* former headerBlock padBottom 12 + root gap 8 */
+  margin: 0 2px 20px; /* bottom: former headerBlock padBottom 12 + root gap 8 */
   box-sizing: border-box;
   border: 1px solid var(--dsw-alias-border-l2);
   border-radius: 24px;
   background: var(--dsw-alias-button-elevated-fill);
   color: var(--dsw-alias-label-primary);
   font-size: 14px;
-  font-weight: 510;
+  font-weight: 500;
   line-height: 22px;
   cursor: pointer;
   overflow: hidden;
-  transition:
-    height var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    padding var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    margin var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    gap var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    border-color var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    background-color 200ms var(--ds-ease-in-out);
 }
 
 .newSession:hover {
@@ -153,9 +162,9 @@
 }
 
 .collapsed .newSession {
-  height: 24px;
+  height: 36px;
   padding: 0;
-  margin-bottom: 8px;
+  margin: 0 0 12px;
   gap: 0;
   border-color: transparent;
   background: transparent;
@@ -169,7 +178,6 @@
   max-width: 200px;
   overflow: hidden;
   white-space: nowrap;
-  transition: max-width var(--ds-transition-duration-slow) var(--ds-ease-in-out);
 }
 
 .collapsed .newSessionLabel {
@@ -191,16 +199,12 @@
   border-radius: 12px;
   overflow: hidden;
   color: var(--dsw-alias-label-tertiary);
-  transition:
-    height var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    padding var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    margin var(--ds-transition-duration-slow) var(--ds-ease-in-out);
 }
 
 .collapsed .sectionHeader {
-  height: 24px;
+  height: 36px;
   padding-left: 0;
-  margin-bottom: 8px;
+  margin-bottom: 12px;
 }
 
 .sectionLabel {
@@ -211,8 +215,8 @@
   line-height: 20px;
 }
 
-/* Search input: 38px capsule (figma 133:7649) morphing into the rail's
-   search control. Upstream binds a dedicated design-system variable (light
+/* Search input: 38px capsule (figma 133:7649); collapsed it renders as the
+   rail's search control. Upstream binds a dedicated design-system variable (light
    #F1F3F5 / dark #1B1B1C) matching no shipped alias — a component token
    pinned to the static scale mirrors it (ruled compliant: indirect via
    custom property, upstream-variable equivalent). */
@@ -223,7 +227,7 @@
   align-items: center;
   gap: 8px;
   height: 38px;
-  margin-bottom: 12px; /* former listArea gap 4 + own 8 (spec padB12 to the first cell) */
+  margin: 0 2px 12px; /* bottom: former listArea gap 4 + own 8 (spec padB12 to the first cell) */
   padding: 0 14px;
   box-sizing: border-box;
   border: 1px solid var(--dsw-alias-border-l2);
@@ -231,13 +235,6 @@
   background: var(--dsh-search-input-fill);
   color: var(--dsw-alias-label-caption);
   overflow: hidden;
-  transition:
-    height var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    padding var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    margin var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    gap var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    border-color var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    background-color 200ms var(--ds-ease-in-out);
 }
 
 :global(body[data-ds-dark-theme]) .search {
@@ -245,9 +242,9 @@
 }
 
 .collapsed .search {
-  height: 24px;
+  height: 36px;
   padding: 0;
-  margin-bottom: 8px;
+  margin: 0 0 12px;
   gap: 0;
   border-color: transparent;
   background: transparent;
@@ -261,8 +258,6 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 24px;
-  height: 24px;
   border: none;
   border-radius: 50%;
   padding: 0;
@@ -272,9 +267,11 @@
 }
 
 .collapsed .searchButton {
+  width: 36px;
+  height: 36px;
   pointer-events: auto;
   cursor: pointer;
-  color: var(--dsw-alias-label-secondary);
+  color: var(--dsw-alias-label-primary);
 }
 
 .collapsed .searchButton:hover {
@@ -366,39 +363,41 @@
   font-size: 13px;
 }
 
-/* Foot: settings entry (figma 133:7668). Left padding lands the 14px glyph
-   on the rail's icon axis when collapsed. */
+/* Foot: settings entry (figma 133:7668, 49 hug): the former 18/10 vertical
+   margins fold into the row so the hover pill spans the full 49px. */
 .foot {
   flex: none;
   display: flex;
   align-items: center;
   gap: 8px;
-  height: 29px;
-  margin: 18px 0 10px; /* former root gap 8 + own 10 above; root padBottom 6 below */
+  height: 49px;
+  margin: 8px 0 0; /* + 49px row + root padBottom 6 keeps the old 57px band */
   padding: 0 2px 0 6px;
   border-radius: 12px;
   cursor: pointer;
   overflow: hidden;
   color: var(--dsw-alias-label-primary);
-  transition:
-    padding var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    gap var(--ds-transition-duration-slow) var(--ds-ease-in-out);
 }
 
 .foot:hover {
   background: var(--dsw-alias-interactive-bg-hover);
 }
 
+/* Rail settings: the same 36x36 circle box as the other rail controls. */
 .collapsed .foot {
+  width: 36px;
+  height: 36px;
+  margin: 18px 0 10px;
+  justify-content: center;
   gap: 0;
-  padding: 0 0 0 5px;
+  padding: 0;
+  border-radius: 50%;
 }
 
 .footLabel {
   max-width: 120px;
   overflow: hidden;
   white-space: nowrap;
-  transition: max-width var(--ds-transition-duration-slow) var(--ds-ease-in-out);
 }
 
 .collapsed .footLabel {
@@ -406,16 +405,12 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .root,
   .wide,
-  .logoRow,
-  .iconButton,
-  .newSession,
-  .newSessionLabel,
-  .sectionHeader,
-  .search,
-  .foot,
-  .footLabel {
+  .fading > *,
+  .railIn .iconButton,
+  .railIn .newSession,
+  .railIn .searchButton,
+  .railIn .foot {
     transition: none;
     animation: none;
   }
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
index a2f730b2d4..ed707769ce 100644
--- a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
@@ -6,28 +6,32 @@
  * state, and rows are derived in render via useMemo (slot design section 6:
  * derived data is a pure function, no materializing store).
  *
- * Collapse is a morph, not a swap: the four control rows persist into the
- * 56px rail (collapse/new session/new workspace/search, one icon each, same
- * top-down order as their expanded rows) and animate their geometry on the
- * deepsuite curve, while wide-only content (brand, labels, input, tree)
- * cross-fades out and unmounts once the collapse settles — dropping the
- * sessions subscription. Rail search expands and focuses the search box.
+ * Collapse is a slide + crossfade: the content freezes at its expanded
+ * width (inline style) and fades out in place while the sliding column
+ * (AppFrame grid tracks) clips it — nothing reflows mid-slide. At settle
+ * the wide-only content (brand, labels, input, tree) unmounts, dropping
+ * the sessions subscription, and the control rows snap to the 56px rail
+ * (one icon each, same top-down order) fading in as the slide ends. Rail
+ * search expands and focuses the search box.
  */
 import { Fragment, useEffect, useMemo, useRef, useState } from 'react'
 import clsx from 'clsx'
 import {
-  FishLogo,
+  BrandWordmark, FishLogo,
   IconCloseFill14, IconNewChatOutline16, IconPanelLeftOutline16, IconPersonalizationOutline16,
   IconProjectAddOutline16, IconSearchOutline16, IconSettingsOutline14,
-  Menu,
+  Menu, Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SidebarRootComponentProps } from './contract/slots.ts'
 import { deriveRows } from './tree.ts'
 import { ProjectRowItem, SessionRowItem } from './Rows.tsx'
 import css from './SidebarRoot.module.css'
 
-/** Wide-content unmount delay; matches --ds-transition-duration-slow (0.3s). */
-const COLLAPSE_SETTLE_MS = 300
+/** Wide-content unmount delay; matches the 150ms wide-content fade-out. */
+const COLLAPSE_SETTLE_MS = 150
+
+/** Column slide length (--ds-transition-duration-slow): rail-search focus waits it out — focus() forces a synchronous layout and would jank the slide. */
+const EXPAND_SLIDE_MS = 300
 
 const GROUP_BY_ITEMS = [
   { id: 'workspace', label: 'WorkSpace' },
@@ -134,7 +138,7 @@ function SessionTree({ useSessions, onOpen, onCreate, query }: SessionTreeProps)
  * @param props - composed slot props (runtime share + injected callbacks, contract/slots.ts).
  * @returns the sidebar element tree.
  */
-export function SidebarRoot({ collapsed, useSessions, onOpen, onCreate, onToggleSidebar }: SidebarRootComponentProps) {
+export function SidebarRoot({ collapsed, width, useSessions, onOpen, onCreate, onToggleSidebar }: SidebarRootComponentProps) {
   // The query outlives the tree and the input (both wide-only) so collapsing
   // does not silently drop an in-progress filter.
   const [query, setQuery] = useState('')
@@ -150,72 +154,98 @@ export function SidebarRoot({ collapsed, useSessions, onOpen, onCreate, onToggle
   }, [collapsed])
   const wide = !collapsed || !settled
 
+  // Freeze the content at its expanded width while it fades out (collapsed
+  // && wide): the sliding column then clips it instead of reflowing it. The
+  // rail layout (.collapsed styles) only applies once the fade settles.
+  const lastWideWidth = useRef(width)
+  if (!collapsed) lastWideWidth.current = width
+
+  // Rail-in only crossfades a live collapse: a refresh straight into the
+  // collapsed state renders the rail statically (no delay-hidden icons).
+  const everWide = useRef(!collapsed)
+  if (!collapsed) everWide.current = true
+
   // Rail search = expand + land in the search box: the flag arms before the
   // expand toggle; once expanded the input is mounted and takes focus.
   const [searchOnExpand, setSearchOnExpand] = useState(false)
   useEffect(() => {
     if (!collapsed && searchOnExpand) {
-      searchInput.current?.focus()
-      setSearchOnExpand(false)
+      const timer = window.setTimeout(() => {
+        searchInput.current?.focus({ preventScroll: true })
+        setSearchOnExpand(false)
+      }, EXPAND_SLIDE_MS)
+      return () => { window.clearTimeout(timer) }
     }
   }, [collapsed, searchOnExpand])
 
   return (
-    <div className={clsx(css.root, collapsed && css.collapsed)}>
+    <div
+      className={clsx(css.root, !wide && css.collapsed, !wide && everWide.current && css.railIn, collapsed && wide && css.fading)}
+      style={wide ? { width: collapsed ? lastWideWidth.current : width } : undefined}
+    >
       <div className={css.logoRow}>
         {wide && (
           <span className={clsx(css.brand, css.wide)}>
-            {/* Wordmark svg not extracted yet (figma 88:8932) — text stands in at the same ink. */}
-            <FishLogo size={23} />
-            <span className={css.wordmark}>deepseek</span>
-            <span className={css.badge}>HARNESS</span>
+            <BrandWordmark />
           </span>
         )}
-        <button
-          type="button"
-          className={css.iconButton}
-          aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
-          onClick={() => { onToggleSidebar() }}
-        >
-          <IconPanelLeftOutline16 />
-        </button>
+        {/* Rail resting state is the whale mark; hovering swaps in the panel
+            icon (the expand affordance, figma sidebar-hover flow). */}
+        <Tooltip label="Open sidebar" disabled={wide}>
+          <button
+            type="button"
+            className={clsx(css.iconButton, css.toggle)}
+            aria-label={collapsed ? 'Open sidebar' : 'Collapse sidebar'}
+            onClick={() => { onToggleSidebar() }}
+          >
+            {!wide && <FishLogo className={css.railFish} size={24} />}
+            {/* Rail icons render at 18 (figma rail spec); expanded keeps the glyph-native sizes. */}
+            <IconPanelLeftOutline16 className={css.panelIcon} size={wide ? 16 : 18} />
+          </button>
+        </Tooltip>
       </div>
 
-      <button
-        type="button"
-        className={css.newSession}
-        aria-label="New session"
-        onClick={() => { onCreate() }}
-      >
-        <IconNewChatOutline16 size={14} />
-        {wide && <span className={clsx(css.newSessionLabel, css.wide)}>New Session</span>}
-      </button>
+      <Tooltip label="New session" disabled={wide}>
+        <button
+          type="button"
+          className={css.newSession}
+          aria-label="New session"
+          onClick={() => { onCreate() }}
+        >
+          <IconNewChatOutline16 size={wide ? 14 : 18} />
+          {wide && <span className={clsx(css.newSessionLabel, css.wide)}>New Session</span>}
+        </button>
+      </Tooltip>
 
       <div className={css.sectionHeader}>
         {wide && <span className={clsx(css.sectionLabel, css.wide)}>WorkSpace</span>}
         {wide && <GroupByMenu />}
-        <button
-          type="button"
-          className={css.iconButton}
-          aria-label="New workspace"
-          onClick={() => { onCreate() }}
-        >
-          <IconProjectAddOutline16 />
-        </button>
+        <Tooltip label="New Workspace" disabled={wide}>
+          <button
+            type="button"
+            className={css.iconButton}
+            aria-label="New workspace"
+            onClick={() => { onCreate() }}
+          >
+            <IconProjectAddOutline16 size={wide ? 16 : 18} />
+          </button>
+        </Tooltip>
       </div>
 
       {/* Expanded: the row is a click-to-focus field (the leading icon is
           decorative). Collapsed: the icon is the rail's search control. */}
       <div className={css.search} onClick={() => { if (!collapsed) searchInput.current?.focus() }}>
-        <button
-          type="button"
-          className={css.searchButton}
-          aria-label="Search sessions"
-          tabIndex={collapsed ? 0 : -1}
-          onClick={() => { if (collapsed) { setSearchOnExpand(true); onToggleSidebar() } }}
-        >
-          <IconSearchOutline16 size={14} />
-        </button>
+        <Tooltip label="Search" disabled={wide}>
+          <button
+            type="button"
+            className={css.searchButton}
+            aria-label="Search sessions"
+            tabIndex={collapsed ? 0 : -1}
+            onClick={() => { if (collapsed) { setSearchOnExpand(true); onToggleSidebar() } }}
+          >
+            <IconSearchOutline16 size={wide ? 14 : 18} />
+          </button>
+        </Tooltip>
         {wide && (
           <input
             ref={searchInput}
@@ -245,7 +275,7 @@ export function SidebarRoot({ collapsed, useSessions, onOpen, onCreate, onToggle
       </div>
 
       <div className={css.foot} role="button" tabIndex={0} aria-label="Settings">
-        <IconSettingsOutline14 />
+        <IconSettingsOutline14 size={wide ? 14 : 18} />
         {wide && <span className={clsx(css.footLabel, css.wide)}>Settings</span>}
       </div>
     </div>
diff --git a/packages/client/ui-sidebar/src/client/contract/slots.ts b/packages/client/ui-sidebar/src/client/contract/slots.ts
index 3012a760af..a5ce65ef59 100644
--- a/packages/client/ui-sidebar/src/client/contract/slots.ts
+++ b/packages/client/ui-sidebar/src/client/contract/slots.ts
@@ -25,8 +25,8 @@ export type SidebarRootInjected = {
   /** Open (switch to) a session. */
   onOpen: (id: SessionId) => void
   /**
-   * Create a session and open it; cwd targets a project group (the
-   * sidebar's three creation entries all land in the new session).
+   * New-session affordance: no cwd clears selection onto the empty-state
+   * launch; a cwd create-then-opens a session in that project group.
    */
   onCreate: (cwd?: string) => void
   /** Collapse the sidebar column (layout service action; owner share stays {collapsed,width}). */
diff --git a/packages/client/ui-sidebar/src/client/index.ts b/packages/client/ui-sidebar/src/client/index.ts
index fe799a864f..be757ca183 100644
--- a/packages/client/ui-sidebar/src/client/index.ts
+++ b/packages/client/ui-sidebar/src/client/index.ts
@@ -27,9 +27,15 @@ export function apply(ctx: ClientContext): void {
     // list snapshot); layout keeps only panel geometry.
     onOpen: (id) => { ctx.sessions.open(id) },
     onCreate: (cwd) => {
-      // Create-then-open: the sidebar's three creation entries all land
-      // in the new session (empty-state first-send stays with ui-conversation).
-      void ctx.sessions.create(cwd === undefined ? {} : { cwd })
+      // Top-level New Session / New Workspace: clear selection so AppFrame
+      // shows conversation.empty (EmptyState + shared InputBar). Per-project
+      // "+" still create-then-opens into that cwd until workspace seeding
+      // reaches the empty-state picker.
+      if (cwd === undefined) {
+        ctx.sessions.clear()
+        return
+      }
+      void ctx.sessions.create({ cwd })
         .then((id: SessionId) => { ctx.sessions.open(id) })
     },
     onToggleSidebar: () => { ctx.layout.toggleSidebar() },
diff --git a/packages/client/ui-sidebar/src/client/tree.ts b/packages/client/ui-sidebar/src/client/tree.ts
index ab100739cb..021c7e9276 100644
--- a/packages/client/ui-sidebar/src/client/tree.ts
+++ b/packages/client/ui-sidebar/src/client/tree.ts
@@ -154,7 +154,7 @@ function sessionRow(g: Group, s: SessionSummary, depth: number, hasChildren: boo
     type: 'session',
     id: s.id,
     groupKey: g.key,
-    title: s.title,
+    title: s.displayTitle,
     depth,
     hasChildren,
     expanded,
@@ -183,7 +183,7 @@ function flattenVisible(g: Group, expandedSessions: ReadonlySet<string>, rows: S
 function searchVisible(g: Group, q: string): Set<SessionId> {
   const visible = new Set<SessionId>()
   for (const m of g.summaries.values()) {
-    if (!m.title.toLowerCase().includes(q)) continue
+    if (!m.displayTitle.toLowerCase().includes(q)) continue
     let cur: SessionSummary | undefined = m
     while (cur !== undefined && !visible.has(cur.id)) {
       visible.add(cur.id)
@@ -213,9 +213,9 @@ function flattenSearch(g: Group, visible: ReadonlySet<SessionId>, rows: SidebarR
  *
  * Normal mode: every project row shows; sessions show under expanded
  * projects, descending only into expanded sessions. Search mode (non-blank
- * query, case-insensitive title substring): expansion state is ignored —
+ * query, case-insensitive display-title substring): expansion state is ignored —
  * matched sessions and their ancestor chains are forced visible, groups
- * without a title or label hit are dropped, and a label-only hit keeps the
+ * without a display-title or label hit are dropped, and a label-only hit keeps the
  * bare project row.
  * @param list - sessions list snapshot.
  * @param view - local expansion arrays and search query.
diff --git a/packages/client/ui-sidebar/tests/apply.spec.tsx b/packages/client/ui-sidebar/tests/apply.spec.tsx
index 31c98b1843..44fdae18f8 100644
--- a/packages/client/ui-sidebar/tests/apply.spec.tsx
+++ b/packages/client/ui-sidebar/tests/apply.spec.tsx
@@ -23,10 +23,15 @@ async function bench() {
   await ctx.plugin(SlotsService).await()
   const list = createSnapshotStore<SessionListState>({
     ids: [sid('a')],
-    byId: { [sid('a')]: { id: sid('a'), title: 'alpha', cwd: '/proj', running: false, updatedAt: 1 } },
+    byId: { [sid('a')]: { id: sid('a'), title: 'alpha', displayTitle: 'alpha', cwd: '/proj', running: false, updatedAt: 1 } },
     current: undefined,
   })
-  const sessions = { list, create: vi.fn(async () => sid('minted')), open: vi.fn() }
+  const sessions = {
+    list,
+    create: vi.fn(async () => sid('minted')),
+    open: vi.fn(),
+    clear: vi.fn(),
+  }
   const layout = { toggleSidebar: vi.fn() }
   ctx.provide('sessions', sessions)
   ctx.provide('layout', layout)
@@ -91,14 +96,15 @@ describe('apply', () => {
     expect(sessions.open).toHaveBeenCalledWith('a')
 
     injected.onCreate()
-    expect(sessions.create).toHaveBeenCalledWith({})
+    expect(sessions.clear).toHaveBeenCalledOnce()
+    expect(sessions.create).not.toHaveBeenCalled()
+
+    injected.onCreate('/proj')
+    expect(sessions.create).toHaveBeenCalledWith({ cwd: '/proj' })
     // create-then-open lands after the create promise resolves.
     await Promise.resolve()
     await Promise.resolve()
     expect(sessions.open).toHaveBeenCalledWith('minted')
-
-    injected.onCreate('/proj')
-    expect(sessions.create).toHaveBeenCalledWith({ cwd: '/proj' })
   })
 
   it('teardown unregisters the slot entry', async () => {
diff --git a/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx b/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx
index 08a2769049..71416aef36 100644
--- a/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx
+++ b/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx
@@ -38,6 +38,7 @@ function summary(init: SummaryInit): SessionSummary {
   const s: SessionSummary = {
     id: sid(init.id),
     title: init.title ?? init.id,
+    displayTitle: init.title ?? init.id,
     running: init.running ?? false,
     updatedAt: init.updatedAt ?? 0,
   }
@@ -90,10 +91,13 @@ const projectData = () => [
 /** Flush the store's microtask-batched notification into React. */
 const flush = async () => { await act(async () => { await Promise.resolve() }) }
 
+/** The brand wordmark is decorative svg (aria-hidden, no text); locate it by its native viewBox. */
+const wordmark = () => document.querySelector('svg[viewBox="0 0 182 24"]')
+
 describe('SidebarRoot', () => {
   it('renders chrome and collapsed project rows', () => {
     mount(...projectData())
-    expect(screen.getByText('HARNESS')).toBeTruthy()
+    expect(wordmark()).not.toBeNull()
     expect(screen.getByText('New Session')).toBeTruthy()
     expect(screen.getByText('proj')).toBeTruthy()
     expect(screen.getByText('2 sessions')).toBeTruthy()
@@ -165,15 +169,15 @@ describe('SidebarRoot', () => {
       act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) })
       expect(onToggleSidebar).toHaveBeenCalledOnce()
       // Fade window: the wide chrome is still mounted while it fades.
-      expect(screen.getByText('HARNESS')).toBeTruthy()
+      expect(wordmark()).not.toBeNull()
       expect(screen.getByRole('tree')).toBeTruthy()
       // Settle: wide content unmounts, the rail controls remain.
       act(() => { vi.advanceTimersByTime(300) })
-      expect(screen.queryByText('HARNESS')).toBeNull()
+      expect(wordmark()).toBeNull()
       expect(screen.queryByText('New Session')).toBeNull()
       expect(screen.queryByRole('tree')).toBeNull()
-      // Rail order mirrors the expanded rows: expand, new session, new workspace, search.
-      const rail = ['Expand sidebar', 'New session', 'New workspace', 'Search sessions', 'Settings']
+      // Rail order mirrors the expanded rows: open, new session, new workspace, search.
+      const rail = ['Open sidebar', 'New session', 'New workspace', 'Search sessions', 'Settings']
         .map((label) => screen.getByLabelText(label))
       for (let i = 1; i < rail.length; i++) {
         expect(rail[i - 1]!.compareDocumentPosition(rail[i]!) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
@@ -181,7 +185,7 @@ describe('SidebarRoot', () => {
       // Rail creation entries route like their expanded counterparts.
       act(() => { fireEvent.click(screen.getByLabelText('New session')) })
       expect(onCreate).toHaveBeenLastCalledWith()
-      act(() => { fireEvent.click(screen.getByLabelText('Expand sidebar')) })
+      act(() => { fireEvent.click(screen.getByLabelText('Open sidebar')) })
       expect(onToggleSidebar).toHaveBeenCalledTimes(2)
       expect(screen.getByLabelText('Collapse sidebar')).toBeTruthy()
       expect(screen.getByText('New Session')).toBeTruthy()
@@ -194,10 +198,15 @@ describe('SidebarRoot', () => {
     vi.useFakeTimers()
     try {
       const { onToggleSidebar } = mount(...projectData())
+      // While expanded the search control is inert (the row click focuses instead).
+      act(() => { fireEvent.click(screen.getByLabelText('Search sessions')) })
+      expect(onToggleSidebar).not.toHaveBeenCalled()
       act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) })
       act(() => { vi.advanceTimersByTime(300) })
       act(() => { fireEvent.click(screen.getByLabelText('Search sessions')) })
       expect(onToggleSidebar).toHaveBeenCalledTimes(2)
+      // Focus waits out the 300ms column slide (EXPAND_SLIDE_MS).
+      act(() => { vi.advanceTimersByTime(300) })
       const input = screen.getByPlaceholderText('Search name, keywords...')
       expect(document.activeElement).toBe(input)
     } finally {
@@ -221,7 +230,7 @@ describe('SidebarRoot', () => {
       act(() => { fireEvent.change(input, { target: { value: 'forked' } }) })
       act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) })
       act(() => { vi.advanceTimersByTime(300) })
-      act(() => { fireEvent.click(screen.getByLabelText('Expand sidebar')) })
+      act(() => { fireEvent.click(screen.getByLabelText('Open sidebar')) })
       const restored = screen.getByPlaceholderText('Search name, keywords...') as HTMLInputElement
       expect(restored.value).toBe('forked')
       expect(screen.getByText('forked child')).toBeTruthy()
diff --git a/packages/client/ui-sidebar/tests/tree.spec.ts b/packages/client/ui-sidebar/tests/tree.spec.ts
index fad12f632b..037a2a82ac 100644
--- a/packages/client/ui-sidebar/tests/tree.spec.ts
+++ b/packages/client/ui-sidebar/tests/tree.spec.ts
@@ -11,6 +11,7 @@ const sid = (s: string) => s as SessionId
 interface SummaryInit {
   id: string
   title?: string
+  displayTitle?: string
   cwd?: string
   parentId?: string
   running?: boolean
@@ -20,10 +21,11 @@ interface SummaryInit {
 function summary(init: SummaryInit): SessionSummary {
   const s: SessionSummary = {
     id: sid(init.id),
-    title: init.title ?? init.id,
+    displayTitle: init.displayTitle ?? init.title ?? init.id,
     running: init.running ?? false,
     updatedAt: init.updatedAt ?? 0,
   }
+  if (init.title !== undefined) s.title = init.title
   if (init.cwd !== undefined) s.cwd = init.cwd
   if (init.parentId !== undefined) s.parentId = sid(init.parentId)
   return s
@@ -211,6 +213,15 @@ describe('deriveRows search', () => {
     const rows = deriveRows(list, view({ query: '   ' }))
     expect(rows.every(r => r.type === 'project')).toBe(true)
   })
+
+  it('matches the effective display title when no durable title is available', () => {
+    const fallback = listOf(summary({ id: 'raw-id', displayTitle: 'project fallback', cwd: '/elsewhere' }))
+    const rows = deriveRows(fallback, view({ query: 'fallback' }))
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/elsewhere' }),
+      expect.objectContaining({ type: 'session', id: 'raw-id', title: 'project fallback' }),
+    ])
+  })
 })
 
 describe('formatRelativeTime', () => {
diff --git a/packages/client/ui-slots/README.md b/packages/client/ui-slots/README.md
index e7adb5a79b..16d6380639 100644
--- a/packages/client/ui-slots/README.md
+++ b/packages/client/ui-slots/README.md
@@ -11,11 +11,13 @@ One `register({ name, children?, store?, inject?, ...kind }, Component)` call co
 | store | `PropsStore<H>` | the declared handle: `useStore` selector hook + draft-stripped `actions` |
 | business | `I` | inferred from the `inject` factory's return |
 
+Chain-kind slots invert keyed routing — entries self-nominate instead of the dispatch site picking an `entryKey`: each registration carries a pure `ChainSelect` selector (plus optional ascending `priority`, ties in registration order), the first non-null return elects its entry and becomes the component's `matched` prop, and all-null falls to the owner's `renderSlotChain` fallback (`ChainRenderOpts`).
+
 The standard-kit interfaces (`SessionStandardProps`, `GlobalStandardProps`) are declared empty here and merged by the runtime package (same declare-merge pattern as SlotMap keys). 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.
 
-`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 — 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. `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. `renderer.ts` carries the install seam (`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/src/index.ts b/packages/client/ui-slots/src/index.ts
index e08f884f44..809ba21d5a 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -22,8 +22,8 @@ export * from './renderer.ts'
 /** Slot contract table. Owners extend via declaration merging; entries are {@link SlotEntryDef}. */
 export interface SlotMap {}
 
-/** Slot cardinality: single occupant, ordered list, or key-dispatched. */
-export type SlotKind = 'single' | 'list' | 'keyed'
+/** Slot cardinality: single occupant, ordered list, key-dispatched, or selector-routed chain. */
+export type SlotKind = 'single' | 'list' | 'keyed' | 'chain'
 
 /** Slot data context: root (no session) or session-bound. */
 export type SlotScope = 'root' | 'session'
@@ -98,6 +98,34 @@ export type PropsRuntime<K extends keyof SlotMap & string> =
 /** renderSlot dispatch options: keyed dispatch key, list filtering, empty fallback. */
 export interface RenderOpts { entryKey?: string; only?: string; fallback?: ReactNode }
 
+/** renderSlotChain dispatch options: the owner's fallback body, rendered when every entry's selector declines. */
+export interface ChainRenderOpts { fallback?: ReactNode }
+
+/**
+ * Chain-entry selector: the routing decision of one chain contribution.
+ * Runs at render time in chain order (ascending `priority`, default 0, lower
+ * tries first; ties keep registration = assembly order); the first non-null
+ * return elects its entry
+ * and becomes the component's `matched` prop; `null` passes to the next
+ * entry; all-null falls to the owner's {@link ChainRenderOpts} fallback.
+ * MUST be pure — a function of the owner props only, no external mutable
+ * reads, no side effects (the decline decision lives here, never in a
+ * mounted component probing its own props).
+ */
+export type ChainSelect<O extends object, M> = (owner: O) => M | null
+
+/** Keys of a slot-key union whose SlotMap entry is chain-kind (renderSlotChain's dispatch domain). */
+export type ChainKeysOf<S extends keyof SlotMap & string> =
+  S extends unknown ? (SlotMap[S]['kind'] extends 'chain' ? S : never) : never
+
+/**
+ * Chain matched share: a chain-slot component receives its selector's
+ * non-null result as the framework-injected `matched` prop; other kinds add
+ * nothing to the composed constraint.
+ */
+export type MatchedShare<E extends SlotEntryDef, M> =
+  E['kind'] extends 'chain' ? { matched: M } : object
+
 /**
  * Conversation-session selector hook alias for props contracts. Wide by
  * default at this dependency-inverted layer; the runtime narrows at its
@@ -135,15 +163,27 @@ export type SessionProviderComponent = (props: SessionAreaProps) => ReactNode
  */
 export type PropsRenderSlots<S extends keyof SlotMap & string> = {
   /**
-   * Render a declared child slot.
+   * Render a declared non-chain child slot (chain keys dispatch through
+   * `renderSlotChain` — their routing lives in entry selectors).
    * @param key - declared child key.
    * @param owner - owner props share for that key (decided at the render site).
    * @param opts - kind dispatch options.
    * @returns rendered node(s).
    */
-  renderSlot: <K extends S>(key: K, owner: OwnerOf<K>, opts?: RenderOpts) => ReactNode
+  renderSlot: <K extends Exclude<S, ChainKeysOf<S>>>(key: K, owner: OwnerOf<K>, opts?: RenderOpts) => ReactNode
   readonly __renders?: ((key: S) => void) | undefined
-} & ('session' extends ScopeOf<S>
+} & ([ChainKeysOf<S>] extends [never] ? object : {
+  /**
+   * Render a declared chain child slot: entry selectors run in chain order
+   * over `owner`; the first non-null match renders its component with the
+   * selector result injected as `matched`; all-null renders `opts.fallback`.
+   * @param key - declared chain child key.
+   * @param owner - owner props share (the selectors' routing input).
+   * @param opts - fallback body for the all-null case.
+   * @returns rendered node(s).
+   */
+  renderSlotChain: <K extends ChainKeysOf<S>>(key: K, owner: OwnerOf<K>, opts?: ChainRenderOpts) => ReactNode
+}) & ('session' extends ScopeOf<S>
   // The SessionProvider seat rides the same source as renderSlot: declaring
   // a session-scope child is what makes a session area exist, so the seat
   // derives from the children key set's scopes (renderer injects the value).
@@ -168,7 +208,8 @@ export type ComposedProps<
   S extends keyof SlotMap & string,
   H,
   I extends object,
-> = PropsRuntime<K> & PropsRenderSlots<S> & PropsStore<H> & I
+  M = never,
+> = PropsRuntime<K> & PropsRenderSlots<S> & PropsStore<H> & I & MatchedShare<SlotMap[K], M>
 
 /**
  * Inject factory parameter list, derived from the registration's declaration:
@@ -182,27 +223,35 @@ export type InjectParams<K extends keyof SlotMap & string, H> =
     ? ([H] extends [StoreDecl] ? [sessionId: SessionIdOf, actions: BoundActions<HandleOf<H>>] : [sessionId: SessionIdOf])
     : ([H] extends [StoreDecl] ? [actions: BoundActions<HandleOf<H>>] : [])
 
-/** Kind shape fields carried in register options (keyed dispatch key; list id/order/label). */
-export type KindOptions<E extends SlotEntryDef> =
+/** 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?: string }
-      : object
+      : E['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>
+        /** Explicit chain position (ascending, default 0, lower tries first); ties keep registration = assembly order. */
+        priority?: number
+      }
+        : object
 
 /**
  * Compile-time presence check: an entry declaring children MUST consume
- * `renderSlot` (declaring is claiming — an entry that does not render its
- * children should not declare them). Evaluates to an unsatisfiable
- * intersection member naming the declared keys when violated.
+ * `renderSlot` (or `renderSlotChain` when its only children are chain slots)
+ * — declaring is claiming; an entry that does not render its children should
+ * not declare them. Evaluates to an unsatisfiable intersection member naming
+ * the declared keys when violated.
  */
 type RendersCheck<C, D> =
   [keyof D & keyof SlotMap & string] extends [never] ? unknown
     : C extends (props: infer P) => ReactNode
       ? ('renderSlot' extends keyof P ? unknown
-        : { 'children declared but the component consumes no renderSlot': keyof D & keyof SlotMap & string })
+        : 'renderSlotChain' extends keyof P ? unknown
+          : { 'children declared but the component consumes no renderSlot': keyof D & keyof SlotMap & string })
       : unknown
 
 /** Common register options share (see {@link SlotCore.register} for semantics). */
-type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H> = {
+type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H, M = never> = {
   /** Target slot key (the entry contributes INTO this slot). */
   name: K
   /** Child-slot declaration + render authorization + runtime spec, in one table. */
@@ -211,7 +260,7 @@ type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H> =
   store?: H
   /** Registrant identity label for diagnostics (the runtime Service wrapper stamps the caller's fiber name). */
   registrant?: string
-} & KindOptions<SlotMap[K]>
+} & KindOptions<SlotMap[K], M>
 
 /**
  * One stored registration, as recorded by the core and read by the render
@@ -220,7 +269,9 @@ type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H> =
  */
 export interface StoredEntry {
   component: unknown
-  options: { key?: string; id?: string; order?: number; label?: string }
+  options: { key?: string; id?: string; order?: number; label?: string; priority?: number }
+  /** Chain routing selector (type-erased like `inject`; present exactly on chain-slot entries). */
+  select?: ((owner: never) => unknown) | undefined
   /** Registrant business face; positional params derive from the declaration (sessionId?, actions?). */
   inject?: ((...args: never[]) => Record<string, unknown>) | undefined
   /** Child-slot declaration table (declaration + authorization + runtime spec in one). */
@@ -243,6 +294,8 @@ interface ErasedOptions {
   id?: string | undefined
   order?: number | undefined
   label?: string | undefined
+  select?: ((owner: never) => unknown) | undefined
+  priority?: number | undefined
   children?: Record<string, SlotSpec<SlotEntryDef>> | undefined
   store?: StoreDecl | undefined
   /* eslint-disable-next-line @typescript-eslint/no-explicit-any --
@@ -308,7 +361,8 @@ export class SlotCore {
    * names the first declarer); mounting one shared store handle under slots
    * of different scopes throws. Kind constraints: single — duplicate
    * registration throws; keyed — missing/duplicate `key` throws; list —
-   * missing/duplicate `id` throws.
+   * missing/duplicate `id` throws; chain — missing `select` throws (the
+   * selector is the entry's routing seat, see {@link ChainSelect}).
    *
    * Lifecycle: the disposer removes the contribution AND collapses every
    * declared child slot (child entries clear recursively; their stale
@@ -326,11 +380,12 @@ export class SlotCore {
     K extends keyof SlotMap & string,
     const D extends ChildrenDecl = Record<never, never>,
     H extends StoreDecl | undefined = undefined,
+    M = never,
     C extends SlotComponent<never> = SlotComponent<never>,
   >(
-    options: BaseOptions<K, D, H> & { inject?: undefined },
+    options: BaseOptions<K, D, H, M> & { inject?: undefined },
     component: C
-      & SlotComponent<ComposedProps<K, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, object>>
+      & SlotComponent<ComposedProps<K, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, object, NoInfer<M>>>
       & RendersCheck<C, D>,
   ): () => void
   /**
@@ -348,11 +403,12 @@ export class SlotCore {
     I extends object,
     const D extends ChildrenDecl = Record<never, never>,
     H extends StoreDecl | undefined = undefined,
+    M = never,
     C extends SlotComponent<never> = SlotComponent<never>,
   >(
-    options: BaseOptions<K, D, H> & { inject: (...args: InjectParams<K, H>) => I },
+    options: BaseOptions<K, D, H, M> & { inject: (...args: InjectParams<K, H>) => I },
     component: C
-      & SlotComponent<ComposedProps<K, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, I>>
+      & SlotComponent<ComposedProps<K, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, I, NoInfer<M>>>
       & RendersCheck<C, D>,
   ): () => void
   register(options: ErasedOptions, component: unknown): () => void {
@@ -379,6 +435,9 @@ export class SlotCore {
           throw new Error(`list slot "${options.name}" already has an entry with id "${options.id}"`)
         }
         break
+      case 'chain':
+        if (options.select === undefined) throw new Error(`chain slot "${options.name}" requires options.select`)
+        break
     }
     if (options.children) {
       for (const childKey of Object.keys(options.children)) {
@@ -407,15 +466,19 @@ export class SlotCore {
         ...(options.id !== undefined ? { id: options.id } : {}),
         ...(options.order !== undefined ? { order: options.order } : {}),
         ...(options.label !== undefined ? { label: options.label } : {}),
+        ...(options.priority !== undefined ? { priority: options.priority } : {}),
       },
+      ...(options.select !== undefined ? { select: options.select } : {}),
       ...(options.inject !== undefined ? { inject: options.inject } : {}),
       ...(options.children !== undefined ? { children: options.children } : {}),
       ...(options.store !== undefined ? { store: options.store } : {}),
       ...(options.registrant !== undefined ? { registrant: options.registrant } : {}),
     }
     const next = [...rec.entries, entry]
-    // Stable sort: order ascending, ties keep registration sequence.
+    // Stable sorts: ascending, ties keep registration sequence (list rides
+    // `order`, chain rides `priority` — lower priority tries first).
     if (spec.kind === 'list') next.sort((a, b) => (a.options.order ?? 0) - (b.options.order ?? 0))
+    if (spec.kind === 'chain') next.sort((a, b) => (a.options.priority ?? 0) - (b.options.priority ?? 0))
     rec.entries = next
     this.markDirty(options.name, rec)
     if (options.children) {
diff --git a/packages/client/ui-slots/tests/core.spec.ts b/packages/client/ui-slots/tests/core.spec.ts
index 87c96177d8..8ed6b56498 100644
--- a/packages/client/ui-slots/tests/core.spec.ts
+++ b/packages/client/ui-slots/tests/core.spec.ts
@@ -13,6 +13,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'test.session': { kind: 'single'; scope: 'session' }
     'test.list': { kind: 'list'; scope: 'root' }
     'test.keyed': { kind: 'keyed'; scope: 'session' }
+    'test.chain': { kind: 'chain'; scope: 'session'; owner: { tags: string[] } }
     'test.grandchild': { kind: 'single'; scope: 'root' }
   }
 }
@@ -39,6 +40,7 @@ function mountFrame(core: SlotCore) {
       'test.session': { kind: 'single', scope: 'session' },
       'test.list': { kind: 'list', scope: 'root' },
       'test.keyed': { kind: 'keyed', scope: 'session' },
+      'test.chain': { kind: 'chain', scope: 'session' },
     },
   // Type-level renderSlot presence is proven by the type-chain spec; erasing
   // here keeps runtime fixtures terse.
@@ -148,6 +150,31 @@ describe('kind semantics', () => {
     expect(core.entries('test.list').map(e => e.options.id)).toEqual(['a', 'b', 'c'])
   })
 
+  it('chain: missing select throws; select and priority land on the stored entry', () => {
+    const core = new SlotCore()
+    mountFrame(core)
+    // Statically rejected (KindOptions); runtime guard stays for dynamic callers.
+    // @ts-expect-error chain registration requires options.select
+    expect(() => core.register({ name: 'test.chain' }, Comp)).toThrow('requires options.select')
+    const select = ({ tags }: { tags: string[] }) => tags[0] ?? null
+    core.register({ name: 'test.chain', select, priority: 5 }, Comp as never)
+    const entry = core.entries('test.chain')[0]!
+    expect(entry.select).toBe(select)
+    expect(entry.options.priority).toBe(5)
+  })
+
+  it('chain: entries sort by priority ascending, ties keep registration order', () => {
+    const core = new SlotCore()
+    mountFrame(core)
+    const sel = () => null
+    core.register({ name: 'test.chain', select: sel, priority: 10, registrant: 'late' }, Comp as never)
+    core.register({ name: 'test.chain', select: sel, registrant: 'default-a' }, Comp as never)
+    core.register({ name: 'test.chain', select: sel, registrant: 'default-b' }, Comp as never)
+    core.register({ name: 'test.chain', select: sel, priority: -1, registrant: 'first' }, Comp as never)
+    expect(core.entries('test.chain').map(e => e.registrant))
+      .toEqual(['first', 'default-a', 'default-b', 'late'])
+  })
+
   it('single: second registration throws, disposer frees the seat', () => {
     const core = new SlotCore()
     mountFrame(core)
@@ -294,7 +321,7 @@ describe('subscription surface', () => {
     const off = core.onMutate(key => keys.push(key))
     mountFrame(core)
     // Contribution first, then each declared child key.
-    expect(keys).toEqual(['root', 'test.single', 'test.session', 'test.list', 'test.keyed'])
+    expect(keys).toEqual(['root', 'test.single', 'test.session', 'test.list', 'test.keyed', 'test.chain'])
     keys.length = 0
     core.register({ name: 'test.list', id: 'a' }, Comp)
     expect(keys).toEqual(['test.list'])
diff --git a/packages/client/ui-slots/tests/type-chain.spec.tsx b/packages/client/ui-slots/tests/type-chain.spec.tsx
index d45dfee0a3..8469697557 100644
--- a/packages/client/ui-slots/tests/type-chain.spec.tsx
+++ b/packages/client/ui-slots/tests/type-chain.spec.tsx
@@ -20,9 +20,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'chain.side': { kind: 'single'; scope: 'root'; owner: { collapsed: boolean; width: number } }
     'chain.conv': { kind: 'single'; scope: 'session' }
     'chain.tools': { kind: 'keyed'; scope: 'session' }
+    'chain.takeover': { kind: 'chain'; scope: 'session'; owner: { items: readonly Item[] } }
   }
 }
 
+/** Chain-currency fixture: the owner share carries a union the selectors narrow. */
+interface Item { kind: 'q' | 'a'; id: string }
+
 declare const defineStore: DefineStore
 
 /** Factory form (exclusive seat): module-level export, never a handle. */
@@ -68,6 +72,9 @@ 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 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
 
 describe('terminal-design type chain', () => {
   it('holds the positive chain and the compile-time negatives', () => {
@@ -115,6 +122,28 @@ describe('terminal-design type chain', () => {
       // Keyed registration carries key.
       core.register({ name: 'chain.tools', key: 'bash' }, Tool)
 
+      // Chain registration: select is mandatory, M infers from its return,
+      // matched joins the component constraint; priority is the explicit
+      // chain position.
+      core.register({
+        name: 'chain.takeover',
+        select: ({ items }) => items.find((i) => i.kind === 'q') ?? null,
+        priority: 1,
+      }, Takeover)
+
+      // A component accepting a wider matched than the selector supplies
+      // checks through parameter contravariance.
+      core.register({
+        name: 'chain.takeover',
+        select: ({ items }) => items.find((i) => i.kind === 'q') ?? null,
+      }, WideTakeover)
+
+      // renderSlotChain share: chain keys dispatch with the fallback bag;
+      // non-chain keys stay on renderSlot.
+      const chainSlots: PropsRenderSlots<'chain.takeover' | 'chain.conv'> = null as never
+      chainSlots.renderSlotChain('chain.takeover', { items: [] }, { fallback: null })
+      chainSlots.renderSlot('chain.conv', {})
+
       // ── negatives ──────────────────────────────────────────────────
       // children spec must match the SlotMap entry.
       core.register({
@@ -156,6 +185,34 @@ describe('terminal-design type chain', () => {
       // @ts-expect-error keyed registration requires options.key
       core.register({ name: 'chain.tools' }, Tool)
 
+      // chain registration without select.
+      // @ts-expect-error chain registration requires options.select
+      core.register({ name: 'chain.takeover' }, Takeover)
+
+      // Drifted chain component: demands a matched shape the selector cannot
+      // supply (NoInfer pins M to the select return — the component position
+      // must not widen it).
+      // @ts-expect-error component matched prop drifts from the select return
+      core.register({
+        name: 'chain.takeover',
+        select: ({ items }: { items: readonly Item[] }) => items.find((i) => i.kind === 'q') ?? null,
+      }, NarrowTakeover)
+
+      // select must return M | null, not undefined (find() must be coalesced).
+      // @ts-expect-error select may not return undefined
+      core.register({
+        name: 'chain.takeover',
+        select: ({ items }: { items: readonly Item[] }) => items.find((i) => i.kind === 'q'),
+      }, Takeover)
+
+      // Chain keys are not renderSlot-dispatchable (and vice versa).
+      // @ts-expect-error chain keys dispatch through renderSlotChain only
+      chainSlots.renderSlot('chain.takeover', { items: [] })
+      // @ts-expect-error non-chain keys have no renderSlotChain dispatch
+      chainSlots.renderSlotChain('chain.conv', {})
+      // @ts-expect-error a children set without chain keys provides no renderSlotChain
+      fp.renderSlotChain
+
       // renderSlot owner share typed at the call site.
       // @ts-expect-error owner shape mismatch (width missing)
       fp.renderSlot('chain.side', { collapsed: false })
diff --git a/packages/client/ui-theme/package.json b/packages/client/ui-theme/package.json
index fbad2194c3..4e601914e3 100644
--- a/packages/client/ui-theme/package.json
+++ b/packages/client/ui-theme/package.json
@@ -28,10 +28,6 @@
     "platform": "web",
     "immediately": true
   },
-  "scripts": {
-    "bundle": "tsdown",
-    "watch": "tsdown --watch"
-  },
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
diff --git a/packages/client/ui-theme/src/styles/design-platform.css b/packages/client/ui-theme/src/styles/design-platform.css
index 96408ce4b9..e00ec415b7 100644
--- a/packages/client/ui-theme/src/styles/design-platform.css
+++ b/packages/client/ui-theme/src/styles/design-platform.css
@@ -169,6 +169,7 @@ body {
   --dsw-alias-border-l3: rgba(0, 0, 0, 0.12);
   --dsw-alias-border-l4: rgba(0, 0, 0, 0.16);
   --dsw-alias-brand-primary-invert: var(--dsw-static-neutral-bluish-1000);
+  --dsw-alias-brand-primary-new-colorprimary-new-color: rgb(65, 118, 230);
   --dsw-alias-brand-primary: var(--dsw-static-neutral-bluish-1000);
   --dsw-alias-brand-text: var(--dsw-static-neutral-bluish-1000);
   --dsw-alias-button-contrast-fill: var(--dsw-static-neutral-bluish-700);
@@ -217,6 +218,7 @@ body {
   --dsw-alias-state-error-secondary: var(--dsw-static-red-400);
   --dsw-alias-state-success-primary: var(--dsw-static-green-500);
   --dsw-alias-state-success-secondary: var(--dsw-static-green-400);
+  --dsw-alias-state-success-tertiary: var(--dsw-static-green-100);
   --dsw-alias-state-warn-label: var(--dsw-static-amber-600);
   --dsw-alias-state-warn-primary: var(--dsw-static-amber-500);
   --dsw-alias-state-warn-secondary: var(--dsw-static-amber-400);
@@ -257,11 +259,12 @@ body[data-ds-dark-theme] {
   --dsw-alias-border-l3: rgba(255, 255, 255, 0.16);
   --dsw-alias-border-l4: rgba(255, 255, 255, 0.2);
   --dsw-alias-brand-primary-invert: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-brand-primary-new-colorprimary-new-color: var(--dsw-static-deepseek-450);
   --dsw-alias-brand-primary: var(--dsw-static-neutral-bluish-50);
   --dsw-alias-brand-text: var(--dsw-static-neutral-bluish-50);
   --dsw-alias-button-contrast-fill: var(--dsw-static-neutral-bluish-50);
   --dsw-alias-button-elevated-fill: var(--dsw-static-neutral-bluish-750);
-  --dsw-alias-button-floating-fill: var(--dsw-static-neutral-bluish-950);
+  --dsw-alias-button-floating-fill: var(--dsw-static-neutral-bluish-850);
   --dsw-alias-button-floating-hover: var(--dsw-static-neutral-bluish-800);
   --dsw-alias-button-ghost-active-border: var(--dsw-static-neutral-bluish-600);
   --dsw-alias-button-ghost-active-fill: var(--dsw-static-neutral-bluish-750);
diff --git a/packages/client/ui-trajectory/README.md b/packages/client/ui-trajectory/README.md
index cd3f74f448..f99a5c8386 100644
--- a/packages/client/ui-trajectory/README.md
+++ b/packages/client/ui-trajectory/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-ui-trajectory
 
-Trajectory/Waterfall placeholder views; the pure-consumer minimal plugin exemplar (registers two views, provides no service, declares no Context merge). Contract: api-contracts v3 §8.
+Trajectory turn-list chrome (sticky Turn / Message·Step groups / step cells) plus Waterfall placeholder; the pure-consumer minimal plugin exemplar (registers two view tabs into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge). Contract: api-contracts v3 §8.
 
 ## Model Experience
 
@@ -12,4 +12,4 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **Both views are placeholders by charter** — coarse span derivation with no visual acceptance bar; the real implementations, anchor deep-linking, and span-click selection handoff are the P-III project.
+- **In-flight Time stays blank** — `partial` / `runningCalls` rows render with `—` until a live clock policy lands; selected styling is local-only (not wired to chat details); anchor deep-linking remains deferred.
diff --git a/packages/client/ui-trajectory/package.json b/packages/client/ui-trajectory/package.json
index d6f93e8156..28f6620f2c 100644
--- a/packages/client/ui-trajectory/package.json
+++ b/packages/client/ui-trajectory/package.json
@@ -33,19 +33,19 @@
     "watch": "tsdown --watch"
   },
   "license": "BSD-3-Clause",
-  "dependencies": {
-    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
-    "react": "^18.2.0"
-  },
   "peerDependencies": {
     "@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-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"
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
   },
   "files": [
     "lib/index.js",
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryCell.module.css b/packages/client/ui-trajectory/src/client/TrajectoryCell.module.css
new file mode 100644
index 0000000000..1120fe2746
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryCell.module.css
@@ -0,0 +1,93 @@
+/* Trajectory step cell — 38px row: index · kind tag · text · optional message
+ * metrics · elapsed time. */
+
+.root {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 38px;
+  padding: 0 8px 0 20px;
+  gap: 24px;
+  border-radius: 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  background: var(--dsw-alias-bg-layer-3);
+  min-width: 0;
+}
+
+.selected {
+  border-color: transparent;
+  box-shadow: inset 0 0 0 2px var(--dsw-alias-brand-primary-new-colorprimary-new-color);
+}
+
+.index {
+  flex: none;
+  width: 24px;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.tagSlot {
+  flex: none;
+  width: 80px;
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+.tag {
+  display: inline-flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 22px;
+  max-width: 100%;
+  padding: 0 4px;
+  border-radius: 6px;
+  font: var(--dsw-font-xs-strong-13);
+  white-space: nowrap;
+}
+
+.tagUser {
+  color: var(--dsw-alias-state-success-primary);
+  background: var(--dsw-alias-state-success-tertiary);
+}
+
+.tagMessage {
+  color: var(--dsw-alias-brand-primary-new-colorprimary-new-color);
+  background: var(--dsw-specific-bubble);
+}
+
+.tagTool {
+  color: var(--dsw-alias-state-warn-label);
+  background: var(--dsw-alias-state-warn-tertiary);
+}
+
+.text {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Same column geometry as TrajectoryTurnHeader: 4×71 + 3×12 = 320. */
+.trailing {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  width: 320px;
+  gap: 12px;
+  min-width: 0;
+}
+
+.metric,
+.time {
+  flex: none;
+  width: 71px;
+  text-align: left;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+  white-space: nowrap;
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryCell.tsx b/packages/client/ui-trajectory/src/client/TrajectoryCell.tsx
new file mode 100644
index 0000000000..de99d027d8
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryCell.tsx
@@ -0,0 +1,99 @@
+// TrajectoryCell: one step row in the trajectory list — index, kind tag,
+// ellipsis text, optional Message token metrics, and own-duration time.
+
+import type { HTMLAttributes } from 'react'
+import css from './TrajectoryCell.module.css'
+
+/** Closed set of trajectory step kinds (call+result fold into Tool; no Think). */
+export type TrajectoryCellKind = 'user' | 'message' | 'tool'
+
+/** Display label per kind (matches the design tags). */
+const KIND_LABEL: Record<TrajectoryCellKind, string> = {
+  user: 'User',
+  message: 'Message',
+  tool: 'Tool',
+}
+
+const TAG_CLASS: Record<TrajectoryCellKind, string> = {
+  user: css.tagUser!,
+  message: css.tagMessage!,
+  tool: css.tagTool!,
+}
+
+export interface TrajectoryCellProps extends HTMLAttributes<HTMLDivElement> {
+  /** 1-based step index shown as `#N`. */
+  index: number
+  kind: TrajectoryCellKind
+  /** Single-line summary; CSS ellipsis when it overflows. */
+  text: string
+  /**
+   * Own duration in seconds. `null` means no duration to show (em dash) —
+   * used for in-flight tools and tools missing callTime.
+   */
+  timeSeconds: number | null
+  /** Message-only: prompt token count. */
+  input?: number
+  /** Message-only: completion token count. */
+  output?: number
+  /** Message-only: reasoning token count (usage column, not a Think cell). */
+  think?: number
+  /** Selected: 2px inset brand-primary-new-color ring (not wired to chat selection yet). */
+  selected?: boolean
+}
+
+/**
+ * Format own-duration for the trailing time column: `—` when unknown, `+Ns`
+ * or `+N.1s` otherwise.
+ * @param seconds - duration seconds, or null when absent.
+ * @returns display string.
+ */
+export function formatElapsedSeconds(seconds: number | null): string {
+  if (seconds === null || !Number.isFinite(seconds)) return '—'
+  const rounded = Math.round(seconds * 10) / 10
+  if (Number.isInteger(rounded)) return `+${rounded}s`
+  return `+${rounded.toFixed(1)}s`
+}
+
+/**
+ * Render one trajectory step cell.
+ * @param props - index, kind, text, time, and optional Message metrics.
+ * @returns the cell element.
+ */
+export function TrajectoryCell({
+  index,
+  kind,
+  text,
+  timeSeconds,
+  input,
+  output,
+  think,
+  selected = false,
+  className,
+  ...rest
+}: TrajectoryCellProps) {
+  const rootClass = [
+    css.root,
+    selected ? css.selected : undefined,
+    className,
+  ].filter((c): c is string => c !== undefined).join(' ')
+  const showMetrics = kind === 'message'
+  return (
+    <div className={rootClass} data-kind={kind} data-selected={selected || undefined} {...rest}>
+      <span className={css.index}>#{index}</span>
+      <span className={css.tagSlot}>
+        <span className={`${css.tag} ${TAG_CLASS[kind]}`}>{KIND_LABEL[kind]}</span>
+      </span>
+      <span className={css.text}>{text}</span>
+      <span className={css.trailing}>
+        {showMetrics ? (
+          <>
+            <span className={css.metric}>{input ?? ''}</span>
+            <span className={css.metric}>{output ?? ''}</span>
+            <span className={css.metric}>{think ?? ''}</span>
+          </>
+        ) : null}
+        <span className={css.time}>{formatElapsedSeconds(timeSeconds)}</span>
+      </span>
+    </div>
+  )
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryGroupHeader.module.css b/packages/client/ui-trajectory/src/client/TrajectoryGroupHeader.module.css
new file mode 100644
index 0000000000..6de7074aaa
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryGroupHeader.module.css
@@ -0,0 +1,27 @@
+/* Message / Step group title row inside a turn body. */
+
+.root {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 36px;
+  padding: 0 20px;
+  gap: 24px;
+  min-width: 0;
+}
+
+.title {
+  flex: none;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-primary);
+}
+
+.description {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryGroupHeader.tsx b/packages/client/ui-trajectory/src/client/TrajectoryGroupHeader.tsx
new file mode 100644
index 0000000000..90252ce373
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryGroupHeader.tsx
@@ -0,0 +1,26 @@
+// TrajectoryGroupHeader: "Message" or "Step N" row with optional description.
+
+import css from './TrajectoryGroupHeader.module.css'
+
+export interface TrajectoryGroupHeaderProps {
+  /** Group title (`Message`, `Step 1`, …). */
+  title: string
+  /** Secondary summary (`49s`, `2.2s skill`, …). */
+  description?: string
+}
+
+/**
+ * Render a Message/Step group header inside a turn body.
+ * @param props - title and optional description.
+ * @returns the group header element.
+ */
+export function TrajectoryGroupHeader({ title, description }: TrajectoryGroupHeaderProps) {
+  return (
+    <div className={css.root}>
+      <span className={css.title}>{title}</span>
+      {description !== undefined && description !== ''
+        ? <span className={css.description}>{description}</span>
+        : null}
+    </div>
+  )
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.tsx b/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.tsx
index f250452f2e..3495e2b0c6 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.tsx
+++ b/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.tsx
@@ -1,28 +1,21 @@
-// TrajectoryStatsHeader: span totals row mounted as chrome.header on both
-// placeholder views — the second chrome-attachment consumer (chat's
-// StatsLine footer is the first), proving both mount points render.
-// Subscribes to `nodes` only: chunk batches never swap that reference, so
-// the row is quiet during streaming.
+// TrajectoryStatsHeader: span totals row rendered at the top of both
+// placeholder view bodies (chrome dissolved into the views — the header is
+// part of what these views ARE, not registration metadata). Subscribes to
+// `nodes` only: chunk batches never swap that reference, so the row is quiet
+// during streaming.
 
 import { memo, useMemo } from 'react'
 import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ChromeProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { deriveSpans, deriveSpanStats } from './spans.ts'
 import css from './TrajectoryStatsHeader.module.css'
 
-/** Per-view chrome extension (the view map entry's chromeProps slot). */
-export interface TrajectoryChromeProps {
-  /** Render the tool-calls segment; defaults to true (waterfall lanes already
-   *  visualize calls, so that view may drop the redundant count). */
-  showCalls?: boolean
-}
+/** Props: the conversation-snapshot selector hook (handed down by the view body). */
+export interface TrajectoryStatsHeaderProps { useSession: SnapshotSelectorHook<ConversationSnapshot> }
 
-export const TrajectoryStatsHeader = memo(function TrajectoryStatsHeader({ useSession, showCalls }: ChromeProps & TrajectoryChromeProps) {
-  const nodes = (useSession as SnapshotSelectorHook<ConversationSnapshot>)((s) => s.nodes)
+export const TrajectoryStatsHeader = memo(function TrajectoryStatsHeader({ useSession }: TrajectoryStatsHeaderProps) {
+  const nodes = useSession((s) => s.nodes)
   const stats = useMemo(() => deriveSpanStats(deriveSpans(nodes)), [nodes])
   if (stats.turns === 0) return null
-  const parts = [`${stats.turns} turns`, `${stats.steps} steps`]
-  if (showCalls !== false) parts.push(`${stats.calls} tool calls`)
-  return <div className={css.root}>{parts.join(' · ')}</div>
+  return <div className={css.root}>{`${stats.turns} turns · ${stats.steps} steps · ${stats.calls} tool calls`}</div>
 })
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryTurn.module.css b/packages/client/ui-trajectory/src/client/TrajectoryTurn.module.css
new file mode 100644
index 0000000000..c1f243c8b9
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryTurn.module.css
@@ -0,0 +1,16 @@
+/* One turn block: sticky header + padded body with 10px item gap. */
+
+.root {
+  width: 100%;
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 8px 16px 22px;
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryTurn.tsx b/packages/client/ui-trajectory/src/client/TrajectoryTurn.tsx
new file mode 100644
index 0000000000..6ebce17731
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryTurn.tsx
@@ -0,0 +1,26 @@
+// TrajectoryTurn: sticky Turn header plus the padded Message/Step body.
+
+import type { ReactNode } from 'react'
+import { TrajectoryTurnHeader } from './TrajectoryTurnHeader.tsx'
+import css from './TrajectoryTurn.module.css'
+
+export interface TrajectoryTurnProps {
+  /** 1-based turn index for the sticky header. */
+  turn: number
+  /** Message / Step headers and TrajectoryCell rows. */
+  children?: ReactNode
+}
+
+/**
+ * Render one turn section (sticky header + body).
+ * @param props - turn index and body children.
+ * @returns the turn section element.
+ */
+export function TrajectoryTurn({ turn, children }: TrajectoryTurnProps) {
+  return (
+    <section className={css.root} data-turn={turn}>
+      <TrajectoryTurnHeader turn={turn} />
+      <div className={css.body}>{children}</div>
+    </section>
+  )
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryTurnHeader.module.css b/packages/client/ui-trajectory/src/client/TrajectoryTurnHeader.module.css
new file mode 100644
index 0000000000..4aaed68551
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryTurnHeader.module.css
@@ -0,0 +1,48 @@
+/* Sticky turn bar: full-bleed ghost-active fill across the panel; title +
+ * metric labels sit in a centered 880 content lane (4×71 + 3×12 = 320). */
+
+.root {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  box-sizing: border-box;
+  width: 100%;
+  height: 44px;
+  background: var(--dsw-alias-button-ghost-active-fill);
+}
+
+.inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 880px;
+  height: 100%;
+  margin: 0 auto;
+  padding: 0 16px;
+}
+
+.title {
+  flex: none;
+  font: var(--dsw-font-xs-strong-13);
+  color: var(--dsw-alias-label-primary);
+}
+
+.columns {
+  flex: none;
+  display: flex;
+  align-items: center;
+  width: 320px;
+  gap: 12px;
+  /* Match cell padding-right: 8 so Time lines up with the trailing lane. */
+  margin-right: 8px;
+}
+
+.column {
+  flex: none;
+  width: 71px;
+  text-align: left;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-secondary);
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryTurnHeader.tsx b/packages/client/ui-trajectory/src/client/TrajectoryTurnHeader.tsx
new file mode 100644
index 0000000000..ba54ed1c34
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryTurnHeader.tsx
@@ -0,0 +1,30 @@
+// TrajectoryTurnHeader: sticky per-turn bar with Input/Output/Think/Time labels.
+
+import css from './TrajectoryTurnHeader.module.css'
+
+const COLUMN_LABELS = ['Input', 'Output', 'Think', 'Time'] as const
+
+export interface TrajectoryTurnHeaderProps {
+  /** 1-based turn index shown as `Turn N`. */
+  turn: number
+}
+
+/**
+ * Render the sticky turn header row.
+ * @param props.turn - turn index.
+ * @returns the sticky header element.
+ */
+export function TrajectoryTurnHeader({ turn }: TrajectoryTurnHeaderProps) {
+  return (
+    <div className={css.root}>
+      <div className={css.inner}>
+        <span className={css.title}>Turn {turn}</span>
+        <div className={css.columns} aria-hidden="true">
+          {COLUMN_LABELS.map((label) => (
+            <span key={label} className={css.column}>{label}</span>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
index 4f4dbb1939..45277eb628 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
+++ b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
@@ -1,27 +1,39 @@
-// TrajectoryView: P-I placeholder body for the trajectory tab — per-turn
-// span list with node-count weights (no timing data exists yet; deviation
-// ledger #3 defers real rendering to P-III).
+// TrajectoryView: sticky Turn sections with Message/Step groups and step cells.
 
 import { useMemo } from 'react'
-import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { deriveSpans } from './spans.ts'
+import { TrajectoryCell } from './TrajectoryCell.tsx'
+import { TrajectoryGroupHeader } from './TrajectoryGroupHeader.tsx'
+import { TrajectoryTurn } from './TrajectoryTurn.tsx'
+import { deriveTrajectoryLayout } from './layout.ts'
 import css from './views.module.css'
 
 export function TrajectoryView({ useSession }: ConvViewProps) {
-  const nodes = (useSession as SnapshotSelectorHook<ConversationSnapshot>)((s) => s.nodes)
-  const spans = useMemo(() => deriveSpans(nodes), [nodes])
-  if (spans.length === 0) return <div className={css.root}><p className={css.empty}>暂无轨迹数据</p></div>
+  const nodes = useSession((s) => s.nodes)
+  const partial = useSession((s) => s.partial)
+  const runningCalls = useSession((s) => s.runningCalls)
+  const turns = useMemo(
+    () => deriveTrajectoryLayout({ nodes, partial, runningCalls }),
+    [nodes, partial, runningCalls],
+  )
+  if (turns.length === 0) {
+    return <div className={css.root}><p className={css.empty}>暂无轨迹数据</p></div>
+  }
   return (
     <div className={css.root}>
-      {spans.map((span) => (
-        <div key={span.turn} className={css.row}>
-          <span className={css.turnTag}>turn {span.turn}</span>
-          <span className={css.meta}>
-            {span.steps} steps · {span.calls} calls · {span.nodes} nodes
-          </span>
-        </div>
+      {turns.map((turn) => (
+        <TrajectoryTurn key={turn.turn} turn={turn.turn}>
+          {turn.groups.flatMap((group) => [
+            <TrajectoryGroupHeader
+              key={`${group.title}-h`}
+              title={group.title}
+              {...(group.description !== undefined ? { description: group.description } : {})}
+            />,
+            ...group.cells.map((cell) => (
+              <TrajectoryCell key={cell.index} {...cell} />
+            )),
+          ])}
+        </TrajectoryTurn>
       ))}
     </div>
   )
diff --git a/packages/client/ui-trajectory/src/client/WaterfallView.tsx b/packages/client/ui-trajectory/src/client/WaterfallView.tsx
index a2e555d963..feeb6a7f16 100644
--- a/packages/client/ui-trajectory/src/client/WaterfallView.tsx
+++ b/packages/client/ui-trajectory/src/client/WaterfallView.tsx
@@ -1,20 +1,18 @@
-// WaterfallView: P-I placeholder body for the waterfall tab — node-count
-// bars per turn stand in for duration lanes (no timing data yet; deviation
-// ledger #3 defers real rendering to P-III).
+// WaterfallView: P-I placeholder body for the waterfall tab — span stats
+// header over node-count bars per turn standing in for duration lanes (no
+// timing data yet; deviation ledger #3 defers real rendering to P-III).
 
 import { useMemo } from 'react'
-import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { deriveSpans } from './spans.ts'
+import { TrajectoryStatsHeader } from './TrajectoryStatsHeader.tsx'
 import css from './views.module.css'
 
 /** Bar width scale: px per node, clamped so tiny windows still show a bar. */
 const PX_PER_NODE = 14
 const MIN_BAR_PX = 8
 
-/** Per-view extension merged into the waterfall body's props through the
- *  conversation view map ({ extraProps? } entry slot). */
+/** Optional density override (test/standalone knob; the register site passes nothing). */
 export interface WaterfallExtraProps {
   /** Bar-lane density in px per node; defaults to 14. */
   pxPerNode?: number
@@ -22,28 +20,31 @@ export interface WaterfallExtraProps {
 
 export function WaterfallView({ useSession, pxPerNode }: ConvViewProps & WaterfallExtraProps) {
   const scale = pxPerNode ?? PX_PER_NODE
-  const nodes = (useSession as SnapshotSelectorHook<ConversationSnapshot>)((s) => s.nodes)
+  const nodes = useSession((s) => s.nodes)
   const spans = useMemo(() => deriveSpans(nodes), [nodes])
   if (spans.length === 0) return <div className={css.root}><p className={css.empty}>暂无瀑布数据</p></div>
   return (
-    <div className={css.root}>
-      {spans.map((span, i) => (
-        <div key={span.turn} className={css.row} style={{ paddingLeft: i * 12 }}>
-          <span className={css.turnTag}>turn {span.turn}</span>
-          <span
-            className={css.bar}
-            style={{ width: Math.max(span.nodes * scale, MIN_BAR_PX) }}
-            title={`${span.nodes} nodes`}
-          />
-          {span.calls > 0 && (
+    <>
+      <TrajectoryStatsHeader useSession={useSession} />
+      <div className={css.root}>
+        {spans.map((span, i) => (
+          <div key={span.turn} className={css.row} style={{ paddingLeft: i * 12 }}>
+            <span className={css.turnTag}>turn {span.turn}</span>
             <span
-              className={`${css.bar} ${css.barCalls}`}
-              style={{ width: Math.max(span.calls * scale, MIN_BAR_PX) }}
-              title={`${span.calls} tool calls`}
+              className={css.bar}
+              style={{ width: Math.max(span.nodes * scale, MIN_BAR_PX) }}
+              title={`${span.nodes} nodes`}
             />
-          )}
-        </div>
-      ))}
-    </div>
+            {span.calls > 0 && (
+              <span
+                className={`${css.bar} ${css.barCalls}`}
+                style={{ width: Math.max(span.calls * scale, MIN_BAR_PX) }}
+                title={`${span.calls} tool calls`}
+              />
+            )}
+          </div>
+        ))}
+      </div>
+    </>
   )
 }
diff --git a/packages/client/ui-trajectory/src/client/index.ts b/packages/client/ui-trajectory/src/client/index.ts
index 8c8ebc330d..4a902fe9ff 100644
--- a/packages/client/ui-trajectory/src/client/index.ts
+++ b/packages/client/ui-trajectory/src/client/index.ts
@@ -1,44 +1,36 @@
 /**
- * Trajectory/Waterfall plugin, browser half: merges ConversationViewMap and
- * registers the two placeholder views. Pure consumer — no ctx service, no
- * Context declaration merge; the minimal-plugin exemplar. Contract:
- * api-contracts v3 section 8.
+ * Trajectory/Waterfall plugin, browser half: contributes the two placeholder
+ * views into the conversation view ring (the 'conversation.view' list slot
+ * declared by ui-conversation). Pure consumer — no ctx service, no Context
+ * declaration merge; the minimal-plugin exemplar. Contract: api-contracts v3
+ * section 8.
  */
 import type { Context } from 'cordis'
-import { TrajectoryStatsHeader, type TrajectoryChromeProps } from './TrajectoryStatsHeader.tsx'
+// Type-only: the 'conversation.view' SlotMap row (declared by the slot's
+// owning package) must be in the program for the register calls to type.
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { TrajectoryView } from './TrajectoryView.tsx'
-import { WaterfallView, type WaterfallExtraProps } from './WaterfallView.tsx'
-
-export type { TrajectoryChromeProps } from './TrajectoryStatsHeader.tsx'
-export type { WaterfallExtraProps } from './WaterfallView.tsx'
-
-declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
-  interface ConversationViewMap {
-    // Per-view extension shapes merged through the map (view-ring design):
-    // the stats header's chrome props ride both entries; the waterfall body
-    // additionally takes its lane-density extra. P-III widens these.
-    trajectory: { chromeProps: TrajectoryChromeProps }
-    waterfall: { chromeProps: TrajectoryChromeProps; extraProps: WaterfallExtraProps }
-  }
-}
-
-/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
-export const inject = ['conversation']
+import { WaterfallView } from './WaterfallView.tsx'
 
 /**
- * Client plugin body: register the trajectory and waterfall views. The
- * registrations are effects on this fiber (plugin unload removes both tabs).
+ * Required services (cordis fiber inject). 'conversation' is an ordering
+ * edge, not a call dependency: the 'conversation.view' slot is declared by
+ * ui-conversation's apply (which then provides the service), and register()
+ * into an undeclared slot throws — service waiting is what orders this
+ * apply after the declaring one.
+ */
+export const inject = ['slots', 'conversation']
+
+/**
+ * Client plugin body: register the trajectory and waterfall view tabs. The
+ * registrations ride the slot service's effect wrapper (plugin unload
+ * removes both tabs). Trajectory owns its turn list in-body; Waterfall keeps
+ * the span stats header inside its body (chrome attachment retired).
  * @param ctx - client root context.
  */
 export function apply(ctx: Context): void {
-  // chrome.header on both views: the second chrome-attachment consumer
-  // (chat's footer StatsLine is the first) — proves both mount points live.
-  ctx.conversation.registerView({
-    id: 'trajectory', label: 'Trajectory', order: 10,
-    component: TrajectoryView, chrome: { header: TrajectoryStatsHeader },
-  })
-  ctx.conversation.registerView({
-    id: 'waterfall', label: 'Waterfall', order: 20,
-    component: WaterfallView, chrome: { header: TrajectoryStatsHeader },
-  })
+  ctx.slots.register(
+    { name: 'conversation.view', id: 'trajectory', order: 10, label: 'Trajectory' }, TrajectoryView)
+  ctx.slots.register(
+    { name: 'conversation.view', id: 'waterfall', order: 20, label: 'Waterfall' }, WaterfallView)
 }
diff --git a/packages/client/ui-trajectory/src/client/layout.ts b/packages/client/ui-trajectory/src/client/layout.ts
new file mode 100644
index 0000000000..e188498554
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/layout.ts
@@ -0,0 +1,418 @@
+/**
+ * Trajectory list fold: expand assistant blocks, attach usage to Message,
+ * own-duration times, in-flight partial/runningCalls, and group descriptions.
+ */
+import type {
+  AssistantMessageNode,
+  ConversationSnapshot,
+  ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { TrajectoryCellProps } from './TrajectoryCell.tsx'
+
+/** One Message or Step group inside a turn. */
+export interface TrajectoryGroupModel {
+  title: string
+  description?: string
+  cells: readonly TrajectoryCellProps[]
+}
+
+/** One sticky-turn section. */
+export interface TrajectoryTurnModel {
+  turn: number
+  groups: readonly TrajectoryGroupModel[]
+}
+
+/** Snapshot slice the trajectory view folds. */
+export interface TrajectoryLayoutInput {
+  nodes: ConversationSnapshot['nodes']
+  partial: ConversationSnapshot['partial']
+  runningCalls: ConversationSnapshot['runningCalls']
+}
+
+interface UsageLike {
+  inputTokens?: number
+  outputTokens?: number
+  reasoningTokens?: number
+}
+
+/** Cell plus absolute ms for group wall-span descriptions. */
+interface LaidCell {
+  cell: TrajectoryCellProps
+  absTime: number | null
+  toolName?: string
+  callId?: string
+}
+
+/**
+ * Fold a snapshot into turn → Message/Step groups with expanded cells.
+ * @param input - nodes plus in-flight partial/runningCalls.
+ * @returns turns ordered by first appearance.
+ */
+export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly TrajectoryTurnModel[] {
+  const { nodes, partial, runningCalls } = input
+  const resultByCall = indexResults(nodes)
+  const turns = new Map<number, { message: LaidCell[]; steps: Map<number, LaidCell[]> }>()
+  let index = 0
+  let prevAbsTime: number | null = null
+  let lastAssistantTurn: number | null = null
+
+  const bucket = (turn: number) => {
+    let entry = turns.get(turn)
+    if (entry === undefined) {
+      entry = { message: [], steps: new Map() }
+      turns.set(turn, entry)
+    }
+    return entry
+  }
+
+  const pushMessage = (turn: number, laid: LaidCell) => {
+    bucket(turn).message.push(laid)
+  }
+  const pushStep = (turn: number, step: number, laid: LaidCell) => {
+    const steps = bucket(turn).steps
+    const list = steps.get(step) ?? []
+    list.push(laid)
+    steps.set(step, list)
+  }
+
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i]
+    /* v8 ignore next -- dense-array guard: i stays within nodes.length, so the undefined arm needs a sparse array no caller builds. */
+    if (node === undefined) continue
+    if (node.kind === 'user' || node.kind === 'steering') {
+      // user/message has no turn on the wire; enclose it in the next assistant
+      // (or partial) turn, else open the turn after the last assistant.
+      const turn = node.kind === 'steering'
+        ? node.turn
+        : enclosingUserTurn(nodes, i, partial, lastAssistantTurn)
+      pushMessage(turn, {
+        absTime: finiteTime(node.time),
+        cell: {
+          index: ++index, kind: 'user', text: summarizeContent(node.content),
+          timeSeconds: 0,
+        },
+      })
+      prevAbsTime = finiteTime(node.time) ?? prevAbsTime
+      continue
+    }
+    if (node.kind === 'assistant') {
+      const laidList = expandAssistant(node, index + 1, prevAbsTime, resultByCall)
+      for (const laid of laidList) {
+        if (node.step > 0) pushStep(node.turn, node.step, laid)
+        else pushMessage(node.turn, laid)
+      }
+      const last = laidList[laidList.length - 1]
+      if (last !== undefined) index = last.cell.index
+      prevAbsTime = finiteTime(node.time) ?? prevAbsTime
+      lastAssistantTurn = node.turn
+      continue
+    }
+    if (node.kind === 'context') {
+      // No trajectory cell, but the surface still advances the duration cursor.
+      prevAbsTime = finiteTime(node.time) ?? prevAbsTime
+      continue
+    }
+    if (node.kind === 'tool-result') {
+      if (!callEmittedInAssistant(nodes, node.callId)) {
+        const toolName = node.call?.name
+        pushStep(0, 1, {
+          absTime: finiteTime(node.callTime ?? node.time),
+          ...(toolName !== undefined ? { toolName } : {}),
+          callId: node.callId,
+          cell: {
+            index: ++index,
+            kind: 'tool',
+            text: node.call !== null
+              ? summarizeCall(node.call.name, node.call.argsRaw)
+              : summarizeResult(node),
+            timeSeconds: durationSeconds(node.time, node.callTime),
+          },
+        })
+      }
+      prevAbsTime = finiteTime(node.time) ?? prevAbsTime
+    }
+  }
+
+  if (partial !== null) {
+    const fake: AssistantMessageNode = {
+      kind: 'assistant', seq: Number.MAX_SAFE_INTEGER, time: 0,
+      turn: partial.turn, step: partial.step, blocks: partial.blocks,
+    }
+    const laidList = expandAssistant(fake, index + 1, prevAbsTime, resultByCall, { streaming: true })
+    for (const laid of laidList) {
+      if (partial.step > 0) pushStep(partial.turn, partial.step, laid)
+      else pushMessage(partial.turn, laid)
+    }
+    const last = laidList[laidList.length - 1]
+    if (last !== undefined) index = last.cell.index
+  }
+
+  const seenCalls = collectCallIds(turns)
+  for (const call of runningCalls) {
+    if (seenCalls.has(call.callId)) continue
+    pushStep(call.turn, call.step > 0 ? call.step : 1, {
+      absTime: null,
+      toolName: call.name,
+      callId: call.callId,
+      cell: {
+        index: ++index,
+        kind: 'tool',
+        text: summarizeCall(call.name, call.argsRaw),
+        timeSeconds: null,
+      },
+    })
+  }
+
+  // Orphan turn-0 cells (orphaned tools / steering turn 0) fold into Turn 1.
+  const prologue = turns.get(0)
+  if (prologue !== undefined) {
+    turns.delete(0)
+    const emptyTurn = (): { message: LaidCell[]; steps: Map<number, LaidCell[]> } => ({
+      message: [],
+      steps: new Map(),
+    })
+    const first = turns.get(1) ?? emptyTurn()
+    first.message = [...prologue.message, ...first.message]
+    for (const [step, cells] of prologue.steps) {
+      const existing = first.steps.get(step) ?? []
+      first.steps.set(step, [...cells, ...existing])
+    }
+    turns.set(1, first)
+  }
+
+  return [...turns.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([turn, entry]) => toTurnModel(turn, entry))
+}
+
+function toTurnModel(
+  turn: number,
+  entry: { message: LaidCell[]; steps: Map<number, LaidCell[]> },
+): TrajectoryTurnModel {
+  const groups: TrajectoryGroupModel[] = []
+  if (entry.message.length > 0) {
+    const description = groupDescription(entry.message)
+    groups.push({
+      title: 'Message',
+      ...(description !== undefined ? { description } : {}),
+      cells: entry.message.map(l => l.cell),
+    })
+  }
+  for (const step of [...entry.steps.keys()].sort((a, b) => a - b)) {
+    const laid = entry.steps.get(step) ?? []
+    const description = groupDescription(laid)
+    groups.push({
+      title: `Step ${step}`,
+      ...(description !== undefined ? { description } : {}),
+      cells: laid.map(l => l.cell),
+    })
+  }
+  return { turn, groups }
+}
+
+/** Wall-span duration + tool histogram, e.g. `1.5s bash×6`. */
+function groupDescription(laid: readonly LaidCell[]): string | undefined {
+  const parts: string[] = []
+  // Tool rows contribute start (absTime) and end (start + own duration) so a
+  // single Tool cell still spans call→result for the group wall clock.
+  const times: number[] = []
+  for (const l of laid) {
+    if (l.absTime === null || !Number.isFinite(l.absTime)) continue
+    times.push(l.absTime)
+    if (l.cell.kind === 'tool' && l.cell.timeSeconds !== null && Number.isFinite(l.cell.timeSeconds)) {
+      times.push(l.absTime + l.cell.timeSeconds * 1000)
+    }
+  }
+  if (times.length >= 2) {
+    const span = formatGroupDuration((Math.max(...times) - Math.min(...times)) / 1000)
+    if (span !== undefined) parts.push(span)
+  } else if (times.length === 1) {
+    const own = laid.find(l => l.absTime === times[0])?.cell.timeSeconds
+    const span = own !== null && own !== undefined ? formatGroupDuration(own) : undefined
+    if (span !== undefined) parts.push(span)
+  }
+  const tools = new Map<string, number>()
+  for (const l of laid) {
+    if (l.toolName === undefined || l.cell.kind !== 'tool') continue
+    tools.set(l.toolName, (tools.get(l.toolName) ?? 0) + 1)
+  }
+  for (const [name, count] of tools) {
+    parts.push(count > 1 ? `${name}×${count}` : name)
+  }
+  return parts.length === 0 ? undefined : parts.join(' ')
+}
+
+function formatGroupDuration(seconds: number): string | undefined {
+  if (!Number.isFinite(seconds)) return undefined
+  const rounded = Math.round(seconds * 10) / 10
+  if (Number.isInteger(rounded)) return `${rounded}s`
+  return `${rounded.toFixed(1)}s`
+}
+
+/** Own-duration seconds from two epoch-ms stamps; null when either is unusable. */
+function durationSeconds(later: number, earlier: number | null): number | null {
+  if (earlier === null || !Number.isFinite(later) || !Number.isFinite(earlier)) return null
+  return Math.max(0, (later - earlier) / 1000)
+}
+
+/** Epoch-ms usable as an absolute time, else null. */
+function finiteTime(time: number): number | null {
+  return Number.isFinite(time) ? time : null
+}
+
+function expandAssistant(
+  node: AssistantMessageNode,
+  startIndex: number,
+  prevAbsTime: number | null,
+  results: Map<string, ToolResultNode>,
+  opts?: { streaming?: boolean },
+): LaidCell[] {
+  const out: LaidCell[] = []
+  let index = startIndex - 1
+  const usage = node.usage as UsageLike | undefined
+  const streaming = opts?.streaming === true
+  const messageDuration = streaming ? null : durationSeconds(node.time, prevAbsTime)
+  const nodeAbs = streaming ? null : finiteTime(node.time)
+  let usageAttached = false
+
+  for (const block of node.blocks) {
+    // Reasoning blocks are skipped: no block-level clock, so no Think cell.
+    if (block.kind === 'reasoning') continue
+    if (block.kind === 'text') {
+      if (block.text === '' && streaming) continue
+      const cell: TrajectoryCellProps = {
+        index: ++index, kind: 'message', text: summarizeText(block.text),
+        timeSeconds: messageDuration,
+      }
+      if (!usageAttached) {
+        attachUsage(cell, usage)
+        usageAttached = usage !== undefined
+      }
+      out.push({ absTime: nodeAbs, cell })
+      continue
+    }
+    if (block.kind === 'tool-call') {
+      const result = results.get(block.callId)
+      const toolDuration = streaming || result === undefined
+        ? null
+        : durationSeconds(result.time, result.callTime)
+      const callAbs = streaming
+        ? null
+        : (result?.callTime !== null && result?.callTime !== undefined && Number.isFinite(result.callTime)
+          ? result.callTime
+          : nodeAbs)
+      out.push({
+        absTime: callAbs,
+        toolName: block.name,
+        callId: block.callId,
+        cell: {
+          index: ++index, kind: 'tool',
+          text: summarizeCall(block.name, block.argsRaw),
+          timeSeconds: toolDuration,
+        },
+      })
+    }
+  }
+
+  if (out.length === 0 && !streaming) {
+    // Reasoning-only / empty success still owns provider usage on the Message row.
+    const cell: TrajectoryCellProps = {
+      index: ++index, kind: 'message', text: '', timeSeconds: messageDuration,
+    }
+    attachUsage(cell, usage)
+    out.push({ absTime: nodeAbs, cell })
+  }
+  return out
+}
+
+/**
+ * Turn that encloses a user/message: next assistant/steering turn, else the
+ * in-flight partial, else the turn after the last finalized assistant (or 1).
+ */
+function enclosingUserTurn(
+  nodes: ConversationSnapshot['nodes'],
+  userIndex: number,
+  partial: ConversationSnapshot['partial'],
+  lastAssistantTurn: number | null,
+): number {
+  for (let i = userIndex + 1; i < nodes.length; i++) {
+    const n = nodes[i]
+    /* v8 ignore next -- dense-array guard: i stays within nodes.length, so the undefined arm needs a sparse array no caller builds. */
+    if (n === undefined) continue
+    if (n.kind === 'assistant' || n.kind === 'steering') return n.turn
+  }
+  if (partial !== null) return partial.turn
+  if (lastAssistantTurn !== null) return lastAssistantTurn + 1
+  return 1
+}
+
+/** Copy provider usage onto a Message cell when present. */
+function attachUsage(cell: TrajectoryCellProps, usage: UsageLike | undefined): void {
+  if (usage === undefined) return
+  if (usage.inputTokens !== undefined) cell.input = usage.inputTokens
+  if (usage.outputTokens !== undefined) cell.output = usage.outputTokens
+  if (usage.reasoningTokens !== undefined) cell.think = usage.reasoningTokens
+}
+
+function indexResults(nodes: ConversationSnapshot['nodes']): Map<string, ToolResultNode> {
+  const map = new Map<string, ToolResultNode>()
+  for (const node of nodes) {
+    if (node.kind === 'tool-result') map.set(node.callId, node)
+  }
+  return map
+}
+
+function callEmittedInAssistant(nodes: ConversationSnapshot['nodes'], callId: string): boolean {
+  for (const node of nodes) {
+    if (node.kind !== 'assistant') continue
+    if (node.blocks.some(b => b.kind === 'tool-call' && b.callId === callId)) return true
+  }
+  return false
+}
+
+function collectCallIds(
+  turns: Map<number, { message: LaidCell[]; steps: Map<number, LaidCell[]> }>,
+): Set<string> {
+  const ids = new Set<string>()
+  for (const entry of turns.values()) {
+    for (const laid of entry.message) {
+      if (laid.callId !== undefined) ids.add(laid.callId)
+    }
+    for (const list of entry.steps.values()) {
+      for (const laid of list) {
+        if (laid.callId !== undefined) ids.add(laid.callId)
+      }
+    }
+  }
+  return ids
+}
+
+function summarizeCall(name: string, argsRaw: string): string {
+  const args = argsRaw.replace(/\s+/g, ' ').trim()
+  if (args === '') return name
+  const clipped = args.length > 72 ? `${args.slice(0, 71)}…` : args
+  return `${name} · ${clipped}`
+}
+
+function summarizeResult(node: ToolResultNode): string {
+  if (node.isError) {
+    return node.error?.code ?? 'error'
+  }
+  for (const block of node.content) {
+    if (block.type === 'text' && typeof block.text === 'string' && block.text !== '') {
+      return summarizeText(block.text)
+    }
+  }
+  return node.call?.name ?? node.callId
+}
+
+function summarizeContent(content: readonly { type: string; text?: string }[]): string {
+  for (const block of content) {
+    if (block.type === 'text' && typeof block.text === 'string') return summarizeText(block.text)
+  }
+  return ''
+}
+
+function summarizeText(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
diff --git a/packages/client/ui-trajectory/src/client/views.module.css b/packages/client/ui-trajectory/src/client/views.module.css
index 951a5e2705..d3089b3568 100644
--- a/packages/client/ui-trajectory/src/client/views.module.css
+++ b/packages/client/ui-trajectory/src/client/views.module.css
@@ -1,25 +1,34 @@
+/* Full-bleed scroll host so Turn sticky bars can paint edge-to-edge;
+ * cell content width is capped on the turn body (max 880). */
 .root {
-  padding: 16px;
   overflow-y: auto;
+  height: 100%;
+  min-height: 0;
+  width: 100%;
+  box-sizing: border-box;
   color: var(--dsw-alias-label-primary);
-  font-size: 13px;
+  background: var(--dsw-specific-sidebar-fill);
 }
 
 .empty {
+  padding: 16px;
   color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xs-13);
 }
 
+/* Waterfall placeholder rows (shared module). */
 .row {
   display: flex;
   align-items: center;
   gap: 8px;
-  padding: 4px 0;
+  padding: 4px 16px;
 }
 
 .turnTag {
   flex: none;
   width: 64px;
   color: var(--dsw-alias-label-secondary);
+  font: var(--dsw-font-xs-13);
 }
 
 .bar {
@@ -29,9 +38,10 @@
 }
 
 .barCalls {
-  background: var(--dsw-alias-brand-primary);
+  background: var(--dsw-alias-brand-primary-new-colorprimary-new-color);
 }
 
 .meta {
   color: var(--dsw-alias-label-caption);
+  font: var(--dsw-font-xs-13);
 }
diff --git a/packages/client/ui-trajectory/src/invariant.ts b/packages/client/ui-trajectory/src/invariant.ts
index 46efab68a3..8638145fbe 100644
--- a/packages/client/ui-trajectory/src/invariant.ts
+++ b/packages/client/ui-trajectory/src/invariant.ts
@@ -16,8 +16,8 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: a pure-consumer plugin — it emits no cordis events
- * and owns no mutable cross-plugin state; both view registrations are plain
- * effects whose disposal the conversation registry's own specs and this
+ * and owns no mutable cross-plugin state; both view-slot registrations are
+ * plain effects whose disposal the slot ledger's own specs and this
  * package's behavior specs observe directly.
  */
 const install: InvariantInstaller = () => {}
diff --git a/packages/client/ui-trajectory/tests/cell.spec.tsx b/packages/client/ui-trajectory/tests/cell.spec.tsx
new file mode 100644
index 0000000000..d9c9004622
--- /dev/null
+++ b/packages/client/ui-trajectory/tests/cell.spec.tsx
@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+/**
+ * TrajectoryCell presentation: kind tags, ellipsis-hosting text, Message
+ * metric columns, own-duration formatting, and selected ring.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import {
+  formatElapsedSeconds,
+  TrajectoryCell,
+  type TrajectoryCellKind,
+} from '../src/client/TrajectoryCell.tsx'
+
+afterEach(cleanup)
+
+describe('formatElapsedSeconds', () => {
+  it('formats known durations and uses an em dash when absent', () => {
+    expect(formatElapsedSeconds(null)).toBe('—')
+    expect(formatElapsedSeconds(235)).toBe('+235s')
+    expect(formatElapsedSeconds(235.0)).toBe('+235s')
+    expect(formatElapsedSeconds(235.2)).toBe('+235.2s')
+    expect(formatElapsedSeconds(235.25)).toBe('+235.3s')
+    expect(formatElapsedSeconds(0)).toBe('+0s')
+    expect(formatElapsedSeconds(Number.NaN)).toBe('—')
+  })
+})
+
+describe('TrajectoryCell', () => {
+  it('renders index, kind tag, text, and time for a Tool row', () => {
+    render(
+      <TrajectoryCell
+        index={6}
+        kind="tool"
+        text="bash · Read src/index.ts"
+        timeSeconds={5}
+      />,
+    )
+    expect(screen.getByText('#6')).toBeTruthy()
+    expect(screen.getByText('Tool')).toBeTruthy()
+    expect(screen.getByText('bash · Read src/index.ts')).toBeTruthy()
+    expect(screen.getByText('+5s')).toBeTruthy()
+  })
+
+  it('Message rows expose Input / Output / Think metric columns before time', () => {
+    const { container } = render(
+      <TrajectoryCell
+        index={3}
+        kind="message"
+        text="Let me now read the actual source files to understa..."
+        timeSeconds={235.2}
+        input={136}
+        output={381}
+        think={155}
+      />,
+    )
+    expect(screen.getByText('Message')).toBeTruthy()
+    expect(screen.getByText('136')).toBeTruthy()
+    expect(screen.getByText('381')).toBeTruthy()
+    expect(screen.getByText('155')).toBeTruthy()
+    expect(screen.getByText('+235.2s')).toBeTruthy()
+    const texts = [...container.querySelectorAll('span')].map((el) => el.textContent)
+    expect(texts.indexOf('136')).toBeLessThan(texts.indexOf('381'))
+    expect(texts.indexOf('381')).toBeLessThan(texts.indexOf('155'))
+    expect(texts.indexOf('155')).toBeLessThan(texts.indexOf('+235.2s'))
+  })
+
+  it('selected marks the row for the brand-primary inset ring', () => {
+    const { container } = render(
+      <TrajectoryCell index={15} kind="message" text="pictur..." timeSeconds={123.6} selected />,
+    )
+    expect(container.firstElementChild?.getAttribute('data-selected')).toBe('true')
+  })
+
+  it.each([
+    ['user', 'User'],
+    ['tool', 'Tool'],
+  ] as const)('kind %s shows the %s tag and no metric columns', (kind: TrajectoryCellKind, label: string) => {
+    const { container } = render(
+      <TrajectoryCell index={1} kind={kind} text="summary" timeSeconds={kind === 'user' ? 0 : null} input={1} output={2} think={3} />,
+    )
+    expect(screen.getByText(label)).toBeTruthy()
+    expect(container.querySelector('[data-kind]')?.getAttribute('data-kind')).toBe(kind)
+    expect(screen.queryByText('1')).toBeNull()
+    expect(screen.queryByText('2')).toBeNull()
+    expect(screen.queryByText('3')).toBeNull()
+  })
+})
diff --git a/packages/client/ui-trajectory/tests/client-bundle.spec.ts b/packages/client/ui-trajectory/tests/client-bundle.spec.ts
index 1cf411420c..edaf34a2cb 100644
--- a/packages/client/ui-trajectory/tests/client-bundle.spec.ts
+++ b/packages/client/ui-trajectory/tests/client-bundle.spec.ts
@@ -1,21 +1,21 @@
 // @vitest-environment jsdom
 /**
  * Real tsdown artifact shape: lib/client.js hands off through
- * window.DSHClientProxy.loadPlugin, resolves externals through the injected
+ * window.__ModuleLoader__.load, resolves externals through the injected
  * require, returns the export surface (apply + inject), and a mounted apply
- * registers both views into a real ConversationService. Skips when dist/ is
+ * registers both view tabs into a real SlotsService ring. Skips when dist/ is
  * not built (`pnpm --filter @deepseek-ai/dsh-client-ui-trajectory bundle`).
  */
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it } from 'vitest'
-import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 
 const PLUGIN_ID = '@deepseek-ai/dsh-client-ui-trajectory'
 
 interface Handoff { id: string; factory: (require: (spec: string) => unknown) => Record<string, unknown> }
-type Win = { DSHClientProxy?: { loadPlugin(h: Handoff): void } }
+type Win = { __ModuleLoader__?: { load(h: Handoff): void } }
 
 function readBundle(): string | undefined {
   try {
@@ -28,7 +28,7 @@ function readBundle(): string | undefined {
 }
 
 afterEach(() => {
-  delete (window as Win).DSHClientProxy
+  delete (window as Win).__ModuleLoader__
   for (const el of document.querySelectorAll('style')) el.remove()
 })
 
@@ -37,7 +37,7 @@ describe('tsdown client artifact', () => {
 
   async function loadArtifact() {
     let handoff: Handoff | undefined
-    ;(window as Win).DSHClientProxy = { loadPlugin: (h) => { handoff = h } }
+    ;(window as Win).__ModuleLoader__ = { load: (h) => { handoff = h } }
     // Same execution form the loader uses (inline script eval, window scope) —
     // the implied-eval ban targets accidental string execution, not this
     // deliberate bundle-execution fixture.
@@ -59,18 +59,27 @@ describe('tsdown client artifact', () => {
     const { handoff, surface } = await loadArtifact()
     expect(handoff.id).toBe(PLUGIN_ID)
     expect(surface.apply).toBeTypeOf('function')
-    expect(surface.inject).toEqual(['conversation'])
+    expect(surface.inject).toEqual(['slots', 'conversation'])
   })
 
-  it.skipIf(code === undefined)('mounted as an object plugin, apply registers both views on the real service', async () => {
+  it.skipIf(code === undefined)('mounted as an object plugin, apply registers both view tabs on the real ring', async () => {
     const { surface } = await loadArtifact()
     const ctx = new Context()
-    const svc = new ConversationService(ctx)
+    const slots = new SlotsService(ctx)
+    // The conversation entry's role: the ring must be declared before riders land.
+    slots.register({
+      name: 'root',
+      children: { 'conversation.view': { kind: 'list', scope: 'session' } },
+    }, (_p: { renderSlot?: unknown }) => null)
+    // The plugin injects 'conversation' as an ordering edge (the declaring
+    // plugin provides it after declaring the ring); the bench declares the
+    // ring itself, so a stub satisfies the wait.
+    ctx.provide('conversation', {})
     const fiber = ctx.plugin(surface as { apply: (ctx: Context) => void })
     await fiber.await()
-    expect(svc.views().map(v => v.id)).toEqual(['trajectory', 'waterfall'])
+    expect(slots.entries('conversation.view').map(e => e.options.id)).toEqual(['trajectory', 'waterfall'])
     await fiber.dispose()
-    expect(svc.views()).toHaveLength(0)
+    expect(slots.entries('conversation.view')).toHaveLength(0)
   })
 
   it.skipIf(code === undefined)('injects plugin-tagged module CSS during factory execution', async () => {
diff --git a/packages/client/ui-trajectory/tests/layout.spec.tsx b/packages/client/ui-trajectory/tests/layout.spec.tsx
new file mode 100644
index 0000000000..9773f6fe57
--- /dev/null
+++ b/packages/client/ui-trajectory/tests/layout.spec.tsx
@@ -0,0 +1,206 @@
+// @vitest-environment jsdom
+/**
+ * Trajectory turn chrome and layout fold: expand blocks, usage on Message,
+ * tool own-duration, group wall-span descriptions, in-flight rows.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import { TrajectoryGroupHeader } from '../src/client/TrajectoryGroupHeader.tsx'
+import { TrajectoryTurn } from '../src/client/TrajectoryTurn.tsx'
+import { TrajectoryTurnHeader } from '../src/client/TrajectoryTurnHeader.tsx'
+import { deriveTrajectoryLayout } from '../src/client/layout.ts'
+
+afterEach(cleanup)
+
+describe('TrajectoryTurnHeader', () => {
+  it('renders Turn N and the four metric column labels', () => {
+    render(<TrajectoryTurnHeader turn={1} />)
+    expect(screen.getByText('Turn 1')).toBeTruthy()
+    expect(screen.getByText('Input')).toBeTruthy()
+    expect(screen.getByText('Output')).toBeTruthy()
+    expect(screen.getByText('Think')).toBeTruthy()
+    expect(screen.getByText('Time')).toBeTruthy()
+  })
+})
+
+describe('TrajectoryGroupHeader', () => {
+  it('renders title and optional description', () => {
+    render(<TrajectoryGroupHeader title="Step 1" description="2.2s skill" />)
+    expect(screen.getByText('Step 1')).toBeTruthy()
+    expect(screen.getByText('2.2s skill')).toBeTruthy()
+  })
+
+  it('omits the description node when absent', () => {
+    const { container } = render(<TrajectoryGroupHeader title="Message" />)
+    expect(screen.getByText('Message')).toBeTruthy()
+    expect(container.querySelectorAll('span')).toHaveLength(1)
+  })
+})
+
+describe('TrajectoryTurn', () => {
+  it('wraps a sticky header and body children', () => {
+    render(
+      <TrajectoryTurn turn={3}>
+        <TrajectoryGroupHeader title="Message" description="49s" />
+      </TrajectoryTurn>,
+    )
+    expect(screen.getByText('Turn 3')).toBeTruthy()
+    expect(screen.getByText('Message')).toBeTruthy()
+    expect(screen.getByText('49s')).toBeTruthy()
+  })
+})
+
+describe('deriveTrajectoryLayout', () => {
+  it('expands assistant blocks, hangs usage on Message, and folds call+result into Tool', () => {
+    const nodes = [
+      { kind: 'user', seq: 1, time: 1_000, content: [{ type: 'text', text: 'hello' }], source: null },
+      {
+        kind: 'assistant', seq: 2, time: 6_000, turn: 1, step: 1,
+        blocks: [
+          { kind: 'reasoning', text: 'thinking…' },
+          { kind: 'text', text: 'I will run bash' },
+          { kind: 'tool-call', callId: 'c1', name: 'bash', argsRaw: '{"command":"ls"}' },
+        ],
+        usage: { inputTokens: 10, outputTokens: 20, reasoningTokens: 5 },
+      },
+      {
+        kind: 'tool-result', seq: 3, time: 7_500, callId: 'c1',
+        call: { name: 'bash', argsRaw: '{"command":"ls"}' }, callTime: 6_200,
+        content: [{ type: 'text', text: 'a.txt' }], isError: false, callView: null, resultView: null,
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    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))
+    expect(kinds).toEqual(['user', 'message', 'tool'])
+    const message = turns[0]?.groups.flatMap((g) => g.cells).find((c) => c.kind === 'message')
+    expect(message).toMatchObject({
+      input: 10, output: 20, think: 5, timeSeconds: 5,
+    })
+    const tool = turns[0]?.groups.flatMap((g) => g.cells).find((c) => c.kind === 'tool')
+    expect(tool?.text).toBe('bash · {"command":"ls"}')
+    expect(tool?.timeSeconds).toBe(1.3)
+  })
+
+  it('adds runningCalls not already present and leaves their time blank', () => {
+    const turns = deriveTrajectoryLayout({
+      nodes: [] as unknown as ConversationSnapshot['nodes'],
+      partial: null,
+      runningCalls: [{
+        callId: 'r1', name: 'bash', argsRaw: '{"command":"pwd"}',
+        turn: 1, step: 2, time: 9_000, callView: null,
+      }],
+    })
+    expect(turns[0]?.groups.map((g) => g.title)).toEqual(['Step 2'])
+    expect(turns[0]?.groups[0]?.cells[0]).toMatchObject({
+      kind: 'tool', text: 'bash · {"command":"pwd"}', timeSeconds: null,
+    })
+  })
+
+  it('omits duration when node times are missing instead of rendering NaN', () => {
+    const nodes = [
+      { kind: 'user', seq: 1, content: [{ type: 'text', text: 'hi' }], source: null },
+      {
+        kind: 'assistant', seq: 2, turn: 1, step: 1,
+        blocks: [
+          { kind: 'reasoning', text: '…' },
+          { kind: 'text', text: 'ok' },
+        ],
+        usage: { inputTokens: 1, outputTokens: 2, reasoningTokens: 3 },
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    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()
+  })
+
+  it('builds a wall-span step description with a tool histogram', () => {
+    const nodes = [
+      {
+        kind: 'assistant', seq: 1, time: 1_000, turn: 1, step: 1,
+        blocks: [
+          { kind: 'tool-call', callId: 'a', name: 'bash', argsRaw: '{}' },
+          { kind: 'tool-call', callId: 'b', name: 'bash', argsRaw: '{}' },
+        ],
+      },
+      {
+        kind: 'tool-result', seq: 2, time: 2_500, callId: 'a',
+        call: { name: 'bash', argsRaw: '{}' }, callTime: 1_100,
+        content: [], isError: false, callView: null, resultView: null,
+      },
+      {
+        kind: 'tool-result', seq: 3, time: 4_000, callId: 'b',
+        call: { name: 'bash', argsRaw: '{}' }, callTime: 2_600,
+        content: [], isError: false, callView: null, resultView: null,
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
+    expect(turns[0]?.groups[0]?.description).toBe('2.9s bash×2')
+  })
+
+  it('assigns each user message to its enclosing turn instead of pooling into Turn 1', () => {
+    const nodes = [
+      { kind: 'user', seq: 1, time: 1_000, content: [{ type: 'text', text: 'first' }], source: null },
+      {
+        kind: 'assistant', seq: 2, time: 2_000, turn: 1, step: 0,
+        blocks: [{ kind: 'text', text: 'ok1' }],
+      },
+      { kind: 'user', seq: 3, time: 3_000, content: [{ type: 'text', text: 'second' }], source: null },
+      {
+        kind: 'assistant', seq: 4, time: 4_000, turn: 2, step: 0,
+        blocks: [{ kind: 'text', text: 'ok2' }],
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    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'])
+  })
+
+  it('keeps usage on the fallback Message row when assistant has no text block', () => {
+    const nodes = [
+      {
+        kind: 'assistant', seq: 1, time: 5_000, turn: 1, step: 0,
+        blocks: [{ kind: 'reasoning', text: '…' }],
+        usage: { inputTokens: 11, outputTokens: 22, reasoningTokens: 3 },
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    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,
+    })
+  })
+
+  it('advances the duration cursor over context nodes', () => {
+    const nodes = [
+      { kind: 'user', seq: 1, time: 1_000, content: [{ type: 'text', text: 'hi' }], source: null },
+      {
+        kind: 'assistant', seq: 2, time: 2_000, turn: 1, step: 1,
+        blocks: [{ kind: 'tool-call', callId: 'c1', name: 'bash', argsRaw: '{}' }],
+      },
+      {
+        kind: 'tool-result', seq: 3, time: 3_000, callId: 'c1',
+        call: { name: 'bash', argsRaw: '{}' }, callTime: 2_100,
+        content: [], isError: false, callView: null, resultView: null,
+      },
+      {
+        kind: 'context', seq: 4, time: 9_000,
+        content: [{ type: 'text', text: 'extra' }], source: null,
+      },
+      {
+        kind: 'assistant', seq: 5, time: 10_000, turn: 1, step: 0,
+        blocks: [{ kind: 'text', text: 'done' }],
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
+    const message = turns[0]?.groups
+      .flatMap((g) => g.cells)
+      .find((c) => c.kind === 'message' && c.text === 'done')
+    // From context at 9s, not from the earlier user/tool surfaces.
+    expect(message?.timeSeconds).toBe(1)
+  })
+})
diff --git a/packages/client/ui-trajectory/tests/views.spec.tsx b/packages/client/ui-trajectory/tests/views.spec.tsx
index e7f99d9128..4818e67db5 100644
--- a/packages/client/ui-trajectory/tests/views.spec.tsx
+++ b/packages/client/ui-trajectory/tests/views.spec.tsx
@@ -1,25 +1,25 @@
 // @vitest-environment jsdom
 /**
  * View registration acceptance on the real framework stack: the plugin fiber
- * registers trajectory/waterfall into a real ConversationService, tabs switch
- * inside ConversationRoot (four-share props form; view rendering is
- * in-component now) without collapsing chat, chrome.header renders the span
- * stats bar, and fiber disposal removes both tabs. Span derivation edge cases
- * ride along.
+ * registers trajectory/waterfall into a real SlotsService view ring, tabs
+ * switch inside ConversationRoot (renderSlot share driven by the same tab
+ * projection apply uses) without collapsing chat, trajectory renders the
+ * turn-list chrome (no span stats bar), waterfall keeps in-body stats, and
+ * fiber disposal removes both tabs. Span derivation edge cases ride along.
  */
 import { Context } from 'cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
-import { createElement, type FC } from 'react'
-import { bindSnapshotSelector } from '../../web-react/src/bind.ts'
+import { createElement, type FC, type ReactNode } from 'react'
+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-ui-slots'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSnapshot, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
-import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ConvViewProps, ViewTab } from '@deepseek-ai/dsh-client-ui-conversation/client'
 // Export discipline: packages/client/AGENTS.md.
-import { ConversationRoot } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/ConversationRoot.tsx'
+import { ConversationRoot, type ConversationRootProps } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/ConversationRoot.tsx'
 import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
-import type { ConvViewProps, ViewId } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-trajectory/client'
 import { deriveSpans, deriveSpanStats } from '@deepseek-ai/dsh-client-ui-trajectory/src/client/spans.ts'
 import { TrajectoryStatsHeader } from '@deepseek-ai/dsh-client-ui-trajectory/src/client/TrajectoryStatsHeader.tsx'
@@ -28,118 +28,164 @@ import { WaterfallView } from '@deepseek-ai/dsh-client-ui-trajectory/src/client/
 import { apply as nodeApply } from '@deepseek-ai/dsh-client-ui-trajectory'
 
 const SID = 's1' as SessionId
+/** Fallback-only chain stub (no composer takeover in these benches). */
+const fallbackRenderSlotChain: ConversationRootProps['renderSlotChain'] =
+  (_key, _owner, opts) => opts?.fallback ?? null
 
 afterEach(cleanup)
 // The chat store persists under its declared key; clear so one case's active
 // view cannot rehydrate into the next.
 beforeEach(() => {
-  localStorage.clear()
+  // Node 22+ exposes an experimental localStorage global that is undefined
+  // without --localstorage-file; only clear when a real Storage is present.
+  if (typeof localStorage !== 'undefined') localStorage.clear()
 })
 
 /** Node fixture: user prologue, two turns, one tool result inside turn 1. */
 const NODES = [
-  { kind: 'user', seq: 1, content: [], source: null },
-  { kind: 'assistant', seq: 2, turn: 1, step: 1, blocks: [] },
-  { kind: 'tool-result', seq: 3, callId: 'c1', call: null, content: [], isError: false, callView: null, resultView: null },
-  { kind: 'assistant', seq: 4, turn: 2, step: 1, blocks: [] },
+  { kind: 'user', seq: 1, time: 1_000, content: [], source: null },
+  { kind: 'assistant', seq: 2, time: 2_000, turn: 1, step: 1, blocks: [] },
+  {
+    kind: 'tool-result', seq: 3, time: 3_000, callId: 'c1', call: null, callTime: null,
+    content: [], isError: false, callView: null, resultView: null,
+  },
+  { kind: 'assistant', seq: 4, time: 4_000, turn: 2, step: 1, blocks: [] },
 ] as unknown as ConversationSnapshot['nodes']
 
 function fakeSession(nodes: ConversationSnapshot['nodes']) {
-  const store = createSnapshotStore<{ nodes: ConversationSnapshot['nodes'] }>({ nodes })
+  const store = createSnapshotStore({
+    nodes, partial: null, runningCalls: [] as ConversationSnapshot['runningCalls'],
+  })
   return { store, useSession: bindSnapshotSelector(store) as unknown as UseSession<ConversationSnapshot> }
 }
 
-/** Empty sessions-list hook stub (breadcrumbs fall back to the raw id). */
+/** Empty sessions-list hook stub (breadcrumbs fall back to the raw id; engines carry no hook since the store migration — bind here). */
 function emptySessions() {
   const store = createSnapshotStore<SessionListState>(
     { ids: [], byId: {}, current: undefined } as SessionListState)
   return bindSnapshotSelector(store)
 }
 
-/** Chat-view stand-in props for standalone view mounts. */
+/** SessionProvider seat stub (render-prop pass-through; ConversationRoot never invokes it). */
+const SessionProviderStub: ConversationRootProps['SessionProvider'] = ({ children }) => <>{children(SID)}</>
+
+/** Standalone view props: the session-scope standard kit the outlet would bake. */
 function standaloneProps(nodes: ConversationSnapshot['nodes']): ConvViewProps {
-  const chat = createChatStore().create()
   return {
     sessionId: SID,
     useSession: fakeSession(nodes).useSession,
-    useStore: bindSnapshotSelector(chat),
-    actions: { openDetails: vi.fn(), loadOlder: vi.fn() },
+    useSessions: emptySessions(),
   } as unknown as ConvViewProps
 }
 
-/** Real-stack bench: root Context + real ConversationService + the plugin fiber. */
+/** Real-stack bench: root Context + real SlotsService ring + the plugin fiber. */
 async function bench() {
   const ctx = new Context()
-  const svc = new ConversationService(ctx)
+  const slots = new SlotsService(ctx)
+  // The conversation entry's role: declare the ring, then seed the chat entry.
+  slots.register({
+    name: 'root',
+    children: { 'conversation.view': { kind: 'list', scope: 'session' } },
+  }, (_p: { renderSlot?: unknown }) => null)
   const chatBody = vi.fn(() => <div data-testid="chat-body" />)
-  svc.registerView({ id: 'chat' as ViewId, label: 'Chat', order: 0, component: chatBody as unknown as FC<ConvViewProps> })
+  slots.register(
+    { name: 'conversation.view', id: 'chat', order: 0, label: 'Chat' } as never, chatBody as never)
+  // 'conversation' inject is an ordering edge; the bench declares the ring
+  // itself, so a stub satisfies the wait.
+  ctx.provide('conversation', {})
   const fiber = ctx.plugin({ inject: [...inject], apply })
   await fiber.await()
-  return { ctx, svc, fiber }
+  return { ctx, slots, fiber }
 }
 
-/** Mount ConversationRoot over the service's registry face (four-share form: chrome/view rendering is in-component). */
-function mount(svc: ConversationService, nodes: ConversationSnapshot['nodes'] = NODES) {
-  const sessionSnapshot = createSnapshotStore<{ running: boolean; removed: boolean; promptError: null; nodes: ConversationSnapshot['nodes'] }>({
+/** Tab projection twin of apply's viewTabs (the render-side consumption path). */
+function tabsOf(slots: SlotsService): ViewTab[] {
+  return slots.entries('conversation.view')
+    .map(e => ({ id: e.options.id!, label: e.options.label ?? e.options.id! }))
+}
+
+/** Mount ConversationRoot over the ring ledger with an outlet-faithful renderSlot. */
+function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES) {
+  const sessionSnapshot = createSnapshotStore({
     running: false, removed: false, promptError: null, nodes,
+    partial: null, runningCalls: [] as ConversationSnapshot['runningCalls'],
   })
+  const useSession = bindSnapshotSelector(sessionSnapshot) as unknown as UseSession<ConversationSnapshot>
   const chat = createChatStore().create()
+  // Minimal outlet twin: resolve the ring entry by the `only` filter and
+  // render it with the session standard kit (what SlotOutlet does for a
+  // list-kind session slot, minus machinery).
+  const renderSlot = ((key: string, _owner: object, opts?: { only?: string }): ReactNode => {
+    const entry = slots.entries('conversation.view').find(e => e.options.id === opts?.only)
+    if (entry === undefined) return null
+    const View = entry.component as FC<ConvViewProps>
+    return (
+      <View
+        {...({ sessionId: SID, useSession, useSessions: emptySessions() } as unknown as ConvViewProps)}
+        key={key}
+      />
+    )
+  }) as unknown as ConversationRootProps['renderSlot']
   return render(
     <ConversationRoot
       sessionId={SID}
-      useSession={bindSnapshotSelector(sessionSnapshot) as unknown as UseSession<ConversationSnapshot>}
+      useSession={useSession}
       useSessions={emptySessions()}
       useStore={bindSnapshotSelector(chat)}
       actions={chat.actions}
+      renderSlot={renderSlot}
+      renderSlotChain={fallbackRenderSlotChain}
+      SessionProvider={SessionProviderStub}
       views={{
-        list: () => svc.views(),
-        subscribe: (fn) => svc.subscribeViews(fn),
-        version: () => svc.viewsVersion(),
+        list: () => tabsOf(slots),
+        subscribe: (fn) => slots.subscribe('conversation.view', fn),
+        version: () => slots.getVersion('conversation.view'),
       }}
       send={vi.fn()}
       stop={vi.fn()}
-      openDetails={vi.fn()}
-      loadOlder={vi.fn()}
       open={vi.fn()}
     />,
   )
 }
 
 describe('plugin registration', () => {
-  it('registers trajectory and waterfall after chat, both with header chrome', async () => {
+  it('registers trajectory and waterfall after chat on the ring', async () => {
     const b = await bench()
-    const views = b.svc.views()
-    expect(views.map((v) => v.id)).toEqual(['chat', 'trajectory', 'waterfall'])
-    expect(views[1]?.chrome?.header).toBeDefined()
-    expect(views[2]?.chrome?.header).toBeDefined()
-    expect(views[1]?.chrome?.footer).toBeUndefined()
+    expect(tabsOf(b.slots)).toEqual([
+      { id: 'chat', label: 'Chat' },
+      { id: 'trajectory', label: 'Trajectory' },
+      { id: 'waterfall', label: 'Waterfall' },
+    ])
   })
 
   it('fiber disposal removes both tabs and leaves chat standing', async () => {
     const b = await bench()
     await b.fiber.dispose()
-    expect(b.svc.views().map((v) => v.id)).toEqual(['chat'])
+    expect(tabsOf(b.slots).map((v) => v.id)).toEqual(['chat'])
   })
 })
 
 describe('tab switching in ConversationRoot', () => {
-  it('renders all three tabs, defaults to chat, and switches to trajectory with its header stats', async () => {
+  it('renders all three tabs, defaults to chat, and switches to trajectory without stats chrome', async () => {
     const b = await bench()
-    mount(b.svc)
+    mount(b.slots)
     expect(screen.getByTestId('chat-body')).toBeTruthy()
     expect(screen.getAllByRole('tab').map((t) => t.textContent)).toEqual(['Chat', 'Trajectory', 'Waterfall'])
 
     fireEvent.click(screen.getByRole('tab', { name: 'Trajectory' }))
-    // chrome.header stats over NODES: turns 0/1/2, 2 assistant steps, 1 tool call.
-    expect(screen.getByText('3 turns · 2 steps · 1 tool calls')).toBeTruthy()
-    expect(screen.getByText('turn 0')).toBeTruthy()
-    expect(screen.getByText('1 steps · 1 calls · 2 nodes')).toBeTruthy()
+    // Trajectory no longer mounts the span stats bar; the turn-list chrome owns the body.
+    expect(screen.queryByText(/turns ·/)).toBeNull()
+    expect(screen.getByText('Turn 1')).toBeTruthy()
+    expect(screen.getByText('Turn 2')).toBeTruthy()
+    expect(screen.getAllByText('Message').length).toBeGreaterThan(0)
+    expect(screen.getAllByText('Step 1').length).toBeGreaterThan(0)
+    expect(screen.getAllByText('Input').length).toBeGreaterThan(0)
     expect(screen.queryByTestId('chat-body')).toBeNull()
   })
 
   it('waterfall renders bars and switching back to chat does not collapse it', async () => {
     const b = await bench()
-    mount(b.svc)
+    mount(b.slots)
     fireEvent.click(screen.getByRole('tab', { name: 'Waterfall' }))
     expect(screen.getByTitle('2 nodes')).toBeTruthy()
     expect(screen.getByTitle('1 tool calls')).toBeTruthy()
@@ -148,9 +194,9 @@ describe('tab switching in ConversationRoot', () => {
     expect(screen.getByTestId('chat-body')).toBeTruthy()
   })
 
-  it('empty window: placeholder copy in the body, header chrome renders nothing', async () => {
+  it('empty window: placeholder copy in the body, the stats header renders nothing', async () => {
     const b = await bench()
-    mount(b.svc, [] as unknown as ConversationSnapshot['nodes'])
+    mount(b.slots, [] as unknown as ConversationSnapshot['nodes'])
     fireEvent.click(screen.getByRole('tab', { name: 'Trajectory' }))
     expect(screen.getByText('暂无轨迹数据')).toBeTruthy()
     expect(screen.queryByText(/turns ·/)).toBeNull()
@@ -175,7 +221,7 @@ describe('span derivation', () => {
   it('empty inputs produce zero stats and standalone components render their empty forms', () => {
     expect(deriveSpanStats(deriveSpans([] as unknown as ConversationSnapshot['nodes']))).toEqual({ turns: 0, steps: 0, calls: 0 })
     const { useSession } = fakeSession([] as unknown as ConversationSnapshot['nodes'])
-    const { container } = render(createElement(TrajectoryStatsHeader, { sessionId: SID, useSession }))
+    const { container } = render(createElement(TrajectoryStatsHeader, { useSession: useSession as never }))
     expect(container.firstChild).toBeNull()
     render(createElement(TrajectoryView as FC<ConvViewProps>,
       standaloneProps([] as unknown as ConversationSnapshot['nodes'])))
diff --git a/packages/client/web-react/README.md b/packages/client/web-react/README.md
index fcc67a8ec2..704e09d96f 100644
--- a/packages/client/web-react/README.md
+++ b/packages/client/web-react/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-web-react
 
-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. 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 (store relocation); business plugins depend on ui-slots types only, never on this package.
 
 ## Model Experience
 
diff --git a/packages/client/web-react/src/index.ts b/packages/client/web-react/src/index.ts
index cd3189b891..b5c975305a 100644
--- a/packages/client/web-react/src/index.ts
+++ b/packages/client/web-react/src/index.ts
@@ -22,7 +22,7 @@ export type UseSession<Snap extends object = object> = SnapshotSelectorHook<Snap
 
 // -- renderer: the install-seam implementation; contract lives in ui-slots --
 export type {
-  HostObservable, RenderOpts, SessionCell, SnapshotSelectorHook,
+  ChainRenderOpts, HostObservable, RenderOpts, SessionCell, SnapshotSelectorHook,
   SlotRenderer, SlotRendererHost, StoreInstanceLike,
 } from '@deepseek-ai/dsh-client-ui-slots'
 export { SlotOwnershipError, StaleAuthorizationError } from '@deepseek-ai/dsh-client-ui-slots'
diff --git a/packages/client/web-react/src/scoped-slots.tsx b/packages/client/web-react/src/scoped-slots.tsx
index 8e2e10821f..603ea1091f 100644
--- a/packages/client/web-react/src/scoped-slots.tsx
+++ b/packages/client/web-react/src/scoped-slots.tsx
@@ -5,9 +5,12 @@
  * renderSlot binding synthesized from the entry's children declaration.
  * Standard-kit synthesis per entry: the global useSessions hook, the session
  * pair (useSession + sessionId) under SessionProvider, the store pair
- * (useStore + actions) for store-declaring entries, and the renderSlot
- * binding (entry-identity bound, stale-checked) for children-declaring
- * entries. Inject factories run inside the entry component bodies ON PURPOSE
+ * (useStore + actions) for store-declaring entries, the renderSlot binding
+ * (entry-identity bound, stale-checked) for children-declaring entries, and
+ * the renderSlotChain binding for entries declaring a chain-kind child
+ * (selector-routed: first non-null select elects and its value joins the
+ * props as `matched`; all-null falls to the owner fallback).
+ * Inject factories run inside the entry component bodies ON PURPOSE
  * — the per-entry error boundary contains a throwing factory to its own
  * entry; parameters follow the declaration (sessionId for session slots,
  * baked actions when a store is declared).
@@ -15,8 +18,8 @@
 import { Component, useSyncExternalStore, type FC, type ReactNode } from 'react'
 import {
   SlotOwnershipError, StaleAuthorizationError,
-  type RenderOpts, type SessionCell, type SlotRenderer, type SlotRendererHost,
-  type StoredEntry,
+  type ChainRenderOpts, type RenderOpts, type SessionCell, type SlotRenderer,
+  type SlotRendererHost, type StoredEntry,
 } from '@deepseek-ai/dsh-client-ui-slots'
 import {
   HostContext, SessionProvider, SlotAssemblyError, observableHook, useHost, useSessionCell,
@@ -27,6 +30,9 @@ type InjectedProps = Record<string, unknown>
 /** Owner-facing renderSlot binding shape (typed narrowing lands on the wave-1 props seam). */
 type RenderSlotBinding = (key: string, owner: object, opts?: RenderOpts) => ReactNode
 
+/** Owner-facing renderSlotChain binding shape (typed narrowing lands on the props seam). */
+type RenderSlotChainBinding = (key: string, owner: object, opts?: ChainRenderOpts) => ReactNode
+
 /**
  * Per-entry renderSlot bindings. The binding is identity-stable per entry
  * (memoized components must not resubscribe on unrelated re-renders) and dies
@@ -43,9 +49,13 @@ function boundRenderSlot(host: SlotRendererHost, entry: StoredEntry): RenderSlot
         throw new StaleAuthorizationError(`renderSlot('${key}') from a disposed registration`)
       }
       // Plain-JS backstop; typed callers are narrowed to the declared keys.
-      if (entry.children?.[key] === undefined) {
+      const declared = entry.children?.[key]
+      if (declared === undefined) {
         throw new SlotOwnershipError(`slot '${key}' is not declared by this entry's children`)
       }
+      if (declared.kind === 'chain') {
+        throw new SlotOwnershipError(`slot '${key}' is declared 'chain' — use renderSlotChain`)
+      }
       return <SlotOutlet slotKey={key} ownerProps={owner} opts={opts} />
     }
     renderSlotCache.set(entry, binding)
@@ -53,6 +63,35 @@ function boundRenderSlot(host: SlotRendererHost, entry: StoredEntry): RenderSlot
   return binding
 }
 
+/**
+ * Per-entry renderSlotChain bindings: identity-stable per entry (same cache
+ * axis as renderSlot — a per-frame dispatch must not rebuild the binding) and
+ * dead with the entry. The chain-kind check is the plain-JS backstop twin of
+ * the declaration check; typed callers are narrowed to chain keys.
+ */
+const renderSlotChainCache = new WeakMap<StoredEntry, RenderSlotChainBinding>()
+
+function boundRenderSlotChain(host: SlotRendererHost, entry: StoredEntry): RenderSlotChainBinding {
+  let binding = renderSlotChainCache.get(entry)
+  if (!binding) {
+    binding = (key, owner, opts) => {
+      if (!host.isLive(entry)) {
+        throw new StaleAuthorizationError(`renderSlotChain('${key}') from a disposed registration`)
+      }
+      const declared = entry.children?.[key]
+      if (declared === undefined) {
+        throw new SlotOwnershipError(`slot '${key}' is not declared by this entry's children`)
+      }
+      if (declared.kind !== 'chain') {
+        throw new SlotOwnershipError(`slot '${key}' is declared '${declared.kind}', not 'chain' — use renderSlot`)
+      }
+      return <SlotOutlet slotKey={key} ownerProps={owner} opts={opts} />
+    }
+    renderSlotChainCache.set(entry, binding)
+  }
+  return binding
+}
+
 /**
  * Inject results cache: root entries per entry, session entries per
  * (entry x session cell). WeakMap keys are entry/cell objects (both
@@ -96,6 +135,26 @@ function cachedSessionInject(entry: StoredEntry, cell: SessionCell, actions: obj
   return props
 }
 
+/**
+ * Entry-identity React keys for chain boundaries. A chain outlet renders ONE
+ * elected entry through an error boundary; without a key, a boundary that
+ * failed on entry A would survive a re-election and keep a healthy entry B
+ * blacked out. Keying by entry identity remounts the boundary fresh whenever
+ * the election changes (entries are identity-stable per registration, so the
+ * key is stable while the same entry stays elected).
+ */
+let nextEntryKey = 0
+const entryKeys = new WeakMap<StoredEntry, number>()
+
+function entryKeyOf(entry: StoredEntry): number {
+  let key = entryKeys.get(entry)
+  if (key === undefined) {
+    key = nextEntryKey++
+    entryKeys.set(entry, key)
+  }
+  return key
+}
+
 /**
  * Per-entry isolation: one registrant crashing (component render or inject
  * factory) must not take down siblings. Assembly errors (missing providers)
@@ -144,6 +203,11 @@ function standardKit(host: SlotRendererHost, entry: StoredEntry, cell: SessionCe
   }
   if (entry.children !== undefined) {
     kit['renderSlot'] = boundRenderSlot(host, entry)
+    // renderSlotChain rides the same declaration source: only entries whose
+    // children include a chain-kind slot receive the chain dispatch seat.
+    if (Object.values(entry.children).some((spec) => spec.kind === 'chain')) {
+      kit['renderSlotChain'] = boundRenderSlotChain(host, entry)
+    }
     // SessionProvider standard seat: entries declaring a session-scope child
     // render the session area, so the framework hands them the self-wired
     // provider (module-level component = stable reference; no value import).
@@ -198,9 +262,9 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   // 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) => (
+  const guarded = (entry: StoredEntry, key?: string | number, owner: object = ownerProps) => (
     <SlotErrorBoundary slotKey={slotKey} key={key}>
-      <Entry entry={entry} ownerProps={ownerProps} />
+      <Entry entry={entry} ownerProps={owner} />
     </SlotErrorBoundary>
   )
 
@@ -214,6 +278,32 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
     if (!entry) return <>{opts?.fallback ?? null}</>
     return guarded(entry)
   }
+  if (spec.kind === 'chain') {
+    // Entries arrive priority-sorted from the ledger (the core orders at
+    // register, ties keep registration sequence). Selectors are pure
+    // functions of the owner props (register-face contract), so the routing
+    // pass runs per render with zero mount side effects: the first non-null
+    // election renders, decliners never mount.
+    for (const entry of entries) {
+      let matched: unknown
+      try {
+        // Chain entries always carry select (SlotCore register validation).
+        matched = (entry.select as (owner: object) => unknown)(ownerProps)
+      } catch (error) {
+        // A throwing selector is a registrant contract breach (select MUST be
+        // pure and total), but it runs before the entry's SlotErrorBoundary
+        // exists — uncontained it would black out the whole owner region. So
+        // it degrades to a decline: the chain and the fallback stay intact,
+        // and the breach is reported like a crashed entry.
+        console.error(
+          `chain selector crashed in '${slotKey}' (${entry.registrant ?? 'unknown registrant'}), treating as declined:`,
+          error)
+        continue
+      }
+      if (matched !== null) return guarded(entry, entryKeyOf(entry), { ...ownerProps, matched })
+    }
+    return <>{opts?.fallback ?? null}</>
+  }
   // list: registration order refined by explicit order, optional id filter.
   const withListOptions = entries.map((entry) => ({
     entry,
diff --git a/packages/client/web-react/tests/scoped-slots.spec.tsx b/packages/client/web-react/tests/scoped-slots.spec.tsx
index 8cbbf21be4..aab243ab47 100644
--- a/packages/client/web-react/tests/scoped-slots.spec.tsx
+++ b/packages/client/web-react/tests/scoped-slots.spec.tsx
@@ -13,13 +13,14 @@ import { act, render } from '@testing-library/react'
 import type { ReactNode } from 'react'
 import type { ActionsDecl, SlotEntryDef, SlotSpec, StoreHandle, StoredEntry } from '@deepseek-ai/dsh-client-ui-slots'
 import {
-  createSlotRenderer, SessionProvider, SlotOwnershipError,
+  createSlotRenderer, SessionProvider, SlotOwnershipError, StaleAuthorizationError,
   type RenderOpts, type SessionCell,
   type SlotRendererHost, type StoreInstanceLike,
 } from '@deepseek-ai/dsh-client-web-react'
 
 type AnyProps = Record<string, unknown>
 type RenderSlotFn = (key: string, owner: object, opts?: RenderOpts) => ReactNode
+type RenderSlotChainFn = (key: string, owner: object, opts?: { fallback?: ReactNode }) => ReactNode
 type DeclaredSpec = SlotSpec<SlotEntryDef>
 /** Entry literal helper: fake entries default the mandatory options bag. */
 const entryOf = (partial: Omit<StoredEntry, 'options'> & { options?: StoredEntry['options'] }): StoredEntry =>
@@ -129,7 +130,13 @@ function makeHost() {
     declare: (key: string, spec: DeclaredSpec) => { specs.set(key, spec); bump(key) },
     add: (key: string, partial: Omit<StoredEntry, 'options'> & { options?: StoredEntry['options'] }) => {
       const entry = entryOf(partial)
-      entries.set(key, [...(entries.get(key) ?? []), entry])
+      const next = [...(entries.get(key) ?? []), entry]
+      // Mirror the ledger contract: chain entries arrive priority-sorted
+      // (stable, ascending) — outlets iterate entries() order as-is.
+      if (specs.get(key)?.kind === 'chain') {
+        next.sort((a, b) => (a.options.priority ?? 0) - (b.options.priority ?? 0))
+      }
+      entries.set(key, next)
       live.add(entry)
       bump(key)
       return () => {
@@ -165,6 +172,29 @@ function mountRoot(h: Fake, children: Record<string, DeclaredSpec>, body: (rende
 
 const SINGLE_ROOT: DeclaredSpec = { kind: 'single', scope: 'root' }
 const SINGLE_SESSION: DeclaredSpec = { kind: 'single', scope: 'session' }
+const CHAIN_ROOT: DeclaredSpec = { kind: 'chain', scope: 'root' }
+
+/** Chain entry literal: top-level select, priority in the options bag (the StoredEntry chain shape). */
+const chainEntryOf = (partial: {
+  component: unknown
+  select: (owner: object) => unknown
+  priority?: number
+}): Omit<StoredEntry, 'options'> & { options?: StoredEntry['options'] } => ({
+  component: partial.component,
+  select: partial.select as StoredEntry['select'],
+  ...(partial.priority !== undefined ? { options: { priority: partial.priority } } : {}),
+})
+
+/** Mount a root entry whose component renders `body` with its kit renderSlotChain. */
+function mountChainRoot(h: Fake, children: Record<string, DeclaredSpec>, body: (renderSlotChain: RenderSlotChainFn) => ReactNode) {
+  const dispose = h.add('root', {
+    component: (props: { renderSlotChain: RenderSlotChainFn }) => <>{body(props.renderSlotChain)}</>,
+    children,
+  })
+  const renderer = createSlotRenderer()
+  const view = render(<>{renderer.renderRoot(h.host, {})}</>)
+  return { view, dispose }
+}
 
 describe('root outlet', () => {
   it('renders the root registration and fails loud when root is unregistered (boot order)', () => {
@@ -262,6 +292,183 @@ describe('child outlets and the renderSlot binding', () => {
   })
 })
 
+describe('chain outlets and the renderSlotChain binding', () => {
+  it('elects the first non-null selector in order, injects matched, and skips decliners without mounting them', () => {
+    const h = makeHost()
+    h.declare('k.chain', CHAIN_ROOT)
+    const declinerBody = vi.fn(() => <span>never</span>)
+    h.add('k.chain', chainEntryOf({
+      component: declinerBody,
+      select: () => null,
+    }))
+    h.add('k.chain', chainEntryOf({
+      component: ({ matched }: { matched?: { label: string } }) => <b>{matched?.label}</b>,
+      select: (owner) => ({ label: `hit:${(owner as { tag: string }).tag}` }),
+    }))
+    const { view } = mountChainRoot(h, { 'k.chain': CHAIN_ROOT },
+      (renderSlotChain) => renderSlotChain('k.chain', { tag: 'T' }))
+    // The declining entry never mounts: the routing decision is select-layer only.
+    expect(view.container.textContent).toBe('hit:T')
+    expect(declinerBody).not.toHaveBeenCalled()
+  })
+
+  it('contains a throwing selector to its entry: reported, treated as declined, chain and fallback intact', () => {
+    const h = makeHost()
+    h.declare('k.chain', CHAIN_ROOT)
+    h.add('k.chain', chainEntryOf({
+      component: () => <span>never</span>,
+      select: () => { throw new Error('selector boom') },
+    }))
+    h.add('k.chain', chainEntryOf({
+      component: ({ matched }: { matched?: string }) => <b>{matched}</b>,
+      select: (owner) => (owner as { pick?: string }).pick ?? null,
+    }))
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { view } = mountChainRoot(h, { 'k.chain': CHAIN_ROOT }, (renderSlotChain) => <>
+      <main>{renderSlotChain('k.chain', { pick: 'OK' })}</main>
+      <aside>{renderSlotChain('k.chain', {}, { fallback: <i>fb</i> })}</aside>
+    </>)
+    // The breach never escapes to the owner region: later entries still get
+    // tried, and an all-throw/all-null pass still lands on the fallback.
+    expect(view.container.querySelector('main')!.textContent).toBe('OK')
+    expect(view.container.querySelector('aside')!.textContent).toBe('fb')
+    expect(spy.mock.calls.some(([msg]) => String(msg).includes('chain selector crashed'))).toBe(true)
+    spy.mockRestore()
+  })
+
+  it('remounts the boundary on re-election: a failed entry does not black out its replacement', () => {
+    const h = makeHost()
+    h.declare('k.chain', CHAIN_ROOT)
+    h.add('k.chain', chainEntryOf({
+      component: () => { throw new Error('entry A boom') },
+      select: (owner) => (owner as { pick?: string }).pick === 'A' ? {} : null,
+    }))
+    h.add('k.chain', chainEntryOf({
+      component: () => <b>B-ok</b>,
+      select: (owner) => (owner as { pick?: string }).pick === 'B' ? {} : null,
+    }))
+    let pick = 'A'
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { view } = mountChainRoot(h, { 'k.chain': CHAIN_ROOT },
+      (renderSlotChain) => renderSlotChain('k.chain', { pick }))
+    spy.mockRestore()
+    expect(view.container.querySelector('[data-slot-error]')).not.toBeNull()
+    // Re-elect entry B: the entry-keyed boundary remounts fresh instead of
+    // holding A's failed state over the healthy replacement.
+    pick = 'B'
+    act(() => { h.add('root', { component: () => null }) })   // root bump re-renders the dispatch site
+    expect(view.container.textContent).toBe('B-ok')
+    expect(view.container.querySelector('[data-slot-error]')).toBeNull()
+  })
+
+  it('falls to the owner fallback when every selector declines, and re-routes live', () => {
+    const h = makeHost()
+    h.declare('k.chain', CHAIN_ROOT)
+    h.add('k.chain', chainEntryOf({
+      component: ({ matched }: { matched?: string }) => <b>{matched}</b>,
+      select: (owner) => (owner as { pick?: string }).pick ?? null,
+    }))
+    const { view } = mountChainRoot(h, { 'k.chain': CHAIN_ROOT }, (renderSlotChain) => <>
+      <main>{renderSlotChain('k.chain', {}, { fallback: <i>bar</i> })}</main>
+      <aside>{renderSlotChain('k.chain', { pick: 'P' }, { fallback: <i>bar</i> })}</aside>
+    </>)
+    // Same chain, two dispatch sites: all-null owner props fall back, matching ones elect.
+    expect(view.container.querySelector('main')!.textContent).toBe('bar')
+    expect(view.container.querySelector('aside')!.textContent).toBe('P')
+  })
+
+  it('renders the fallback for an empty chain and elects live once an entry registers', () => {
+    const h = makeHost()
+    h.declare('k.chain', CHAIN_ROOT)
+    const { view } = mountChainRoot(h, { 'k.chain': CHAIN_ROOT },
+      (renderSlotChain) => renderSlotChain('k.chain', {}, { fallback: <i>none</i> }))
+    expect(view.container.textContent).toBe('none')
+    let dispose = () => {}
+    act(() => {
+      dispose = h.add('k.chain', chainEntryOf({
+        component: () => <b>IN</b>,
+        select: () => ({}),
+      }))
+    })
+    expect(view.container.textContent).toBe('IN')
+    act(() => { dispose() })
+    expect(view.container.textContent).toBe('none')
+  })
+
+  it('orders the chain by ascending priority with registration sequence breaking ties', () => {
+    const h = makeHost()
+    h.declare('k.chain', CHAIN_ROOT)
+    // Registered first but priority 2: must yield to the later priority-1 entry.
+    h.add('k.chain', chainEntryOf({
+      component: () => <b>late</b>,
+      select: () => ({}),
+      priority: 2,
+    }))
+    h.add('k.chain', chainEntryOf({
+      component: () => <b>early</b>,
+      select: () => ({}),
+      priority: 1,
+    }))
+    // Tie pair at priority 1: registration order decides (early wins over tie).
+    h.add('k.chain', chainEntryOf({
+      component: () => <b>tie</b>,
+      select: () => ({}),
+      priority: 1,
+    }))
+    const { view } = mountChainRoot(h, { 'k.chain': CHAIN_ROOT },
+      (renderSlotChain) => renderSlotChain('k.chain', {}))
+    expect(view.container.textContent).toBe('early')
+  })
+
+  it('keeps the renderSlotChain binding identity-stable across re-renders', () => {
+    const h = makeHost()
+    h.declare('k.chain', CHAIN_ROOT)
+    const seen: RenderSlotChainFn[] = []
+    mountChainRoot(h, { 'k.chain': CHAIN_ROOT }, (renderSlotChain) => {
+      seen.push(renderSlotChain)
+      return renderSlotChain('k.chain', {}, { fallback: <i>fb</i> })
+    })
+    act(() => { h.add('root', { component: () => null }) })   // root bump re-renders the entry
+    expect(seen.length).toBeGreaterThan(1)
+    expect(seen.at(-1)).toBe(seen[0])
+  })
+
+  it('backstops off-declaration keys, kind mismatches both ways, and disposed registrations', () => {
+    const h = makeHost()
+    h.declare('k.chain', CHAIN_ROOT)
+    h.declare('k.single', SINGLE_ROOT)
+    let chainFn: RenderSlotChainFn | undefined
+    let slotFn: RenderSlotFn | undefined
+    const dispose = h.add('root', {
+      component: (props: { renderSlot: RenderSlotFn; renderSlotChain: RenderSlotChainFn }) => {
+        slotFn = props.renderSlot
+        chainFn = props.renderSlotChain
+        return null
+      },
+      children: { 'k.chain': CHAIN_ROOT, 'k.single': SINGLE_ROOT },
+    })
+    const view = render(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
+    expect(() => chainFn!('k.undeclared', {})).toThrow(SlotOwnershipError)
+    expect(() => chainFn!('k.single', {})).toThrow(SlotOwnershipError)   // non-chain key via chain face
+    expect(() => slotFn!('k.chain', {})).toThrow(SlotOwnershipError)     // chain key via plain face
+    view.unmount()
+    dispose()
+    expect(() => chainFn!('k.chain', {})).toThrow(StaleAuthorizationError)
+  })
+
+  it('withholds the renderSlotChain seat from entries declaring no chain child', () => {
+    const h = makeHost()
+    h.declare('k.single', SINGLE_ROOT)
+    const seen: AnyProps[] = []
+    h.add('root', {
+      component: (props: AnyProps) => { seen.push(props); return null },
+      children: { 'k.single': SINGLE_ROOT },
+    })
+    render(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
+    expect(seen.at(-1)!['renderSlotChain']).toBeUndefined()
+  })
+})
+
 describe('standard-kit synthesis', () => {
   it('delivers a live useSessions hook to every slot component', () => {
     const h = makeHost()
diff --git a/packages/client/web/README.md b/packages/client/web/README.md
index 0501cb0384..4b26238cf6 100644
--- a/packages/client/web/README.md
+++ b/packages/client/web/README.md
@@ -1,8 +1,14 @@
 # @deepseek-ai/dsh-client-web
 
-Web shell library: `bootWebShell(el, seams?)` mounts the whole client — loader machinery (statically held; a loader cannot load itself), pure-library module-table seeding, AppRoot (boot loading page → settled → full UI in one switch), and the SessionProvider/scopedSlots assembly closure. The vite application entry lives in apps/web and only calls `bootWebShell`. Contract: api-contracts v3 §9.3.
+Web shell kernel: `bootWebShell(el, seams?)` 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.
 
-The optional `seams` parameter forwards the client loader's `fetchBundle`/`executeBundle` transport overrides (`BootSeams`); production callers omit it — it exists for test environments where `<script>` execution cannot reach the page context (jsdom).
+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 `fetchBundle`/`executeBundle` transport overrides (`BootSeams`); production callers omit it — it exists for test environments where `<script>` execution cannot reach the page context (jsdom).
+
+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.
 
 ## Model Experience
 
@@ -14,6 +20,5 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **One-shot rendering by design** — the UI waits for `loader.settled()`; a single plugin failure keeps the loading page with a loud error, no partial availability (progressive rendering returns with its own project).
-- **No HMR** — the dev loop is tsdown watch + manual refresh for plugins; vite serves only the shell.
+- **One-shot rendering by design** — the UI waits for the boot settle; a single entry failure keeps the loading page with a loud per-entry report, no partial availability (progressive rendering returns with its own project).
 - **Narrow-window acceptance is deferred** — the concession chain is implemented in ui-layout but the shell-level narrow-viewport walkthrough is a P-II acceptance item.
diff --git a/packages/client/web/package.json b/packages/client/web/package.json
index 6c3e89080c..0bd34e322e 100644
--- a/packages/client/web/package.json
+++ b/packages/client/web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-web",
-  "description": "Web shell library: bootWebShell (loader holding + module-table seeding + AppRoot gate + plugin assembly), consumed by the apps/web vite entry",
+  "description": "Web shell kernel: bootWebShell (module system holding + seed table + two-stage boot + AppRoot gate + app-shell assembly entry), consumed by the apps/web vite entry",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -20,8 +20,7 @@
   },
   "license": "BSD-3-Clause",
   "dependencies": {
-    "@deepseek-ai/dsh-client-connection": "workspace:^",
-    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-modules": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
@@ -30,6 +29,8 @@
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
@@ -37,6 +38,7 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
diff --git a/packages/client/web/src/AppRoot.tsx b/packages/client/web/src/AppRoot.tsx
index 401d253b78..5b6a3c83a8 100644
--- a/packages/client/web/src/AppRoot.tsx
+++ b/packages/client/web/src/AppRoot.tsx
@@ -1,39 +1,46 @@
 /**
- * Shell root: boot loading page → (loader settled) → real UI in one switch.
- * Pure shell component with zero plugin dependencies — before settled it may
- * only rely on itself; the real UI is produced by the boot assembly closure
- * (renderApp) once every plugin is active. A failed plugin keeps the loading
- * page and lists the failures (fail loud, no partial UI).
+ * Shell root: boot loading page → (boot settled) → real UI in one switch.
+ * 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
+ * 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).
  */
 import { useSyncExternalStore } from 'react'
 import type { ReactNode } from 'react'
-import type { ObservableSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import type { LoaderStatus } from '@deepseek-ai/dsh-client-runtime/client'
+import type { KernelSignal, LoaderStatus } from './loader-status.ts'
 import css from './AppRoot.module.css'
 
-/** AppRoot props: settled signal, loader status feed, deferred real-UI factory. */
+/** AppRoot props: settled signal, fiber-state projection feed, boot failure report, deferred real-UI factory. */
 export interface AppRootProps {
-  /** True once loader.settled() resolved (the boot closure flips it; status-derived guesses race an incrementally filled table). */
-  settled: ObservableSnapshot<boolean>
-  /** Loader per-plugin status store (drives loading/failed rendering). */
-  status: SnapshotStore<LoaderStatus>
+  /** True once the boot chain settled (loader quiesced + all entries ACTIVE); the boot closure flips it. */
+  settled: KernelSignal<boolean>
+  /** Per-entry fiber-state projection store (drives loading/failed rendering). */
+  status: KernelSignal<LoaderStatus>
+  /** Boot failure report (the settle rejection message); undefined while loading or after success. */
+  error: KernelSignal<string | undefined>
   /** Builds the real UI; called only after settled. */
   renderApp: () => ReactNode
 }
 
-/** Boot gate: loading page until the loader settles; failures stay here. */
+/** Boot gate: loading page until the boot settles; failures stay here. */
 export function AppRoot(props: AppRootProps) {
   const settled = useSyncExternalStore(props.settled.subscribe, props.settled.getSnapshot)
   const status = useSyncExternalStore(props.status.subscribe, props.status.getSnapshot)
+  const error = useSyncExternalStore(props.error.subscribe, props.error.getSnapshot)
   const failed = Object.entries(status).filter(([, s]) => s === 'failed')
 
   if (settled) return <>{props.renderApp()}</>
 
+  const loud = error !== undefined || failed.length > 0
+
   return (
     <div className={css.boot}>
       <div className={css.card}>
         <div className={css.wordmark}>HARNESS</div>
-        {failed.length === 0
+        {!loud
           ? (
               <>
                 <div className={css.spinner} />
@@ -44,6 +51,7 @@ export function AppRoot(props: AppRootProps) {
               <div className={css.failed}>
                 <div className={css.failedTitle}>Failed to load plugins</div>
                 {failed.map(([id]) => <div key={id} className={css.failedItem}>{id}</div>)}
+                {error !== undefined && <div className={css.failedItem}>{error}</div>}
               </div>
             )}
       </div>
diff --git a/packages/client/web/src/DocumentTitle.tsx b/packages/client/web/src/DocumentTitle.tsx
new file mode 100644
index 0000000000..608f97497d
--- /dev/null
+++ b/packages/client/web/src/DocumentTitle.tsx
@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react'
+
+/** Props for the shell-owned browser title projection. */
+export interface DocumentTitleProps {
+  /** Durable title of the selected session, or undefined for the product title. */
+  title?: string
+}
+
+/**
+ * Project the selected durable session title into the browser title and
+ * restore the shell's original product title when unmounted.
+ * @param props - selected session title projection.
+ * @returns no rendered content.
+ */
+export function DocumentTitle({ title }: DocumentTitleProps): null {
+  const original = useRef(document.title)
+  useEffect(() => {
+    document.title = title === undefined ? original.current : `${title} — ${original.current}`
+    return () => { document.title = original.current }
+  }, [title])
+  return null
+}
diff --git a/packages/client/web/src/app-shell.ts b/packages/client/web/src/app-shell.ts
new file mode 100644
index 0000000000..0730290dcf
--- /dev/null
+++ b/packages/client/web/src/app-shell.ts
@@ -0,0 +1,59 @@
+/**
+ * App-shell assembly plugin (design §3.4): the shell's ONLY composition
+ * responsibility, packaged as a normal static-arrival entry so the host graph
+ * stays the single composition authority. It rides the same entry lifecycle
+ * as every other plugin — the fiber waits on slots/sessions/layout, so by the
+ * time apply runs the layout entry is mounted and its export surface is
+ * readable from the governance side (module loadCache, design §2.6).
+ *
+ * The pseudo package id exists only in the host graph and the shell's static
+ * registry; there is no npm package behind it.
+ */
+import type { ReactNode } from 'react'
+import type { Context } from 'cordis'
+import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
+import { buildRenderApp } from './app.tsx'
+
+/** Shell-owned pseudo entry id under which the host graph mounts this plugin. */
+export const APP_SHELL_ID = '@deepseek-ai/dsh-client-app-shell'
+
+/** The assembled-UI face AppRoot renders once the boot settles. */
+export interface AppShellService {
+  /** Build (once) and render the real UI tree. */
+  renderApp: () => ReactNode
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** The shell assembly face, provided by the app-shell entry once its inject set is active. */
+    appShell: AppShellService
+  }
+}
+
+/** Cordis plugin name. */
+export const name = 'app-shell'
+
+/** Required services: the product services the assembly closes over (layout registers the 'root' slot entry). */
+export const inject = ['slots', 'sessions', 'layout']
+
+/**
+ * Plugin body: install the React renderer into the slot system and provide
+ * the renderApp face (one ctx-level renderSlot('root') call).
+ * @param ctx - plugin context (inject set active).
+ */
+export function apply(ctx: Context): void {
+  // The renderer install is shell territory (web-react is shell-bundled),
+  // but ctx.slots exists only once the runtime entry is active — so it lands
+  // here, on the entry whose inject set guarantees that ordering.
+  ctx.slots.install(createSlotRenderer())
+
+  // Assemble once on first render: the closure must be identity-stable
+  // across AppRoot re-renders.
+  let renderApp: (() => ReactNode) | undefined
+  ctx.reflect.provide('appShell', {
+    renderApp: (): ReactNode => {
+      renderApp ??= buildRenderApp({ ctx })
+      return renderApp()
+    },
+  })
+}
diff --git a/packages/client/web/src/app.tsx b/packages/client/web/src/app.tsx
index e79609c3ab..5f8040102f 100644
--- a/packages/client/web/src/app.tsx
+++ b/packages/client/web/src/app.tsx
@@ -1,28 +1,45 @@
 /**
- * Real-UI assembly closure. Runs only after loader.settled(): the whole
- * layout tree hangs off the built-in 'root' slot (ui-layout registers
- * AppFrame there and renders the child slots internally) — the shell's
- * render is the one ctx-level renderSlot call in the program.
+ * Real-UI assembly closure, invoked by the app-shell plugin once its inject
+ * set is active: the whole layout tree hangs off the built-in 'root' slot
+ * (ui-layout registers AppFrame there and renders the child slots
+ * internally) — the shell's render is the one ctx-level renderSlot call in
+ * the program.
  */
 import type { ReactNode } from 'react'
 import type { Context } from 'cordis'
+import type { SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { DocumentTitle } from './DocumentTitle.tsx'
 // Type-only: pulls the runtime's SlotMap declaration merge (the 'root' key) into this program.
 import type {} from '@deepseek-ai/dsh-client-runtime/client'
 
-/** Assembly inputs: the settled root ctx plus the loader's module-table read surface. */
+/** Assembly inputs: the active app-shell plugin ctx (slots/sessions/layout services provided). */
 export interface AssemblyDeps {
-  /** Client root context (all plugin services provided). */
+  /** Client context with the assembly's inject set active. */
   ctx: Context
-  /** Module-table resolver (the loader's require; missing spec = throw). Kept in the seam for future shell needs. */
-  requireModule: (spec: string) => unknown
 }
 
 /**
- * Build the renderApp factory handed to AppRoot.
+ * Build the renderApp factory the app-shell plugin provides to AppRoot.
  * @param deps - assembly inputs.
  * @returns factory producing the real UI tree (called once per AppRoot render after settled).
  */
 export function buildRenderApp(deps: AssemblyDeps): () => ReactNode {
   const { ctx } = deps
-  return () => ctx.slots.renderSlot('root', {})
+  const sessions = ctx.get('sessions') as SessionsService | undefined
+  if (sessions === undefined) throw new Error('shell assembly: sessions service unavailable')
+  const useSessions = bindSnapshotSelector(sessions.list)
+  const SessionDocumentTitle = (): ReactNode => {
+    const title = useSessions((state) => {
+      const id = state.current
+      return id === undefined ? undefined : state.byId[id]?.title
+    })
+    return <DocumentTitle {...title === undefined ? {} : { title }} />
+  }
+  return () => (
+    <>
+      <SessionDocumentTitle />
+      {ctx.slots.renderSlot('root', {})}
+    </>
+  )
 }
diff --git a/packages/client/web/src/base.css b/packages/client/web/src/base.css
index 53dbde8db7..991a03bbca 100644
--- a/packages/client/web/src/base.css
+++ b/packages/client/web/src/base.css
@@ -17,3 +17,13 @@ body {
   color: var(--dsw-alias-label-primary);
   background: var(--dsw-alias-bg-base);
 }
+
+/* Form controls don't inherit the body font (UA sheets pin their families —
+   Chrome buttons fall back to Arial, textareas to monospace), so the app
+   stack is re-applied to them explicitly, as upstream's global reset does. */
+button,
+input,
+select,
+textarea {
+  font-family: inherit;
+}
diff --git a/packages/client/web/src/boot.tsx b/packages/client/web/src/boot.tsx
index 0e9c68be9e..6c04f1619b 100644
--- a/packages/client/web/src/boot.tsx
+++ b/packages/client/web/src/boot.tsx
@@ -1,73 +1,172 @@
 /**
- * Web shell boot — the library face consumed by the apps/web entry (api
- * contracts v3 §0.3/§9.3): root ctx → hold the loader machinery (statically
- * imported; the loader cannot load itself) → seed the module table → render
- * the AppRoot loading page → loader.start() → await settled() → flip the
- * settled signal so AppRoot switches to the real UI in one pass. Load
- * failures reject settled(); AppRoot stays on the loading page listing them
- * (fail loud).
+ * Web shell boot — the kernel face consumed by the apps/web entry. Everything
+ * here is machinery that cannot itself be an entry, and none of it
+ * value-imports a plugin package (web2 shell self-sufficiency rule: the
+ * loading page must work while — especially when — plugins fail).
+ *
+ * Two-stage boot (web2 §0):
+ *   Stage one (module face): build the module system over the host graph
+ *   (`window.__DSH_BOOT__`) and prefetch every `immediately` row in parallel
+ *   — fetch + execute registers factories only; module side effects wait for
+ *   materialization. Prefetch failures are non-fatal here: stage two's
+ *   import path retries the fetch and owns the loud failure.
+ *   Stage two (plugin face): mount the vendored cordis Loader, inject the
+ *   module system as its internal seam (BEFORE any entry exists — the
+ *   bare-import fallback in tree.import must never run in a browser), create
+ *   one loader entry per graph row (tree.import materializes each module),
+ *   let fibers activate on service availability, then loader.await() + a
+ *   full fiber sweep (all ACTIVE, else reject listing who/what/which
+ *   service) → flip the settled signal so AppRoot switches to the real UI in
+ *   one pass.
+ *
+ * Composition lives in the host graph; the shell makes zero composition
+ * decisions (the app-shell assembly is itself a graph entry, the only
+ * shell-own module registered with the module system).
  */
 import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
 import { createRoot } from 'react-dom/client'
-import type { ReactNode } from 'react'
-import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
-import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
-import { createClientLoader, type ClientLoaderOptions } from '@deepseek-ai/dsh-client-runtime/loader'
+import {
+  createClientModuleLoader,
+  type ClientModuleLoader, type ClientModuleLoaderOptions, type DshWindow, type WebBootGraph,
+} from '@deepseek-ai/dsh-client-modules'
+import * as AppShell from './app-shell.ts'
+import { APP_SHELL_ID } from './app-shell.ts'
 import { AppRoot } from './AppRoot.tsx'
-import { buildRenderApp } from './app.tsx'
-import { seedModules } from './seed.ts'
+import { getStaticModules } from './seed.ts'
+import {
+  STATE_LABELS, createLoaderStatusStore, createSignal, type LoaderStatusStore,
+} from './loader-status.ts'
 import './base.css'
 
-/** Manually flipped settled signal (AppRoot's gate; see AppRootProps.settled). */
-function settledSignal(): ObservableSnapshot<boolean> & { flip: () => void } {
-  let value = false
-  const listeners = new Set<() => void>()
-  return {
-    getSnapshot: () => value,
-    subscribe: (fn) => { listeners.add(fn); return () => { listeners.delete(fn) } },
-    flip: () => {
-      value = true
-      for (const fn of [...listeners]) fn()
-    },
+/** Module transport seams the shell passes through (jsdom tests replace the <script> path). */
+export type BootSeams = Pick<ClientModuleLoaderOptions, 'fetchBundle' | 'executeBundle'>
+
+/**
+ * Sweep every loader entry after the tree quiesced: an entry without a fiber
+ * failed its import; a fiber not ACTIVE is FAILED (apply threw) or PENDING
+ * (a required service never arrived — cordis inject waiting has no timeout,
+ * so this sweep is the fail-loud compensation).
+ */
+function assertEntriesActive(ctx: Context): void {
+  const failures: string[] = []
+  for (const entry of ctx.loader.entries()) {
+    const name = entry.options.name
+    if (entry.fiber === undefined) {
+      failures.push(`${name}: import failed (see console for the import error)`)
+      continue
+    }
+    const state = STATE_LABELS[entry.fiber.state]
+    if (state === 'active') continue
+    if (state === 'pending') {
+      const missing = Object.keys(entry.fiber.inject).filter((service) => ctx.get(service) === undefined)
+      failures.push(`${name}: pending (waiting for service${missing.length === 1 ? '' : 's'}: ${missing.join(', ') || 'unknown'})`)
+    } else {
+      failures.push(`${name}: ${state}`)
+    }
+  }
+  if (failures.length > 0) {
+    throw new Error(`web boot: ${String(failures.length)} entr${failures.length === 1 ? 'y' : 'ies'} did not activate\n${failures.join('\n')}`)
   }
 }
 
-/** Loader transport seams the shell passes through (jsdom tests replace the <script> path). */
-export type BootSeams = Pick<ClientLoaderOptions, 'fetchBundle' | 'executeBundle'>
+/** Stage one: prefetch the immediately tier (factory registration only; failures defer to stage two's import). */
+async function prefetchImmediateTier(modules: ClientModuleLoader, graph: WebBootGraph): Promise<void> {
+  await Promise.all(graph.entries
+    .filter((row) => row.immediately === true)
+    .map((row) => modules.prefetch(row.id).catch(() => {
+      // Import (stage two) refetches and reports this loudly per entry;
+      // swallowing here keeps one failing prefetch from masking the others.
+    })))
+}
+
+/** Stage two: mount the Loader, inject the internal seam, create the graph entries, settle, sweep. */
+async function runPluginBoot(
+  ctx: Context, modules: ClientModuleLoader, graph: WebBootGraph, status: LoaderStatusStore,
+): Promise<void> {
+  await ctx.plugin(Loader)
+  const loader = ctx.loader
+  // Inject the module system BEFORE any entry exists: tree.import falls back
+  // to a bare dynamic import when internal is undefined, which in a browser
+  // is a guaranteed loud failure — correct as a tripwire, never as a path.
+  loader.internal = modules as never
+
+  // Status projection: AppRoot displays fiber truth. Every internal/status
+  // transition under an entry re-projects that entry's row from its ROOT
+  // fiber (child plugin fibers share the same entry).
+  ctx.on('internal/status', (fiber) => {
+    const entry = fiber.entry
+    if (entry === undefined || entry.fiber === undefined) return
+    status.set(entry.options.name, STATE_LABELS[entry.fiber.state])
+  })
+
+  // Entry creation order carries no semantics (fiber inject waiting owns
+  // activation order); creating concurrently lets non-prefetched bundle
+  // fetches parallelize. The app-shell assembly entry is appended by the
+  // kernel: it is shell-own code (host graph rows are all plugin bundles),
+  // and mounting the assembly is not a composition decision — it rides the
+  // same entry lifecycle so the sweep and status cover it uniformly.
+  const rows = [...graph.entries.map((row) => row.id), APP_SHELL_ID]
+  await Promise.all(rows.map(async (name) => {
+    status.set(name, 'loading')
+    const id = await loader.create({ name })
+    // A failed import leaves the entry fiberless (Entry._init logs and
+    // returns); project it as failed — no fiber means no status event.
+    if (loader.resolve(id).fiber === undefined) {
+      status.set(name, 'failed')
+    }
+  }))
+
+  await loader.await()
+  assertEntriesActive(ctx)
+}
 
 /**
- * Mount the web shell into a DOM element and start the plugin load chain.
+ * Mount the web shell into a DOM element and start the two-stage boot chain.
  * @param el - mount point (the app's #root).
- * @param seams - optional loader transport overrides (test environments).
+ * @param seams - optional module transport overrides (test environments).
  * @returns unmount disposer.
  */
 export function bootWebShell(el: HTMLElement, seams?: BootSeams): () => void {
-  const ctx = new Context()
-  const loader = createClientLoader({ ctx, modules: seedModules(), ...seams })
-  ctx.reflect.provide('loader', loader)
+  const graph = (globalThis as DshWindow).__DSH_BOOT__
+  if (graph === undefined) throw new Error('web boot: no entry graph (window.__DSH_BOOT__ missing)')
 
-  const settled = settledSignal()
-  // Assemble once on first post-settled render: SessionProvider and the slot
-  // closures must be identity-stable across re-renders.
-  let renderApp: (() => ReactNode) | undefined
-  const renderAppOnce = (): ReactNode => {
-    renderApp ??= buildRenderApp({ ctx, requireModule: (spec) => loader.requireModule(spec) })
-    return renderApp()
-  }
+  const ctx = new Context()
+  const modules = createClientModuleLoader({ graph, staticModules: getStaticModules(), ...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).
+  modules.registerStatic(APP_SHELL_ID, AppShell)
+  // Contract C5: the module system is a boot-owned kernel service (ctx.modules).
+  ctx.reflect.provide('modules', modules)
+
+  const status = createLoaderStatusStore()
+  const settled = createSignal(false)
+  const error = createSignal<string | undefined>(undefined)
 
   const root = createRoot(el)
-  root.render(<AppRoot settled={settled} status={loader.status} renderApp={renderAppOnce} />)
-
-  loader.start()
-  loader.settled().then(
-    () => {
-      // The renderer install is a shell-boot act, but ctx.slots exists only
-      // once the runtime plugin loaded — so it lands here, after settled and
-      // before the flip that lets renderApp call renderSlot('root').
-      ctx.slots.install(createSlotRenderer())
-      settled.flip()
-    },
-    () => { /* stay on the loading page; failures render from loader.status */ },
+  root.render(
+    <AppRoot
+      settled={settled}
+      status={status}
+      error={error}
+      renderApp={() => {
+        const shell = ctx.get('appShell')
+        // Unreachable after a clean settle (the app-shell entry is in every graph).
+        if (shell === undefined) throw new Error('web boot: appShell service missing after settled')
+        return shell.renderApp()
+      }}
+    />,
   )
+
+  prefetchImmediateTier(modules, graph)
+    .then(() => runPluginBoot(ctx, modules, graph, status))
+    .then(
+      () => { settled.set(true) },
+      (reason: unknown) => {
+        // Stay on the loading page; surface the sweep report (fail loud).
+        console.error(reason)
+        error.set(reason instanceof Error ? reason.message : String(reason))
+      },
+    )
   return () => { root.unmount() }
 }
diff --git a/packages/client/web/src/index.ts b/packages/client/web/src/index.ts
index 4ea9ad46a7..6fa7df6c1b 100644
--- a/packages/client/web/src/index.ts
+++ b/packages/client/web/src/index.ts
@@ -1,11 +1,20 @@
 /**
  * Web shell library entry. The shell's product is {@link bootWebShell} —
  * apps/web's vite entry calls it against #root; everything else (AppRoot
- * gate, assembly closure, module-table seed) is internal to the boot chain.
+ * gate, app-shell assembly entry, module-table staticModules, platform constants) is
+ * internal to the boot chain. PLATFORM_MODULES is re-exported as the C1
+ * single source of truth for the tsdown client externals projection.
  * @module @deepseek-ai/dsh-client-web
  */
 
-export { bootWebShell } from './boot.tsx'
+export { bootWebShell, type BootSeams } from './boot.tsx'
 export { AppRoot, type AppRootProps } from './AppRoot.tsx'
 export { buildRenderApp, type AssemblyDeps } from './app.tsx'
-export { seedModules } from './seed.ts'
+export { DocumentTitle, type DocumentTitleProps } from './DocumentTitle.tsx'
+export { APP_SHELL_ID, type AppShellService } from './app-shell.ts'
+export { getStaticModules } from './seed.ts'
+export { PLATFORM_MODULES, type PlatformModule } from './platform.ts'
+export {
+  STATE_LABELS, FIBER_STATE, createSignal, createLoaderStatusStore,
+  type LoaderStatus, type LoaderEntryState, type KernelSignal, type KernelValueSignal, type LoaderStatusStore,
+} from './loader-status.ts'
diff --git a/packages/client/web/src/loader-status.ts b/packages/client/web/src/loader-status.ts
new file mode 100644
index 0000000000..9a999d4a70
--- /dev/null
+++ b/packages/client/web/src/loader-status.ts
@@ -0,0 +1,111 @@
+/**
+ * Fiber-state projection vocabulary and the kernel-owned status store for the
+ * boot loading page. The status AppRoot renders is a projection of the real
+ * 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
+ * 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
+ */
+import type { FiberState } from 'cordis'
+
+/**
+ * Value mirror of cordis's `FiberState` const enum: a const enum has no
+ * runtime object to import (and esbuild-based pipelines cannot inline it
+ * across modules), so these values mirror the pinned vendored definition
+ * while retaining its type (same rationale as dsh-tool-cordis's mirror).
+ */
+export const FIBER_STATE = {
+  PENDING: 0 as FiberState.PENDING,
+  LOADING: 1 as FiberState.LOADING,
+  ACTIVE: 2 as FiberState.ACTIVE,
+  FAILED: 3 as FiberState.FAILED,
+  DISPOSED: 4 as FiberState.DISPOSED,
+  UNLOADING: 5 as FiberState.UNLOADING,
+} as const
+
+/** One entry's projected state label (lower-case face of {@link FiberState}). */
+export type LoaderEntryState = 'pending' | 'loading' | 'active' | 'failed' | 'disposed' | 'unloading'
+
+/** Label for each fiber state, keyed by member (inlining-safe — no reverse mapping). */
+export const STATE_LABELS: Record<FiberState, LoaderEntryState> = {
+  [FIBER_STATE.PENDING]: 'pending',
+  [FIBER_STATE.LOADING]: 'loading',
+  [FIBER_STATE.ACTIVE]: 'active',
+  [FIBER_STATE.FAILED]: 'failed',
+  [FIBER_STATE.DISPOSED]: 'disposed',
+  [FIBER_STATE.UNLOADING]: 'unloading',
+}
+
+/** Per-entry state projection (AppRoot's status feed), keyed by entry name. */
+export type LoaderStatus = Record<string, LoaderEntryState>
+
+/** Minimal observable snapshot the kernel components consume (useSyncExternalStore shape). */
+export interface KernelSignal<T> {
+  /** Current value (stable reference between changes). */
+  getSnapshot(): T
+  /**
+   * Subscribe to changes.
+   * @param fn - change listener.
+   * @returns the unsubscribe disposer.
+   */
+  subscribe(fn: () => void): () => void
+}
+
+/** Writable one-value signal (settled flag, boot failure report). */
+export interface KernelValueSignal<T> extends KernelSignal<T> {
+  /**
+   * Publish a new value and notify subscribers.
+   * @param next - the new value.
+   */
+  set(next: T): void
+}
+
+/**
+ * Create a writable kernel signal.
+ * @param init - initial value.
+ * @returns the signal.
+ */
+export function createSignal<T>(init: T): KernelValueSignal<T> {
+  let value = init
+  const listeners = new Set<() => void>()
+  return {
+    getSnapshot: () => value,
+    subscribe: (fn) => { listeners.add(fn); return () => { listeners.delete(fn) } },
+    set: (next) => {
+      value = next
+      for (const fn of [...listeners]) fn()
+    },
+  }
+}
+
+/** The boot status store: per-entry rows over a {@link KernelSignal} face. */
+export interface LoaderStatusStore extends KernelSignal<LoaderStatus> {
+  /**
+   * Project one entry's state (copy-on-write so getSnapshot references only
+   * change on writes — useSyncExternalStore contract).
+   * @param id - entry name.
+   * @param state - projected fiber state.
+   */
+  set(id: string, state: LoaderEntryState): void
+}
+
+/**
+ * Create the boot status store.
+ * @returns the store (empty until the boot chain projects rows).
+ */
+export function createLoaderStatusStore(): LoaderStatusStore {
+  let value: LoaderStatus = {}
+  const listeners = new Set<() => void>()
+  return {
+    getSnapshot: () => value,
+    subscribe: (fn) => { listeners.add(fn); return () => { listeners.delete(fn) } },
+    set: (id, state) => {
+      value = { ...value, [id]: state }
+      for (const fn of [...listeners]) fn()
+    },
+  }
+}
diff --git a/packages/client/web/src/platform.ts b/packages/client/web/src/platform.ts
new file mode 100644
index 0000000000..3888ed0119
--- /dev/null
+++ b/packages/client/web/src/platform.ts
@@ -0,0 +1,20 @@
+/**
+ * Platform singletons the shell shares into the module table.
+ * Single source of truth (design §3.3, contract C1): seed keys = tsdown
+ * client externals = the shared surface. The three projections import this
+ * module — the seed table ({@link ../seed.ts}), the tsdown client preset's
+ * external judgement (packages/client/tsdown.client.ts), and the vite alias
+ * check — so the list cannot drift between them.
+ * @module @deepseek-ai/dsh-client-web/src/platform
+ */
+
+/** The module specifiers the shell shares into the frozen module table. */
+export const PLATFORM_MODULES = [
+  'react', 'react/jsx-runtime', 'react-dom', 'react-dom/client', 'cordis',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-web-react',
+  '@deepseek-ai/dsh-client-ui-primitives',
+] as const
+
+/** One platform module specifier (a seed-table key). */
+export type PlatformModule = (typeof PLATFORM_MODULES)[number]
diff --git a/packages/client/web/src/seed.ts b/packages/client/web/src/seed.ts
index 90f7f547ef..ef66c4d7e3 100644
--- a/packages/client/web/src/seed.ts
+++ b/packages/client/web/src/seed.ts
@@ -1,10 +1,10 @@
 /**
- * Pure-library module-table seed. These are the ONLY entities statically
- * built into the shell bundle besides the loader machinery — every plugin
- * (including the infrastructure four) arrives as a dynamic bundle and
- * resolves its externals against this table through the loader's require.
- * Keys must match the tsdown client preset's external specifiers
- * (packages/client/tsdown.client.ts CLIENT_EXTERNALS ∩ pure libraries).
+ * 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
+ * of truth with the tsdown client externals); values stay shell-static
+ * imports so every bundle sees the same instance.
  */
 import * as React from 'react'
 import * as ReactJsxRuntime from 'react/jsx-runtime'
@@ -14,12 +14,16 @@ import * as Cordis from 'cordis'
 import * as UiSlots from '@deepseek-ai/dsh-client-ui-slots'
 import * as WebReact from '@deepseek-ai/dsh-client-web-react'
 import * as UiPrimitives from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PlatformModule } from './platform.ts'
 
 /**
- * Build the seed table handed to the loader machinery at boot.
- * @returns module specifier → export-surface entity.
+ * Build the static table handed to the module loader at boot.
+ * @returns module specifier → export-surface entity (one entry per platform word).
  */
-export function seedModules(): Record<string, unknown> {
+export function getStaticModules(): Record<string, unknown> {
+  // The satisfies pin is the projection contract: a word added to
+  // PLATFORM_MODULES without a static import here (or vice versa) fails to
+  // compile instead of drifting into a runtime require miss.
   return {
     'react': React,
     'react/jsx-runtime': ReactJsxRuntime,
@@ -29,5 +33,5 @@ export function seedModules(): Record<string, unknown> {
     '@deepseek-ai/dsh-client-ui-slots': UiSlots,
     '@deepseek-ai/dsh-client-web-react': WebReact,
     '@deepseek-ai/dsh-client-ui-primitives': UiPrimitives,
-  }
+  } satisfies Record<PlatformModule, unknown>
 }
diff --git a/packages/client/web/tests/app-root.spec.tsx b/packages/client/web/tests/app-root.spec.tsx
index 1aa0639908..7b42461eb7 100644
--- a/packages/client/web/tests/app-root.spec.tsx
+++ b/packages/client/web/tests/app-root.spec.tsx
@@ -1,42 +1,33 @@
 // @vitest-environment jsdom
 /**
  * AppRoot boot-gate smoke: loading page until the settled signal flips (status
- * alone never opens the gate), fail-loud plugin list, one-pass switch to the
- * real UI. The full browser chain (real loader + bundles) is the e2e's job;
- * this pins the shell-owned gate semantics.
+ * alone never opens the gate), fail-loud entry list + boot failure report,
+ * one-pass switch to the real UI. The full browser chain (real module system
+ * + vendored Loader + bundles) is the e2e's job; this pins the shell-owned
+ * gate semantics. Stores are the kernel-own signals production boot uses
+ * (shell self-sufficiency: the loading page depends on no plugin package).
  */
 import { afterEach, describe, expect, it } from 'vitest'
 import { act, cleanup, render } from '@testing-library/react'
 
 afterEach(cleanup)
-// The snapshot-store engine lives with runtime now; the status-store stub
-// uses the same channel production code does.
-import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
-import type { LoaderStatus } from '@deepseek-ai/dsh-client-runtime/client'
 import { AppRoot } from '@deepseek-ai/dsh-client-web/src/AppRoot.tsx'
-
-function signal(): ObservableSnapshot<boolean> & { flip: () => void } {
-  let value = false
-  const listeners = new Set<() => void>()
-  return {
-    getSnapshot: () => value,
-    subscribe: (fn) => { listeners.add(fn); return () => { listeners.delete(fn) } },
-    flip: () => { value = true; for (const fn of [...listeners]) fn() },
-  }
-}
+import { createLoaderStatusStore, createSignal } from '@deepseek-ai/dsh-client-web/src/loader-status.ts'
 
 function mount() {
-  const settled = signal()
-  const status = createSnapshotStore<LoaderStatus>({})
+  const settled = createSignal(false)
+  const error = createSignal<string | undefined>(undefined)
+  const status = createLoaderStatusStore()
   let renders = 0
   const utils = render(
     <AppRoot
       settled={settled}
       status={status}
+      error={error}
       renderApp={() => { renders += 1; return <div data-testid="real-ui" /> }}
     />,
   )
-  return { settled, status, counts: () => renders, ...utils }
+  return { settled, status, error, counts: () => renders, ...utils }
 }
 
 describe('AppRoot', () => {
@@ -50,24 +41,34 @@ describe('AppRoot', () => {
   it('all-active status alone does not open the gate (settled signal is the only key)', () => {
     const { status, queryByTestId } = mount()
     act(() => {
-      status.update((d) => { d['a'] = 'active'; d['b'] = 'active' })
+      status.set('a', 'active')
+      status.set('b', 'active')
     })
     expect(queryByTestId('real-ui')).toBeNull()
   })
 
-  it('lists failed plugins and stays on the loading page', () => {
+  it('lists failed entries and stays on the loading page', () => {
     const { status, getByText, queryByTestId } = mount()
     act(() => {
-      status.update((d) => { d['@deepseek-ai/dsh-client-ui-theme'] = 'failed'; d['ok'] = 'active' })
+      status.set('@deepseek-ai/dsh-client-ui-layout', 'failed')
+      status.set('ok', 'active')
     })
     expect(getByText('Failed to load plugins')).toBeTruthy()
-    expect(getByText('@deepseek-ai/dsh-client-ui-theme')).toBeTruthy()
+    expect(getByText('@deepseek-ai/dsh-client-ui-layout')).toBeTruthy()
+    expect(queryByTestId('real-ui')).toBeNull()
+  })
+
+  it('renders the boot failure report even when no entry projected failed', () => {
+    const { error, getByText, queryByTestId } = mount()
+    act(() => { error.set('web boot: 1 entry did not activate\nx: pending (waiting for service: y)') })
+    expect(getByText('Failed to load plugins')).toBeTruthy()
+    expect(getByText(/waiting for service/)).toBeTruthy()
     expect(queryByTestId('real-ui')).toBeNull()
   })
 
   it('flipping settled switches to the real UI in one pass', () => {
     const { settled, getByTestId, queryByText, counts } = mount()
-    act(() => { settled.flip() })
+    act(() => { settled.set(true) })
     expect(getByTestId('real-ui')).toBeTruthy()
     expect(queryByText('HARNESS')).toBeNull()
     expect(counts()).toBe(1)
diff --git a/packages/client/web/tests/boot.spec.tsx b/packages/client/web/tests/boot.spec.tsx
deleted file mode 100644
index 46866cfef5..0000000000
--- a/packages/client/web/tests/boot.spec.tsx
+++ /dev/null
@@ -1,226 +0,0 @@
-// @vitest-environment jsdom
-/**
- * bootWebShell over the REAL client loader in jsdom (runScripts:dangerously —
- * the loader's <script> execute path runs for real): fetch is stubbed to
- * serve fake bundle text, everything else is production code — seeded module
- * table, DSHClientProxy handoff, inject topology, renderer install after
- * settled, the one-line renderSlot('root') shell, and the fail-loud paths —
- * through the loader's fetch/execute seams (jsdom's <script> vm context
- * cannot reach the test window, so execute is indirect eval). The fake
- * runtime is the REAL SlotsService mounted by the real runtime plugin shape;
- * full-fidelity plugin content belongs to the apps/web e2e.
- */
-import { afterEach, describe, expect, it } from 'vitest'
-import { act } from '@testing-library/react'
-import { bootWebShell } from '@deepseek-ai/dsh-client-web'
-import { createSnapshotStore, defineStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-
-interface BootWindow extends Window {
-  __DSH_BOOT__?: { plugins: { id: string; url: string; inject: string[]; immediately?: boolean }[] }
-  DSHClientProxy?: unknown
-  __TEST_SLOTS_SERVICE__?: unknown
-  __TEST_RUNTIME_STORE__?: { createSnapshotStore: unknown; defineStore: unknown }
-}
-const win = window as unknown as BootWindow
-
-/**
- * Fake runtime half: mounts the REAL SlotsService (built-in 'root', ledger,
- * install/renderSlot) plus a minimal sessions face for the renderer host.
- * The runtime package is not a seeded library (in production it arrives as a
- * bundle), so the spec hands the real class in through a window global — the
- * plugin body and everything downstream stay production code.
- */
-const RUNTIME_STUB = `
-window.DSHClientProxy.loadPlugin({
-  id: 'fake-runtime',
-  factory: (require) => {
-    const SlotsService = window.__TEST_SLOTS_SERVICE__
-    const { createSnapshotStore } = window.__TEST_RUNTIME_STORE__
-    return {
-      apply: (ctx) => {
-        ctx.plugin(SlotsService)
-        const list = createSnapshotStore({ ids: ['s1'], byId: { s1: { id: 's1', title: 'S1', running: false, updatedAt: 1 } }, current: 's1' })
-        ctx.provide('sessions', {
-          list,
-          cell: (id) => (id === 's1' ? { sessionId: 's1', session: { getSnapshot: () => ({}), subscribe: () => () => {} } } : undefined),
-        })
-      },
-    }
-  },
-})`
-
-/** Fake layout half: ONE terminal register() call — occupy 'root', declare a
- *  child, seat a store factory, expose the store round trip as a probe. */
-const LAYOUT_STUB = `
-window.DSHClientProxy.loadPlugin({
-  id: 'fake-layout',
-  factory: (require) => {
-    const React = require('react')
-    const { defineStore } = window.__TEST_RUNTIME_STORE__
-    return {
-      inject: ['slots'],
-      apply: (ctx) => {
-        const createProbeStore = () => defineStore({
-          init: () => ({ sidebar: 300, details: 360 }),
-          actions: {
-            setSidebar: (d, px) => { d.sidebar = px },
-            setDetails: (d, px) => { d.details = px },
-          },
-        })
-        ctx.slots.register({
-          name: 'root',
-          children: { 'probe.child': { kind: 'single', scope: 'root' } },
-          store: createProbeStore,
-        }, (props) => {
-          const sw = props.useStore((st) => st.sidebar)
-          const dw = props.useStore((st) => st.details)
-          return React.createElement('div', {
-            'data-testid': 'fake-frame',
-            'data-widths': sw + 'x' + dw,
-            onClick: () => { props.actions.setSidebar(311); props.actions.setDetails(411) },
-          }, props.renderSlot('probe.child', {}))
-        })
-      },
-    }
-  },
-})`
-
-// The shell assembly requires the layout surface under its production id.
-const LAYOUT_ID = '@deepseek-ai/dsh-client-ui-layout'
-
-/** Loader seams: serve fake bundle text and execute it via indirect eval (jsdom's <script> vm context cannot see the test window). */
-function seams(bundles: Record<string, string>) {
-  return {
-    fetchBundle: (url: string): Promise<string> => {
-      const hit = Object.keys(bundles).find((b) => url.endsWith(b))
-      if (hit === undefined) return Promise.reject(new Error(`bundle fetch ${url} answered 404`))
-      return Promise.resolve(bundles[hit]!)
-    },
-    executeBundle: (code: string): void => {
-      (0, eval)(code)
-    },
-  }
-}
-
-function mountPoint(): HTMLElement {
-  const el = document.createElement('div')
-  document.body.appendChild(el)
-  return el
-}
-
-async function flushLoader(): Promise<void> {
-  // fetch + per-plugin apply chain across macrotask turns; a few settle it.
-  for (let i = 0; i < 10; i++) await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
-}
-
-function bootPlugins(): { id: string; url: string; inject: string[]; immediately?: boolean }[] {
-  return [
-    { id: 'fake-runtime', url: '/plugins/fake-runtime.js', inject: [], immediately: true },
-    { id: LAYOUT_ID, url: '/plugins/fake-layout.js', inject: ['fake-runtime'] },
-  ]
-}
-
-function fakeBundles(): Record<string, string> {
-  return {
-    '/plugins/fake-runtime.js': RUNTIME_STUB,
-    '/plugins/fake-layout.js': LAYOUT_STUB.replace("id: 'fake-layout'", `id: '${LAYOUT_ID}'`),
-  }
-}
-
-afterEach(() => {
-  delete win.__DSH_BOOT__
-  delete win.DSHClientProxy
-  delete win.__TEST_SLOTS_SERVICE__
-  delete win.__TEST_RUNTIME_STORE__
-  document.body.innerHTML = ''
-  document.head.querySelectorAll('script').forEach((s) => { s.remove() })
-})
-
-/** Hand the real runtime surface to the stub bundle (runtime is not a seeded library). */
-function seedSlotsService(): void {
-  win.__TEST_SLOTS_SERVICE__ = SlotsService
-  win.__TEST_RUNTIME_STORE__ = { createSnapshotStore, defineStore }
-}
-
-describe('bootWebShell (real loader + real script execution)', () => {
-  it('loading page → settled → renderer installed → assembled UI in one pass; unmount clears the tree', async () => {
-    win.__DSH_BOOT__ = { plugins: bootPlugins() }
-    seedSlotsService()
-    const el = mountPoint()
-    let unmount: (() => void) | undefined
-    act(() => { unmount = bootWebShell(el, seams(fakeBundles())) })
-    expect(el.textContent).toContain('HARNESS')
-    expect(el.querySelector('[data-testid="fake-frame"]')).toBeNull()
-
-    await flushLoader()
-    expect(el.querySelector('[data-testid="fake-frame"]')).not.toBeNull()
-    expect(el.textContent).not.toContain('HARNESS')
-
-    act(() => { unmount!() })
-    expect(el.childElementCount).toBe(0)
-  })
-
-  it('store seat round-trips through the entry props (useStore + actions)', async () => {
-    win.__DSH_BOOT__ = { plugins: bootPlugins() }
-    seedSlotsService()
-    const el = mountPoint()
-    act(() => { bootWebShell(el, seams(fakeBundles())) })
-    await flushLoader()
-    const frame = el.querySelector('[data-testid="fake-frame"]')
-    expect(frame).not.toBeNull()
-    // Width write/read round trip through the framework-delivered store share.
-    expect((frame as HTMLElement).dataset['widths']).toBe('300x360')
-    act(() => { (frame as HTMLElement).click() })
-    expect((frame as HTMLElement).dataset['widths']).toBe('311x411')
-  })
-
-  it('fail loud: a 404 bundle keeps the loading page and lists the plugin id', async () => {
-    win.__DSH_BOOT__ = { plugins: [{ id: 'absent-plugin', url: '/plugins/absent.js', inject: [] }] }
-    const el = mountPoint()
-    act(() => { bootWebShell(el, seams({})) })
-    await flushLoader()
-    expect(el.textContent).toContain('Failed to load plugins')
-    expect(el.textContent).toContain('absent-plugin')
-    expect(el.querySelector('[data-testid="fake-frame"]')).toBeNull()
-  })
-
-  it("fail loud: rendering with no 'root' registration throws through the shell error surface", async () => {
-    // Runtime loads (slots service present, renderer installed) but no layout
-    // entry ever registers into 'root' — the ctx-level renderSlot must throw.
-    win.__DSH_BOOT__ = {
-      plugins: [{ id: 'fake-runtime', url: '/plugins/fake-runtime.js', inject: [], immediately: true }],
-    }
-    seedSlotsService()
-    const el = mountPoint()
-    // React logs the render error before the boundary rethrow reaches us — keep the spec output clean.
-    const consoleError = console.error
-    console.error = () => {}
-    try {
-      act(() => { bootWebShell(el, seams({ '/plugins/fake-runtime.js': RUNTIME_STUB })) })
-      let thrown: unknown
-      try {
-        await flushLoader()
-      } catch (error) {
-        thrown = error
-      }
-      expect(String(thrown)).toMatch(/'root' has no registration/)
-    } finally {
-      console.error = consoleError
-    }
-  })
-})
-
-describe('buildRenderApp — assembly contract', () => {
-  it('is exactly the ctx-level root render call (fail-loud before install)', async () => {
-    const { buildRenderApp } = await import('@deepseek-ai/dsh-client-web')
-    const { Context } = await import('cordis')
-    const { SlotsService } = await import('@deepseek-ai/dsh-client-runtime/client')
-    const ctx = new Context()
-    const fiber = ctx.plugin(SlotsService)
-    await fiber.await()
-    const renderApp = buildRenderApp({ ctx, requireModule: () => undefined })
-    expect(renderApp).toBeTypeOf('function')
-    // No renderer installed: the one-line shell must surface the boot-order error.
-    expect(() => renderApp()).toThrow(/renderer not installed/)
-  })
-})
diff --git a/packages/client/web/tests/document-title.spec.tsx b/packages/client/web/tests/document-title.spec.tsx
new file mode 100644
index 0000000000..ed336a1ccc
--- /dev/null
+++ b/packages/client/web/tests/document-title.spec.tsx
@@ -0,0 +1,28 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { DocumentTitle } from '../src/DocumentTitle.tsx'
+
+afterEach(() => {
+  cleanup()
+  document.title = ''
+})
+
+describe('DocumentTitle', () => {
+  it('preserves the product title without a durable title and restores it on unmount', () => {
+    document.title = 'DeepSeek Harness'
+    const mounted = render(<DocumentTitle />)
+    expect(document.title).toBe('DeepSeek Harness')
+
+    mounted.rerender(<DocumentTitle title="First title" />)
+    expect(document.title).toBe('First title — DeepSeek Harness')
+
+    mounted.rerender(<DocumentTitle title="Revised title" />)
+    expect(document.title).toBe('Revised title — DeepSeek Harness')
+
+    mounted.rerender(<DocumentTitle />)
+    expect(document.title).toBe('DeepSeek Harness')
+    mounted.unmount()
+    expect(document.title).toBe('DeepSeek Harness')
+  })
+})
diff --git a/packages/client/web/tsconfig.json b/packages/client/web/tsconfig.json
index f974787045..203ad9c80b 100644
--- a/packages/client/web/tsconfig.json
+++ b/packages/client/web/tsconfig.json
@@ -11,6 +11,12 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../modules"
+    },
     {
       "path": "../ui-slots"
     },
@@ -20,18 +26,9 @@
     {
       "path": "../web-react"
     },
-    {
-      "path": "../connection"
-    },
     {
       "path": "../runtime"
     },
-    {
-      "path": "../ui-theme"
-    },
-    {
-      "path": "../ui-layout"
-    },
     {
       "path": "../../support/invariants"
     }
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 2645e8810e..1838919112 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -10,32 +10,33 @@ Worker-thread implementation of the [`@deepseek-ai/dsh-code-runtime`](../code-ru
   config:
     computeMs: 60000              # busy-time budget (measured event-loop active time)
     maxWallMs: 600000             # wall-clock ceiling; never pauses for anything
-    maxLogBytes: 65536            # shared byte budget for captured log text
-    maxValueBytes: 32768          # rendered-completion-value cap
+    maxOutputBytes: 67108864      # combined serialized outer-output cap (64 MiB)
     maxOldGenerationSizeMb: 512   # worker heap cap (resourceLimits)
 ```
 
-Every field is validated (positive numbers) and defaulted; there are no other tunables.
+Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at least four bytes, the remaining fields are positive finite numbers, and there are no other tunables.
 
 ## Design
 
 - **One fresh worker per run, no pooling** — a program's world dies with its worker: no cross-run state to log, state bleed unrepresentable, runs reconstructable from the session log alone.
 - **Type-strip host-side, in execution context** — the program is wrapped in an async-function shell, stripped with `node:module`'s `stripTypeScriptTypes` (erasable syntax only — `enum`/namespaces are rejected as a program `exception` and no worker spawns), and sliced back out byte-positioned; it then executes as the body of an `AsyncFunction`, so top-level `await`/`return` work.
-- **The port assumes a hostile peer** — model code can reach `parentPort` and forge traffic, so every inbound message is shape-validated and REBUILT before anything reads it (`null`, primitives, junk types, and malformed payloads drop without a throw; forged extra fields never ride along), the host answers each call id at most once, resolves binding names as OWN properties only (a forged `constructor` cannot walk a prototype chain), drops post-settlement replies, and converts a non-cloneable binding resolution into an error reply. Forged `log`/`done` messages cannot bypass the caps: one host-side ledger bounds everything that lands in `logs`, and the completion value is re-capped host-side. Worker-side namespaces are null-prototype with `defineProperty`, so `__proto__`-shaped binding names are ordinary keys.
+- **The port assumes a hostile peer** — model code can reach `parentPort` and forge traffic, so every inbound message is shape-validated and REBUILT before anything reads it (`null`, primitives, junk types, and malformed payloads drop without a throw; forged extra fields never ride along), the host answers each call id at most once, resolves binding names as OWN properties only (a forged `constructor` cannot walk a prototype chain), drops post-settlement replies, and validates every binding resolution and completion as lossless JSON. Forged `log`/`done` messages cannot bypass the outer cap: the host repeats validation and accounts every admitted log plus the completion or diagnostic. Worker-side namespaces are null-prototype with `defineProperty`, so `__proto__`-shaped binding names are ordinary keys.
+- **Binding rejection classes are request data** — an optional namespace descriptor names the constructor global and the own property that receives the failed member name. The worker materializes and injects that real class, so `instanceof` works without hardcoding `tools` or `ToolCallError`; declarations with invalid or colliding globals fail before a worker spawns. Failures use module-captured error and property-definition intrinsics plus null-prototype descriptors, so later model mutations cannot turn a rejected binding into a worker crash.
 - **Two independent budgets, because the peer is hostile** — `computeMs` meters the worker's MEASURED busy time (`worker.performance.eventLoopUtilization()` polling): a hot loop cannot hide behind a pending decoy dispatch, and a program awaiting a slow tool accrues nothing. `maxWallMs` backstops what busy time cannot see (awaiting a promise nobody resolves). Both funnel into `worker.terminate()`, which ends hot synchronous loops too; heap overflow surfaces as the worker's OOM exit (`kind: 'worker-exit'`).
-- **Logs stream eagerly** — console/stdout/stderr text crosses the port in emission order, so a timed-out or killed program still shows what it printed. ONE shared `maxLogBytes` ledger bounds everything: streamed text, forged port traffic, and pipe bytes that bypass the patched streams (appended after), with the overflow marked in-band once.
+- **Intermediate binding values are complete JSON** — binding arguments and resolutions undergo iterative lossless-JSON validation. Before program execution, the worker captures its own realm's plain-container prototype identities plus the native function-source check used only for foreign realms, so constructor-slot mutation and user-authored impostors cannot change container classification. It also captures every structural and metering intrinsic used by this JSON boundary, creates property descriptors without a prototype, and bypasses mutable collection prototypes for private traversal state; model mutations of globals, prototype methods, or descriptor-shaped `Object.prototype` fields therefore cannot alter validation, wire transport, or byte accounting. Values flatten into a bounded-depth pre-order wire value for structured clone and rebuild iteratively on the other side. They have no byte, JavaScript call-stack, or nested structured-clone depth cap. They never enter the outer-output ledger or model context; provider/executor acquisition bounds and process/worker memory remain the limits.
+- **Logs stream eagerly into one outer ledger** — console/stdout/stderr text crosses the port in emission order, so a timed-out or killed program still shows what it printed. The worker charges exact JSON-string bytes and preflights completion values and exception diagnostics against the remaining combined budget before posting them; a thrown million-byte stack therefore becomes the fixed `output-limit` diagnostic at the worker boundary. Native writes that bypass the patched stream slots arrive on pipes independent of the completion port, so the host repeats the ledger for those bytes and hostile forged traffic; settlement continues bounded pipe capture until worker termination completes before materializing the result. `maxOutputBytes` accounts the JSON serialization of the outer `logs` array plus the completion value or failure-message payload; fixed `CodeRunResult` field names, braces, the bounded error-kind tag, and later presentation whitespace are outside that variable-payload ledger. At or below the cap the exact value returns; a lossy completion is `invalid-output`, and a combined overflow is `output-limit` rather than a substituted inspected string. The failure retains the fitting captured prefix and later follows the normal outer `run_code` spill policy.
 - **Empty environment** — the worker gets `env: {}` and `execArgv: []`: no ambient credentials (stronger than the scrubbed-env rule for spawned commands) and no inherited loader flags.
 - **Dispose to quiescence** — teardown fails in-flight runs as `abort` and AWAITS each worker's exit before resolving.
 
 ## The worker entry, unbuilt and built
 
-Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. 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 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.
 
 ## Model Experience
 
-Indirectly, through Code Mode in [`dsh-tools`](../../core/tools/README.md), which renders this worker's capped printed or returned data and exact `[dsh-code-runtime-worker] log capture truncated at <maxLogBytes> bytes` and `… [truncated]` markers into a retained `run_code` result. Binding traffic and worker internals stay outside context.
+Indirectly, through Code Mode in [`dsh-tools`](../../core/tools/README.md), which renders the exact outer value when it fits or an explicit `invalid-output` / `output-limit` failure. Only the outer `run_code` result enters model context and its ordinary spill policy; binding traffic and intermediate values remain execution-local.
 
 #### KV Cache effect
 
@@ -47,4 +48,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **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.
-- **A non-cloneable or oversize completion value does not cross as a value** — it arrives as a bounded, truncation-marked `util.inspect` rendering in `value`'s place.
+- **Intermediate binding values have no byte cap** — a program can exhaust process or worker memory with a value that never becomes outer output.
+- **The 64 MiB default is a rejection boundary, not recoverable storage** — outer spill can save only the bounded logs and diagnostic returned after `output-limit`; bytes rejected beyond the runtime cap never reach the spill layer.
diff --git a/packages/code-runtime/code-runtime-worker/package.json b/packages/code-runtime/code-runtime-worker/package.json
index f9c0f6be4c..e173842fc1 100644
--- a/packages/code-runtime/code-runtime-worker/package.json
+++ b/packages/code-runtime/code-runtime-worker/package.json
@@ -33,6 +33,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-code-runtime": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
@@ -41,6 +42,7 @@
   "devDependencies": {
     "@deepseek-ai/dsh-code-runtime": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
index 7f36364a7c..aad4b7b2e6 100644
--- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
+++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
@@ -6,9 +6,21 @@
  */
 
 import { inspect } from 'node:util'
-import { serialize } from 'node:v8'
-import { logTruncationMarker } from './protocol.ts'
 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'
+
+const CapturedError = Error
+const capturedObjectCreate = Object.create
+const capturedObjectDefineProperty = Object.defineProperty
+
+/** Define one public binding-error field without consulting mutable globals or descriptor prototypes. */
+function defineBindingErrorField(error: Error, key: string, value: string): void {
+  const attributes = capturedObjectCreate(null) as PropertyDescriptor
+  attributes.enumerable = true
+  attributes.value = value
+  capturedObjectDefineProperty(error, key, attributes)
+}
 
 /** The port surface the bootstrap needs — satisfied by `parentPort` and by the tests' fake. */
 export interface BootstrapPort {
@@ -27,26 +39,28 @@ export interface PatchableStream {
 }
 
 /**
- * Ordered text capture under one shared byte budget, delivered to a sink as
- * each item lands (the real sink streams text over the port eagerly, so
- * captured output survives a mid-run termination). Once the budget is
- * exhausted it emits exactly one in-band marker and silently drops everything
- * after. The cap is a blast-radius bound, so "how much was lost" intentionally
- * stays unmeasured.
+ * Ordered text capture under the shared outer JSON-byte budget, delivered to
+ * a sink as each item lands (the real sink streams text over the port eagerly,
+ * so captured output survives a mid-run termination). It includes the log
+ * array syntax and string escaping in its accounting. Once exhausted it emits
+ * the fitting prefix and reports the limit once; the host turns that condition
+ * into an explicit `output-limit` run failure.
  */
 export class LogBuffer {
-  private remaining: number
+  private bytes = 2 // JSON serialization of the empty logs array: []
+  private entries = 0
   private truncated = false
   // Explicit fields, not constructor parameter properties: this module loads
   // under Node's native strip-only mode, which rejects non-erasable syntax —
   // and parameter properties are non-erasable.
-  private readonly maxBytes: number
   private readonly sink: (text: string) => void
+  private readonly onLimit: () => void
+  private readonly maxBytes: number
 
-  constructor(maxBytes: number, sink: (text: string) => void) {
+  constructor(maxBytes: number, sink: (text: string) => void, onLimit: () => void = () => {}) {
     this.maxBytes = maxBytes
     this.sink = sink
-    this.remaining = maxBytes
+    this.onLimit = onLimit
   }
 
   /**
@@ -55,15 +69,32 @@ export class LogBuffer {
    */
   push(text: string): void {
     if (this.truncated) return
-    const cost = Buffer.byteLength(text, 'utf8')
-    if (cost > this.remaining) {
+    const separatorBytes = this.entries > 0 ? 1 : 0
+    const availableBytes = this.maxBytes - this.bytes - separatorBytes
+    const stringBytes = jsonStringBytesUpTo(text, availableBytes)
+    if (stringBytes === undefined) {
       this.truncated = true
-      this.sink(logTruncationMarker(this.maxBytes))
+      const prefix = truncateJsonStringBytes(text, availableBytes)
+      if (prefix.length > 0) {
+        const prefixBytes = jsonStringBytesUpTo(prefix, availableBytes)
+        /* v8 ignore next -- truncateJsonStringBytes guarantees the returned prefix fits. */
+        if (prefixBytes === undefined) throw new CapturedError('worker output ledger produced an oversized log prefix')
+        this.bytes += prefixBytes + separatorBytes
+        this.entries += 1
+        this.sink(prefix)
+      }
+      this.onLimit()
       return
     }
-    this.remaining -= cost
+    this.bytes += stringBytes + separatorBytes
+    this.entries += 1
     this.sink(text)
   }
+
+  /** Remaining exact JSON-byte budget for the completion value or failure message. */
+  remainingOutputBytes(): number {
+    return this.maxBytes - this.bytes
+  }
 }
 
 /** The five console methods the shim captures, in the seam's level vocabulary. */
@@ -122,59 +153,79 @@ export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream): (
 const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 } as const
 
 /**
- * The longest prefix of `text` whose UTF-8 encoding fits `maxBytes`, cut at
- * a code-point boundary (never mid-surrogate-pair). The byte caps are BYTE
- * caps — `String.prototype.slice` counts UTF-16 code units, up to 3× smaller
- * than what a multibyte string actually costs across the boundary.
- * @param text - the string to bound.
- * @param maxBytes - the UTF-8 byte budget the prefix must fit.
- * @returns the prefix (all of `text` when it already fits).
+ * Prepare the program's completion value for the done message. Only lossless
+ * JSON crosses, and a value that does not fit the remaining combined outer
+ * budget reports `output-limit`; the host revalidates hostile traffic and
+ * remains authoritative for native pipe writes the worker cannot observe.
+ *
+ * @param value - the program's completion value.
+ * @param remainingOutputBytes - exact bytes left after captured logs.
+ * @param maxOutputBytes - the configured cap named in an overflow diagnostic.
+ * @returns the done-message fragment: `{}` for `undefined`, else a flat wire `{ value }`.
  */
-export function truncateUtf8Bytes(text: string, maxBytes: number): string {
-  if (Buffer.byteLength(text, 'utf8') <= maxBytes) return text
-  let bytes = 0
-  let end = 0
-  for (const char of text) {
-    const cost = Buffer.byteLength(char, 'utf8')
-    if (bytes + cost > maxBytes) break
-    bytes += cost
-    end += char.length
+export function prepareCompletion(
+  value: unknown,
+  remainingOutputBytes: number,
+  maxOutputBytes: number = remainingOutputBytes,
+): Omit<DoneMessage, 'type'> {
+  if (value === undefined) return {}
+  let snapshot: ReturnType<typeof snapshotCodeJsonValue>
+  try {
+    snapshot = snapshotCodeJsonValue(value)
+  } catch {
+    snapshot = undefined
   }
-  return text.slice(0, end)
+  if (snapshot === undefined) {
+    return prepareFailure(
+      'invalid-output',
+      'program completion must be lossless JSON',
+      remainingOutputBytes,
+      maxOutputBytes,
+    )
+  }
+  if (jsonValueBytesUpTo(snapshot, remainingOutputBytes) === undefined) {
+    return outputLimit(maxOutputBytes)
+  }
+  return { value: encodeWorkerJson(snapshot) }
+}
+
+/** Build the fixed overflow fragment without carrying rejected variable bytes. */
+function outputLimit(maxOutputBytes: number): Omit<DoneMessage, 'type'> {
+  return { error: { kind: 'output-limit', message: `outer output exceeded ${maxOutputBytes} bytes` } }
+}
+
+/** Admit one bounded failure message or replace it with the fixed overflow diagnostic. */
+function prepareFailure(
+  kind: 'exception' | 'invalid-output',
+  message: string,
+  remainingOutputBytes: number,
+  maxOutputBytes: number,
+): Omit<DoneMessage, 'type'> {
+  if (jsonStringBytesUpTo(message, remainingOutputBytes) === undefined) return outputLimit(maxOutputBytes)
+  return { error: { kind, message } }
 }
 
 /**
- * Prepare the program's completion value for the done message: a value whose MEASURED
- * cross-boundary size fits `maxValueBytes` crosses raw — exact bytes for a string, the
- * structured-clone wire size (`v8.serialize`) for everything else, so a huge container whose
- * bounded inspect rendering happens to be small cannot smuggle itself past the cap. Oversized
- * or non-cloneable values are replaced by a bounded string rendering with an in-band marker.
- *
- * @param value - the program's completion value.
- * @param maxValueBytes - the byte cap for the value.
- * @returns the done-message fragment: `{}` for `undefined`, else `{ value }`.
+ * Prepare a thrown program value without sending an unbounded stack or
+ * string across the worker port.
+ * @param error - the value thrown by the program.
+ * @param remainingOutputBytes - exact bytes left after captured logs.
+ * @param maxOutputBytes - the configured cap named in an overflow diagnostic.
+ * @returns a bounded exception or fixed output-limit fragment.
  */
-export function prepareValue(value: unknown, maxValueBytes: number): { value?: unknown } {
-  if (value === undefined) return {}
-  if (typeof value === 'string') {
-    if (Buffer.byteLength(value, 'utf8') <= maxValueBytes) return { value }
-  } else {
-    let size: number | undefined
-    try {
-      size = serialize(value).byteLength
-    } catch {
-      // Only the verdict matters: the value has parts the structured-clone
-      // algorithm rejects (functions, classes, …) and must cross as its
-      // rendering instead.
-      size = undefined
-    }
-    if (size !== undefined && size <= maxValueBytes) return { value }
+export function prepareException(
+  error: unknown,
+  remainingOutputBytes: number,
+  maxOutputBytes: number = remainingOutputBytes,
+): Omit<DoneMessage, 'type'> {
+  let message: string
+  try {
+    const detail: unknown = error instanceof CapturedError ? error.stack ?? error.message : error
+    message = typeof detail === 'string' ? detail : String(detail)
+  } catch {
+    message = 'program threw an unrenderable value'
   }
-  const rendered = typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS)
-  const capped = Buffer.byteLength(rendered, 'utf8') > maxValueBytes
-    ? `${truncateUtf8Bytes(rendered, maxValueBytes)}… [truncated]`
-    : rendered
-  return { value: capped }
+  return prepareFailure('exception', message, remainingOutputBytes, maxOutputBytes)
 }
 
 /** One awaited binding call's settlement handles, keyed by call id in the pending map. */
@@ -183,6 +234,46 @@ export interface PendingCall {
   reject(error: Error): void
 }
 
+/** Constructor shape for one program-visible binding rejection class. */
+export type BindingErrorConstructor = new (memberName: string, message: string) => Error
+
+/**
+ * Materialize the real error constructor declared by one namespace.
+ * @param descriptor - program-global class name and member-name property.
+ * @returns the constructor injected into the program and used for rejections.
+ */
+function makeBindingErrorClass(
+  descriptor: { name: string; memberNameProperty: string },
+): BindingErrorConstructor {
+  return class BindingCallError extends CapturedError {
+    constructor(memberName: string, message: string) {
+      super(message)
+      defineBindingErrorField(this, 'name', descriptor.name)
+      defineBindingErrorField(this, descriptor.memberNameProperty, memberName)
+    }
+  }
+}
+
+/** Create the namespace-specific rejection for one failed binding call. */
+function bindingFailure(errorClass: BindingErrorConstructor | undefined, memberName: string, message: string): Error {
+  return errorClass ? new errorClass(memberName, message) : new CapturedError(message)
+}
+
+/**
+ * Build each declared error class once so calls and `instanceof` share constructor identity.
+ * @param data - binding namespace declarations from the boot payload.
+ * @returns constructors keyed by their owning namespace global.
+ */
+export function makeBindingErrorClasses(
+  data: Pick<WorkerBootData, 'namespaces'>,
+): Map<string, BindingErrorConstructor> {
+  const classes = new Map<string, BindingErrorConstructor>()
+  for (const namespace of data.namespaces) {
+    if (namespace.errorClass) classes.set(namespace.global, makeBindingErrorClass(namespace.errorClass))
+  }
+  return classes
+}
+
 /**
  * Route host replies into the pending-call map: each reply settles its call
  * at most once, and a reply for an unknown id (stray, or a duplicate answer
@@ -197,8 +288,13 @@ export function wireReplies(port: BootstrapPort, pending: Map<number, PendingCal
     const entry = pending.get(message.id)
     if (!entry) return
     pending.delete(message.id)
-    if (message.ok) entry.resolve(message.value)
-    else entry.reject(new Error(message.message))
+    if (message.ok) {
+      const value = decodeWorkerJson(message.value)
+      if (value === undefined) entry.reject(new CapturedError('binding resolution must be lossless JSON'))
+      else entry.resolve(value)
+    } else {
+      entry.reject(new CapturedError(message.message))
+    }
   })
 }
 
@@ -206,12 +302,14 @@ export function wireReplies(port: BootstrapPort, pending: Map<number, PendingCal
  * Build the binding namespace objects the program sees: one null-prototype global per
  * namespace, each declared name an own enumerable async function that bridges over the port
  * (`__proto__`/`constructor`/`toString` are ordinary keys, never prototype collisions).
- * Non-cloneable arguments and host failure replies reject only the corresponding call.
+ * Lossy arguments reject before posting; clone failures and host failure
+ * replies reject only the corresponding call.
  *
  * @param data - the boot payload's namespace declarations (globals + names).
  * @param port - the port binding calls are posted to.
  * @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.
  * @returns one namespace object per declaration, in declaration order.
  */
 export function makeNamespaces(
@@ -219,22 +317,41 @@ export function makeNamespaces(
   port: BootstrapPort,
   pending: Map<number, PendingCall>,
   nextId: { value: number },
+  errorClasses: Map<string, BindingErrorConstructor> = makeBindingErrorClasses(data),
 ): Record<string, unknown>[] {
   return data.namespaces.map(({ global, names }) => {
+    const errorClass = errorClasses.get(global)
     const namespace = Object.create(null) as Record<string, unknown>
     for (const name of names) {
       Object.defineProperty(namespace, name, {
         enumerable: true,
-        value: (args: unknown): Promise<unknown> => new Promise((resolve, reject) => {
-          const id = nextId.value++
-          pending.set(id, { resolve, reject })
+        value: (args: unknown): Promise<unknown> => {
+          let detached: ReturnType<typeof snapshotCodeJsonValue>
           try {
-            port.postMessage({ type: 'call', id, global, name, args })
-          } catch (error: unknown) {
-            pending.delete(id)
-            reject(new Error(`binding arguments must be structured-cloneable: ${error instanceof Error ? error.message : String(error)}`))
+            detached = snapshotCodeJsonValue(args)
+          } catch {
+            detached = undefined
           }
-        }),
+          if (detached === undefined) {
+            return Promise.reject(bindingFailure(errorClass, name, 'binding arguments must be lossless JSON'))
+          }
+          return new Promise((resolve, reject) => {
+            const id = nextId.value++
+            pending.set(id, {
+              resolve,
+              reject: (error) => {
+                reject(bindingFailure(errorClass, name, error.message))
+              },
+            })
+            try {
+              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)}`
+              reject(bindingFailure(errorClass, name, message))
+            }
+          })
+        },
       })
     }
     return namespace
@@ -254,7 +371,11 @@ export async function runWorkerMain(
   data: WorkerBootData,
   streams: { stdout: PatchableStream; stderr: PatchableStream },
 ): Promise<void> {
-  const logs = new LogBuffer(data.maxLogBytes, (text) => { port.postMessage({ type: 'log', text }) })
+  const logs = new LogBuffer(
+    data.maxOutputBytes,
+    (text) => { port.postMessage({ type: 'log', text }) },
+    () => { port.postMessage({ type: 'output-limit' }) },
+  )
   captureStreamWrites(logs, streams.stdout)
   captureStreamWrites(logs, streams.stderr)
 
@@ -262,7 +383,18 @@ export async function runWorkerMain(
   wireReplies(port, pending)
 
   const nextId = { value: 1 }
-  const namespaces = makeNamespaces(data, port, pending, nextId)
+  const errorClasses = makeBindingErrorClasses(data)
+  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses)
+  const errorClassParameters: string[] = []
+  const errorClassValues: BindingErrorConstructor[] = []
+  for (const namespace of data.namespaces) {
+    if (!namespace.errorClass) continue
+    errorClassParameters.push(namespace.errorClass.name)
+    const errorClass = errorClasses.get(namespace.global)
+    /* v8 ignore next -- makeBindingErrorClasses covers every declaration in the same data. */
+    if (!errorClass) throw new CapturedError(`missing binding error class for ${namespace.global}`)
+    errorClassValues.push(errorClass)
+  }
   const consoleShim = makeConsoleShim(logs)
 
   let done: DoneMessage
@@ -271,12 +403,22 @@ export async function runWorkerMain(
     // `AsyncFunction` is not a global. The program body is strict-mode.
     /* v8 ignore next -- the arrow exists only to reach the AsyncFunction constructor; it is never invoked. */
     const AsyncFunction = (async () => {}).constructor as new (...args: string[]) => (...fnArgs: unknown[]) => Promise<unknown>
-    const fn = new AsyncFunction(...data.namespaces.map(namespace => namespace.global), 'console', `'use strict';\n${data.code}`)
-    const value = await fn(...namespaces, consoleShim)
-    done = { type: 'done', ...prepareValue(value, data.maxValueBytes) }
+    const fn = new AsyncFunction(
+      ...data.namespaces.map(namespace => namespace.global),
+      ...errorClassParameters,
+      'console',
+      `'use strict';\n${data.code}`,
+    )
+    const value = await fn(...namespaces, ...errorClassValues, consoleShim)
+    done = {
+      type: 'done',
+      ...prepareCompletion(value, logs.remainingOutputBytes(), data.maxOutputBytes),
+    }
   } catch (error: unknown) {
-    const message = error instanceof Error ? error.stack ?? error.message : String(error)
-    done = { type: 'done', error: { message } }
+    done = {
+      type: 'done',
+      ...prepareException(error, logs.remainingOutputBytes(), data.maxOutputBytes),
+    }
   }
   port.postMessage(done)
 }
diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts
index 4a13baa07c..e7eae65f2b 100644
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -8,14 +8,17 @@
 
 import { Worker } from 'node:worker_threads'
 import { stripTypeScriptTypes } from 'node:module'
+import type { Readable } from 'node:stream'
 import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
-import type { CodeBindingFunction, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
-import { prepareValue, truncateUtf8Bytes } from './bootstrap.ts'
-import { logTruncationMarker } from './protocol.ts'
+import type { CodeBindingNamespace, CodeJsonValue, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
 import type { ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'
+import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
+import { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
+import type { WorkerJsonWire } from './worker-json.ts'
 
 /** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
 export interface Config {
@@ -35,14 +38,11 @@ export interface Config {
    * nobody will resolve).
    */
   maxWallMs?: number
-  /** Shared byte budget for captured log text (console + raw stream writes), truncation marked in-band. */
-  maxLogBytes?: number
   /**
-   * Byte cap for the completion value, measured by its real cross-boundary
-   * size (string bytes, or structured-clone wire size); an oversized or
-   * non-cloneable value crosses as a capped string rendering.
+   * Hard cap for serialized log-array, completion-value, and failure-message payloads;
+   * fixed result-envelope syntax is excluded.
    */
-  maxValueBytes?: number
+  maxOutputBytes?: number
   /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */
   maxOldGenerationSizeMb?: number
 }
@@ -59,6 +59,9 @@ type ResolvedConfig = Required<Config>
  */
 const ELU_POLL_INTERVAL_MS = 25
 
+/** Smallest cap that can represent the counted payloads: an empty logs array plus an empty JSON failure message. */
+const MIN_OUTPUT_BYTES = 4
+
 /** ECMAScript reserved words that cannot be async-function parameter names — rejected as binding globals. */
 const RESERVED_WORDS = new Set([
   'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
@@ -71,6 +74,9 @@ const RESERVED_WORDS = new Set([
 /** Valid async-function parameter name (the binding global becomes one). */
 const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
+/** Error properties whose binding-member replacement would destroy the promised Error contract. */
+const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
+
 /**
  * The shell a program is wrapped in for the type-strip, matching the
  * grammatical context it will execute in (an async function body, where
@@ -109,6 +115,26 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+/** Resolve after a worker pipe emits all queued data, or closes/errors during termination. */
+function waitForPipeDrain(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)
+    // Close the event-registration race if termination finished between the
+    // initial state check and the listeners above.
+    /* v8 ignore next -- this race cannot be scheduled deterministically between the adjacent state check and listener registration. */
+    if (stream.readableEnded || stream.destroyed) done()
+  })
+}
+
 /**
  * Runtime shape gate for inbound port traffic. The peer runs MODEL CODE and
  * can post anything — `null`, primitives, objects with poisoned fields — so
@@ -124,31 +150,88 @@ function parseWorkerMessage(raw: unknown): WorkerToHost | undefined {
   switch (m.type) {
     case 'call': {
       if (typeof m.id !== 'number' || typeof m.global !== 'string' || typeof m.name !== 'string') return undefined
-      return { type: 'call', id: m.id, global: m.global, name: m.name, args: m.args }
+      return { type: 'call', id: m.id, global: m.global, name: m.name, args: m.args as WorkerJsonWire }
     }
     case 'log': {
       if (typeof m.text !== 'string') return undefined
       return { type: 'log', text: m.text }
     }
+    case 'output-limit': return { type: 'output-limit' }
     case 'done': {
-      if (m.error === undefined) return { type: 'done', ...m.value !== undefined ? { value: m.value } : {} }
+      if (m.error === undefined) return { type: 'done', ...m.value !== undefined ? { value: m.value as WorkerJsonWire } : {} }
       const error = m.error
       if (typeof error !== 'object' || error === null) return undefined
-      const message = (error as Record<string, unknown>).message
-      if (typeof message !== 'string') return undefined
-      return { type: 'done', ...m.value !== undefined ? { value: m.value } : {}, error: { message } }
+      const { kind, message } = error as Record<string, unknown>
+      if ((kind !== 'exception' && kind !== 'invalid-output' && kind !== 'output-limit') || typeof message !== 'string') return undefined
+      return { type: 'done', error: { kind, message } }
     }
     default: return undefined
   }
 }
 
-/**
- * Headroom the host's value re-cap grants over `maxValueBytes`: exactly the
- * truncation suffix {@link prepareValue} appends, so a value the WORKER
- * already capped (byte-exact prefix + this marker) passes through unchanged
- * instead of being marked twice.
- */
-const VALUE_RENDER_SLACK = Buffer.byteLength('… [truncated]', 'utf8')
+
+/** 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. */
+  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 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. */
+  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. */
+  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.
+    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 its returned prefix fits the same budget. */
+        if (prefixBytes === undefined) throw new Error('output ledger produced an oversized log prefix')
+        retained.push(prefix)
+        retainedBytes += prefixBytes + separatorBytes
+      }
+      break
+    }
+    const availableMessageBytes = this.maxBytes - retainedBytes
+    const message = truncateJsonStringBytes(fullMessage, availableMessageBytes)
+    return { logs: retained, error: { kind: 'output-limit', message } }
+  }
+}
 
 /**
  * The shipped {@link CodeRuntime} backend (`ctx.codeRuntime`). Registers as
@@ -161,8 +244,7 @@ export class WorkerCodeRuntime extends CodeRuntime {
   static Config: z<Config> = z.object({
     computeMs: z.number().default(60_000),
     maxWallMs: z.number().default(600_000),
-    maxLogBytes: z.number().default(65_536),
-    maxValueBytes: z.number().default(32_768),
+    maxOutputBytes: z.number().default(67_108_864),
     maxOldGenerationSizeMb: z.number().default(512),
   })
 
@@ -181,6 +263,9 @@ export class WorkerCodeRuntime extends CodeRuntime {
     for (const [key, value] of Object.entries(this.config)) {
       if (!(Number.isFinite(value) && value > 0)) throw new Error(`dsh-code-runtime-worker: config.${key} must be a positive number, got ${String(value)}`)
     }
+    if (!Number.isSafeInteger(this.config.maxOutputBytes) || this.config.maxOutputBytes < MIN_OUTPUT_BYTES) {
+      throw new Error(`dsh-code-runtime-worker: config.maxOutputBytes must be a safe integer of at least ${MIN_OUTPUT_BYTES}, got ${String(this.config.maxOutputBytes)}`)
+    }
     ctx.effect(() => () => this.teardown(), 'worker code-runtime teardown')
   }
 
@@ -208,7 +293,7 @@ export class WorkerCodeRuntime extends CodeRuntime {
     if (this.disposed) throw new Error('dsh-code-runtime-worker: run() after disposal')
     const bindings = this.validateBindings(request)
     if (request.signal?.aborted) {
-      return { logs: [], error: { kind: 'abort', message: String(request.signal.reason) } }
+      return this.failureBeforeWorker({ kind: 'abort', message: String(request.signal.reason) })
     }
 
     let code: string
@@ -219,15 +304,20 @@ export class WorkerCodeRuntime extends CodeRuntime {
       // A program that does not survive the type-strip (syntax error,
       // non-erasable syntax like `enum`) is a program failure, reported the
       // same way a thrown exception would be — and no worker ever spawns.
-      return { logs: [], error: { kind: 'exception', message: messageOf(error) } }
+      return this.failureBeforeWorker({ kind: 'exception', message: messageOf(error) })
     }
 
     return await this.execute(request, code, bindings)
   }
 
-  /** Reject (seam misuse) malformed binding namespaces: non-identifier or reserved globals, duplicates, and the `console` collision. */
-  private validateBindings(request: CodeRunRequest): Map<string, Record<string, CodeBindingFunction>> {
-    const bindings = new Map<string, Record<string, CodeBindingFunction>>()
+  /** Apply the outer-output ledger to failures that occur before a worker owns one. */
+  private failureBeforeWorker(error: CodeRunFailure): CodeRunResult {
+    return new OutputLedger(this.config.maxOutputBytes).failure([], error)
+  }
+
+  /** Reject malformed binding globals or typed-error declarations as seam misuse. */
+  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(`dsh-code-runtime-worker: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
@@ -235,7 +325,23 @@ export class WorkerCodeRuntime extends CodeRuntime {
       if (namespace.global === 'console' || bindings.has(namespace.global)) {
         throw new Error(`dsh-code-runtime-worker: duplicate binding global ${JSON.stringify(namespace.global)}`)
       }
-      bindings.set(namespace.global, namespace.functions)
+      bindings.set(namespace.global, namespace)
+    }
+
+    const errorClassNames = new Set<string>()
+    for (const namespace of request.bindings) {
+      const descriptor = namespace.errorClass
+      if (!descriptor) continue
+      if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
+        throw new Error(`dsh-code-runtime-worker: 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(`dsh-code-runtime-worker: duplicate injected global ${JSON.stringify(descriptor.name)}`)
+      }
+      if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
+        throw new Error(`dsh-code-runtime-worker: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
+      }
+      errorClassNames.add(descriptor.name)
     }
     return bindings
   }
@@ -244,13 +350,16 @@ export class WorkerCodeRuntime extends CodeRuntime {
   private execute(
     request: CodeRunRequest,
     code: string,
-    bindings: Map<string, Record<string, CodeBindingFunction>>,
+    bindings: Map<string, CodeBindingNamespace>,
   ): Promise<CodeRunResult> {
     const bootData: WorkerBootData = {
       code,
-      namespaces: [...bindings].map(([global, functions]) => ({ global, names: Object.keys(functions) })),
-      maxLogBytes: this.config.maxLogBytes,
-      maxValueBytes: this.config.maxValueBytes,
+      namespaces: [...bindings].map(([global, namespace]) => ({
+        global,
+        names: Object.keys(namespace.functions),
+        ...namespace.errorClass ? { errorClass: namespace.errorClass } : {},
+      })),
+      maxOutputBytes: this.config.maxOutputBytes,
     }
     const worker = new Worker(WORKER_PATH, {
       workerData: bootData,
@@ -274,28 +383,22 @@ export class WorkerCodeRuntime extends CodeRuntime {
       const answered = new Set<number>()
       const logs: string[] = []
       const strayLogs: string[] = []
+      const output = new OutputLedger(this.config.maxOutputBytes)
+      let terminalOverride: CodeRunResult | undefined
 
-      // One host-side budget covers normal, forged, and stray-pipe log entries. The first
-      // overflow emits the shared in-band marker and drops everything after it.
-      let logBudget = this.config.maxLogBytes
-      let logsTruncated = false
-      const admit = (text: string, sink: string[]): void => {
-        if (logsTruncated) return
-        const cost = Buffer.byteLength(text, 'utf8')
-        if (cost > logBudget) {
-          logsTruncated = true
-          sink.push(logTruncationMarker(this.config.maxLogBytes))
-          return
-        }
-        logBudget -= cost
-        sink.push(text)
-      }
-
-      // No settled guard: `finish` snapshots the arrays when it resolves, so
-      // a chunk flushing after settlement mutates only the discarded buffers,
-      // and the ledger bounds that growth until the pipes close.
+      // Pipe and message-port delivery are independent. Continue bounded pipe
+      // capture after a terminal message while worker termination drains bytes
+      // that were already queued; `finish` materializes the result only after
+      // termination completes.
       const captureStray = (chunk: Buffer): void => {
-        admit(chunk.toString('utf8'), strayLogs)
+        /* v8 ignore next -- a second post-overflow chunk races immediate worker termination; the first overflow path is covered. */
+        if (terminalOverride !== undefined) return
+        const text = chunk.toString('utf8')
+        if (!output.admit(text, strayLogs)) {
+          const limited = output.limit([...logs, ...strayLogs, text])
+          terminalOverride = limited
+          finish(limited)
+        }
       }
       worker.stdout.on('data', captureStray)
       worker.stderr.on('data', captureStray)
@@ -304,27 +407,42 @@ export class WorkerCodeRuntime extends CodeRuntime {
       // logs captured before timeout, abort, or failure remain in the result.
       let finishResolve!: () => void
       const finished = new Promise<void>((done) => { finishResolve = done })
-      const finish = (result: Omit<CodeRunResult, 'logs'>): void => {
+      const finish = (finalize: CodeRunResult | (() => CodeRunResult)): void => {
         if (settled) return
         settled = true
         clearInterval(eluTimer)
         clearTimeout(wallTimer)
         request.signal?.removeEventListener('abort', onAbort)
         this.live.delete(live)
-        void worker.terminate().then(() => {
+        // Let the poll phase deliver pipe bytes already queued independently
+        // of the terminal port message before termination closes the streams.
+        void new Promise<void>((resume) => { setImmediate(resume) }).then(async () => {
+          const stdoutDrained = waitForPipeDrain(worker.stdout)
+          const stderrDrained = waitForPipeDrain(worker.stderr)
+          await Promise.all([worker.terminate(), stdoutDrained, stderrDrained])
+          const result = terminalOverride ?? (typeof finalize === 'function' ? finalize() : finalize)
           finishResolve()
-          resolve({ ...result, logs: [...logs, ...strayLogs] })
+          resolve(result)
         })
       }
 
       const onDone = (message: WorkerToHost): void => {
         if (message.type !== 'done') return
-        // Re-cap forged completion traffic at the hostile boundary. Honest worker-capped values
-        // pass unchanged via VALUE_RENDER_SLACK; error text is bounded too.
-        finish({
-          ...prepareValue(message.value, this.config.maxValueBytes + VALUE_RENDER_SLACK),
-          ...message.error ? { error: { kind: 'exception' as const, message: truncateUtf8Bytes(message.error.message, this.config.maxValueBytes) } } : {},
-        })
+        if (message.error) {
+          const error = message.error
+          finish(() => output.failure([...logs, ...strayLogs], error))
+          return
+        }
+        if (message.value === undefined) {
+          finish(() => output.success([...logs, ...strayLogs]))
+          return
+        }
+        const value = decodeWorkerJson(message.value)
+        if (value === undefined) {
+          finish(() => output.failure([...logs, ...strayLogs], { kind: 'invalid-output', message: 'program completion must be lossless JSON' }))
+        } else {
+          finish(() => output.success([...logs, ...strayLogs], value))
+        }
       }
 
       const onCall = (message: WorkerToHost): void => {
@@ -336,15 +454,11 @@ export class WorkerCodeRuntime extends CodeRuntime {
         answered.add(message.id)
         const reply = (payload: ReplyMessage): void => {
           if (settled) return
-          try {
-            worker.postMessage(payload)
-          } catch {
-            // The reply value failed structured clone; renegotiate as an error
-            // reply, which is always clone-plain. Nothing else throws here.
-            worker.postMessage({ type: 'reply', id: message.id, ok: false, message: 'binding resolution is not structured-cloneable' })
-          }
+          // Canonical resolutions were snapshotted as lossless JSON before
+          // this point, so this payload is structured-cloneable by contract.
+          worker.postMessage(payload)
         }
-        const record = bindings.get(message.global)
+        const record = bindings.get(message.global)?.functions
         // Own-property lookup only: a forged name like 'constructor' or
         // 'hasOwnProperty' must not walk the record's prototype chain and
         // reach a callable the consumer never declared.
@@ -353,9 +467,25 @@ export class WorkerCodeRuntime extends CodeRuntime {
           reply({ 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) {
+          reply({ type: 'reply', id: message.id, ok: false, message: 'binding arguments must be lossless JSON' })
+          return
+        }
         void (async () => {
           try {
-            reply({ type: 'reply', id: message.id, ok: true, value: await fn(message.args) })
+            const resolved = await fn(args)
+            let value: CodeJsonValue | undefined
+            try {
+              value = snapshotJsonValue(resolved)
+            } catch {
+              value = undefined
+            }
+            if (value === undefined) {
+              reply({ type: 'reply', id: message.id, ok: false, message: 'binding resolution must be lossless JSON' })
+            } else {
+              reply({ type: 'reply', id: message.id, ok: true, value: encodeWorkerJson(value) })
+            }
           } catch (error: unknown) {
             reply({ type: 'reply', id: message.id, ok: false, message: messageOf(error) })
           }
@@ -367,15 +497,24 @@ export class WorkerCodeRuntime extends CodeRuntime {
         // this listener would crash the host process. Junk drops silently.
         const message = parseWorkerMessage(raw)
         if (!message) return
-        if (message.type === 'log' && !settled) admit(message.text, logs)
+        if (message.type === 'log' && !settled && !output.admit(message.text, logs)) {
+          const limited = output.limit([...logs, ...strayLogs, message.text])
+          finish(limited)
+          return
+        }
+        if (message.type === 'output-limit' && !settled) {
+          const limited = output.limit([...logs, ...strayLogs])
+          finish(limited)
+          return
+        }
         onCall(message)
         onDone(message)
       })
       worker.on('error', (error: Error) => {
-        finish({ error: { kind: 'worker-exit', message: `worker error: ${error.message}` } })
+        finish(() => output.failure([...logs, ...strayLogs], { kind: 'worker-exit', message: `worker error: ${error.message}` }))
       })
       worker.on('exit', (exitCode: number) => {
-        finish({ error: { kind: 'worker-exit', message: `worker exited with code ${exitCode} before completing` } })
+        finish(() => output.failure([...logs, ...strayLogs], { kind: 'worker-exit', message: `worker exited with code ${exitCode} before completing` }))
       })
 
       // The compute budget reads the worker's own measured busy time, so a
@@ -384,21 +523,21 @@ export class WorkerCodeRuntime extends CodeRuntime {
       const eluTimer = setInterval(() => {
         const elu = worker.performance.eventLoopUtilization()
         if (elu.active > this.config.computeMs) {
-          finish({ error: { kind: 'timeout', message: `compute budget exhausted (${this.config.computeMs}ms busy)` } })
+          finish(() => output.failure([...logs, ...strayLogs], { kind: 'timeout', message: `compute budget exhausted (${this.config.computeMs}ms busy)` }))
         }
       }, ELU_POLL_INTERVAL_MS)
       const wallTimer = setTimeout(() => {
-        finish({ error: { kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` } })
+        finish(() => output.failure([...logs, ...strayLogs], { kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` }))
       }, this.config.maxWallMs)
       const onAbort = (): void => {
-        finish({ error: { kind: 'abort', message: String(request.signal?.reason) } })
+        finish(() => output.failure([...logs, ...strayLogs], { kind: 'abort', message: String(request.signal?.reason) }))
       }
       request.signal?.addEventListener('abort', onAbort, { once: true })
 
       const live: LiveRun = {
         worker,
         finished,
-        settle: (failure: CodeRunFailure) => { finish({ error: failure }) },
+        settle: (failure: CodeRunFailure) => { finish(() => output.failure([...logs, ...strayLogs], failure)) },
       }
       this.live.add(live)
     })
diff --git a/packages/code-runtime/code-runtime-worker/src/output-json.ts b/packages/code-runtime/code-runtime-worker/src/output-json.ts
new file mode 100644
index 0000000000..06d56292bf
--- /dev/null
+++ b/packages/code-runtime/code-runtime-worker/src/output-json.ts
@@ -0,0 +1,179 @@
+/** JSON string-prefix accounting for the outer-output ledger. @module @deepseek-ai/dsh-code-runtime-worker/output-json */
+
+import type { CodeJsonValue } from '@deepseek-ai/dsh-code-runtime'
+
+type IntrinsicCallable = (this: unknown, ...args: unknown[]) => unknown
+
+const intrinsicReflectApply = Reflect.apply as (
+  target: IntrinsicCallable,
+  thisArgument: unknown,
+  argumentsList: readonly unknown[],
+) => unknown
+const intrinsicArrayIsArray = Array.isArray
+const IntrinsicBuffer = Buffer
+const intrinsicBufferByteLength = Reflect.get(Buffer, 'byteLength') as IntrinsicCallable
+const intrinsicObjectCreate = Object.create
+const intrinsicObjectDefineProperty = Object.defineProperty
+const intrinsicObjectKeys = Object.keys
+const intrinsicString = String
+const intrinsicStringCharCodeAt = Reflect.get(String.prototype, 'charCodeAt') as IntrinsicCallable
+const intrinsicStringCodePointAt = Reflect.get(String.prototype, 'codePointAt') as IntrinsicCallable
+const intrinsicStringSlice = Reflect.get(String.prototype, 'slice') as IntrinsicCallable
+
+/** Build a data descriptor that cannot inherit model-defined accessor fields. */
+function dataDescriptor(value: unknown): PropertyDescriptor {
+  const descriptor = intrinsicObjectCreate(null) as PropertyDescriptor
+  descriptor.value = value
+  return descriptor
+}
+
+/** Define an ordinary enumerable data slot without a prototype-bearing descriptor. */
+function defineEnumerableDataProperty(target: object, key: PropertyKey, value: unknown): void {
+  const descriptor = dataDescriptor(value)
+  descriptor.enumerable = true
+  descriptor.configurable = true
+  descriptor.writable = true
+  intrinsicObjectDefineProperty(target, key, descriptor)
+}
+
+/** UTF-8 byte length through the module-captured Node intrinsic. */
+function byteLength(text: string): number {
+  return intrinsicReflectApply(intrinsicBufferByteLength, IntrinsicBuffer, [text, 'utf8']) as number
+}
+
+/** Append without consulting a model-mutated `Array.prototype`. */
+function append<T>(target: T[], value: T): void {
+  defineEnumerableDataProperty(target, target.length, value)
+}
+
+/** Pop without consulting a model-mutated `Array.prototype`. */
+function takeLast<T>(target: T[]): T | undefined {
+  if (target.length === 0) return undefined
+  const index = target.length - 1
+  const value = target[index]
+  intrinsicObjectDefineProperty(target, 'length', dataDescriptor(index))
+  return value
+}
+
+/** One code-point-aligned character from a string. */
+function characterAt(text: string, index: number): string {
+  const codePoint = intrinsicReflectApply(intrinsicStringCodePointAt, text, [index]) as number
+  const width = codePoint > 0xffff ? 2 : 1
+  return intrinsicReflectApply(intrinsicStringSlice, text, [index, index + width]) as string
+}
+
+/** Serialized bytes contributed by one complete Unicode code point inside JSON quotes. */
+function serializedCharacterBytes(character: string): number {
+  if (character.length === 2) return 4
+  if (character === '"' || character === '\\') return 2
+  const code = intrinsicReflectApply(intrinsicStringCharCodeAt, character, [0]) as number
+  if (code >= 0xd800 && code <= 0xdfff) return 6
+  if (code < 0x20) return code === 0x08 || code === 0x09 || code === 0x0a || code === 0x0c || code === 0x0d ? 2 : 6
+  return byteLength(character)
+}
+
+/**
+ * Measure one JSON string without materializing its complete escaped form.
+ * @param text - the candidate string.
+ * @param maxBytes - largest serialized size the caller can admit.
+ * @returns Exact serialized bytes, or `undefined` as soon as the cap is crossed.
+ */
+export function jsonStringBytesUpTo(text: string, maxBytes: number): number | undefined {
+  if (maxBytes < 2) return undefined
+  let bytes = 2
+  for (let index = 0; index < text.length;) {
+    const character = characterAt(text, index)
+    bytes += serializedCharacterBytes(character)
+    if (bytes > maxBytes) return undefined
+    index += character.length
+  }
+  return bytes
+}
+
+/**
+ * Measure one lossless JSON value without allocating its serialized form.
+ * @param value - already validated lossless JSON.
+ * @param maxBytes - largest serialized size the caller can admit.
+ * @returns Exact serialized bytes, or `undefined` as soon as the cap is crossed.
+ */
+export function jsonValueBytesUpTo(value: CodeJsonValue, maxBytes: number): number | undefined {
+  type Task =
+    | { kind: 'value'; value: CodeJsonValue }
+    | { kind: 'array'; value: CodeJsonValue[]; index: number }
+    | { kind: 'object'; value: Record<string, CodeJsonValue>; keys: string[]; index: number }
+
+  let bytes = 0
+  const add = (cost: number): boolean => {
+    bytes += cost
+    return bytes <= maxBytes
+  }
+  const tasks: Task[] = [{ kind: 'value', value }]
+  for (let task = takeLast(tasks); task !== undefined; task = takeLast(tasks)) {
+    if (task.kind === 'value') {
+      const current = task.value
+      if (current === null) {
+        if (!add(4)) return undefined
+      } else if (typeof current === 'string') {
+        const stringBytes = jsonStringBytesUpTo(current, maxBytes - bytes)
+        if (stringBytes === undefined) return undefined
+        bytes += stringBytes
+      } else if (typeof current === 'number') {
+        if (!add(byteLength(intrinsicString(current)))) return undefined
+      } else if (typeof current === 'boolean') {
+        if (!add(current ? 4 : 5)) return undefined
+      } else if (intrinsicArrayIsArray(current)) {
+        if (!add(2)) return undefined
+        if (current.length > 0) append(tasks, { kind: 'array', value: current, index: 0 })
+      } else {
+        if (!add(2)) return undefined
+        const keys = intrinsicObjectKeys(current)
+        if (keys.length > 0) append(tasks, { kind: 'object', value: current, keys, index: 0 })
+      }
+      continue
+    }
+
+    if (task.index > 0 && !add(1)) return undefined
+    if (task.kind === 'array') {
+      const item = task.value[task.index]
+      if (item === undefined) return undefined
+      if (task.index + 1 < task.value.length) append(tasks, { ...task, index: task.index + 1 })
+      append(tasks, { kind: 'value', value: item })
+      continue
+    }
+
+    const key = task.keys[task.index]
+    /* v8 ignore next -- an object frame is created and advanced only for an existing Object.keys entry. */
+    if (key === undefined) return undefined
+    const keyBytes = jsonStringBytesUpTo(key, maxBytes - bytes)
+    if (keyBytes === undefined) return undefined
+    if (!add(keyBytes + 1)) return undefined
+    const item = task.value[key]
+    if (item === undefined) return undefined
+    if (task.index + 1 < task.keys.length) append(tasks, { ...task, index: task.index + 1 })
+    append(tasks, { kind: 'value', value: item })
+  }
+  return bytes
+}
+
+/**
+ * Return the longest code-point-aligned prefix whose JSON string encoding,
+ * including its surrounding quotes, fits `maxBytes`.
+ *
+ * @param text - the candidate string.
+ * @param maxBytes - serialized JSON-string bytes available.
+ * @returns the fitting prefix, or an empty string when even useful content cannot fit.
+ */
+export function truncateJsonStringBytes(text: string, maxBytes: number): string {
+  if (maxBytes < 2) return ''
+  let bytes = 2
+  let end = 0
+  for (let index = 0; index < text.length;) {
+    const character = characterAt(text, index)
+    const cost = serializedCharacterBytes(character)
+    if (bytes + cost > maxBytes) break
+    bytes += cost
+    end += character.length
+    index += character.length
+  }
+  return end === text.length ? text : intrinsicReflectApply(intrinsicStringSlice, text, [0, end]) as string
+}
diff --git a/packages/code-runtime/code-runtime-worker/src/protocol.ts b/packages/code-runtime/code-runtime-worker/src/protocol.ts
index 1ce108b7cc..11559d23b7 100644
--- a/packages/code-runtime/code-runtime-worker/src/protocol.ts
+++ b/packages/code-runtime/code-runtime-worker/src/protocol.ts
@@ -5,16 +5,20 @@
  * @module @deepseek-ai/dsh-code-runtime-worker/src/protocol
  */
 
+import type { WorkerJsonWire } from './worker-json.ts'
+
 /** What the host hands the worker at spawn, via `workerData`. */
 export interface WorkerBootData {
   /** The type-stripped (plain JS) program body. */
   code: string
-  /** Binding namespaces to materialize: the global name plus the function names (functions themselves stay host-side). */
-  namespaces: { global: string; names: string[] }[]
-  /** Shared byte budget for captured log text; exceeding it drops further entries after one in-band marker. */
-  maxLogBytes: number
-  /** Byte cap for the rendered completion value (see the value-preparation contract in bootstrap.ts). */
-  maxValueBytes: number
+  /** Binding namespaces to materialize; functions themselves stay host-side. */
+  namespaces: {
+    global: string
+    names: string[]
+    errorClass?: { name: string; memberNameProperty: string }
+  }[]
+  /** Hard cap for the combined serialized outer logs plus completion value or failure diagnostic. */
+  maxOutputBytes: number
 }
 
 /** Worker → host: one bridged binding call. */
@@ -26,8 +30,8 @@ interface CallMessage {
   global: string
   /** The function name within the namespace. */
   name: string
-  /** The single argument, structured-clone-plain. */
-  args: unknown
+  /** The single argument as a flat lossless-JSON wire value. */
+  args: WorkerJsonWire
 }
 
 /** Worker → host: captured text, streamed eagerly so output survives a mid-run termination (timeout, abort, OOM). */
@@ -36,37 +40,29 @@ interface LogMessage {
   text: string
 }
 
+/** Worker → host: worker-side capture or completion measurement exceeded the outer cap. */
+interface OutputLimitMessage {
+  type: 'output-limit'
+}
+
 /**
- * Worker → host: the program settled. `error` carries a program exception
- * (the only failure the bootstrap itself can report — budgets, aborts, and
- * substrate death are observed host-side). `value` is present only on a
- * clean completion that produced one (already size-capped and
- * clone-safe per the bootstrap's value preparation). Logs are NOT carried
- * here — they streamed eagerly as {@link LogMessage}s.
+ * Worker → host: the program settled. `error` carries a program exception,
+ * invalid completion, or output overflow (budgets, aborts, and substrate death
+ * are observed host-side). `value` is present only on a clean completion that
+ * produced one, as a flat wire value already lossless and admitted against
+ * the remaining combined output cap. Logs are NOT carried here — they streamed
+ * eagerly as {@link LogMessage}s.
  */
 export interface DoneMessage {
   type: 'done'
-  value?: unknown
-  error?: { message: string }
+  value?: WorkerJsonWire
+  error?: { kind: 'exception' | 'invalid-output' | 'output-limit'; message: string }
 }
 
 /** Every message the worker sends. */
-export type WorkerToHost = CallMessage | LogMessage | DoneMessage
+export type WorkerToHost = CallMessage | LogMessage | OutputLimitMessage | DoneMessage
 
 /** Host → worker: the answer to one {@link CallMessage}. */
 export type ReplyMessage =
-  | { type: 'reply'; id: number; ok: true; value: unknown }
+  | { type: 'reply'; id: number; ok: true; value: WorkerJsonWire }
   | { type: 'reply'; id: number; ok: false; message: string }
-
-/**
- * The in-band marker entry text announcing that log capture stopped at the
- * byte budget. Shared wire vocabulary: the worker's LogBuffer emits it when
- * ITS budget exhausts, and the host emits the identical text when its own
- * ledger drops an entry first (forged port traffic, stray pipe bytes) — so
- * a truncated run reads the same however the cap was hit.
- * @param maxBytes - the configured `maxLogBytes` the marker names.
- * @returns the marker line.
- */
-export function logTruncationMarker(maxBytes: number): string {
-  return `[dsh-code-runtime-worker] log capture truncated at ${maxBytes} bytes`
-}
diff --git a/packages/code-runtime/code-runtime-worker/src/worker-json.ts b/packages/code-runtime/code-runtime-worker/src/worker-json.ts
new file mode 100644
index 0000000000..b91005bb68
--- /dev/null
+++ b/packages/code-runtime/code-runtime-worker/src/worker-json.ts
@@ -0,0 +1,417 @@
+/** Lossless-JSON snapshots for the dependency-free source worker closure. @module @deepseek-ai/dsh-code-runtime-worker/worker-json */
+
+import type { CodeJsonValue } from '@deepseek-ai/dsh-code-runtime'
+
+/* jscpd:ignore-start -- the source worker mirrors session JSON helpers without workspace runtime imports */
+type IntrinsicCallable = (this: unknown, ...args: unknown[]) => unknown
+
+const intrinsicFunctionToString = Reflect.get(Function.prototype, 'toString') as IntrinsicCallable
+const intrinsicReflectApply = Reflect.get(Reflect, 'apply') as (
+  target: IntrinsicCallable,
+  thisArgument: unknown,
+  argumentsList: readonly unknown[],
+) => unknown
+const IntrinsicError = Error
+const IntrinsicSet = Set
+const intrinsicArrayIsArray = Array.isArray
+const intrinsicArrayPrototype = Array.prototype
+const intrinsicNumberIsFinite = Number.isFinite
+const intrinsicNumberIsSafeInteger = Number.isSafeInteger
+const intrinsicObjectCreate = Object.create
+const intrinsicObjectDefineProperty = Object.defineProperty
+const intrinsicObjectGetOwnPropertyDescriptor = Object.getOwnPropertyDescriptor
+const intrinsicObjectGetPrototypeOf = Object.getPrototypeOf
+const intrinsicObjectHasOwn = Object.hasOwn
+const intrinsicObjectIs = Object.is
+const intrinsicObjectKeys = Object.keys
+const intrinsicObjectPrototype = Object.prototype
+const intrinsicObjectPropertyIsEnumerable = Reflect.get(intrinsicObjectPrototype, 'propertyIsEnumerable') as IntrinsicCallable
+const intrinsicReflectOwnKeys = Reflect.ownKeys
+const intrinsicSetAdd = Reflect.get(Set.prototype, 'add') as IntrinsicCallable
+const intrinsicSetDelete = Reflect.get(Set.prototype, 'delete') as IntrinsicCallable
+const intrinsicSetHas = Reflect.get(Set.prototype, 'has') as IntrinsicCallable
+
+/** Build a data descriptor that cannot inherit model-defined accessor fields. */
+function dataDescriptor(value: unknown): PropertyDescriptor {
+  const descriptor = intrinsicObjectCreate(null) as PropertyDescriptor
+  descriptor.value = value
+  return descriptor
+}
+
+/** Define an ordinary enumerable data slot without a prototype-bearing descriptor. */
+function defineEnumerableDataProperty(target: object, key: PropertyKey, value: unknown): void {
+  const descriptor = dataDescriptor(value)
+  descriptor.enumerable = true
+  descriptor.configurable = true
+  descriptor.writable = true
+  intrinsicObjectDefineProperty(target, key, descriptor)
+}
+
+/** Append without consulting a model-mutated `Array.prototype`. */
+function append<T>(target: T[], value: T): void {
+  defineEnumerableDataProperty(target, target.length, value)
+}
+
+/** Pop without consulting a model-mutated `Array.prototype`. */
+function takeLast<T>(target: T[]): T | undefined {
+  if (target.length === 0) return undefined
+  const index = target.length - 1
+  const value = target[index]
+  intrinsicObjectDefineProperty(target, 'length', dataDescriptor(index))
+  return value
+}
+
+/** Whether one captured-intrinsic Set contains a value. */
+function setHas<T>(target: Set<T>, value: T): boolean {
+  return intrinsicReflectApply(intrinsicSetHas, target, [value]) as boolean
+}
+
+/** Add to one captured-intrinsic Set. */
+function setAdd<T>(target: Set<T>, value: T): void {
+  intrinsicReflectApply(intrinsicSetAdd, target, [value])
+}
+
+/** Delete from one captured-intrinsic Set. */
+function setDelete<T>(target: Set<T>, value: T): void {
+  intrinsicReflectApply(intrinsicSetDelete, target, [value])
+}
+
+/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
+function hasIntrinsicConstructor(prototype: object, name: 'Array' | 'Object'): boolean {
+  const descriptor = intrinsicObjectGetOwnPropertyDescriptor(prototype, 'constructor')
+  const constructor: unknown = descriptor?.value
+  if (typeof constructor !== 'function') return false
+  try {
+    return constructor.name === name
+      && constructor.prototype === prototype
+      && intrinsicReflectApply(intrinsicFunctionToString, constructor, []) === `function ${name}() { [native code] }`
+  } catch {
+    return false
+  }
+}
+
+/** Whether a candidate is a foreign realm's intrinsic `Object.prototype`. */
+function isForeignIntrinsicObjectPrototype(value: object): boolean {
+  return intrinsicObjectGetPrototypeOf(value) === null && hasIntrinsicConstructor(value, 'Object')
+}
+
+/** Whether an array uses one realm's intrinsic `Array.prototype`, not a subclass or forged prototype. */
+function hasPlainArrayPrototype(value: unknown[]): boolean {
+  const prototype: unknown = intrinsicObjectGetPrototypeOf(value)
+  if (prototype === intrinsicArrayPrototype) return true
+  if (!intrinsicArrayIsArray(prototype) || !hasIntrinsicConstructor(prototype, 'Array')) return false
+  const objectPrototype: unknown = intrinsicObjectGetPrototypeOf(prototype)
+  return typeof objectPrototype === 'object'
+    && objectPrototype !== null
+    && isForeignIntrinsicObjectPrototype(objectPrototype)
+}
+
+/** Whether an object is a plain or null-prototype record from any JavaScript realm. */
+function hasPlainObjectPrototype(value: object): boolean {
+  const prototype: unknown = intrinsicObjectGetPrototypeOf(value)
+  return prototype === null
+    || prototype === intrinsicObjectPrototype
+    || typeof prototype === 'object' && isForeignIntrinsicObjectPrototype(prototype)
+}
+
+/** Return every JSON-visible object key, or reject own data JSON would discard. */
+function enumerableStringKeys(value: object): string[] | undefined {
+  const keys = intrinsicReflectOwnKeys(value)
+  for (let index = 0; index < keys.length; index++) {
+    const key = keys[index]
+    if (typeof key !== 'string' || !intrinsicReflectApply(intrinsicObjectPropertyIsEnumerable, value, [key])) return undefined
+  }
+  return keys as string[]
+}
+
+type SnapshotDestination =
+  | { kind: 'root' }
+  | { kind: 'array'; target: CodeJsonValue[]; index: number }
+  | { kind: 'object'; target: Record<string, CodeJsonValue>; key: string }
+
+type SnapshotTask =
+  | { kind: 'visit'; value: unknown; destination: SnapshotDestination }
+  | { kind: 'array-item'; source: unknown[]; index: number; target: CodeJsonValue[] }
+  | { kind: 'object-property'; source: Record<string, unknown>; key: string; target: Record<string, CodeJsonValue> }
+  | { kind: 'leave'; source: object }
+
+/**
+ * Validate and detach one worker-boundary value without loading another
+ * workspace package at runtime. This mirrors the session-owned canonical
+ * JSON boundary while remaining safe to import from the unbuilt worker.
+ * Its iterative traversal adds no JavaScript call-stack depth limit.
+ *
+ * @param value - the candidate completion value.
+ * @returns a detached lossless-JSON snapshot, or `undefined` when invalid.
+ */
+export function snapshotCodeJsonValue(value: unknown): CodeJsonValue | undefined {
+  const active = new IntrinsicSet<object>()
+  let root: CodeJsonValue | undefined
+  const assign = (destination: SnapshotDestination, item: CodeJsonValue): void => {
+    if (destination.kind === 'root') {
+      root = item
+    } else if (destination.kind === 'array') {
+      defineEnumerableDataProperty(destination.target, destination.index, item)
+    } else {
+      defineEnumerableDataProperty(destination.target, destination.key, item)
+    }
+  }
+
+  const tasks: SnapshotTask[] = [{ kind: 'visit', value, destination: { kind: 'root' } }]
+  for (let task = takeLast(tasks); task !== undefined; task = takeLast(tasks)) {
+    if (task.kind === 'leave') {
+      setDelete(active, task.source)
+      continue
+    }
+    if (task.kind === 'array-item') {
+      if (!intrinsicObjectHasOwn(task.source, task.index)) return undefined
+      append(tasks, {
+        kind: 'visit',
+        value: task.source[task.index],
+        destination: { kind: 'array', target: task.target, index: task.index },
+      })
+      continue
+    }
+    if (task.kind === 'object-property') {
+      append(tasks, {
+        kind: 'visit',
+        value: task.source[task.key],
+        destination: { kind: 'object', target: task.target, key: task.key },
+      })
+      continue
+    }
+
+    const candidate = task.value
+    if (candidate === null) {
+      assign(task.destination, null)
+      continue
+    }
+    if (typeof candidate === 'boolean' || typeof candidate === 'string') {
+      assign(task.destination, candidate)
+      continue
+    }
+    if (typeof candidate === 'number') {
+      if (!intrinsicNumberIsFinite(candidate) || intrinsicObjectIs(candidate, -0)) return undefined
+      assign(task.destination, candidate)
+      continue
+    }
+    if (typeof candidate !== 'object') return undefined
+    if (setHas(active, candidate)) return undefined
+
+    if (intrinsicArrayIsArray(candidate)) {
+      if (!hasPlainArrayPrototype(candidate)) return undefined
+      const length = candidate.length
+      if (intrinsicReflectOwnKeys(candidate).length !== length + 1) return undefined
+      const target: CodeJsonValue[] = []
+      assign(task.destination, target)
+      setAdd(active, candidate)
+      append(tasks, { kind: 'leave', source: candidate })
+      for (let index = length - 1; index >= 0; index--) {
+        append(tasks, { kind: 'array-item', source: candidate, index, target })
+      }
+      continue
+    }
+
+    if (!hasPlainObjectPrototype(candidate)) return undefined
+    const keys = enumerableStringKeys(candidate)
+    if (keys === undefined) return undefined
+    const target: Record<string, CodeJsonValue> = {}
+    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]
+      /* v8 ignore next -- the loop is bounded by the captured key count. */
+      if (key === undefined) return undefined
+      append(tasks, { kind: 'object-property', source: candidate as Record<string, unknown>, key, target })
+    }
+  }
+  return root
+}
+
+interface ArrayWireToken {
+  kind: 'array'
+  length: number
+}
+
+interface ObjectWireToken {
+  kind: 'object'
+  keys: string[]
+}
+
+type WorkerJsonToken = null | boolean | number | string | ArrayWireToken | ObjectWireToken
+
+/**
+ * A pre-order, bounded-depth transport for one lossless JSON value. Container
+ * markers and scalar leaves share one flat token array, so `worker_threads`
+ * never has to structured-clone the value's application nesting.
+ */
+export type WorkerJsonWire = WorkerJsonToken[]
+
+/**
+ * Flatten one validated JSON value for the worker-thread message port.
+ * @param value - the lossless JSON value to transport.
+ * @returns a pre-order token stream whose own nesting is bounded.
+ */
+export function encodeWorkerJson(value: CodeJsonValue): WorkerJsonWire {
+  const wire: WorkerJsonWire = []
+  const pending: CodeJsonValue[] = [value]
+  for (let current = takeLast(pending); current !== undefined; current = takeLast(pending)) {
+    if (current === null || typeof current === 'boolean' || typeof current === 'number' || typeof current === 'string') {
+      append(wire, current)
+      continue
+    }
+    if (intrinsicArrayIsArray(current)) {
+      append(wire, { kind: 'array', length: current.length })
+      for (let index = current.length - 1; index >= 0; index--) {
+        const item = current[index]
+        if (item === undefined) throw new IntrinsicError('cannot encode a sparse JSON array')
+        append(pending, item)
+      }
+      continue
+    }
+    const keys = intrinsicObjectKeys(current)
+    append(wire, { kind: 'object', keys })
+    for (let index = keys.length - 1; index >= 0; index--) {
+      const key = keys[index]
+      /* v8 ignore next -- the loop is bounded by the captured key count. */
+      if (key === undefined) throw new IntrinsicError('cannot encode a missing JSON object key')
+      const item = current[key]
+      if (item === undefined) throw new IntrinsicError('cannot encode an undefined JSON object property')
+      append(pending, item)
+    }
+  }
+  return wire
+}
+
+type DecodeFrame =
+  | { kind: 'array'; target: CodeJsonValue[]; length: number; index: number }
+  | { kind: 'object'; target: Record<string, CodeJsonValue>; keys: string[]; index: number }
+
+/** Whether an array contains exactly its dense indexed slots and `length`. */
+function isDenseArray(value: unknown[]): boolean {
+  if (!hasPlainArrayPrototype(value) || intrinsicReflectOwnKeys(value).length !== value.length + 1) return false
+  for (let index = 0; index < value.length; index++) {
+    if (!intrinsicObjectHasOwn(value, index)) return false
+  }
+  return true
+}
+
+/** Whether one exact string-key list contains a key, without consulting its prototype. */
+function keysContain(keys: string[], expected: string): boolean {
+  for (let index = 0; index < keys.length; index++) {
+    if (keys[index] === expected) return true
+  }
+  return false
+}
+
+/** Return one exact container marker, or reject any extra/missing fields. */
+function containerToken(value: object): ArrayWireToken | ObjectWireToken | undefined {
+  if (intrinsicArrayIsArray(value) || !hasPlainObjectPrototype(value)) return undefined
+  const keys = enumerableStringKeys(value)
+  if (keys === undefined) return undefined
+  const token = value as Record<string, unknown>
+  if (token.kind === 'array') {
+    if (keys.length !== 2 || !keysContain(keys, 'kind') || !keysContain(keys, 'length')) return undefined
+    const length = token.length
+    return typeof length === 'number' && intrinsicNumberIsSafeInteger(length) && length >= 0
+      ? { kind: 'array', length }
+      : undefined
+  }
+  if (token.kind === 'object') {
+    if (keys.length !== 2 || !keysContain(keys, 'kind') || !keysContain(keys, 'keys')) return undefined
+    const objectKeys = token.keys
+    if (!intrinsicArrayIsArray(objectKeys) || !isDenseArray(objectKeys)) return undefined
+    const unique = new IntrinsicSet<string>()
+    const normalizedKeys: string[] = []
+    const objectKeyValues = objectKeys as unknown[]
+    for (let index = 0; index < objectKeyValues.length; index++) {
+      const key = objectKeyValues[index]
+      if (typeof key !== 'string' || setHas(unique, key)) return undefined
+      setAdd(unique, key)
+      append(normalizedKeys, key)
+    }
+    return { kind: 'object', keys: normalizedKeys }
+  }
+  return undefined
+}
+
+/**
+ * Rebuild one lossless JSON value from the flat worker-thread wire format.
+ * Malformed or incomplete traffic returns `undefined`; traversal is iterative
+ * and therefore independent of the transported value's application depth.
+ * @param input - untrusted message-port payload.
+ * @returns the detached JSON value, or `undefined` when the wire is invalid.
+ */
+export function decodeWorkerJson(input: unknown): CodeJsonValue | undefined {
+  try {
+    if (!intrinsicArrayIsArray(input) || !isDenseArray(input) || input.length === 0) return undefined
+    const wire = input as unknown[]
+    const frames: DecodeFrame[] = []
+    let root: CodeJsonValue | undefined
+    let rootAssigned = false
+
+    const attach = (value: CodeJsonValue): boolean => {
+      const parent = frames[frames.length - 1]
+      if (!parent) {
+        if (rootAssigned) return false
+        root = value
+        rootAssigned = true
+        return true
+      }
+      /* v8 ignore next -- completed frames are popped before another token can attach. */
+      if (parent.index >= (parent.kind === 'array' ? parent.length : parent.keys.length)) return false
+      if (parent.kind === 'array') {
+        append(parent.target, value)
+      } else {
+        const key = parent.keys[parent.index]
+        /* v8 ignore next -- object frames are built from validated keys and their exact length. */
+        if (key === undefined) return false
+        defineEnumerableDataProperty(parent.target, key, value)
+      }
+      parent.index += 1
+      return true
+    }
+
+    for (let tokenIndex = 0; tokenIndex < wire.length; tokenIndex++) {
+      const token = wire[tokenIndex]
+      let value: CodeJsonValue
+      let frame: DecodeFrame | undefined
+      if (token === null || typeof token === 'boolean' || typeof token === 'string') {
+        value = token
+      } else if (typeof token === 'number') {
+        if (!intrinsicNumberIsFinite(token) || intrinsicObjectIs(token, -0)) return undefined
+        value = token
+      } else {
+        if (typeof token !== 'object') return undefined
+        const marker = containerToken(token)
+        if (!marker) return undefined
+        const remainingTokens = wire.length - tokenIndex - 1
+        if (marker.kind === 'array') {
+          if (marker.length > remainingTokens) return undefined
+          const target: CodeJsonValue[] = []
+          value = target
+          if (marker.length > 0) frame = { kind: 'array', target, length: marker.length, index: 0 }
+        } else {
+          if (marker.keys.length > remainingTokens) return undefined
+          const target: Record<string, CodeJsonValue> = {}
+          value = target
+          if (marker.keys.length > 0) frame = { kind: 'object', target, keys: marker.keys, index: 0 }
+        }
+      }
+      if (!attach(value)) return undefined
+      if (frame) append(frames, frame)
+      while (frames.length > 0) {
+        const current = frames[frames.length - 1]
+        /* v8 ignore next -- the loop condition guarantees a final frame. */
+        if (current === undefined) break
+        if (current.index < (current.kind === 'array' ? current.length : current.keys.length)) break
+        takeLast(frames)
+      }
+    }
+    return frames.length === 0 ? root : undefined
+  } catch {
+    return undefined
+  }
+}
+/* jscpd:ignore-end */
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 111aa4f15f..a2aac6d9c2 100644
--- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
@@ -1,8 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { EventEmitter } from 'node:events'
-import { LogBuffer, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareValue, runWorkerMain, truncateUtf8Bytes, wireReplies } from '../src/bootstrap.ts'
+import { LogBuffer, makeBindingErrorClasses, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareCompletion, prepareException, runWorkerMain, wireReplies } from '../src/bootstrap.ts'
 import type { BootstrapPort, PatchableStream, PendingCall } from '../src/bootstrap.ts'
 import type { ReplyMessage, WorkerToHost } from '../src/protocol.ts'
+import { decodeWorkerJson, encodeWorkerJson } from '../src/worker-json.ts'
 
 /**
  * An in-process stand-in for the worker's parentPort: the test plays the
@@ -37,25 +38,52 @@ class FakePort implements BootstrapPort {
   done(): WorkerToHost | undefined {
     return this.sent.find(message => message.type === 'done')
   }
+
+  doneValue(): unknown {
+    const done = this.done()
+    return done?.type === 'done' && done.value !== undefined ? decodeWorkerJson(done.value) : undefined
+  }
 }
 
 function fakeStreams(): { stdout: PatchableStream; stderr: PatchableStream } {
   return { stdout: { write: () => true }, stderr: { write: () => true } }
 }
 
-const BOOT = { maxLogBytes: 65_536, maxValueBytes: 32_768 }
+/** Capture one promise rejection without Vitest's intentionally `any` matcher channel. */
+async function rejectionOf(promise: Promise<unknown>): Promise<unknown> {
+  try {
+    await promise
+    return undefined
+  } catch (error: unknown) {
+    return error
+  }
+}
+
+const BOOT = { maxOutputBytes: 65_536 }
+const TOOL_ERROR_CLASS = { name: 'ToolCallError', memberNameProperty: 'toolName' } as const
+
+/** One worker declaration for the Code Mode tools namespace. */
+function toolNamespace(names: string[]) {
+  return { global: 'tools', names, errorClass: TOOL_ERROR_CLASS }
+}
 
 describe('LogBuffer', () => {
-  it('streams entries to the sink until the byte budget, then emits one marker and drops the rest', () => {
+  it('streams entries to the sink until the byte budget, then emits one fitting prefix and reports the limit once', () => {
     const seen: string[] = []
-    const buffer = new LogBuffer(10, text => seen.push(text))
+    let limits = 0
+    const buffer = new LogBuffer(15, text => seen.push(text), () => { limits += 1 })
     buffer.push('12345')
     buffer.push('123456')
     buffer.push('dropped')
-    expect(seen).toEqual([
-      '12345',
-      '[dsh-code-runtime-worker] log capture truncated at 10 bytes',
-    ])
+    expect(seen).toEqual(['12345', '123'])
+    expect(limits).toBe(1)
+    expect(buffer.remainingOutputBytes()).toBe(0)
+
+    const exactlyFull: string[] = []
+    const fullBuffer = new LogBuffer(6, text => exactlyFull.push(text))
+    fullBuffer.push('12')
+    fullBuffer.push('no-prefix-fits')
+    expect(exactlyFull).toEqual(['12'])
   })
 })
 
@@ -109,66 +137,87 @@ describe('captureStreamWrites', () => {
   })
 })
 
-describe('prepareValue', () => {
-  it('omits undefined, passes small cloneable values raw', () => {
-    expect(prepareValue(undefined, 100)).toEqual({})
-    expect(prepareValue({ a: [1, 'two'] }, 100)).toEqual({ value: { a: [1, 'two'] } })
+describe('prepareCompletion', () => {
+  it('omits undefined and passes lossless JSON values exactly', () => {
+    expect(prepareCompletion(undefined, 100)).toEqual({})
+    expect(prepareCompletion({ a: [1, 'two'] }, 100)).toEqual({ value: encodeWorkerJson({ a: [1, 'two'] }) })
   })
 
-  it('replaces a non-cloneable value with its rendering', () => {
-    const { value } = prepareValue({ fn: () => 1 }, 1_000)
-    expect(typeof value).toBe('string')
-    expect(value).toContain('fn')
+  it('turns every lossy completion shape into invalid-output', () => {
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+    const sparse = Array(2)
+    class Exotic { readonly marker = true }
+    for (const value of [{ fn: () => 1 }, -0, Number.POSITIVE_INFINITY, sparse, cyclic, new Exotic()]) {
+      expect(prepareCompletion(value, 1_000)).toEqual({
+        error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' },
+      })
+    }
   })
 
-  it('replaces an oversized value with a truncation-marked capped rendering', () => {
-    const { value } = prepareValue('x'.repeat(50), 10)
-    expect(value).toBe(`${'x'.repeat(10)}… [truncated]`)
+  it('reports an oversized value instead of substituting rendered text', () => {
+    expect(prepareCompletion('x'.repeat(50), 10)).toEqual({
+      error: { kind: 'output-limit', message: 'outer output exceeded 10 bytes' },
+    })
   })
 
-  it('measures a container by its structured-clone wire size, not its bounded rendering', () => {
-    // The bounded inspect rendering of a huge array is tiny ("... N more
-    // items"), but its real cross-boundary size is not — the cap must catch
-    // it, replacing the value with that bounded rendering.
-    const huge = new Array(50_000).fill(7)
-    const { value } = prepareValue(huge, 1_000)
-    expect(typeof value).toBe('string')
-    expect(value).toContain('more items')
+  it('measures the exact JSON serialization at and over the boundary', () => {
+    expect(prepareCompletion('€', 5)).toEqual({ value: encodeWorkerJson('€') })
+    expect(prepareCompletion('€', 4)).toEqual({
+      error: { kind: 'output-limit', message: 'outer output exceeded 4 bytes' },
+    })
   })
 
-  it('caps a multibyte string by UTF-8 bytes, not UTF-16 length', () => {
-    // 4 code units but 12 UTF-8 bytes: a length-counting cap would pass the
-    // full string through untruncated.
-    expect(prepareValue('€€€€', 4)).toEqual({ value: '€… [truncated]' })
+  it('contains a getter failure as invalid-output', () => {
+    const value = Object.defineProperty({}, 'x', { enumerable: true, get() { throw new Error('getter exploded') } })
+    expect(prepareCompletion(value, 1_000)).toEqual({
+      error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' },
+    })
   })
 
-  it('caps a multibyte rendering by UTF-8 bytes too', () => {
-    // Wire size (24-byte string inside an array) exceeds the cap, so the
-    // value crosses as its rendering — whose truncation must also be
-    // byte-exact: "[ '" (3 bytes) + two € (6 bytes) = 9; a third € would
-    // overflow the 10-byte budget.
-    expect(prepareValue(['€€€€€€€€'], 10)).toEqual({ value: "[ '€€… [truncated]" })
+  it('uses the remaining combined budget for invalid-output diagnostics', () => {
+    expect(prepareCompletion(() => 1, 4, 64)).toEqual({
+      error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
+    })
   })
 })
 
-describe('truncateUtf8Bytes', () => {
-  it('returns a fitting string whole', () => {
-    expect(truncateUtf8Bytes('fits', 4)).toBe('fits')
+describe('prepareException', () => {
+  it('passes a fitting diagnostic and rejects one byte over without carrying its text', () => {
+    expect(prepareException('boom', 6, 64)).toEqual({ error: { kind: 'exception', message: 'boom' } })
+    expect(prepareException('boom', 5, 64)).toEqual({
+      error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
+    })
   })
 
-  it('cuts at a code-point boundary, never mid-surrogate-pair', () => {
-    // Each 😀 is one code point, two code units, four UTF-8 bytes: a 5-byte
-    // budget fits exactly one — and never leaves a lone surrogate behind.
-    const cut = truncateUtf8Bytes('😀😀', 5)
-    expect(cut).toBe('😀')
-    expect(Buffer.byteLength(truncateUtf8Bytes('😀😀', 3), 'utf8')).toBe(0)
+  it('contains a thrown value whose string conversion fails', () => {
+    const thrown = { toString() { throw new Error('cannot render') } }
+    expect(prepareException(thrown, 1_000)).toEqual({
+      error: { kind: 'exception', message: 'program threw an unrenderable value' },
+    })
+
+    const strangeStack = Object.defineProperty(new Error('ignored'), 'stack', { value: 42 })
+    expect(prepareException(strangeStack, 1_000)).toEqual({
+      error: { kind: 'exception', message: '42' },
+    })
   })
 })
 
 describe('makeNamespaces', () => {
+  it('rejects a malformed success reply instead of resolving a lossy binding value', async () => {
+    const port = new FakePort()
+    const pending = new Map<number, PendingCall>()
+    wireReplies(port, pending)
+    const result = new Promise<unknown>((resolve, reject) => { pending.set(1, { resolve, reject }) })
+    port.deliver({ type: 'reply', id: 1, ok: true, value: [undefined] as never })
+    await expect(result).rejects.toThrow('binding resolution must be lossless JSON')
+  })
+
   it('exposes prototype-colliding names as ordinary own properties', async () => {
     const port = new FakePort()
-    port.respond = message => message.type === 'call' ? { type: 'reply', id: message.id, ok: true, value: `${message.name}-ok` } : undefined
+    port.respond = message => message.type === 'call'
+      ? { type: 'reply', id: message.id, ok: true, value: encodeWorkerJson(`${message.name}-ok`) }
+      : undefined
     const pending = new Map<number, PendingCall>()
     wireReplies(port, pending)
     const [tools] = makeNamespaces({ namespaces: [{ global: 'tools', names: ['__proto__', 'constructor', 'toString'] }] }, port, pending, { value: 1 }) as [Record<string, (args: unknown) => Promise<unknown>>]
@@ -178,7 +227,7 @@ describe('makeNamespaces', () => {
     await expect(tools['toString']?.({})).resolves.toBe('toString-ok')
   })
 
-  it('rejects a non-cloneable argument without leaking the pending entry', async () => {
+  it('rejects a postMessage clone failure without leaking the pending entry', async () => {
     let firstCall = true
     const throwingPort: BootstrapPort = {
       // First call throws an Error (the real DataCloneError shape), the
@@ -190,24 +239,108 @@ describe('makeNamespaces', () => {
       on: () => {},
     }
     const pending = new Map<number, PendingCall>()
-    const [tools] = makeNamespaces({ namespaces: [{ global: 'tools', names: ['x'] }] }, throwingPort, pending, { value: 1 }) as [Record<string, (args: unknown) => Promise<unknown>>]
-    await expect(tools.x?.(() => 1)).rejects.toThrow(/structured-cloneable: DataCloneError-ish/)
-    await expect(tools.x?.(() => 1)).rejects.toThrow(/structured-cloneable: raw-clone-failure/)
+    const data = { namespaces: [toolNamespace(['x'])] }
+    const errorClasses = makeBindingErrorClasses(data)
+    const ToolCallError = errorClasses.get('tools')
+    const [tools] = makeNamespaces(
+      data,
+      throwingPort,
+      pending,
+      { value: 1 },
+      errorClasses,
+    ) as [Record<string, (args: unknown) => Promise<unknown>>]
+    const first = await rejectionOf(tools.x?.({ first: true }) ?? Promise.resolve())
+    const second = await rejectionOf(tools.x?.({ second: true }) ?? Promise.resolve())
+    expect(first).toMatchObject({ name: 'ToolCallError', toolName: 'x' })
+    expect(second).toMatchObject({ name: 'ToolCallError', toolName: 'x' })
+    expect(first).toBeInstanceOf(ToolCallError)
+    expect(second).toBeInstanceOf(ToolCallError)
+    expect((first as Error).message).toMatch(/DataCloneError-ish/)
+    expect((second as Error).message).toMatch(/raw-clone-failure/)
     expect(pending.size).toBe(0)
   })
+
+  it('rejects lossy arguments before posting or allocating a call id', async () => {
+    let posts = 0
+    const port: BootstrapPort = { postMessage: () => { posts += 1 }, on: () => {} }
+    const pending = new Map<number, PendingCall>()
+    const nextId = { value: 1 }
+    const [tools] = makeNamespaces(
+      { namespaces: [toolNamespace(['x'])] }, port, pending, nextId,
+    ) as [Record<string, (args: unknown) => Promise<unknown>>]
+    const decorated = [1]
+    Object.defineProperty(decorated, 'extra', { value: true })
+    const throwing = Object.defineProperty({}, 'value', {
+      enumerable: true,
+      get: () => { throw new Error('getter exploded') },
+    })
+
+    for (const value of [() => 1, new Date(), decorated, throwing]) {
+      const failure = await rejectionOf(tools.x?.(value) ?? Promise.resolve())
+      expect(failure).toMatchObject({
+        name: 'ToolCallError', toolName: 'x', message: 'binding arguments must be lossless JSON',
+      })
+    }
+    expect(posts).toBe(0)
+    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'
+      ? { type: 'reply', id: message.id, ok: false, message: 'helper denied' }
+      : undefined
+    const deniedPending = new Map<number, PendingCall>()
+    wireReplies(deniedPort, deniedPending)
+    const [helpers] = makeNamespaces({ namespaces: [{ global: 'helpers', names: ['x'] }] }, deniedPort, deniedPending, { value: 1 }) as [Record<string, (args: unknown) => Promise<unknown>>]
+    const denied = await rejectionOf(helpers.x?.({}) ?? Promise.resolve())
+    expect(denied).toBeInstanceOf(Error)
+    expect(denied).toMatchObject({ name: 'Error', message: 'helper denied' })
+    expect(denied).not.toHaveProperty('toolName')
+
+    const invalid = await rejectionOf(helpers.x?.(() => 1) ?? Promise.resolve())
+    expect(invalid).toBeInstanceOf(Error)
+    expect((invalid as Error).message).toBe('binding arguments must be lossless JSON')
+
+    const clonePort: BootstrapPort = { postMessage: () => { throw new Error('clone failed') }, on: () => {} }
+    const [cloneHelpers] = makeNamespaces({ namespaces: [{ global: 'helpers', names: ['x'] }] }, clonePort, new Map(), { value: 1 }) as [Record<string, (args: unknown) => Promise<unknown>>]
+    const cloneFailure = await rejectionOf(cloneHelpers.x?.({}) ?? Promise.resolve())
+    expect(cloneFailure).toBeInstanceOf(Error)
+    expect(cloneFailure).not.toHaveProperty('toolName')
+  })
 })
 
 describe('runWorkerMain', () => {
   it('runs a program end-to-end: bindings, console, return value', async () => {
     const port = new FakePort()
-    port.respond = message => message.type === 'call' ? { type: 'reply', id: message.id, ok: true, value: (message.args as { n: number }).n * 2 } : undefined
+    port.respond = (message) => {
+      if (message.type !== 'call') return undefined
+      const args = decodeWorkerJson(message.args) as { n: number }
+      return { type: 'reply', id: message.id, ok: true, value: encodeWorkerJson(args.n * 2) }
+    }
     await runWorkerMain(port, {
       ...BOOT,
       code: 'const doubled = await tools.double({ n: 21 }); console.log("got", doubled); return { doubled };',
       namespaces: [{ global: 'tools', names: ['double'] }],
     }, fakeStreams())
     expect(port.logs()).toEqual(['got 42'])
-    expect(port.done()).toEqual({ type: 'done', value: { doubled: 42 } })
+    expect(port.doneValue()).toEqual({ doubled: 42 })
+  })
+
+  it('reports worker-side log capture overflow before completing', async () => {
+    const port = new FakePort()
+    await runWorkerMain(port, {
+      maxOutputBytes: 4,
+      code: 'console.log("12345"); return null',
+      namespaces: [],
+    }, fakeStreams())
+    expect(port.logs()).toEqual([])
+    expect(port.sent).toContainEqual({ type: 'output-limit' })
+    expect(port.done()).toEqual({
+      type: 'done',
+      error: { kind: 'output-limit', message: 'outer output exceeded 4 bytes' },
+    })
   })
 
   it('reports a thrown program error on the done message', async () => {
@@ -215,6 +348,7 @@ describe('runWorkerMain', () => {
     await runWorkerMain(port, { ...BOOT, code: 'throw new Error("boom")', namespaces: [] }, fakeStreams())
     const done = port.done()
     expect(done?.type).toBe('done')
+    expect(done?.type === 'done' ? done.error?.kind : undefined).toBe('exception')
     expect(done?.type === 'done' ? done.error?.message : undefined).toContain('boom')
     expect(done?.type === 'done' ? done.value : undefined).toBeUndefined()
   })
@@ -222,11 +356,35 @@ describe('runWorkerMain', () => {
   it('renders non-Error throws and stack-less Errors on the done message', async () => {
     const rawPort = new FakePort()
     await runWorkerMain(rawPort, { ...BOOT, code: 'throw "raw-throw"', namespaces: [] }, fakeStreams())
-    expect(rawPort.done()).toEqual({ type: 'done', error: { message: 'raw-throw' } })
+    expect(rawPort.done()).toEqual({ type: 'done', error: { kind: 'exception', message: 'raw-throw' } })
 
     const barePort = new FakePort()
     await runWorkerMain(barePort, { ...BOOT, code: 'const e = new Error("bare"); e.stack = undefined; throw e', namespaces: [] }, fakeStreams())
-    expect(barePort.done()).toEqual({ type: 'done', error: { message: 'bare' } })
+    expect(barePort.done()).toEqual({ type: 'done', error: { kind: 'exception', message: 'bare' } })
+  })
+
+  it('replaces giant thrown strings and Error stacks before posting the done message', async () => {
+    const rawPort = new FakePort()
+    await runWorkerMain(rawPort, {
+      maxOutputBytes: 64,
+      code: 'throw "x".repeat(1_000_000)',
+      namespaces: [],
+    }, fakeStreams())
+    expect(rawPort.done()).toEqual({
+      type: 'done',
+      error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
+    })
+
+    const stackPort = new FakePort()
+    await runWorkerMain(stackPort, {
+      maxOutputBytes: 64,
+      code: 'throw new Error("x".repeat(1_000_000))',
+      namespaces: [],
+    }, fakeStreams())
+    expect(stackPort.done()).toEqual({
+      type: 'done',
+      error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
+    })
   })
 
   it('surfaces a host failure reply as a program-side rejection it can catch', async () => {
@@ -234,10 +392,27 @@ describe('runWorkerMain', () => {
     port.respond = message => message.type === 'call' ? { type: 'reply', id: message.id, ok: false, message: 'denied by host' } : undefined
     await runWorkerMain(port, {
       ...BOOT,
-      code: 'try { await tools.x({}) } catch (error) { return `caught: ${error.message}` }',
-      namespaces: [{ global: 'tools', names: ['x'] }],
+      code: 'try { await tools.x({}) } catch (error) { return { caught: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message } }',
+      namespaces: [toolNamespace(['x'])],
     }, fakeStreams())
-    expect(port.done()).toEqual({ type: 'done', value: 'caught: denied by host' })
+    expect(port.doneValue()).toEqual({ caught: true, name: 'ToolCallError', toolName: 'x', message: 'denied by host' })
+  })
+
+  it('materializes a consumer-declared rejection class without knowing the namespace', async () => {
+    const port = new FakePort()
+    port.respond = message => message.type === 'call'
+      ? { type: 'reply', id: message.id, ok: false, message: 'helper denied' }
+      : undefined
+    await runWorkerMain(port, {
+      ...BOOT,
+      code: 'try { await helpers.x({}) } catch (error) { return { caught: error instanceof HelperCallError, name: error.name, helperName: error.helperName, message: error.message } }',
+      namespaces: [{
+        global: 'helpers',
+        names: ['x'],
+        errorClass: { name: 'HelperCallError', memberNameProperty: 'helperName' },
+      }],
+    }, fakeStreams())
+    expect(port.doneValue()).toEqual({ caught: true, name: 'HelperCallError', helperName: 'x', message: 'helper denied' })
   })
 
   it('ignores replies for unknown pending ids', async () => {
@@ -245,15 +420,15 @@ describe('runWorkerMain', () => {
     port.respond = (message) => {
       if (message.type !== 'call') return undefined
       // Deliver a stray reply first; the real one follows.
-      port.deliver({ type: 'reply', id: 9_999, ok: true, value: 'stray' })
-      return { type: 'reply', id: message.id, ok: true, value: 'real' }
+      port.deliver({ type: 'reply', id: 9_999, ok: true, value: encodeWorkerJson('stray') })
+      return { type: 'reply', id: message.id, ok: true, value: encodeWorkerJson('real') }
     }
     await runWorkerMain(port, {
       ...BOOT,
       code: 'return await tools.x({})',
       namespaces: [{ global: 'tools', names: ['x'] }],
     }, fakeStreams())
-    expect(port.done()).toEqual({ type: 'done', value: 'real' })
+    expect(port.doneValue()).toBe('real')
   })
 
   it('captures raw stream writes through the patched process streams', async () => {
diff --git a/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts b/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
index ff68fd09fe..4c6098a2ec 100644
--- a/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
@@ -23,8 +23,15 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => {
       const ctx = new Context()
       await ctx.plugin(WorkerCodeRuntime, {})
       const result = await ctx.codeRuntime.run({
-        program: 'const doubled: number = await tools.double({ n: 21 }); console.log("halfway", doubled); return doubled;',
-        bindings: [{ global: 'tools', functions: { double: async args => args.n * 2 } }],
+        program: 'const doubled: number = await tools.double({ n: 21 }); console.log("halfway", doubled); let failure; try { await tools.fail({}) } catch (error) { failure = { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message } } return { doubled, failure };',
+        bindings: [{
+          global: 'tools',
+          functions: {
+            double: async args => args.n * 2,
+            fail: async () => { throw new Error('denied') },
+          },
+          errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
+        }],
       })
       console.log(JSON.stringify(result))
       process.exit(0)
@@ -40,7 +47,10 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => {
     const lastLine = stdout.trim().split('\n').at(-1) ?? ''
     const result = JSON.parse(lastLine) as { value?: unknown; logs: string[]; error?: unknown }
     expect(result.error).toBeUndefined()
-    expect(result.value).toBe(42)
+    expect(result.value).toEqual({
+      doubled: 42,
+      failure: { typed: true, name: 'ToolCallError', toolName: 'fail', message: 'denied' },
+    })
     expect(result.logs).toContain('halfway 42')
   })
 })
diff --git a/packages/code-runtime/code-runtime-worker/tests/output-json.spec.ts b/packages/code-runtime/code-runtime-worker/tests/output-json.spec.ts
new file mode 100644
index 0000000000..9d3bc4d5ef
--- /dev/null
+++ b/packages/code-runtime/code-runtime-worker/tests/output-json.spec.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { CodeJsonValue } from '@deepseek-ai/dsh-code-runtime'
+import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from '../src/output-json.ts'
+
+describe('truncateJsonStringBytes', () => {
+  it('returns a fitting string whole and rejects budgets without JSON quotes', () => {
+    expect(truncateJsonStringBytes('fits', 6)).toBe('fits')
+    expect(truncateJsonStringBytes('x', 1)).toBe('')
+    expect(jsonStringBytesUpTo('fits', 6)).toBe(6)
+    expect(jsonStringBytesUpTo('fits', 5)).toBeUndefined()
+  })
+
+  it('accounts every JSON escape and cuts only between complete code points', () => {
+    const prefix = '"\\\b\t\n\f\r\u0000😀\ud800€a'
+    const text = `${prefix}z`
+    const budget = Buffer.byteLength(JSON.stringify(prefix), 'utf8')
+
+    expect(truncateJsonStringBytes(text, budget)).toBe(prefix)
+    expect(Buffer.byteLength(JSON.stringify(truncateJsonStringBytes(text, budget)), 'utf8')).toBe(budget)
+  })
+
+  it('bounds hostile strings without materializing their complete escaped form', () => {
+    const stringify = vi.spyOn(JSON, 'stringify').mockImplementation(() => { throw new Error('must not stringify') })
+    try {
+      expect(jsonStringBytesUpTo('"'.repeat(10_000), 32)).toBeUndefined()
+      expect(truncateJsonStringBytes('"'.repeat(10_000), 32)).toBe('"'.repeat(15))
+    } finally {
+      stringify.mockRestore()
+    }
+  })
+})
+
+describe('jsonValueBytesUpTo', () => {
+  it('matches JSON serialization for every lossless value branch and stops at the cap', () => {
+    const value = {
+      empty: {},
+      nil: null,
+      yes: true,
+      no: false,
+      number: 1.5,
+      text: '"\n😀',
+      array: [1, 'x'],
+    }
+    const bytes = Buffer.byteLength(JSON.stringify(value), 'utf8')
+
+    expect(jsonValueBytesUpTo(value, bytes)).toBe(bytes)
+    expect(jsonValueBytesUpTo(value, bytes - 1)).toBeUndefined()
+    expect(jsonValueBytesUpTo({}, 1)).toBeUndefined()
+    expect(jsonValueBytesUpTo([], 1)).toBeUndefined()
+    expect(jsonValueBytesUpTo([], 2)).toBe(2)
+    expect(jsonValueBytesUpTo(null, 3)).toBeUndefined()
+    expect(jsonValueBytesUpTo(10, 1)).toBeUndefined()
+    expect(jsonValueBytesUpTo(false, 4)).toBeUndefined()
+    expect(jsonValueBytesUpTo(new Array<never>(1), 10)).toBeUndefined()
+    expect(jsonValueBytesUpTo([null], 5)).toBeUndefined()
+    expect(jsonValueBytesUpTo([0, 0], 3)).toBeUndefined()
+    expect(jsonValueBytesUpTo({ a: null, b: null }, 10)).toBeUndefined()
+    expect(jsonValueBytesUpTo({ long: null }, 2)).toBeUndefined()
+    expect(jsonValueBytesUpTo({ '': null }, 4)).toBeUndefined()
+    expect(jsonValueBytesUpTo({ a: null }, 9)).toBeUndefined()
+    expect(jsonValueBytesUpTo({ a: undefined } as unknown as CodeJsonValue, 100)).toBeUndefined()
+  })
+
+  it('meters deeply nested arrays without recursive stack growth', () => {
+    let value: CodeJsonValue = null
+    for (let depth = 0; depth < 5_000; depth++) value = [value]
+
+    expect(jsonValueBytesUpTo(value, 10_004)).toBe(10_004)
+    expect(jsonValueBytesUpTo(value, 10_003)).toBeUndefined()
+  })
+
+  it('uses module-captured intrinsics after model-visible globals are mutated', () => {
+    const value: CodeJsonValue = { payload: ['€', 42] }
+    const bytes = Buffer.byteLength(JSON.stringify(value), 'utf8')
+    const arrayIsArrayDescriptor = Object.getOwnPropertyDescriptor(Array, 'isArray')!
+    const arrayPopDescriptor = Object.getOwnPropertyDescriptor(Array.prototype, 'pop')!
+    const arrayPushDescriptor = Object.getOwnPropertyDescriptor(Array.prototype, 'push')!
+    const byteLengthDescriptor = Object.getOwnPropertyDescriptor(Buffer, 'byteLength')!
+    const objectKeysDescriptor = Object.getOwnPropertyDescriptor(Object, 'keys')!
+    const charCodeAtDescriptor = Object.getOwnPropertyDescriptor(String.prototype, 'charCodeAt')!
+    const codePointAtDescriptor = Object.getOwnPropertyDescriptor(String.prototype, 'codePointAt')!
+    const sliceDescriptor = Object.getOwnPropertyDescriptor(String.prototype, 'slice')!
+    let measured: number | undefined
+    let prefix = ''
+    try {
+      Array.isArray = (_value: unknown): _value is never[] => false
+      Array.prototype.pop = () => { throw new Error('mutated pop') }
+      Array.prototype.push = () => { throw new Error('mutated push') }
+      Buffer.byteLength = () => 0
+      Object.keys = () => []
+      String.prototype.charCodeAt = () => { throw new Error('mutated charCodeAt') }
+      String.prototype.codePointAt = () => { throw new Error('mutated codePointAt') }
+      String.prototype.slice = () => { throw new Error('mutated slice') }
+      measured = jsonValueBytesUpTo(value, bytes)
+      prefix = truncateJsonStringBytes('€x', 5)
+    } finally {
+      Object.defineProperty(Array, 'isArray', arrayIsArrayDescriptor)
+      Object.defineProperty(Array.prototype, 'pop', arrayPopDescriptor)
+      Object.defineProperty(Array.prototype, 'push', arrayPushDescriptor)
+      Object.defineProperty(Buffer, 'byteLength', byteLengthDescriptor)
+      Object.defineProperty(Object, 'keys', objectKeysDescriptor)
+      Object.defineProperty(String.prototype, 'charCodeAt', charCodeAtDescriptor)
+      Object.defineProperty(String.prototype, 'codePointAt', codePointAtDescriptor)
+      Object.defineProperty(String.prototype, 'slice', sliceDescriptor)
+    }
+    expect(measured).toBe(bytes)
+    expect(prefix).toBe('€')
+  })
+})
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 ae2cb2b639..f213deede3 100644
--- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker'
 import type { Config } from '@deepseek-ai/dsh-code-runtime-worker'
-import type { CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
+import type { CodeBindingFunction, CodeBindingNamespace, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
 
 /**
  * Integration suite over REAL worker threads (no mocks — workers are cheap
@@ -17,8 +17,12 @@ async function setup(config: Config = {}) {
 }
 
 /** Convenience: one namespace `tools` with the given functions. */
-function tools(functions: Record<string, (args: unknown) => Promise<unknown>>) {
-  return [{ global: 'tools', functions }]
+function tools(functions: Record<string, (args: unknown) => Promise<unknown>>): CodeBindingNamespace[] {
+  return [{
+    global: 'tools',
+    functions: functions as Record<string, CodeBindingFunction>,
+    errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
+  }]
 }
 
 describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
@@ -52,10 +56,10 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
     const result = await runtime.run({
       program: `
         const first = await tools.echo({ n: 1 });
-        let caught = '';
-        try { await tools.fail({}) } catch (error) { caught = error.message }
-        let caughtRaw = '';
-        try { await tools.failRaw({}) } catch (error) { caughtRaw = error.message }
+        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: tools({
@@ -66,10 +70,61 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
       }),
     })
     expect(result.error).toBeUndefined()
-    expect(result.value).toEqual({ first: { echoed: { n: 1 } }, caught: 'nope', caughtRaw: 'raw-nope' })
+    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: tools({ 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: [] })
@@ -90,10 +145,11 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
     expect(result.value).toBe('{}')
   })
 
-  it('replaces a non-cloneable return value with a string rendering', async () => {
+  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(typeof result.value).toBe('string')
+    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 () => {
@@ -166,6 +222,19 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
     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()
@@ -201,30 +270,94 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
     expect(after.value).toBe('alive')
   }, 30_000)
 
-  it('truncates runaway log output at the byte budget with an in-band marker', async () => {
-    const { runtime } = await setup({ maxLogBytes: 300 })
+  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.logs.at(-1)).toContain('truncated at 300 bytes')
-    const total = result.logs.reduce((sum, text) => sum + Buffer.byteLength(text, 'utf8'), 0)
-    expect(total).toBeLessThan(1_000)
+    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('caps an oversized return value with a truncation marker', async () => {
-    const { runtime } = await setup({ maxValueBytes: 64 })
+  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).toBe(`${'y'.repeat(64)}… [truncated]`)
+    expect(result.value).toBeUndefined()
+    expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
   })
 
-  it('caps a multibyte return value by UTF-8 bytes, not string length', async () => {
-    // 4 code units, 12 UTF-8 bytes: a length-counting cap would let the full
-    // string cross. The worker's byte-exact capped rendering then passes the
-    // host re-cap unchanged (cap + marker is exactly the granted slack).
-    const { runtime } = await setup({ maxValueBytes: 4 })
-    const result = await runtime.run({ program: 'return "€€€€"', bindings: [] })
-    expect(result.value).toBe('€… [truncated]')
+  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 () => {
@@ -241,32 +374,67 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
     expect(result.logs).toContain('flushed')
   })
 
-  it('caps a huge container whose bounded rendering is small (wire size, not rendering, is what counts)', async () => {
+  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(typeof result.value).toBe('string')
-    expect(result.value).toContain('more items')
+    expect(result.value).toEqual(new Array(50_000).fill(7))
   })
 
-  it('captures pipe writes that bypass the patched write slot as stray logs, capped by the same budget', async () => {
-    const { runtime } = await setup({ maxLogBytes: 4 })
+  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('accounts pipe writes that bypass the patched write slot in the same outer ledger', async () => {
+    const { runtime } = await setup({ maxOutputBytes: 80 })
     const result = await runtime.run({
       // The prototype write bypasses the patched instance and reaches the real pipe. Pauses keep
       // writes in separate chunks and let both reach the host before settlement.
       program: `
         const write = (text) => Object.getPrototypeOf(process.stdout).write.call(process.stdout, text);
-        write('abcd');
+        write('a'.repeat(20));
         await new Promise(resolve => setTimeout(resolve, 150));
-        write('ef');
+        write('b'.repeat(100));
         await new Promise(resolve => setTimeout(resolve, 100));
         return 1;
       `,
       bindings: [],
     })
+    expect(result.error?.kind).toBe('output-limit')
+    expect(result.logs).toContain('a'.repeat(20))
+    expect(result.logs[1]?.length).toBeGreaterThan(0)
+    expect('b'.repeat(100).startsWith(result.logs[1] ?? '')).toBe(true)
+  }, 15_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.logs).toContain('abcd')
-    expect(result.logs).not.toContain('ef')
+    expect(result.value).toBe('done')
+    expect(result.logs.join('') === payload).toBe(true)
   }, 15_000)
 })
 
@@ -305,7 +473,8 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
           { type: 'log', text: 7 },
           { type: 'log', text: {} },
           { type: 'done', error: 5 },
-          { type: 'done', error: { message: 5 } },
+          { type: 'done', error: { kind: 'exception', message: 5 } },
+          { type: 'done', error: { kind: 'invented', message: 'bad kind' } },
         ]) parentPort.postMessage(junk);
         return await tools.real({});
       `,
@@ -316,67 +485,288 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
     expect(result.logs).toEqual([])
   })
 
-  it('caps forged log floods and forged done values at the configured budgets, dropping forged extra fields', async () => {
-    const { runtime } = await setup({ maxLogBytes: 200, maxValueBytes: 64 })
+  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 the worker-side LogBuffer and prepareValue
+      // Forged messages bypass the worker-side LogBuffer and completion check
       // entirely — only the host-side ledger and re-cap stand between model
       // code and an unbounded result.
       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) });
+        parentPort.postMessage({ type: 'done', value: ['V'.repeat(100000)] });
         for (;;) {}
       `,
       bindings: [],
     })
-    expect(typeof result.value).toBe('string')
-    const value = result.value as string
-    expect(value.startsWith('V'.repeat(64))).toBe(true)
-    expect(value.endsWith('… [truncated]')).toBe(true)
-    expect(value.length).toBeLessThan(120)
-    const marker = '[dsh-code-runtime-worker] log capture truncated at 200 bytes'
-    const total = result.logs.reduce((sum, text) => sum + Buffer.byteLength(text, 'utf8'), 0)
-    expect(total).toBeLessThanOrEqual(200 + Buffer.byteLength(marker, 'utf8'))
-    expect(result.logs.at(-1)).toBe(marker)
+    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('accepts a forged done carrying both value and error (self-sabotage, contained)', async () => {
+  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('bounds one oversized forged log while retaining its fitting escaped prefix', async () => {
+    const { runtime } = await setup({ maxOutputBytes: 96 })
+    const result = await runtime.run({
+      program: `
+        const { parentPort } = await import('node:worker_threads');
+        parentPort.postMessage({ type: 'log', text: '"'.repeat(1_000_000) });
+        for (;;) {}
+      `,
+      bindings: [],
+    })
+    expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 96 bytes' })
+    expect(result.logs).toHaveLength(1)
+    expect(result.logs[0]).toMatch(/^"+$/)
+    expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8') + Buffer.byteLength(JSON.stringify('outer output exceeded 96 bytes'), 'utf8')).toBeLessThanOrEqual(96)
+  })
+
+  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: { message: 'fake failure' } });
-        for (;;) {}
+        parentPort.postMessage({ type: 'done', value: 'lied', error: { kind: 'exception', message: 'fake failure' } });
+        return 'honest';
       `,
       bindings: [],
     })
-    expect(result.value).toBe('lied')
-    expect(result.error).toEqual({ kind: 'exception', message: 'fake failure' })
+    expect(result).toEqual({ logs: [], error: { kind: 'exception', message: 'fake failure' } })
   })
 
-  it('byte-bounds forged multibyte error text at the host', async () => {
-    // Forged error text bypasses the worker entirely; the host bound is a
-    // BYTE bound (two € = 6 bytes fit an 8-byte cap, a third would not).
-    const { runtime } = await setup({ maxValueBytes: 8 })
+  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');
-        parentPort.postMessage({ type: 'done', error: { message: '€'.repeat(1000) } });
+        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: 'exception', message: '€€' })
+    expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
   })
 
-  it('answers a binding whose resolution cannot be cloned with a failure reply', async () => {
+  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 error.message }',
+      program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
       bindings: tools({ bad: async () => (() => 1) }),
     })
-    expect(result.value).toContain('not structured-cloneable')
+    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: tools({ 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: tools({ 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: tools({ 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: tools({ 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: tools({ 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 () => {
@@ -392,7 +782,7 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
 })
 
 describe('WorkerCodeRuntime — seam misuse and lifecycle', () => {
-  it('rejects invalid binding globals loudly (identifier, reserved word, duplicate, console)', async () => {
+  it('rejects invalid and duplicate binding globals loudly', async () => {
     const { runtime } = await setup()
     const cases: [string, RegExp][] = [
       ['not valid!', /not a usable identifier/],
@@ -406,6 +796,32 @@ describe('WorkerCodeRuntime — seam misuse and lifecycle', () => {
       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 () => {
@@ -413,6 +829,12 @@ describe('WorkerCodeRuntime — seam misuse and lifecycle', () => {
     await expect(ctx.plugin(WorkerCodeRuntime, { computeMs: -1 })).rejects.toThrow(/positive number/)
   })
 
+  it('requires maxOutputBytes to fit the smallest counted outer payloads', async () => {
+    const ctx = new Context()
+    await expect(ctx.plugin(WorkerCodeRuntime, { maxOutputBytes: 3 })).rejects.toThrow(/safe integer of at least 4/)
+    await expect(ctx.plugin(WorkerCodeRuntime, { 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: [] })
diff --git a/packages/code-runtime/code-runtime-worker/tests/source-worker.compat.spec.ts b/packages/code-runtime/code-runtime-worker/tests/source-worker.compat.spec.ts
new file mode 100644
index 0000000000..6ef2775114
--- /dev/null
+++ b/packages/code-runtime/code-runtime-worker/tests/source-worker.compat.spec.ts
@@ -0,0 +1,39 @@
+import { copyFile, mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Worker } from 'node:worker_threads'
+import { expect, it } from 'vitest'
+import { decodeWorkerJson } from '../src/worker-json.ts'
+
+/**
+ * Prove the unbuilt worker is a self-contained source closure. Copying it out
+ * of the workspace makes any package runtime import fail even when local
+ * `lib/` artifacts happen to exist.
+ */
+it('boots the source worker without workspace package outputs', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-code-source-worker-'))
+  let worker: Worker | undefined
+  try {
+    const files = ['worker.ts', 'bootstrap.ts', 'protocol.ts', 'worker-json.ts', 'output-json.ts']
+    await Promise.all(files.map(async (file) => {
+      await copyFile(new URL(`../src/${file}`, import.meta.url), join(directory, file))
+    }))
+
+    worker = new Worker(join(directory, 'worker.ts'), {
+      workerData: { code: 'return { answer: 42 }', namespaces: [], maxOutputBytes: 65_536 },
+      env: {},
+      execArgv: [],
+    })
+    const message = await new Promise<unknown>((resolve, reject) => {
+      worker?.once('message', resolve)
+      worker?.once('error', reject)
+    })
+
+    expect(message).toMatchObject({ type: 'done' })
+    const value = typeof message === 'object' && message !== null ? (message as { value?: unknown }).value : undefined
+    expect(decodeWorkerJson(value)).toEqual({ answer: 42 })
+  } finally {
+    if (worker) await worker.terminate()
+    await rm(directory, { recursive: true, force: true })
+  }
+})
diff --git a/packages/code-runtime/code-runtime-worker/tests/worker-json.spec.ts b/packages/code-runtime/code-runtime-worker/tests/worker-json.spec.ts
new file mode 100644
index 0000000000..6ef8d30a09
--- /dev/null
+++ b/packages/code-runtime/code-runtime-worker/tests/worker-json.spec.ts
@@ -0,0 +1,257 @@
+import { runInNewContext } from 'node:vm'
+import { describe, expect, it } from 'vitest'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from '../src/worker-json.ts'
+
+describe('snapshotCodeJsonValue', () => {
+  it('matches the canonical scalar boundary', () => {
+    const unsupported = [undefined, 1n, Symbol('value'), () => 1]
+    for (const value of [null, false, 'text', 1.25, -0, Number.NaN, Number.POSITIVE_INFINITY, ...unsupported]) {
+      expect(snapshotCodeJsonValue(value)).toEqual(snapshotJsonValue(value))
+    }
+  })
+
+  it('detaches dense arrays and plain or null-prototype records', () => {
+    const shared = { value: 1 }
+    const nullPrototype = Object.assign(Object.create(null) as Record<string, unknown>, { shared })
+    const source = { list: [nullPrototype, shared], alias: shared }
+
+    const snapshot = snapshotCodeJsonValue(source) as Record<string, unknown>
+    shared.value = 2
+
+    expect(snapshot).toEqual({ list: [{ shared: { value: 1 } }, { value: 1 }], alias: { value: 1 } })
+    expect(snapshot).not.toBe(source)
+    expect((snapshot.list as unknown[])[0]).not.toBe(nullPrototype)
+    expect(snapshot.alias).not.toBe(shared)
+  })
+
+  it('accepts intrinsic plain containers from another JavaScript realm', () => {
+    const foreign = runInNewContext('({ object: { nested: [1] }, array: [2, { ok: true }] })') as {
+      object: unknown
+      array: unknown
+    }
+
+    expect(snapshotCodeJsonValue(foreign.object)).toEqual({ nested: [1] })
+    expect(snapshotCodeJsonValue(foreign.array)).toEqual([2, { ok: true }])
+  })
+
+  it('reads each accepted slot once and preserves a literal __proto__ key', () => {
+    let objectReads = 0
+    let arrayReads = 0
+    const source = Object.create(null) as Record<string, unknown>
+    Object.defineProperty(source, '__proto__', {
+      enumerable: true,
+      get: () => {
+        objectReads += 1
+        return { safe: true }
+      },
+    })
+    const array = new Array<unknown>(1)
+    Object.defineProperty(array, 0, {
+      enumerable: true,
+      get: () => {
+        arrayReads += 1
+        return arrayReads === 1 ? source : undefined
+      },
+    })
+
+    const snapshot = snapshotCodeJsonValue(array) as Record<string, unknown>[]
+
+    expect(objectReads).toBe(1)
+    expect(arrayReads).toBe(1)
+    expect(Object.getPrototypeOf(snapshot[0])).toBe(Object.prototype)
+    expect(Object.hasOwn(snapshot[0]!, '__proto__')).toBe(true)
+    expect(snapshot[0]?.['__proto__']).toEqual({ safe: true })
+  })
+
+  it('accepts deeply nested valid JSON without using the JavaScript call stack', () => {
+    let value: unknown = 'leaf'
+    for (let depth = 0; depth < 5_000; depth++) value = [value]
+
+    let cursor = snapshotCodeJsonValue(value)
+    for (let depth = 0; depth < 5_000; depth++) {
+      expect(Array.isArray(cursor)).toBe(true)
+      cursor = Array.isArray(cursor) ? cursor[0] : undefined
+    }
+    expect(cursor).toBe('leaf')
+  })
+
+  it('rejects exotic containers, sparse arrays, cycles, and invalid children', () => {
+    class ExoticObject {
+      readonly value = 1
+    }
+    class ExoticArray extends Array<number> {}
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+    const decorated = [1]
+    Object.defineProperty(decorated, 'extra', { value: true })
+    const compensatedSparse = new Array(1)
+    Object.defineProperty(compensatedSparse, 'extra', { value: true })
+    const symbolDecorated = [1]
+    Object.defineProperty(symbolDecorated, Symbol('extra'), { value: true })
+    const hiddenObject = Object.defineProperty({}, 'hidden', { value: true })
+    const symbolObject = { [Symbol('extra')]: true }
+    const customPrototype = Object.create(null) as Record<string, unknown>
+    const customPrototypeObject = Object.assign(Object.create(customPrototype) as Record<string, unknown>, { value: 1 })
+    const forgedPrototype: unknown[] = []
+    Object.setPrototypeOf(forgedPrototype, null)
+    const forgedArray = [1]
+    Object.setPrototypeOf(forgedArray, forgedPrototype)
+    const spoofedObjectPrototype = Object.create(null) as Record<string, unknown>
+    const SpoofedObject = function Object() {}
+    SpoofedObject.prototype = spoofedObjectPrototype
+    Object.defineProperty(spoofedObjectPrototype, 'constructor', { value: SpoofedObject })
+    const spoofedObject = Object.create(spoofedObjectPrototype) as Record<string, unknown>
+    spoofedObject.value = 1
+    const revokedPrototype = Object.create(null) as Record<string, unknown>
+    const RevokedObject = function Object() {}
+    RevokedObject.prototype = revokedPrototype
+    const revokedConstructor = Proxy.revocable(RevokedObject, {})
+    Object.defineProperty(revokedPrototype, 'constructor', { value: revokedConstructor.proxy })
+    const revokedObject = Object.create(revokedPrototype) as Record<string, unknown>
+    revokedConstructor.revoke()
+    const spoofedArrayPrototype: unknown[] = []
+    Object.setPrototypeOf(spoofedArrayPrototype, Object.prototype)
+    const SpoofedArray = function Array() {}
+    SpoofedArray.prototype = spoofedArrayPrototype
+    Object.defineProperty(spoofedArrayPrototype, 'constructor', { value: SpoofedArray })
+    const spoofedArray = [1]
+    Object.setPrototypeOf(spoofedArray, spoofedArrayPrototype)
+
+    for (const value of [
+      new ExoticObject(),
+      new Map([['value', 1]]),
+      new ExoticArray(1),
+      new Array(1),
+      decorated,
+      compensatedSparse,
+      symbolDecorated,
+      hiddenObject,
+      symbolObject,
+      customPrototypeObject,
+      forgedArray,
+      spoofedObject,
+      revokedObject,
+      spoofedArray,
+      cyclic,
+      [undefined],
+      { value: undefined },
+    ]) {
+      const canonical = snapshotJsonValue(value)
+      expect(canonical).toBeUndefined()
+      expect(snapshotCodeJsonValue(value)).toEqual(canonical)
+    }
+  })
+
+  it('rejects an array whose getter mutates the validated length', () => {
+    const array = [0, 2]
+    Object.defineProperty(array, 0, {
+      enumerable: true,
+      get: () => {
+        array.length = 1
+        return 1
+      },
+    })
+
+    expect(snapshotCodeJsonValue(array)).toBeUndefined()
+  })
+
+  it('propagates a throwing getter and releases its recursion guard', () => {
+    const failure = new Error('getter failed')
+    const source = Object.defineProperty({}, 'value', {
+      enumerable: true,
+      get: () => { throw failure },
+    })
+
+    expect(() => snapshotCodeJsonValue(source)).toThrow(failure)
+    expect(snapshotCodeJsonValue({ after: true })).toEqual({ after: true })
+  })
+})
+
+describe('flat worker JSON wire', () => {
+  it('round-trips every JSON root while preserving object keys and container order', () => {
+    const withPrototypeKey = Object.create(null) as Record<string, unknown>
+    withPrototypeKey.__proto__ = { safe: true }
+    const values = [null, false, true, 1.25, 'text', [], {}, [1, { nested: [2] }], withPrototypeKey]
+    for (const value of values) {
+      const snapshot = snapshotCodeJsonValue(value)
+      expect(snapshot).not.toBeUndefined()
+      expect(decodeWorkerJson(encodeWorkerJson(snapshot!))).toEqual(snapshot)
+    }
+    const decoded = decodeWorkerJson(encodeWorkerJson(snapshotCodeJsonValue(withPrototypeKey)!)) as Record<string, unknown>
+    expect(Object.hasOwn(decoded, '__proto__')).toBe(true)
+    expect(decoded.__proto__).toEqual({ safe: true })
+  })
+
+  it('round-trips deep values through a bounded-depth token array', () => {
+    let value: unknown = 'leaf'
+    for (let depth = 0; depth < 5_000; depth++) value = [value]
+    const snapshot = snapshotCodeJsonValue(value)!
+    const wire = encodeWorkerJson(snapshot)
+    expect(wire).toHaveLength(5_001)
+
+    let cursor = decodeWorkerJson(wire)
+    for (let depth = 0; depth < 5_000; depth++) {
+      expect(Array.isArray(cursor)).toBe(true)
+      cursor = Array.isArray(cursor) ? cursor[0] : undefined
+    }
+    expect(cursor).toBe('leaf')
+  })
+
+  it('rejects malformed, incomplete, lossy, sparse, decorated, and throwing wire values', () => {
+    const sparse = new Array(1)
+    const compensatedSparse = new Array(1)
+    Object.defineProperty(compensatedSparse, 'extra', { value: true })
+    const decorated: unknown[] = [null]
+    Object.defineProperty(decorated, 'extra', { value: true })
+    const throwing: unknown[] = []
+    Object.defineProperty(throwing, 0, { enumerable: true, get: () => { throw new Error('wire getter') } })
+    const decoratedKeys: unknown[] = ['x']
+    Object.defineProperty(decoratedKeys, 'extra', { value: true })
+    const foreignMarker: Record<string, unknown> = { kind: 'array', length: 0 }
+    Object.setPrototypeOf(foreignMarker, {})
+    const hiddenMarker = Object.defineProperty({ kind: 'array', length: 0 }, 'hidden', { value: true })
+
+    for (const value of [
+      undefined,
+      null,
+      {},
+      [],
+      sparse,
+      compensatedSparse,
+      decorated,
+      throwing,
+      [undefined],
+      [-0],
+      [Number.NaN],
+      [Number.POSITIVE_INFINITY],
+      [1, 2],
+      [[]],
+      [foreignMarker],
+      [hiddenMarker],
+      [{ kind: 'unknown' }],
+      [{ kind: 'array', bogus: 0 }],
+      [{ kind: 'array' }],
+      [{ kind: 'array', length: '1' }],
+      [{ kind: 'array', length: -1 }],
+      [{ kind: 'array', length: Number.MAX_SAFE_INTEGER + 1 }],
+      [{ kind: 'array', length: 1 }],
+      [{ kind: 'array', length: 2 }, { kind: 'array', length: 1 }, null],
+      [{ kind: 'array', length: 0, extra: true }],
+      [{ kind: 'object' }],
+      [{ kind: 'object', keys: 'x' }],
+      [{ kind: 'object', keys: decoratedKeys }],
+      [{ kind: 'object', keys: [1] }],
+      [{ kind: 'object', keys: ['x', 'x'] }, 1, 2],
+      [{ kind: 'object', keys: ['x'] }],
+      [{ kind: 'object', keys: [], extra: true }],
+    ]) {
+      expect(decodeWorkerJson(value)).toBeUndefined()
+    }
+  })
+
+  it('rejects invalid values passed through a forged static type', () => {
+    expect(() => encodeWorkerJson([undefined] as never)).toThrow(/sparse JSON array/)
+    expect(() => encodeWorkerJson({ value: undefined } as never)).toThrow(/undefined JSON object property/)
+  })
+})
diff --git a/packages/code-runtime/code-runtime-worker/tsconfig.json b/packages/code-runtime/code-runtime-worker/tsconfig.json
index 4a201c70e1..b739c7c3bc 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/README.md b/packages/code-runtime/code-runtime/README.md
index b31af71397..f8e09e301e 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -8,15 +8,15 @@ This package is the interface third of the capability (the bash trio is the temp
 
 | 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, budget expiry, abort, 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 the completion value becomes `result.value` when it survives the serialization boundary. |
+| `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`. |
 | `language` | Readonly descriptor: the source language `run` expects (`'typescript'` is the well-known value). 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**. |
 
-Semantics every implementation must honor (contract details in the class JSDoc): binding calls bridge to the caller's functions verbatim with structured-cloneable arguments/resolutions; the program is treated as a hostile peer (arbitrary binding names are own properties, malformed traffic never crashes the host); no state survives between runs; disposal terminates in-flight runs AND awaits their exit before completing.
+Semantics every implementation must honor (contract details in the class JSDoc): binding calls bridge complete lossless-JSON arguments and resolutions with no seam-level byte cap; the program is treated as a hostile peer (arbitrary binding names are own properties, malformed traffic never crashes the host); no state survives between runs; disposal terminates in-flight runs AND awaits their exit before completing.
 
 ## Vocabulary
 
-`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions`), each exposed to the program as one global object of async callables. `CodeRunResult` reports the completion `value?`, ordered capped `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 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.
 
 ## Model Experience
 
@@ -31,3 +31,4 @@ 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.
diff --git a/packages/code-runtime/code-runtime/src/index.ts b/packages/code-runtime/code-runtime/src/index.ts
index bd8efe1377..bd52b9ed29 100644
--- a/packages/code-runtime/code-runtime/src/index.ts
+++ b/packages/code-runtime/code-runtime/src/index.ts
@@ -8,8 +8,10 @@ import { Context, Service } from 'cordis'
 import type { CodeRunRequest, CodeRunResult } from './types.ts'
 
 export type {
+  CodeBindingErrorClass,
   CodeBindingFunction,
   CodeBindingNamespace,
+  CodeJsonValue,
   CodeRunFailure,
   CodeRunRequest,
   CodeRunResult,
@@ -24,8 +26,9 @@ declare module 'cordis' {
 /**
  * Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate
  * failures resolve in {@link CodeRunResult}; only seam misuse rejects. Implementations bridge
- * structured-cloneable bindings while treating programs as hostile peers, isolate runs from
- * one another, and terminate and await in-flight runs during disposal.
+ * 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.
  */
 export abstract class CodeRuntime extends Service {
   /**
diff --git a/packages/code-runtime/code-runtime/src/types.ts b/packages/code-runtime/code-runtime/src/types.ts
index d7669a4785..a53353799b 100644
--- a/packages/code-runtime/code-runtime/src/types.ts
+++ b/packages/code-runtime/code-runtime/src/types.ts
@@ -9,12 +9,30 @@
 /**
  * One host-side function exposed to the program as an async callable. The
  * runtime bridges calls to it (possibly across a serialization boundary), so
- * `args` and the resolution value MUST be structured-cloneable; a runtime
- * rejects a non-cloneable value with a descriptive error rather than
- * corrupting the run. A rejection of this function surfaces inside the
- * program as a rejection of the corresponding call.
+ * `args` and the resolution value MUST be lossless JSON. A runtime rejects a
+ * lossy or non-cloneable value with a descriptive error rather than corrupting
+ * the run. No seam-level byte cap applies to a binding resolution. A rejection
+ * of this function surfaces inside the program as a rejection of the
+ * corresponding call.
  */
-export type CodeBindingFunction = (args: unknown) => Promise<unknown>
+export type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>
+
+/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+export type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
+
+/**
+ * Program-visible typed rejection for one binding namespace. The runtime
+ * injects a real error constructor under `name`; rejected member calls become
+ * its instances and expose the exact member name through
+ * `memberNameProperty`. Both strings are runtime data rather than knowledge
+ * of a particular consumer such as Code Mode.
+ */
+export interface CodeBindingErrorClass {
+  /** Constructor global and resulting `Error.name` (must be a usable JS identifier). */
+  name: string
+  /** Non-empty own property for the member name; cannot replace `name`, `message`, or `stack`. */
+  memberNameProperty: string
+}
 
 /**
  * A named group of {@link CodeBindingFunction}s the runtime exposes to the
@@ -28,6 +46,8 @@ export interface CodeBindingNamespace {
   global: string
   /** The callable members, keyed by the exact name the program calls. */
   functions: Record<string, CodeBindingFunction>
+  /** Optional program-visible typed rejection contract for this namespace. */
+  errorClass?: CodeBindingErrorClass
 }
 
 /**
@@ -63,10 +83,12 @@ export interface CodeRunRequest {
  * - `'timeout'` — an implementation-owned budget expired; the message says which.
  * - `'abort'` — {@link CodeRunRequest.signal} fired.
  * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
+ * - `'invalid-output'` — the completion value was not lossless JSON.
+ * - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
  */
 export interface CodeRunFailure {
   /** The failure class (see the interface doc for each kind's meaning). */
-  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit'
+  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
   /** Human-readable detail, suitable for feeding back to a model to self-correct. */
   message: string
 }
@@ -79,12 +101,12 @@ export interface CodeRunFailure {
 export interface CodeRunResult {
   /**
    * The program's completion value (its top-level `return`), when it ran to
-   * completion and the value survived the runtime's serialization boundary;
-   * a non-transferable value is replaced by a string rendering, and a failed
-   * or value-less run leaves this absent.
+   * completion and the value crossed the runtime's lossless-JSON boundary.
+   * Invalid or over-limit completions fail the run instead of substituting a
+   * rendered string; a failed or value-less run leaves this absent.
    */
-  value?: unknown
-  /** Text the program emitted, in order (capped by the implementation). */
+  value?: CodeJsonValue
+  /** Text the program emitted, in order, bounded only as part of the outer result. */
   logs: string[]
   /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
   error?: CodeRunFailure
diff --git a/packages/code-runtime/code-runtime/tests/service.spec.ts b/packages/code-runtime/code-runtime/tests/service.spec.ts
index 56a32930c9..605b51934f 100644
--- a/packages/code-runtime/code-runtime/tests/service.spec.ts
+++ b/packages/code-runtime/code-runtime/tests/service.spec.ts
@@ -45,7 +45,7 @@ describe('CodeRuntime service seam', () => {
     const calls: unknown[] = []
     const result = await runtime.run({
       program: 'return 1',
-      bindings: [{ global: 'tools', functions: { probe: async args => void calls.push(args) } }],
+      bindings: [{ global: 'tools', functions: { probe: async (args) => { calls.push(args); return null } } }],
     })
     expect(result).toEqual({ logs: [] })
     expect(calls).toEqual([{ from: 'stub' }])
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index 3ea658b64d..1db86d38e4 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -563,7 +563,10 @@ describe('pressure measurement and retention', () => {
     const result = await compactIfNeeded(compact, session)
     expect(result).not.toBeNull()
     expect(prefix).toHaveLength(1)
-    expect(session.events.some(event => event.type === 'context/message')).toBe(false)
+    // The routed request prefix must not reach the surface as its own message
+    // (the compaction summary itself is an expected plugin-sourced checkpoint).
+    expect(session.events.some(event => event.type === 'user/message'
+      && event.data.content.some(block => block.type === 'text' && block.text.includes('p'.repeat(600))))).toBe(false)
   })
 
   it('uses the latest logged request envelope without an AgentOptions override', async () => {
@@ -959,7 +962,7 @@ describe('compaction region transaction', () => {
     const compact = service()
     const session = conversation(2)
     compact.mutateDuringSummary = () => {
-      session.append('context/message', {
+      session.append('user/message', {
         content: [{ type: 'text', text: 'concurrent surface mutation' }],
         source: { kind: 'plugin', plugin: 'test' },
       }, { surfaceOp: 'append' })
diff --git a/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts b/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts
index 4b3dd7a6b3..83c18f78b4 100644
--- a/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts
@@ -4,7 +4,7 @@ import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-a
 import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -134,7 +134,7 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
   await ctx.plugin(AgentLoop, { agents: [] })
   await ctx.plugin(TokenMeterService)
   ctx.llm.registerAdapter(['mock'], new StepwiseToolAdapter(toolSteps))
-  ctx.tools.register(defineTool({
+  ctx.tools.register(defineContentToolFixture({
     name: 'work',
     description: 'does work',
     parameters: { i: { type: 'number' } },
@@ -197,7 +197,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
         provider: 'unconfigured-agent-fallback',
         model: 'unconfigured-agent-fallback',
       })
-      agent.send([{ type: 'text', text: 'do a routed multi-step task' }])
+      agent.followup([{ type: 'text', text: 'do a routed multi-step task' }])
       await waitForIdle(ctx, agent)
 
       expect(agent.session.requestHeader()?.config.model).toBe('mock')
@@ -215,7 +215,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
     const { ctx } = await harness(8)
     try {
       const agent = ctx.agentLoop.create(SessionId('post-step-order'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'do tool work' }])
+      agent.followup([{ type: 'text', text: 'do tool work' }])
       await waitForIdle(ctx, agent)
 
       const events = [...agent.session.events]
@@ -241,7 +241,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
     const { ctx } = await harness(8)
     try {
       const agent = ctx.agentLoop.create(SessionId('repro'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'do a long multi-step task' }])
+      agent.followup([{ type: 'text', text: 'do a long multi-step task' }])
       await waitForIdle(ctx, agent)
 
       const events = [...agent.session.events]
@@ -297,7 +297,7 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
         })
         seedOverflowHistory(agent)
 
-        agent.send([{ type: 'text', text: 'continue from history' }])
+        agent.followup([{ type: 'text', text: 'continue from history' }])
         await agent.whenIdle()
 
         expect(adapter.conversationRequests).toHaveLength(2)
@@ -360,7 +360,7 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
     try {
       const agent = ctx.agentLoop.create(SessionId('alternating-recovery'), { provider: 'mock', model: 'mock' })
       seedOverflowHistory(agent)
-      agent.send([{ type: 'text', text: 'continue from history' }])
+      agent.followup([{ type: 'text', text: 'continue from history' }])
       await agent.whenIdle()
 
       expect(adapter.conversationRequests).toHaveLength(3)
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index 03b91d653e..ff47ef3b19 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -33,7 +33,7 @@ The private per-session cache is keyed by `session.surface.replaceGeneration` an
 
 ## Surface contract
 
-`SurfaceEventType` is a closed union — only `user/message`, `assistant/message`, `tool/result`, `context/message`, and `steering/message` may carry `surfaceOp`. A `compact/*` event therefore **cannot** appear on the surface. A successful compaction instead:
+`SurfaceEventType` is a closed union — only `user/message`, `assistant/message`, `tool/result`, and `steering/message` may carry `surfaceOp`. A `compact/*` event therefore **cannot** appear on the surface. A successful compaction instead:
 
 1. appends `compact/start` (log-only) — acquires the lock,
 2. summarizes the range,
diff --git a/packages/compact/compact/tests/tool-pairing.spec.ts b/packages/compact/compact/tests/tool-pairing.spec.ts
index 5f48e7f99f..3de0473d57 100644
--- a/packages/compact/compact/tests/tool-pairing.spec.ts
+++ b/packages/compact/compact/tests/tool-pairing.spec.ts
@@ -96,23 +96,23 @@ describe('tool-pairing boundaries', () => {
       content: [{ type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }],
       provenance: { provider: 'mock', model: 'mock' },
     }, SURFACE)
-    midStep.append('context/message', {
+    midStep.append('user/message', {
       content: [{ type: 'text', text: 'background update' }],
       source: { kind: 'plugin', plugin: 'test' },
     }, SURFACE)
     midStep.append('tool/result', {
       turn: 1, step: 1, callId: CallId('c1'), content: [], isError: false,
     }, SURFACE)
-    expect(before(midStep, 'context/message')).toBe(false)
-    expect(after(midStep, 'context/message')).toBe(false)
+    expect(before(midStep, 'user/message')).toBe(false)
+    expect(after(midStep, 'user/message')).toBe(false)
 
     const free = new Session(SessionId('neutral-free'))
-    free.append('context/message', {
+    free.append('user/message', {
       content: [{ type: 'text', text: 'idle injection' }],
       source: { kind: 'user' },
     }, SURFACE)
-    expect(before(free, 'context/message')).toBe(true)
-    expect(after(free, 'context/message')).toBe(true)
+    expect(before(free, 'user/message')).toBe(true)
+    expect(after(free, 'user/message')).toBe(true)
   })
 })
 
diff --git a/packages/context/session-reference/README.md b/packages/context/session-reference/README.md
index b3a4b2013d..4fca9a9977 100644
--- a/packages/context/session-reference/README.md
+++ b/packages/context/session-reference/README.md
@@ -5,7 +5,7 @@
 ## Public API
 
 - `listCandidates(agent, query?, limit?)` lists sessions other than `agent.id`, filters case-insensitively by id or cwd, and ranks same-cwd, cwd-less, then other-cwd records while preserving `listSessions()` creation order within each group. Each selected candidate uses its latest log-backed title as the mention label and falls back to the session id; titles and message bodies are not searched.
-- `prepare(agent, content, references, signal?)` preserves first-mention order, deduplicates ids, rejects self-reference and more than the configured distinct-source limit, reads every source in parallel, and returns detached content plus zero or one aggregated `HookContext`. Any invalid reference, failed read, cancellation, or budget failure rejects before the host calls `send()` or `steer()`.
+- `prepare(agent, content, references, signal?)` preserves first-mention order, deduplicates ids, rejects self-reference and more than the configured distinct-source limit, reads every source in parallel, and returns detached content plus zero or one aggregated `HookContext`. Any invalid reference, failed read, cancellation, or budget failure rejects before the host calls `followup()` or `steer()`.
 - `encodeSessionReferenceUri()` and `decodeSessionReferenceUri()` implement `dsh-session:<base64url(JSON.stringify(sessionId))>` so every JavaScript string id round-trips exactly. `formatSessionReferenceMention()` emits `@[label](uri)`, and `parseSessionReferenceText()` replaces Markdown mentions or bare canonical URIs with readable `@label` text while returning structured references. Explicit Markdown mentions reject every malformed URI; bare text is considered a reference only when a non-empty base64url-shaped payload follows the scheme, and a matching noncanonical candidate still fails. Empty or punctuation-only scheme mentions remain ordinary discussion text.
 
 ## Snapshot semantics
diff --git a/packages/context/session-reference/src/projection.ts b/packages/context/session-reference/src/projection.ts
index bbb2a2c739..dea29b38ee 100644
--- a/packages/context/session-reference/src/projection.ts
+++ b/packages/context/session-reference/src/projection.ts
@@ -57,7 +57,6 @@ function projectSessionConversation(snapshot: SessionSurfaceSnapshot): Projected
         break
       }
       case 'tool/result':
-      case 'context/message':
         break
       /* v8 ignore next 2 -- SurfaceEventType is closed and every variant is handled above. */
       default:
diff --git a/packages/context/session-reference/tests/session-reference.spec.ts b/packages/context/session-reference/tests/session-reference.spec.ts
index bb21cfab05..937535b042 100644
--- a/packages/context/session-reference/tests/session-reference.spec.ts
+++ b/packages/context/session-reference/tests/session-reference.spec.ts
@@ -15,10 +15,24 @@ import SessionReferenceService, {
 } from '@deepseek-ai/dsh-session-reference'
 import { stringifyTagSafeJson } from '../src/serialization.ts'
 
+class TestSessionQueryService extends SessionQueryService {
+  override searchSessions(
+    ..._args: Parameters<SessionQueryService['searchSessions']>
+  ): ReturnType<SessionQueryService['searchSessions']> {
+    return Promise.resolve({ items: [] })
+  }
+
+  override searchEvents(
+    ..._args: Parameters<SessionQueryService['searchEvents']>
+  ): ReturnType<SessionQueryService['searchEvents']> {
+    return Promise.resolve({ items: [] })
+  }
+}
+
 async function harness(config: Config = {}): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SessionQueryService)
+  await ctx.plugin(TestSessionQueryService)
   await ctx.plugin(SessionReferenceService, config)
   return ctx
 }
@@ -61,7 +75,7 @@ function appendConversation(session: Session): void {
     { surfaceOp: 'append' },
   )
   session.append(
-    'context/message',
+    'user/message',
     { content: [{ type: 'text', text: 'workspace secret' }], source: { kind: 'plugin', plugin: 'workspace' } },
     { surfaceOp: 'append' },
   )
@@ -524,19 +538,19 @@ describe('session reference discovery and preparation', () => {
   it('rejects direct invalid configuration before service publication', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
-    await ctx.plugin(SessionQueryService)
+    await ctx.plugin(TestSessionQueryService)
     expect(() => new SessionReferenceService(ctx, { maxReferences: 0 }))
       .toThrow(expectCode('SESSION_REFERENCE_INVALID_CONFIG'))
 
     const oversizedCtx = new Context()
     await oversizedCtx.plugin(SessionStore)
-    await oversizedCtx.plugin(SessionQueryService)
+    await oversizedCtx.plugin(TestSessionQueryService)
     expect(() => new SessionReferenceService(oversizedCtx, { maxReferences: 4 }))
       .toThrow(expectCode('SESSION_REFERENCE_INVALID_CONFIG'))
 
     const defaultCtx = new Context()
     await defaultCtx.plugin(SessionStore)
-    await defaultCtx.plugin(SessionQueryService)
+    await defaultCtx.plugin(TestSessionQueryService)
     expect(() => new SessionReferenceService(defaultCtx)).not.toThrow()
   })
 })
diff --git a/packages/context/time-context/README.md b/packages/context/time-context/README.md
index 2327da81b2..f4938982a1 100644
--- a/packages/context/time-context/README.md
+++ b/packages/context/time-context/README.md
@@ -18,9 +18,9 @@ When `timeZone` is omitted, the plugin resolves the Node process's system zone o
 
 ## Timing semantics
 
-The plugin prepends an `agent/pre-step` listener. When an injection is due, it appends one `context/message` through `agent.inject()` before `step/start` and ordinary automatic compaction, with source `{ kind: 'plugin', plugin: 'time-context' }`. A suppressed attempt appends nothing.
+The plugin prepends an `agent/pre-step` listener. When an injection is due, it appends one injected `user/message` through `agent.inject()` before `step/start` and ordinary automatic compaction, with source `{ kind: 'plugin', plugin: 'time-context' }`. A suppressed attempt appends nothing.
 
-Positive-interval scheduling scans the raw durable session events for the latest `context/message` with that source, including a reading shadowed by compaction. The schedule therefore applies across turns and resumed processes without process-local cache state. It reduces append frequency and history growth but never removes an existing reading, and sessions schedule independently.
+Positive-interval scheduling scans the raw durable session events for the latest `user/message` with that source, including a reading shadowed by compaction. The schedule therefore applies across turns and resumed processes without process-local cache state. It reduces append frequency and history growth but never removes an existing reading, and sessions schedule independently.
 
 Step 1 measures from the latest preceding model-visible message, including the prompt that opened the turn. Later steps measure from the preceding time-context event in the same turn. Both baselines use durable session-event timestamps; backward wall-clock movement clamps elapsed time to zero. A missing first-step baseline, or a later step with no earlier same-turn reading because interval suppression skipped it, reports `unavailable`.
 
diff --git a/packages/context/time-context/src/index.ts b/packages/context/time-context/src/index.ts
index 96ea7165af..fcf9e36efc 100644
--- a/packages/context/time-context/src/index.ts
+++ b/packages/context/time-context/src/index.ts
@@ -64,7 +64,6 @@ function precedingMessageTime(agent: Agent): number | undefined {
       case 'user/message':
       case 'assistant/message':
       case 'tool/result':
-      case 'context/message':
       case 'steering/message':
         return event.time
       default:
@@ -79,7 +78,7 @@ function precedingMessageTime(agent: Agent): number | undefined {
 function precedingStepContextTime(agent: Agent, turn: number): number | undefined {
   for (const event of [...agent.session.events].reverse()) {
     if (event.type === 'turn/start' && event.data.turn === turn) return undefined
-    if (event.type === 'context/message'
+    if (event.type === 'user/message'
       && event.data.source.kind === 'plugin'
       && event.data.source.plugin === name) {
       return event.time
@@ -91,7 +90,7 @@ function precedingStepContextTime(agent: Agent, turn: number): number | undefine
 /** Find this plugin's latest durable injection, including a shadowed surface event. */
 function latestInjectionTime(agent: Agent): number | undefined {
   for (const event of [...agent.session.events].reverse()) {
-    if (event.type === 'context/message'
+    if (event.type === 'user/message'
       && event.data.source.kind === 'plugin'
       && event.data.source.plugin === name) {
       return event.time
diff --git a/packages/context/time-context/src/invariant.ts b/packages/context/time-context/src/invariant.ts
index 45fdb48cba..aa8f0418dd 100644
--- a/packages/context/time-context/src/invariant.ts
+++ b/packages/context/time-context/src/invariant.ts
@@ -48,7 +48,7 @@ function preparationPosition(history: readonly SessionEvent[], fail: InvariantFa
 /** Validate one plugin-attributed time reading against its session position and timestamp. */
 function validateReading(
   history: readonly SessionEvent[],
-  event: SessionEvent<'context/message'>,
+  event: SessionEvent<'user/message'>,
   fail: InvariantFailure,
 ): void {
   const [block] = event.data.content
@@ -84,7 +84,7 @@ function validateReading(
 /** Validate all package-owned readings already present in one session. */
 function validateSession(session: Session, fail: InvariantFailure): void {
   for (const [index, event] of session.events.entries()) {
-    if (event.type !== 'context/message'
+    if (event.type !== 'user/message'
       || event.data.source.kind !== 'plugin'
       || event.data.source.plugin !== SOURCE_NAME) continue
     validateReading(session.events.slice(0, index), event, fail)
@@ -97,7 +97,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
   ctx.on('internal/dispatch', (_mode, eventName, args) => {
     if (eventName !== 'session/event') return
     const [session, event] = args as [Session, SessionEvent]
-    if (event.type !== 'context/message'
+    if (event.type !== 'user/message'
       || event.data.source.kind !== 'plugin'
       || event.data.source.plugin !== SOURCE_NAME) return
     validateReading(session.events, event, fail)
diff --git a/packages/context/time-context/tests/invariant.spec.ts b/packages/context/time-context/tests/invariant.spec.ts
index cd65f1aa3d..855303b295 100644
--- a/packages/context/time-context/tests/invariant.spec.ts
+++ b/packages/context/time-context/tests/invariant.spec.ts
@@ -17,7 +17,7 @@ async function setup(): Promise<Context> {
 
 function event(text: string, time = SECOND + 456, content?: unknown[]): SessionEvent {
   return {
-    type: 'context/message',
+    type: 'user/message',
     seq: 0,
     time,
     data: {
@@ -56,7 +56,7 @@ function preparing(turn: number, step: number): Session {
 }
 
 function appendReading(session: Session, text: string): void {
-  session.append('context/message', {
+  session.append('user/message', {
     content: [{ type: 'text', text }],
     source: { kind: 'plugin', plugin: 'time-context' },
   }, { surfaceOp: 'append' })
@@ -162,7 +162,7 @@ describe('time-context invariants', () => {
 
   it('ignores context messages owned by another package', async () => {
     const ctx = await setup()
-    const other = event('unrelated') as SessionEvent<'context/message'>
+    const other = event('unrelated') as SessionEvent<'user/message'>
     other.data.source = { kind: 'plugin', plugin: 'other' }
     expect(() => { ctx.emit('session/event', preparing(1, 1), other) }).not.toThrow()
     other.data.source = { kind: 'user' }
diff --git a/packages/context/time-context/tests/time-context.e2e.ts b/packages/context/time-context/tests/time-context.e2e.ts
index 2a0c06fe51..02704d3eba 100644
--- a/packages/context/time-context/tests/time-context.e2e.ts
+++ b/packages/context/time-context/tests/time-context.e2e.ts
@@ -48,7 +48,8 @@ describe('time-context through a real headless cordis.yml', () => {
     expect(stderr).not.toContain('UNHANDLED')
     expect(events.filter(event => event.type === 'turn/end')).toHaveLength(2)
 
-    const contexts = events.filter(event => event.type === 'context/message')
+    const contexts = events.filter(
+      (event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind === 'plugin')
     const starts = events.filter(event => event.type === 'step/start')
     expect(contexts).toHaveLength(2)
     expect(starts).toHaveLength(2)
diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts
index d1cd07207e..424363d4b1 100644
--- a/packages/context/time-context/tests/time-context.spec.ts
+++ b/packages/context/time-context/tests/time-context.spec.ts
@@ -3,9 +3,9 @@ import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { agentEvents, AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as timeContext from '@deepseek-ai/dsh-time-context'
@@ -42,14 +42,17 @@ function sessionAgent(session: Session, id = 'agent'): Agent {
     session,
     status: 'running',
     ctx: new Context(),
-    send() {},
-    steer() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
     inject(content, options) {
-      session.append('context/message', {
+      session.append('user/message', {
         content,
         source: options?.source ?? { kind: 'user' },
       }, { surfaceOp: 'append' })
+      return AgentMessageId('stub')
     },
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle: () => Promise.resolve(),
   }
@@ -66,7 +69,7 @@ function openMessageTurn(session: Session, turn: number): void {
 function contextTexts(session: Session): string[] {
   const texts: string[] = []
   for (const event of session.events) {
-    if (event.type === 'context/message'
+    if (event.type === 'user/message'
       && event.data.source.kind === 'plugin'
       && event.data.source.plugin === 'time-context') {
       texts.push(event.data.content.find(block => block.type === 'text')?.text ?? '')
@@ -151,8 +154,8 @@ describe('durable step context', () => {
       + 'Elapsed since the preceding model-visible message: 1d 1h 1m 1s.',
     ])
     const event = session.events.at(-1)
-    expect(event?.type).toBe('context/message')
-    if (event?.type !== 'context/message') throw new Error('missing time context')
+    expect(event?.type).toBe('user/message')
+    if (event?.type !== 'user/message') throw new Error('missing time context')
     expect(event.data.source).toEqual({ kind: 'plugin', plugin: 'time-context' })
     expect(event.surfaceOp).toBe('append')
   })
@@ -230,10 +233,10 @@ describe('durable step context', () => {
     const original = new Session(SessionId('seed-source'))
     openMessageTurn(original, 1)
     await fire(ctx, sessionAgent(original), 1, 1)
-    const user = original.events.find(event => event.type === 'user/message')
-    const reading = original.events.find(event => event.type === 'context/message')
+    const user = original.events.find(event => event.type === 'user/message' && event.data.source.kind === 'user')
+    const reading = original.events.find(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
     if (user === undefined || reading === undefined) throw new Error('missing source surface events')
-    original.append('context/message', {
+    original.append('user/message', {
       content: [{ type: 'text', text: 'compacted history' }],
       source: { kind: 'plugin', plugin: 'compact-basic' },
     }, {
@@ -292,7 +295,7 @@ describe('durable step context', () => {
     openMessageTurn(session, 1)
     let ordinarySawContext = false
     ctx.on('agent/pre-step', (subject) => {
-      ordinarySawContext = subject.session.events.some(event => event.type === 'context/message')
+      ordinarySawContext = subject.session.events.some(event => event.type === 'user/message')
     })
 
     await fire(ctx, agent, 1, 1)
@@ -371,7 +374,7 @@ describe('real agent-loop request history', () => {
     })
     const agent = ctx.agentLoop.create(SessionId(`late-${mode}`), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'start' }])
+    agent.followup([{ type: 'text', text: 'start' }])
     await agent.whenIdle()
 
     expect(laterSawReading).toBe(true)
@@ -386,7 +389,7 @@ describe('real agent-loop request history', () => {
   it('persists one ordered context per request, accumulates readings, and leaves system headers unchanged', async () => {
     const adapter = new ScriptedAdapter([toolCallResponse(), textResponse('done')])
     const ctx = await loopHarness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'tick',
       description: 'advance fake time',
       parameters: {},
@@ -397,11 +400,12 @@ describe('real agent-loop request history', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('loop'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'start' }])
+    agent.followup([{ type: 'text', text: 'start' }])
     await agent.whenIdle()
 
     expect(adapter.requests).toHaveLength(2)
-    const contexts = agent.session.events.filter(event => event.type === 'context/message')
+    const contexts = agent.session.events.filter(
+      (event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind === 'plugin')
     const starts = agent.session.events.filter(event => event.type === 'step/start')
     expect(contexts).toHaveLength(adapter.requests.length)
     expect(starts).toHaveLength(adapter.requests.length)
diff --git a/packages/context/workspace-context/README.md b/packages/context/workspace-context/README.md
index a7245df91f..67ab9b4245 100644
--- a/packages/context/workspace-context/README.md
+++ b/packages/context/workspace-context/README.md
@@ -28,7 +28,7 @@ Instructions from: AGENTS.md
 </system-reminder>
 ```
 
-Newly reached scopes use a durable raw `context/message`:
+Newly reached scopes use a durable injected `user/message` (plugin source):
 
 ```md
 <system-reminder>
@@ -42,11 +42,11 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 
 A same-file edit starts with `Updated instructions from: <path>` and says to use the new content instead of the previously loaded content. When a candidate disappears or becomes a per-directory duplicate of an earlier candidate, the message is `Instructions removed: <path>` followed by `The previously loaded instructions from this file no longer apply.` Literal `</system-reminder>` text inside an instruction file is escaped so file content cannot close the plugin-owned frame.
 
-The plugin owns the complete `<system-reminder>` framing, and every `context/message` (from this plugin or any other) reaches the model verbatim as a user-role message with no wrapping.
+The plugin owns the complete `<system-reminder>` framing, and every injected `user/message` (from this plugin or any other) reaches the model verbatim as a user-role message with no wrapping.
 
 ## State And Refresh
 
-Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, digest? }` changes. 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. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the 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 dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, digest? }` changes. 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. A matching durable `user/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the 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.
 
 An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata 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 session log, 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 metadata, pending state, and the version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates metadata only.
 
@@ -111,7 +111,7 @@ Prefix-stable within one loop instance because the baseline is frozen. A new or
 
 #### What the model sees
 
-After a successful first-party filesystem call reaches a deeper directory, the next request includes one retained raw `context/message` with the newly applicable instruction file.
+After a successful first-party filesystem call reaches a deeper directory, the next request includes one retained injected `user/message` with the newly applicable instruction file.
 
 ##### Additional instruction template
 
diff --git a/packages/context/workspace-context/src/index.ts b/packages/context/workspace-context/src/index.ts
index d06c8c542f..5bd858a8a0 100644
--- a/packages/context/workspace-context/src/index.ts
+++ b/packages/context/workspace-context/src/index.ts
@@ -129,8 +129,7 @@ export function apply(ctx: Context, config: Config): void {
     if (update === undefined) return downstream
     pendingVersionUpdates.set(exec.token, update.versionUpdates)
     return {
-      kind: 'accept',
-      ...downstream.content !== undefined ? { content: downstream.content } : {},
+      ...downstream,
       additionalContexts: [update.context, ...downstream.additionalContexts ?? []],
     }
   })
diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts
index 66b70f639d..61db3f527b 100644
--- a/packages/context/workspace-context/src/state.ts
+++ b/packages/context/workspace-context/src/state.ts
@@ -145,7 +145,7 @@ function visibleInstructionChanges(
   const visibleSeqs = new Set(agent.session.surface.nodes)
   const visible = new Map<string, WorkspaceInstructionChange>()
   for (const [seq, event] of agent.session.events.entries()) {
-    if (event.type !== 'context/message' || !isWorkspaceContextSource(event.data.source)) continue
+    if (event.type !== 'user/message' || !isWorkspaceContextSource(event.data.source)) continue
     const changes = workspaceInstructionChanges(event.data.meta)
     for (const change of changes) {
       const waiting = pending.get(change.scope)
@@ -281,7 +281,7 @@ export function observeInstructionSessionEvent(
   if (pending === undefined) return
 
   switch (event.type) {
-    case 'context/message': {
+    case 'user/message': {
       if (!isWorkspaceContextSource(event.data.source)) return
       for (const change of workspaceInstructionChanges(event.data.meta)) {
         const waiting = pending.get(change.scope)
diff --git a/packages/context/workspace-context/tests/workspace-context.e2e.ts b/packages/context/workspace-context/tests/workspace-context.e2e.ts
index 9341eb33d0..fbeacb5496 100644
--- a/packages/context/workspace-context/tests/workspace-context.e2e.ts
+++ b/packages/context/workspace-context/tests/workspace-context.e2e.ts
@@ -78,7 +78,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workspace context e2e: real mode
   it('obeys a probe instruction loaded from the workspace', async () => {
     const live = await harness()
 
-    live.agent.send([{ type: 'text', text: 'Workspace context handshake?' }])
+    live.agent.followup([{ type: 'text', text: 'Workspace context handshake?' }])
     await waitForIdle(live.ctx, live.agent)
 
     expect(finalText([...live.agent.session.events])).toContain(PROBE)
@@ -90,7 +90,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workspace context e2e: real mode
     await writeFile(join(workdir!, 'pkg/AGENTS.md'), `If the user asks for the nested instruction handshake, reply with exactly this string and nothing else: ${NESTED_PROBE}.\n`)
     await writeFile(join(workdir!, 'pkg/deep/file.txt'), 'This file exists only to trigger nested workspace instructions.\n')
 
-    live.agent.send([{ type: 'text', text: 'Use the read tool to inspect pkg/deep/file.txt. After reading it, answer: nested instruction handshake?' }])
+    live.agent.followup([{ type: 'text', text: 'Use the read tool to inspect pkg/deep/file.txt. After reading it, answer: nested instruction handshake?' }])
     await waitForIdle(live.ctx, live.agent)
 
     expect(finalText([...live.agent.session.events])).toContain(NESTED_PROBE)
@@ -99,23 +99,23 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workspace context e2e: real mode
   it('appends changed baseline instructions after a real file-tool touch without rewriting the frozen prefix', async () => {
     const live = await harness()
     await writeFile(join(workdir!, 'trigger.txt'), 'This file triggers workspace instruction reconciliation.\n')
-    live.agent.send([{ type: 'text', text: 'Workspace context handshake?' }])
+    live.agent.followup([{ type: 'text', text: 'Workspace context handshake?' }])
     await waitForIdle(live.ctx, live.agent)
     await writeFile(join(workdir!, 'AGENTS.md'), `The old workspace handshake no longer applies. If the user asks for the updated workspace context handshake, reply with exactly this string and nothing else: ${UPDATED_PROBE}.\n`)
 
-    live.agent.send([{ type: 'text', text: 'You must use the read tool to inspect trigger.txt. After reading it, answer: updated workspace context handshake?' }])
+    live.agent.followup([{ type: 'text', text: 'You must use the read tool to inspect trigger.txt. After reading it, answer: updated workspace context handshake?' }])
     await waitForIdle(live.ctx, live.agent)
 
     const events = [...live.agent.session.events]
-    const update = events.find(event => event.type === 'context/message'
+    const update = events.find(event => event.type === 'user/message'
       && typeof event.data.meta === 'object'
       && event.data.meta !== null
       && !Array.isArray(event.data.meta)
       && event.data.meta.kind === 'workspace-instructions')
-    expect(update?.type === 'context/message' && update.data.meta).toMatchObject({
+    expect(update?.type === 'user/message' && update.data.meta).toMatchObject({
       changes: [{ action: 'replace', scope: candidateScopeKey('.', 'AGENTS.md'), path: 'AGENTS.md' }],
     })
-    const updateText = update?.type === 'context/message'
+    const updateText = update?.type === 'user/message'
       ? update.data.content.filter(block => block.type === 'text').map(block => block.text).join('')
       : ''
     expect(updateText).toContain('Updated instructions from: AGENTS.md')
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index c26be1a58e..c8c33f3a4b 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -7,7 +7,7 @@ import Loader from '@cordisjs/plugin-loader'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import LlmService, { CallId, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId, SESSION_FORMAT_VERSION, type SessionEvent } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { type Agent, type HookContext } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentMessageId, type Agent, type HookContext } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { FileSystem, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -22,8 +22,11 @@ import type {
 } from '@deepseek-ai/dsh-fs'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ToolExecution, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import type {
+  ToolExecution,
+  ToolExecutionToken,
+} from '@deepseek-ai/dsh-tools'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import {
   discoverBaselineInstructionFiles,
@@ -174,15 +177,18 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent {
     options: {},
     session,
     status: 'idle',
-    send() {},
-    steer() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
     inject(content, options) {
-      session.append('context/message', {
+      session.append('user/message', {
         content,
         source: options?.source ?? { kind: 'user' },
         ...options?.meta !== undefined ? { meta: options.meta } : {},
       }, { surfaceOp: 'append' })
+      return AgentMessageId('stub')
     },
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle: () => Promise.resolve(),
   }
@@ -219,7 +225,7 @@ function workspaceChangeContext(scope: string, digest: string): HookContext {
 function appendAdditionalContexts(agent: Agent, result: { additionalContexts?: HookContext[] }): number | undefined {
   let lastSeq: number | undefined
   for (const context of result.additionalContexts ?? []) {
-    lastSeq = agent.session.append('context/message', {
+    lastSeq = agent.session.append('user/message', {
       content: context.content,
       source: context.source,
       ...context.meta !== undefined ? { meta: context.meta } : {},
@@ -864,6 +870,7 @@ describe('workspace context request injection', () => {
         agent: stubAgent('/virtual/repo'),
       }), {
         isError: false,
+        value: null,
         content: [{ type: 'text', text: 'file content' }],
       }, async () => ({
         kind: 'accept',
@@ -900,7 +907,8 @@ describe('workspace context request injection', () => {
         agent,
       })
       const result = {
-        isError: false,
+        isError: false as const,
+        value: null,
         content: [{ type: 'text' as const, text: 'hello' }],
       }
 
@@ -971,7 +979,7 @@ describe('workspace context request injection', () => {
       const second = await composeBaselinePrefix(ctx, agent)
 
       expect(second).toEqual(first)
-      expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(0)
+      expect(agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toHaveLength(0)
       expect(derivedText(agent)).toContain('repo rule')
     } finally {
       await rm(root, { recursive: true, force: true })
@@ -1143,7 +1151,7 @@ describe('workspace context request injection', () => {
 
       await composeBaselinePrefix(ctx, agent)
 
-      expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(0)
+      expect(agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toHaveLength(0)
       expect(derivedText(agent)).not.toContain('workspace-context:')
     } finally {
       await rm(root, { recursive: true, force: true })
@@ -1699,7 +1707,7 @@ describe('dynamic nested workspace context injection', () => {
       await ctx.plugin(AgentLoop, { agents: [] })
       ctx.llm.registerAdapter(['mock'], adapter)
       const agent = ctx.agentLoop.create(SessionId('workspace-context-abort'), { provider: 'mock', model: 'mock' }, { cwd: root })
-      ctx.tools.register(defineTool({
+      ctx.tools.register(defineContentToolFixture({
         name: 'abort_step',
         description: 'Abort the current test step.',
         parameters: {},
@@ -1709,14 +1717,14 @@ describe('dynamic nested workspace context injection', () => {
         },
       }))
 
-      agent.send([{ type: 'text', text: 'read and abort' }])
+      agent.followup([{ type: 'text', text: 'read and abort' }])
       await agent.whenIdle()
-      expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(1)
+      expect(agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toHaveLength(1)
 
-      agent.send([{ type: 'text', text: 'retry the read' }])
+      agent.followup([{ type: 'text', text: 'retry the read' }])
       await agent.whenIdle()
 
-      const contexts = agent.session.events.filter(event => event.type === 'context/message')
+      const contexts = agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
       // The aborted batch drained its accepted context before step close, so the
       // retry sees durable history without producing a duplicate instruction.
       expect(contexts).toHaveLength(1)
@@ -1770,6 +1778,7 @@ describe('dynamic nested workspace context injection', () => {
       const pending = ctx.waterfall('tools/post-execute', exec, {
         content: [{ type: 'text', text: 'ok' }],
         isError: false,
+        value: null,
       }, () => Promise.resolve({ kind: 'accept' as const }))
 
       await expect(pending).rejects.toBe(reason)
@@ -2490,10 +2499,7 @@ describe('dynamic nested workspace context injection', () => {
         agent,
       })
       appendAdditionalContexts(agent, first)
-      const resumed = {
-        ...agent,
-        session: new Session(agent.session.id, [...agent.session.events], agent.session.header),
-      }
+      const resumed = stubAgent(root, [...agent.session.events])
 
       const afterResume = await ctx.tools.execute({
         signal: testToolSignal,
@@ -2531,11 +2537,11 @@ describe('dynamic nested workspace context injection', () => {
 
       await composeBaselinePrefix(ctx, resumed)
 
-      const update = resumed.session.events.findLast(event => event.type === 'context/message')
-      expect(update?.type === 'context/message' && update.data.meta).toMatchObject({
+      const update = resumed.session.events.findLast(event => event.type === 'user/message' && event.data.source.kind !== 'user')
+      expect(update?.type === 'user/message' && update.data.meta).toMatchObject({
         changes: [{ action: 'replace', scope: sk('pkg', 'AGENTS.md'), path: join('pkg', 'AGENTS.md') }],
       })
-      expect(update?.type === 'context/message' && blocksText(update.data.content)).toContain('new nested rule after resume')
+      expect(update?.type === 'user/message' && blocksText(update.data.content)).toContain('new nested rule after resume')
     } finally {
       await rm(root, { recursive: true, force: true })
       await rm(home, { recursive: true, force: true })
@@ -2681,7 +2687,7 @@ describe('dynamic nested workspace context injection', () => {
       const ctx = new Context()
       await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
       const agent = stubAgent(root)
-      agent.session.append('context/message', {
+      agent.session.append('user/message', {
         content: [
           { type: 'reasoning', text: 'Additional instructions from: pkg/AGENTS.md' },
           { type: 'text', text: 'Updated instructions from: pkg/AGENTS.md' },
@@ -2698,12 +2704,12 @@ describe('dynamic nested workspace context injection', () => {
           ],
         },
       }, { surfaceOp: 'append' })
-      agent.session.append('context/message', {
+      agent.session.append('user/message', {
         content: [{ type: 'text', text: 'stale metadata version' }],
         source: { kind: 'plugin', plugin: 'workspace-context' },
         meta: { kind: 'workspace-instructions', version: 0, changes: [] },
       }, { surfaceOp: 'append' })
-      agent.session.append('context/message', {
+      agent.session.append('user/message', {
         content: [{ type: 'text', text: 'foreign plugin context' }],
         source: { kind: 'plugin', plugin: 'other' },
         meta: {
@@ -2777,7 +2783,8 @@ describe('dynamic nested workspace context injection', () => {
       const result = {
         callId: CallId('provider-probe-result'),
         content: [{ type: 'text' as const, text: 'ok' }],
-        isError: false,
+        isError: false as const,
+        value: null,
       }
 
       const failedStat = await ctx.waterfall('tools/post-execute', stubToolExecution({
@@ -2837,7 +2844,7 @@ describe('dynamic nested workspace context injection', () => {
     }
   })
 
-  it('preserves nested and downstream post-execute contexts as separate entries', async () => {
+  it('preserves a downstream canonical value replacement and keeps contexts separate', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
     try {
@@ -2848,7 +2855,12 @@ describe('dynamic nested workspace context injection', () => {
       await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
       ctx.on('tools/post-execute', async () => ({
         kind: 'accept' as const,
-        content: [{ type: 'text' as const, text: 'downstream replacement' }],
+        value: {
+          path: 'pkg/deep/file.txt',
+          offset: 1,
+          lines: [{ number: 1, text: 'downstream replacement' }],
+          totalLines: 1,
+        },
         additionalContexts: [{
           content: [{ type: 'text' as const, text: 'downstream context' }],
           source: { kind: 'plugin' as const, plugin: 'downstream' },
@@ -2863,7 +2875,15 @@ describe('dynamic nested workspace context injection', () => {
         agent: stubAgent(root),
       })
 
-      expect(blocksText(result.content)).toBe('downstream replacement')
+      expect(result.isError).toBe(false)
+      if (result.isError) throw new Error('expected read replacement success')
+      expect(result.value).toEqual({
+        path: 'pkg/deep/file.txt',
+        offset: 1,
+        lines: [{ number: 1, text: 'downstream replacement' }],
+        totalLines: 1,
+      })
+      expect(blocksText(result.content)).toContain('downstream replacement')
       expect(result.additionalContexts).toHaveLength(2)
       expect(workspaceContextOf(result)?.source).toEqual({ kind: 'plugin', plugin: 'workspace-context' })
       expect(workspaceContextOf(result)?.meta).toMatchObject({
@@ -2980,7 +3000,7 @@ describe('dynamic nested workspace context injection', () => {
       await ctx.plugin(ToolRegistry)
       await ctx.plugin(LocalFileSystem, { cwd: '/' })
       await ctx.plugin(ToolFs)
-      ctx.tools.register(defineTool({
+      ctx.tools.register(defineContentToolFixture({
         name: 'composite-read',
         description: 'read through a nested dispatch',
         parameters: {},
@@ -3035,7 +3055,7 @@ describe('dynamic nested workspace context injection', () => {
       await ctx.plugin(workspaceContext, { maxBytes: 65536 })
       const agent = stubAgent('/')
       const parent = Symbol('parent') as ToolExecutionToken
-      const plainResult = { callId: CallId('plain'), content: [], isError: false }
+      const plainResult = { callId: CallId('plain'), content: [], isError: false as const, value: null }
 
       ctx.emit('tools/result', stubToolExecution({
         signal: testToolSignal,
@@ -3077,7 +3097,8 @@ describe('dynamic nested workspace context injection', () => {
       const result = {
         callId: CallId('manual'),
         content: [{ type: 'text' as const, text: 'manual result' }],
-        isError: false,
+        isError: false as const,
+        value: null,
       }
       const cases = [
         { name: 'read', arguments: { file_path: join('pkg', 'deep', 'file.txt') }, agent: undefined },
@@ -3216,14 +3237,14 @@ describe('workspace context pending state', () => {
       path: join('pkg', 'AGENTS.md'), version: FsVersion('v1'), digest: 'one', trimmedDigest: 'one',
     }]]))
 
-    const unrelated = agent.session.append('context/message', {
+    const unrelated = agent.session.append('user/message', {
       content: [], source: { kind: 'plugin', plugin: 'other' },
     }, { surfaceOp: 'append' })
     observeInstructionSessionEvent(agent.session, unrelated, pending, versions)
     expect(pending.get(agent.session)?.has('pkg')).toBe(true)
 
     const otherContext = workspaceChangeContext('other', 'other')
-    const otherWorkspaceEvent = agent.session.append('context/message', {
+    const otherWorkspaceEvent = agent.session.append('user/message', {
       content: otherContext.content,
       source: otherContext.source,
       ...otherContext.meta !== undefined ? { meta: otherContext.meta } : {},
@@ -3232,7 +3253,7 @@ describe('workspace context pending state', () => {
     expect(pending.get(agent.session)?.has('pkg')).toBe(true)
 
     const context = workspaceChangeContext('pkg', 'one')
-    const confirmed = agent.session.append('context/message', {
+    const confirmed = agent.session.append('user/message', {
       content: context.content,
       source: context.source,
       ...context.meta !== undefined ? { meta: context.meta } : {},
diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md
index 7819cb8c2c..aabc893808 100644
--- a/packages/cordis/tool-cordis/README.md
+++ b/packages/cordis/tool-cordis/README.md
@@ -10,9 +10,11 @@ The self-referential cordis toolset: three model-facing tools over the live runt
 
 Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-catalog.md).
 
+Canonical successes are the inspection string, mount `{ id, pluginName, state, provides, waitingFor }`, and unmount `{ id, pluginName }`. Native renderers preserve the existing prose, so programs can use `mounted.id` while ordinary function calling still sees `mounted dyn-1 (...)`.
+
 ## Trust stance
 
-The sandbox isolates globals but is not a security boundary. Node globals are absent or redirect to Cordis services such as `ctx.fs`, `ctx.web`, and `ctx.bash`, and writes to `globalThis` stay local, but host-realm helpers make escape possible. Mounted plugins receive a façade without framework internals, yet its allowed services affect the live runtime. Treat this toolset like bash access; see the [design and trust stance](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+The sandbox isolates globals but is not a security boundary. Node globals are absent or redirect to Cordis services such as `ctx.fs`, `ctx.web`, and `ctx.bash`, and writes to `globalThis` stay local, but host-realm helpers make escape possible. Mounted plugins receive a façade without framework internals, yet its allowed services affect the live runtime. Dynamic tool schemas and annotations cross the realm through iterative JSON cloning and schema normalization, so valid deep declarations are memory-bounded rather than call-stack-bounded; records with JSON-invisible keys and subclassed or decorated schema arrays reject before normalization. Treat this toolset like bash access; see the [design and trust stance](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
 
 ## Config
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 3b9111f558..c3e4e1858b 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -402,6 +402,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>',
         jsDoc: '/**\n * Create and publish one owner-scoped session after backend setup succeeds.\n * @param owner - exact registered Agent that owns access and cleanup.\n * @param request - backend type plus optional owner-local name and cwd.\n * @param signal - cancellation of unpublished setup.\n * @returns published identity, metadata, status, and MOTD.\n */',
       },
+      {
+        signature: 'hasOwnerActivity(owner: Agent): boolean',
+        jsDoc: '/**\n * Test whether an exact owner has a published session or unpublished spawn.\n * @param owner - exact live owner to inspect.\n * @returns true across the entire spawn-to-close interval, with no publication gap.\n */',
+      },
       {
         signature: 'startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation',
         jsDoc: '/**\n * Start one exclusive interactive send.\n * @param owner - exact session owner.\n * @param id - target PTY identity.\n * @param request - explicit text, submit behavior, and cancellation.\n * @returns live operation handle for foreground await or task registration.\n */',
@@ -458,26 +462,50 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
-        jsDoc: '/**\n * Durably persist a batch of events (called from the write-behind drain at\n * the `session/flush` checkpoint). Honors the append-only and contiguous-seq\n * contracts: the first event\'s `seq` MUST equal the stored next-seq (after\n * `load` has durably closed any interrupted turn). Rejects non-JSON-\n * serializable `event.data` with an error naming the offending event type.\n * @param id - the session the batch belongs to.\n * @param events - the contiguous batch to persist, in seq order.\n */',
+        jsDoc: '/**\n * Durably persist a batch of events. Honors the append-only and contiguous-\n * seq contracts: the first event\'s `seq` MUST equal the stored next-seq\n * (after `load` has durably closed any interrupted turn). Rejects non-JSON-\n * serializable `event.data` with an error naming the offending event type.\n * @param id - the session the batch belongs to.\n * @param events - the contiguous batch to persist, in seq order.\n */',
       },
       {
         signature: 'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
-        jsDoc: '/**\n * Load a header and balanced contiguous log. A complete interrupted final\n * turn is preserved and durably closed with missing tool errors plus any open\n * step and turn boundaries; only a torn final record is discarded. Unknown\n * versions and corruption in the committed prefix reject.\n * @param id - the persisted session to reload.\n * @returns the header and a log ending on a balanced `turn/end`.\n */',
+        jsDoc: '/**\n * Load a header and balanced contiguous log. A complete interrupted final\n * turn is preserved and durably closed with missing tool errors plus any open\n * step and turn boundaries; only a torn final record is discarded. Unknown\n * versions and corruption in the committed prefix reject. Implementations\n * MUST NOT crash-repair an identity still bound to a live Session: a balanced\n * live log may return with its stored header as a durable snapshot, while an\n * open live turn rejects.\n * A coordinator-backed cold load reserves the identity across storage awaits,\n * so concurrent publication of a same-id live Session rejects.\n * @param id - the persisted session to reload.\n * @returns the header and a log ending on a balanced `turn/end`.\n */',
+      },
+      {
+        signature: 'abstract inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
+        jsDoc: '/**\n * Inspect a header and its valid contiguous stored prefix without repairing\n * a torn tail, closing an interrupted turn, or publishing coordinator state.\n * This read is serialized with writes for the same id and returns detached\n * values, so observers cannot mutate backend-owned state.\n * @param id - the persisted session to inspect.\n * @returns the header and valid stored event prefix exactly as observed.\n */',
       },
       {
         signature: 'abstract list(): Promise<SessionHeader[]>',
         jsDoc: '/**\n * Lightweight listing from metadata, without a full-log parse.\n * @returns one header per materialized session.\n */',
       },
+      {
+        signature: 'abstract listSnapshots(): Promise<SessionPersistenceSnapshot[]>',
+        jsDoc: '/**\n * List materialized sessions with cheap per-log change tokens.\n *\n * Repeated observations of an unchanged log return the same revision. A\n * successful mutating {@link load} repair changes the next listed revision.\n * Revisions also distinguish independently backed stores so backend-local\n * counters cannot compare equal across different persistence sources.\n * @returns one header and opaque revision per materialized session without loading full logs.\n */',
+      },
     ],
   },
   {
     key: 'sessionQuery',
-    summary: 'Live-preferred logical-corpus exact-read and relationship-tracing service.',
+    summary: 'Unified live-preferred session query service.',
     methods: [
+      {
+        signature: 'abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>',
+        jsDoc: '/**\n * Search the live-preferred logical corpus and group by session.\n * @param request - query text, metadata filters, page size, and cursor.\n * @param exec - optional cancellation control.\n * @returns session hits ranked by their strongest matching event.\n */',
+      },
+      {
+        signature: 'abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionEventSearchHit>>',
+        jsDoc: '/**\n * Search events within one live-preferred logical session.\n * @param request - target session, query text, filters, page size, and cursor.\n * @param exec - optional cancellation control.\n * @returns matching event hits in deterministic relevance order.\n */',
+      },
       {
         signature: 'listSessions(): Promise<SessionRecord[]>',
         jsDoc: '/**\n * List the complete logical corpus using live-preferred records.\n * @returns deterministic newest-first cloned session records.\n */',
       },
+      {
+        signature: 'async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>',
+        jsDoc: '/**\n * Read and replay-validate one complete logical session log without making it live.\n * @param sessionId - live or persisted session id to read.\n * @returns cloned header and complete raw event log from one observation.\n * @throws when persistence, header compatibility, or replay validation fails.\n */',
+      },
+      {
+        signature: 'async filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]>',
+        jsDoc: '/**\n * Filter the complete logical corpus with provider-independent predicates.\n * @param filters - ANDed session metadata and availability clauses.\n * @returns matching cloned records in deterministic newest-first order.\n */',
+      },
       {
         signature: 'async readTitle(sessionId: SessionId): Promise<SessionTitleSnapshot | undefined>',
         jsDoc: '/**\n * Fold the latest log-backed title from one live-preferred logical session.\n * @param sessionId - live or persisted session id to read.\n * @returns latest title snapshot, or `undefined` when the log has no title event.\n */',
@@ -486,6 +514,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>',
         jsDoc: '/**\n * List lightweight raw-log event records for one logical session.\n * @param sessionId - live-preferred session id to read.\n * @returns event records in ascending seq order.\n */',
       },
+      {
+        signature: 'async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>',
+        jsDoc: '/**\n * Scan first-party semantic event documents with provider-independent filters.\n * @param sessionId - live-preferred session id to scan.\n * @param filters - ANDed metadata and literal-text predicates.\n * @returns matching semantic documents in ascending seq order.\n */',
+      },
       {
         signature: 'async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>',
         jsDoc: '/**\n * Read one session\'s complete current model surface from one corpus observation.\n * @param sessionId - live-preferred session id to read.\n * @returns cloned header, current surface, and raw-log capture boundary.\n * @throws when source resolution fails or the session surface is invalid.\n */',
@@ -730,7 +762,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'register(definition: ToolDefinition): () => void',
-        jsDoc: '/**\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 - the tool schema, execution, and optional presentation functions.\n * @returns the exact disposer that unregisters the tool.\n */',
+        jsDoc: '/**\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 */',
       },
       {
         signature: 'restrict(filter: ToolRestriction): () => void',
@@ -754,7 +786,17 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>',
-        jsDoc: '/**\n * Execute through pre-policy, guards, around-dispatch, post-policy, and final\n * notification. Tool and listener failures resolve as materialized error\n * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is\n * the same lossless, frozen 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 */',
+        jsDoc: '/**\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 */',
+      },
+    ],
+  },
+  {
+    key: 'tui',
+    summary: 'Optional terminal-local interaction service provided by one mounted TUI.',
+    methods: [
+      {
+        signature: 'abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession',
+        jsDoc: '/**\n * Queue an interactive overlay owned by the calling plugin fiber.\n *\n * The TUI displays one overlay at a time in FIFO order. Disposing the caller\n * removes a queued overlay or closes an active one before plugin teardown\n * settles. This live presentation is neither logged nor replayed.\n *\n * @param request - component factory, layout constraints, and cancellation.\n * @returns the effect-owned overlay session.\n * @throws when the TUI has begun shutting down.\n */',
       },
     ],
   },
@@ -843,6 +885,27 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * A step or turn errored. The loop reports a failure here (plus the logger)\n * even when the error has no in-turn position for a session `error` event.\n * @param agent - the agent whose turn errored.\n * @param turn - the turn in which the failure surfaced.\n * @param step - the step at which the failure surfaced.\n * @param error - the failure, verbatim.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'A step or turn errored.',
   },
+  {
+    name: 'agent/inbox/dequeue',
+    mode: 'emit',
+    signature: '\'agent/inbox/dequeue\'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void',
+    jsDoc: '/**\n * The driver claimed one item out of the inbox: a queued item at a turn\n * boundary, or steering drained between steps. Fires after the item leaves\n * its FIFO and before it becomes a durable message.\n * @param agent - the agent whose inbox item was claimed.\n * @param message - the claimed message (matching the `id` from its `agent/inbox/enqueue`).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    summary: 'The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps.',
+  },
+  {
+    name: 'agent/inbox/discard',
+    mode: 'emit',
+    signature: '\'agent/inbox/discard\'(this: Scoped<Agent>, agent: Agent, messages: AgentMessage[]): void',
+    jsDoc: '/**\n * Pending inbox items were dropped without delivering them, so every\n * enqueued id receives exactly one terminal `agent/inbox/dequeue` OR\n * `agent/inbox/discard`. Emitters: `cancel()` without `keepInbox` (after\n * `agent/cancel-requested`, before the abort); a terminal `agent/turn-stop`\n * dropping pending steering (in-turn and on the post-turn late-steering\n * drain); and disposal of any still-pending items (before\n * `agent/status(\'disposed\')`). Fires once per drop with every dropped item.\n * @param agent - the agent whose inbox items were dropped.\n * @param messages - the discarded messages in FIFO order (queued then steering); never empty.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    summary: 'Pending inbox items were dropped without delivering them, so every enqueued id receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`.',
+  },
+  {
+    name: 'agent/inbox/enqueue',
+    mode: 'emit',
+    signature: '\'agent/inbox/enqueue\'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void',
+    jsDoc: '/**\n * A detached, frozen item entered the agent\'s inbox (queued or steering\n * FIFO). Source defaults are already applied, so `message` holds the exact\n * accepted values. This is the enqueue-time live signal; the durable record\n * is the eventual `user/message`/`steering/message`. Injection through\n * `agent.inject()` or equivalent `send()` routing bypasses the FIFOs\n * and does not emit this.\n * @param agent - the agent whose inbox received the item.\n * @param message - the accepted message (its returned `id`, content, source, contexts, steering, and wakeup facts).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    summary: 'A detached, frozen item entered the agent\'s inbox (queued or steering FIFO).',
+  },
   {
     name: 'agent/post-step',
     mode: 'serial',
@@ -864,13 +927,6 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * Allow, rewrite, or block one claimed prompt before it becomes a user\n * message. Call `next()` for the unchanged default. A listener wrapping a\n * downstream `allow` must preserve its `content` and `additionalContexts`\n * unless it intentionally replaces them. The signal controls only this turn;\n * listeners may cooperate with it but must not retain it to control another\n * turn. Steering messages do not dispatch this event; they join an open turn\n * at a steering checkpoint.\n * @param agent - the agent whose turn claimed the message.\n * @param content - the claimed message\'s blocks, as queued.\n * @param source - the message\'s resolved source.\n * @param 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: 'Allow, rewrite, or block one claimed prompt before it becomes a user message.',
   },
-  {
-    name: 'agent/queued',
-    mode: 'emit',
-    signature: '\'agent/queued\'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; contexts: HookContext[]; steering: boolean }): void',
-    jsDoc: '/**\n * Detached, frozen content entered the agent\'s inbox. Source defaults have\n * already been applied, so these are the exact values retained for the log.\n * @param agent - the agent whose inbox received the message.\n * @param content - the accepted content blocks retained by the inbox.\n * @param info - the accepted source, contexts, and whether it entered as steering.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
-    summary: 'Detached, frozen content entered the agent\'s inbox.',
-  },
   {
     name: 'agent/request',
     mode: 'waterfall',
@@ -903,7 +959,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/status',
     mode: 'emit',
     signature: '\'agent/status\'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void',
-    jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does\n * not enter `running` synchronously; drive lifecycle from this event.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`, or → `disposed`). A waking\n * delivery does not enter `running` synchronously; drive lifecycle from this event.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'Agent status changed (`idle` ⇄ `running`, or → `disposed`).',
   },
   {
@@ -1129,7 +1185,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
 export const TYPE_API: readonly TypeApiEntry[] = [
   {
     name: 'Agent',
-    declaration: 'export interface Agent {\n    readonly id: SessionId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    send(content: ContentBlock[], options?: SendOptions): void;\n    steer(content: ContentBlock[], options?: SendOptions): void;\n    inject(content: ContentBlock[], options?: InjectOptions): void;\n    cancel(cause?: AgentCancelCause): void;\n    whenIdle(): Promise<void>;\n}',
+    declaration: 'export interface Agent {\n    readonly id: SessionId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    followup(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n    queue(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n    steer(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n    inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId;\n    send(input: ResolvedAgentInput): AgentMessageId;\n    cancel(cause?: AgentCancelCause, options?: CancelOptions): void;\n    whenIdle(): Promise<void>;\n}',
   },
   {
     name: 'AgentCancelCause',
@@ -1143,6 +1199,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'AgentHandle',
     declaration: 'export interface AgentHandle {\n    agent: Agent;\n    dispose(): Promise<void>;\n}',
   },
+  {
+    name: 'AgentMessageId',
+    declaration: 'export type AgentMessageId = Branded<\'AgentMessageId\'>;',
+  },
   {
     name: 'AgentOptions',
     declaration: 'export interface AgentOptions {\n    provider?: string;\n    model?: string;\n}',
@@ -1243,17 +1303,29 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'CallId',
     declaration: 'export type CallId = Branded<\'CallId\'>;',
   },
+  {
+    name: 'CancelOptions',
+    declaration: 'export interface CancelOptions {\n    keepInbox?: boolean;\n}',
+  },
+  {
+    name: 'CodeBindingErrorClass',
+    declaration: 'export interface CodeBindingErrorClass {\n    name: string;\n    memberNameProperty: string;\n}',
+  },
   {
     name: 'CodeBindingFunction',
-    declaration: 'export type CodeBindingFunction = (args: unknown) => Promise<unknown>;',
+    declaration: 'export type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>;',
   },
   {
     name: 'CodeBindingNamespace',
-    declaration: 'export interface CodeBindingNamespace {\n    global: string;\n    functions: Record<string, CodeBindingFunction>;\n}',
+    declaration: 'export interface CodeBindingNamespace {\n    global: string;\n    functions: Record<string, CodeBindingFunction>;\n    errorClass?: CodeBindingErrorClass;\n}',
+  },
+  {
+    name: 'CodeJsonValue',
+    declaration: 'export type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | {\n    [key: string]: CodeJsonValue;\n};',
   },
   {
     name: 'CodeRunFailure',
-    declaration: 'export interface CodeRunFailure {\n    kind: \'exception\' | \'timeout\' | \'abort\' | \'worker-exit\';\n    message: string;\n}',
+    declaration: 'export interface CodeRunFailure {\n    kind: \'exception\' | \'timeout\' | \'abort\' | \'worker-exit\' | \'invalid-output\' | \'output-limit\';\n    message: string;\n}',
   },
   {
     name: 'CodeRunRequest',
@@ -1261,7 +1333,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CodeRunResult',
-    declaration: 'export interface CodeRunResult {\n    value?: unknown;\n    logs: string[];\n    error?: CodeRunFailure;\n}',
+    declaration: 'export interface CodeRunResult {\n    value?: CodeJsonValue;\n    logs: string[];\n    error?: CodeRunFailure;\n}',
   },
   {
     name: 'CollectedOutput',
@@ -1409,7 +1481,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'GenerateOptions',
-    declaration: 'export interface GenerateOptions {\n    provider: string;\n    model: string;\n    messages: Message[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<\'SessionId\'>;\n    purpose?: \'compaction\';\n}',
+    declaration: 'export interface GenerateOptions {\n    provider: string;\n    model: string;\n    messages: Message[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<\'SessionId\'>;\n    purpose?: \'compaction\' | \'session-title\';\n}',
   },
   {
     name: 'GenericCallView',
@@ -1453,7 +1525,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InjectOptions',
-    declaration: 'export interface InjectOptions extends Omit<SendOptions, \'contexts\'> {\n    meta?: JsonValue;\n}',
+    declaration: 'export interface InjectOptions {\n    source?: MessageSource;\n    meta?: JsonValue;\n}',
   },
   {
     name: 'InvariantFailure',
@@ -1463,10 +1535,26 @@ 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: '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}',
+  },
+  {
+    name: 'JsonSchemaScalar',
+    declaration: 'export type JsonSchemaScalar = string | number | boolean | null;',
+  },
+  {
+    name: 'JsonSchemaType',
+    declaration: 'export type JsonSchemaType = \'object\' | \'array\' | \'string\' | \'number\' | \'integer\' | \'boolean\' | \'null\';',
+  },
   {
     name: 'JsonValue',
     declaration: 'export type JsonValue = null | boolean | number | string | JsonValue[] | {\n    [key: string]: JsonValue;\n};',
   },
+  {
+    name: 'LlmAdapter',
+    declaration: 'export abstract class LlmAdapter {\n    providerInfo(provider: string): LlmProviderInfo;\n    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;\n    resolveModelContext(_provider: string, _model: string): Promise<LlmModelContext | undefined>;\n    abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}',
+  },
   {
     name: 'LlmCallConfig',
     declaration: 'export interface LlmCallConfig {\n    provider: string;\n    model: string;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}',
@@ -1499,6 +1587,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'MessageSourceMap',
     declaration: 'export interface MessageSourceMap {\n    user: {\n        kind: \'user\';\n    };\n    plugin: {\n        kind: \'plugin\';\n        plugin: string;\n    };\n}',
   },
+  {
+    name: 'ObjectJsonSchema',
+    declaration: 'export type ObjectJsonSchema = JsonSchemaNode & {\n    type: \'object\';\n};',
+  },
   {
     name: 'OutOfBandSessionEventMap',
     declaration: 'export interface OutOfBandSessionEventMap {\n}',
@@ -1525,7 +1617,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'PromptMessageData',
-    declaration: 'export interface PromptMessageData {\n    content: ContentBlock[];\n    source: MessageSource;\n    envelope?: PromptMessageEnvelope;\n}',
+    declaration: 'export interface PromptMessageData {\n    content: ContentBlock[];\n    source: MessageSource;\n    envelope?: PromptMessageEnvelope;\n    meta?: JsonValue;\n}',
   },
   {
     name: 'PromptMessageEnvelope',
@@ -1627,6 +1719,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ReasoningBlock',
     declaration: 'export interface ReasoningBlock {\n    type: \'reasoning\';\n    text: string;\n}',
   },
+  {
+    name: 'RequestHeaderReason',
+    declaration: 'export type RequestHeaderReason = \'initial\' | \'resume\' | \'change\';',
+  },
+  {
+    name: 'ResolvedAgentInput',
+    declaration: 'export type ResolvedAgentInput = {\n    content: ContentBlock[];\n    source: MessageSource;\n    meta: JsonValue | undefined;\n} & ({\n    target: \'next-turn\';\n    wakeup: boolean;\n    contexts: HookContext[];\n} | {\n    target: \'next-step\';\n    wakeup: true;\n    contexts: HookContext[];\n} | {\n    target: \'next-step\';\n    wakeup: false;\n    contexts: [\n    ];\n});',
+  },
   {
     name: 'ResumeAgentOptions',
     declaration: 'export interface ResumeAgentOptions {\n    readonly resumeSessionId: SessionId;\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
@@ -1661,7 +1761,15 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SendOptions',
-    declaration: 'export interface SendOptions {\n    source?: MessageSource;\n    contexts?: HookContext[];\n}',
+    declaration: 'export interface SendOptions {\n    source?: MessageSource;\n    contexts?: HookContext[];\n    meta?: JsonValue;\n}',
+  },
+  {
+    name: 'Session',
+    declaration: 'export class Session {\n    get surface(): SessionSurface;\n    readonly header: SessionHeader;\n    get id(): SessionId;\n    constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\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    deriveMessages(): Message[];\n    deriveEventMessage(event: SessionEvent): Message | null;\n}',
+  },
+  {
+    name: 'SessionAvailability',
+    declaration: 'export type SessionAvailability = \'live\' | \'persisted\';',
   },
   {
     name: 'SessionEvent',
@@ -1669,7 +1777,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionEventMap',
-    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\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\': PromptMessageData;\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        meta?: JsonValue;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        provenance: AssistantProvenance;\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        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: unknown;\n    };\n    \'steering/message\': PromptMessageData & {\n        turn: number;\n    };\n    \'todo/write\': {\n        todos: TodoItem[];\n    };\n    \'request/header\': {\n        header: EpochHeader;\n        reason: Req /* …truncated — full shape in source */',
+    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\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\': PromptMessageData;\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        provenance: AssistantProvenance;\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        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: JsonValue;\n    };\n    \'steering/message\': PromptMessageData & {\n        turn: number;\n    };\n    \'todo/write\': {\n        todos: TodoItem[];\n    };\n    \'request/header\': {\n        header: EpochHeader;\n        reason: RequestHeaderReason;\n    };\n}',
+  },
+  {
+    name: 'SessionEventMetadataFilter',
+    declaration: 'export type SessionEventMetadataFilter = Exclude<SessionEventResultFilter, {\n    kind: \'text\';\n}>;',
   },
   {
     name: 'SessionEventReadRequest',
@@ -1679,6 +1791,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionEventRecord',
     declaration: 'export interface SessionEventRecord {\n    sessionId: SessionId;\n    seq: number;\n    type: SessionEventType;\n    time: number;\n    surface: SessionEventSurface;\n}',
   },
+  {
+    name: 'SessionEventResultFilter',
+    declaration: 'export type SessionEventResultFilter = ({\n    kind: \'seq\';\n} & SessionResultRange) | ({\n    kind: \'time\';\n} & SessionResultRange) | {\n    kind: \'type\';\n    values: readonly SessionEventType[];\n} | {\n    kind: \'surface\';\n    values: readonly SessionEventSurface[];\n} | {\n    kind: \'text\';\n    text: string;\n};',
+  },
+  {
+    name: 'SessionEventSearchDocument',
+    declaration: 'export interface SessionEventSearchDocument extends SessionEventRecord {\n    text: string;\n}',
+  },
+  {
+    name: 'SessionEventSearchHit',
+    declaration: 'export interface SessionEventSearchHit extends SessionEventRecord {\n    snippet: string;\n}',
+  },
+  {
+    name: 'SessionEventSearchRequest',
+    declaration: 'export interface SessionEventSearchRequest {\n    sessionId: SessionId;\n    query: string;\n    filters?: readonly SessionEventMetadataFilter[];\n    limit?: number;\n    cursor?: SessionSearchCursor;\n}',
+  },
   {
     name: 'SessionEventSurface',
     declaration: 'export type SessionEventSurface = \'current\' | \'shadowed\' | \'log-only\';',
@@ -1723,6 +1851,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionLocation',
     declaration: 'export interface SessionLocation {\n    readonly kind: string;\n    readonly path: string;\n}',
   },
+  {
+    name: 'SessionLogSnapshot',
+    declaration: 'export interface SessionLogSnapshot {\n    session: SessionHeader;\n    events: SessionEvent[];\n}',
+  },
+  {
+    name: 'SessionPersistenceRevision',
+    declaration: 'export type SessionPersistenceRevision = Branded<\'SessionPersistenceRevision\'>;',
+  },
+  {
+    name: 'SessionPersistenceSnapshot',
+    declaration: 'export interface SessionPersistenceSnapshot {\n    header: SessionHeader;\n    revision: SessionPersistenceRevision;\n}',
+  },
   {
     name: 'SessionRecord',
     declaration: 'export interface SessionRecord {\n    header: SessionHeader;\n    live: boolean;\n    persisted: boolean;\n}',
@@ -1735,6 +1875,38 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionReferenceInput',
     declaration: 'export interface SessionReferenceInput {\n    sessionId: SessionId;\n    label?: string;\n}',
   },
+  {
+    name: 'SessionResultFilter',
+    declaration: 'export type SessionResultFilter = {\n    kind: \'id\';\n    values: readonly SessionId[];\n} | {\n    kind: \'cwd\';\n    values: readonly (string | null)[];\n} | ({\n    kind: \'created-at\';\n} & SessionResultRange) | {\n    kind: \'parent\';\n    values: readonly (SessionId | null)[];\n} | {\n    kind: \'availability\';\n    values: readonly SessionAvailability[];\n};',
+  },
+  {
+    name: 'SessionResultRange',
+    declaration: 'export interface SessionResultRange {\n    from?: number;\n    to?: number;\n}',
+  },
+  {
+    name: 'SessionSearchCursor',
+    declaration: 'export type SessionSearchCursor = Branded<\'SessionSearchCursor\'>;',
+  },
+  {
+    name: 'SessionSearchExecContext',
+    declaration: 'export interface SessionSearchExecContext {\n    signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'SessionSearchHit',
+    declaration: 'export interface SessionSearchHit extends SessionRecord {\n    bestMatch: SessionEventSearchHit;\n}',
+  },
+  {
+    name: 'SessionSearchPage',
+    declaration: 'export interface SessionSearchPage<T> {\n    items: readonly T[];\n    nextCursor?: SessionSearchCursor;\n}',
+  },
+  {
+    name: 'SessionSearchRequest',
+    declaration: 'export interface SessionSearchRequest {\n    query: string;\n    sessionFilters?: readonly SessionResultFilter[];\n    eventFilters?: readonly SessionEventMetadataFilter[];\n    limit?: number;\n    cursor?: SessionSearchCursor;\n}',
+  },
+  {
+    name: 'SessionSurface',
+    declaration: 'export interface SessionSurface {\n    readonly nodes: readonly number[];\n    readonly replaceGeneration: number;\n}',
+  },
   {
     name: 'SessionSurfaceSnapshot',
     declaration: 'export interface SessionSurfaceSnapshot {\n    session: SessionHeader;\n    capturedThroughSeq: number | null;\n    events: SurfaceEvent[];\n}',
@@ -1831,22 +2003,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'StreamChunk',
     declaration: '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};',
   },
-  {
-    name: 'StructuredOutputSchema',
-    declaration: 'export type StructuredOutputSchema = StructuredSchemaNode & {\n    type: \'object\';\n};',
-  },
-  {
-    name: 'StructuredScalar',
-    declaration: 'export type StructuredScalar = string | number | boolean | null;',
-  },
-  {
-    name: 'StructuredSchemaNode',
-    declaration: 'export interface StructuredSchemaNode {\n    type: StructuredSchemaType;\n    properties?: Record<string, StructuredSchemaNode>;\n    required?: string[];\n    additionalProperties?: boolean;\n    items?: StructuredSchemaNode;\n    enum?: StructuredScalar[];\n    const?: StructuredScalar;\n    description?: string;\n    title?: string;\n    default?: unknown;\n    examples?: unknown;\n}',
-  },
-  {
-    name: 'StructuredSchemaType',
-    declaration: 'export type StructuredSchemaType = \'object\' | \'array\' | \'string\' | \'number\' | \'integer\' | \'boolean\' | \'null\';',
-  },
   {
     name: 'SubagentCapabilities',
     declaration: 'export interface SubagentCapabilities {\n    readonly outputSchema: boolean;\n    readonly depthLimit: boolean;\n    readonly toolFilter: boolean;\n    readonly persona: boolean;\n}',
@@ -1865,7 +2021,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubagentStartRequest',
-    declaration: 'export interface SubagentStartRequest {\n    readonly prompt: ContentBlock[];\n    readonly parent: Agent;\n    readonly signal: AbortSignal;\n    readonly agentOptions?: AgentOptions;\n    readonly outputSchema?: StructuredOutputSchema;\n    readonly maxDepth?: number;\n    readonly toolFilter?: ToolRestriction;\n    readonly persona?: string;\n}',
+    declaration: 'export interface SubagentStartRequest {\n    readonly prompt: ContentBlock[];\n    readonly parent: Agent;\n    readonly signal: AbortSignal;\n    readonly agentOptions?: AgentOptions;\n    readonly outputSchema?: ObjectJsonSchema;\n    readonly maxDepth?: number;\n    readonly toolFilter?: ToolRestriction;\n    readonly persona?: string;\n}',
   },
   {
     name: 'SubagentStopReason',
@@ -1881,7 +2037,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SurfaceEventType',
-    declaration: 'export type SurfaceEventType = \'user/message\' | \'assistant/message\' | \'tool/result\' | \'context/message\' | \'steering/message\';',
+    declaration: 'export type SurfaceEventType = \'user/message\' | \'assistant/message\' | \'tool/result\' | \'steering/message\';',
+  },
+  {
+    name: 'SurfaceIntent',
+    declaration: 'export interface SurfaceIntent {\n    surfaceOp: SurfaceOp;\n    sourceEventSeqs?: number[];\n}',
   },
   {
     name: 'SurfaceOp',
@@ -1917,11 +2077,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TaskSnapshot',
-    declaration: 'export interface TaskSnapshot {\n    id: TaskId;\n    kind: TaskKind;\n    label: string;\n    ownerSession?: SessionId;\n    status: TaskStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
+    declaration: 'export interface TaskSnapshot {\n    id: TaskId;\n    kind: TaskKind;\n    label: string;\n    outputLimitBytes?: number;\n    ownerSession?: SessionId;\n    status: TaskStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
   },
   {
     name: 'TaskStart',
-    declaration: 'export interface TaskStart {\n    kind: TaskKind;\n    label: string;\n    owner?: Agent;\n    run(): TaskHooks;\n}',
+    declaration: 'export interface TaskStart {\n    kind: TaskKind;\n    label: string;\n    outputLimitBytes?: number;\n    owner?: Agent;\n    run(): TaskHooks;\n}',
   },
   {
     name: 'TaskStatus',
@@ -1969,20 +2129,20 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolDefinition',
-    declaration: 'export interface ToolDefinition extends ToolSchema {\n    execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>;\n    timeoutMs?: number;\n    isConcurrencySafe?(args: unknown): boolean;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
+    declaration: '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}',
   },
   {
     name: 'ToolErrorInfo',
     declaration: 'export interface ToolErrorInfo {\n    name: string;\n    code: string;\n}',
   },
-  {
-    name: 'ToolExecuteReturn',
-    declaration: 'export type ToolExecuteReturn = ContentBlock[] | {\n    content: ContentBlock[];\n    meta?: unknown;\n};',
-  },
   {
     name: 'ToolExecution',
     declaration: 'export interface ToolExecution extends ToolExecutionInput {\n    readonly token: ToolExecutionToken;\n}',
   },
+  {
+    name: 'ToolExecutionFailure',
+    declaration: '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?: HookContext[];\n}',
+  },
   {
     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}',
@@ -1993,16 +2153,28 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolExecutionResult',
-    declaration: 'export interface ToolExecutionResult {\n    content: ContentBlock[];\n    isError: boolean;\n    error?: ToolErrorInfo;\n    additionalContexts?: HookContext[];\n    meta?: unknown;\n}',
+    declaration: 'export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;',
+  },
+  {
+    name: 'ToolExecutionSuccess',
+    declaration: '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?: HookContext[];\n}',
   },
   {
     name: 'ToolExecutionToken',
     declaration: 'export type ToolExecutionToken = symbol & {\n    readonly [toolExecutionTokenBrand]: true;\n};',
   },
+  {
+    name: 'ToolFailure',
+    declaration: 'export interface ToolFailure {\n    message: string;\n    info?: ToolErrorInfo;\n}',
+  },
   {
     name: 'ToolGuard',
     declaration: 'export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;',
   },
+  {
+    name: 'ToolOutputDefinition',
+    declaration: 'export interface ToolOutputDefinition {\n    readonly schema: JsonSchemaNode;\n    render(args: unknown, value: JsonValue): ContentBlock[];\n    presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n}',
+  },
   {
     name: 'ToolProviderResult',
     declaration: 'export interface ToolProviderResult {\n    readonly schemas: readonly ToolSchema[];\n    readonly knownNames?: readonly string[];\n}',
@@ -2013,7 +2185,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolResult',
-    declaration: 'export interface ToolResult {\n    content: ContentBlock[];\n    isError: boolean;\n    meta?: unknown;\n}',
+    declaration: 'export interface ToolResult {\n    content: ContentBlock[];\n    isError: boolean;\n    meta?: JsonValue;\n}',
   },
   {
     name: 'ToolResultBlock',
@@ -2031,6 +2203,58 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ToolSchema',
     declaration: 'export interface ToolSchema {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}',
   },
+  {
+    name: 'TuiComponent',
+    declaration: 'export interface TuiComponent {\n    render(width: number): string[];\n    handleInput?(data: string): void;\n    wantsKeyRelease?: boolean;\n    invalidate(): void;\n}',
+  },
+  {
+    name: 'TuiFocusable',
+    declaration: 'export interface TuiFocusable {\n    focused: boolean;\n}',
+  },
+  {
+    name: 'TuiOverlayAnchor',
+    declaration: 'export type TuiOverlayAnchor = \'center\' | \'top-left\' | \'top-right\' | \'bottom-left\' | \'bottom-right\' | \'top-center\' | \'bottom-center\' | \'left-center\' | \'right-center\';',
+  },
+  {
+    name: 'TuiOverlayCloseReason',
+    declaration: 'export type TuiOverlayCloseReason = \'closed\' | \'aborted\' | \'owner-disposed\' | \'tui-disposed\' | \'error\';',
+  },
+  {
+    name: 'TuiOverlayHost',
+    declaration: 'export interface TuiOverlayHost {\n    readonly signal: AbortSignal;\n    readonly viewport: TuiViewport;\n    readonly theme: TuiTheme;\n    display(value: string): string;\n    invalidate(): void;\n    close(): void;\n}',
+  },
+  {
+    name: 'TuiOverlayMargin',
+    declaration: 'export interface TuiOverlayMargin {\n    readonly top?: number;\n    readonly right?: number;\n    readonly bottom?: number;\n    readonly left?: number;\n}',
+  },
+  {
+    name: 'TuiOverlayOptions',
+    declaration: 'export interface TuiOverlayOptions {\n    readonly width?: number | `${number}%`;\n    readonly minWidth?: number;\n    readonly maxHeight?: number | `${number}%`;\n    readonly anchor?: TuiOverlayAnchor;\n    readonly margin?: number | TuiOverlayMargin;\n}',
+  },
+  {
+    name: 'TuiOverlayOutcome',
+    declaration: 'export type TuiOverlayOutcome = {\n    readonly reason: Exclude<TuiOverlayCloseReason, \'error\'>;\n} | {\n    readonly reason: \'error\';\n    readonly error: unknown;\n};',
+  },
+  {
+    name: 'TuiOverlayRequest',
+    declaration: 'export interface TuiOverlayRequest {\n    readonly create: (host: TuiOverlayHost) => TuiComponent & Partial<TuiFocusable>;\n    readonly options?: TuiOverlayOptions;\n    readonly signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'TuiOverlaySession',
+    declaration: 'export interface TuiOverlaySession {\n    readonly state: TuiOverlayState;\n    readonly closed: Promise<TuiOverlayOutcome>;\n    close(): Promise<TuiOverlayOutcome>;\n}',
+  },
+  {
+    name: 'TuiOverlayState',
+    declaration: 'export type TuiOverlayState = \'queued\' | \'active\' | \'closed\';',
+  },
+  {
+    name: 'TuiTheme',
+    declaration: 'export interface TuiTheme {\n    readonly text: (value: string) => string;\n    readonly muted: (value: string) => string;\n    readonly dim: (value: string) => string;\n    readonly accent: (value: string) => string;\n    readonly success: (value: string) => string;\n    readonly warning: (value: string) => string;\n    readonly error: (value: string) => string;\n    readonly bold: (value: string) => string;\n}',
+  },
+  {
+    name: 'TuiViewport',
+    declaration: 'export interface TuiViewport {\n    readonly columns: number;\n    readonly rows: number;\n}',
+  },
   {
     name: 'TurnEndReason',
     declaration: 'export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];',
diff --git a/packages/cordis/tool-cordis/src/fiber-state.ts b/packages/cordis/tool-cordis/src/fiber-state.ts
index 8c9f0e2f45..dcd9da149b 100644
--- a/packages/cordis/tool-cordis/src/fiber-state.ts
+++ b/packages/cordis/tool-cordis/src/fiber-state.ts
@@ -21,11 +21,11 @@ export const FiberState = {
 export type FiberState = FiberStateEnum
 
 /** Human-readable label for each {@link FiberState}, keyed by member (inlining-safe — no reverse mapping). */
-export const STATE_LABELS: Record<FiberState, string> = {
+export const STATE_LABELS = {
   [FiberState.PENDING]: 'pending',
   [FiberState.LOADING]: 'loading',
   [FiberState.ACTIVE]: 'active',
   [FiberState.FAILED]: 'failed',
   [FiberState.DISPOSED]: 'disposed',
   [FiberState.UNLOADING]: 'unloading',
-}
+} as const satisfies Record<FiberState, string>
diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts
index 2198533376..b9bc992ad8 100644
--- a/packages/cordis/tool-cordis/src/guard.ts
+++ b/packages/cordis/tool-cordis/src/guard.ts
@@ -1,13 +1,13 @@
 /**
- * The registration boundary between sandboxed mount code and the real runtime: SchemaSpec
+ * The registration boundary between sandboxed mount code and the real runtime: ParameterSchemaSpec
  * normalization + validation with teaching errors, the marker-guarded `harness.defineTool` /
  * `harness.registerTool` pair, the SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives
  * in place of the real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox
  * return values with. The façade is a whitelist of lifecycle-safe verbs and declared services;
  * framework internals and context-valued service returns are denied.
  *
- * VM-realm schemas are rebuilt as host objects, and tool results are JSON-round-tripped and
- * shape-checked before session logging. Common JSON-Schema spellings are normalized when they
+ * VM-realm schemas and canonical values are rebuilt as host objects, while rendered content and
+ * presentation metadata are shape-checked before entering the registry. Common JSON-Schema spellings are normalized when they
  * have one meaning; invalid vocabulary fails during registration with a teaching error.
  * @module @deepseek-ai/dsh-tool-cordis/guard
  */
@@ -15,84 +15,470 @@
 import { Context } from 'cordis'
 import type { Plugin } from 'cordis'
 import { scopeOf } from '@deepseek-ai/dsh-scope'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools'
+import { assertSupportedJsonSchema, defineTool } from '@deepseek-ai/dsh-tools'
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 
 const DYNAMIC_TOOL = Symbol('tool-cordis.dynamic-tool')
-const SCHEMA_TYPES = new Set<unknown>(['string', 'number', 'boolean', 'object', 'array'])
-const VALID_TYPES = '\'string\' | \'number\' | \'boolean\' | \'object\' | \'array\''
+const SCHEMA_TYPES = new Set<unknown>(['string', 'number', 'integer', 'boolean', 'null', 'object', 'array', 'json'])
+const VALID_TYPES = '\'string\' | \'number\' | \'integer\' | \'boolean\' | \'null\' | \'object\' | \'array\' | \'json\''
+const ANNOTATION_KEYS = ['description', 'title', 'default', 'examples'] as const
 
 type DynamicToolDefinition = ToolDefinition & { [DYNAMIC_TOOL]: true }
 type DynamicToolMarker = { [DYNAMIC_TOOL]?: unknown }
 
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return Object.prototype.toString.call(value) === '[object Object]'
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const prototype: unknown = Object.getPrototypeOf(value)
+  return prototype === null
+    || typeof prototype === 'object'
+      && Object.getPrototypeOf(prototype) === null
+      && hasIntrinsicConstructor(prototype, 'Object')
+}
+
+/* jscpd:ignore-start -- this VM boundary mirrors the session-owned realm-safe intrinsic test */
+/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
+function hasIntrinsicConstructor(prototype: object, name: 'Array' | 'Object'): boolean {
+  const descriptor = Object.getOwnPropertyDescriptor(prototype, 'constructor')
+  const constructor: unknown = descriptor?.value
+  if (typeof constructor !== 'function') return false
+  try {
+    return constructor.name === name
+      && constructor.prototype === prototype
+      && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`
+  } catch {
+    return false
+  }
+}
+
+/** Whether an array uses one realm's intrinsic Array prototype rather than a subclass. */
+function hasPlainArrayPrototype(value: unknown[]): boolean {
+  const prototype: unknown = Object.getPrototypeOf(value)
+  if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, 'Array')) return false
+  const objectPrototype: unknown = Object.getPrototypeOf(prototype)
+  return typeof objectPrototype === 'object'
+    && objectPrototype !== null
+    && Object.getPrototypeOf(objectPrototype) === null
+    && hasIntrinsicConstructor(objectPrototype, 'Object')
+}
+/* jscpd:ignore-end */
+
+/** Whether a schema list is a dense intrinsic array with no JSON-invisible decorations. */
+function isDensePlainArray(value: unknown): value is unknown[] {
+  if (!Array.isArray(value) || !hasPlainArrayPrototype(value) || Reflect.ownKeys(value).length !== value.length + 1) {
+    return false
+  }
+  for (let index = 0; index < value.length; index++) {
+    if (!Object.hasOwn(value, index)) return false
+  }
+  return true
+}
+
+/** Reject schema records whose declarations would disappear from object enumeration. */
+function assertSchemaContainerKeys(value: Record<string, unknown>, path: string): void {
+  if (Reflect.ownKeys(value).some(key => typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(value, key))) {
+    throw new Error(`harness.defineTool ${path} must contain only own enumerable string keys`)
+  }
+}
+
+/** Where one cloned JSON value is installed. */
+type CloneDestination =
+  | { kind: 'root' }
+  | { kind: 'array'; target: unknown[]; index: number }
+  | { kind: 'object'; target: Record<string, unknown>; key: string }
+
+/** Deferred work for stack-safe cross-realm JSON cloning. */
+type CloneTask =
+  | { kind: 'visit'; value: unknown; path: string; destination: CloneDestination }
+  | { kind: 'array-item'; source: unknown[]; index: number; path: string; target: unknown[] }
+  | { kind: 'leave'; source: object }
+
+/** Materialize realm-foreign lossless JSON without allowing JSON.stringify coercions. */
+function cloneJson(value: unknown, path: string): unknown {
+  const ancestors = new Set<object>()
+  let root: unknown
+  const assign = (destination: CloneDestination, item: unknown): void => {
+    if (destination.kind === 'root') {
+      root = item
+      return
+    }
+    if (destination.kind === 'array') {
+      destination.target[destination.index] = item
+      return
+    }
+    Object.defineProperty(destination.target, destination.key, {
+      value: item,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+  }
+  const reject = (at: string): never => {
+    throw new Error(`harness.defineTool ${at} must be lossless JSON data`)
+  }
+
+  const tasks: CloneTask[] = [{ kind: 'visit', value, path, destination: { kind: 'root' } }]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      ancestors.delete(task.source)
+      continue
+    }
+    if (task.kind === 'array-item') {
+      if (!Object.hasOwn(task.source, task.index)) reject(task.path)
+      tasks.push({
+        kind: 'visit',
+        value: task.source[task.index],
+        path: `${task.path}[${task.index}]`,
+        destination: { kind: 'array', target: task.target, index: task.index },
+      })
+      continue
+    }
+
+    const current = task.value
+    if (current === null || typeof current === 'string' || typeof current === 'boolean') {
+      assign(task.destination, current)
+      continue
+    }
+    if (typeof current === 'number') {
+      if (!Number.isFinite(current) || Object.is(current, -0)) reject(task.path)
+      assign(task.destination, current)
+      continue
+    }
+    if (typeof current !== 'object' || ancestors.has(current)) reject(task.path)
+
+    if (Array.isArray(current)) {
+      if (!hasPlainArrayPrototype(current) || Reflect.ownKeys(current).length !== current.length + 1) reject(task.path)
+      const output: unknown[] = []
+      assign(task.destination, output)
+      ancestors.add(current)
+      tasks.push({ kind: 'leave', source: current })
+      for (let index = current.length - 1; index >= 0; index--) {
+        tasks.push({ kind: 'array-item', source: current, index, path: task.path, target: output })
+      }
+      continue
+    }
+    if (!isPlainRecord(current)) reject(task.path)
+    const record = current as Record<string, unknown>
+    if (Reflect.ownKeys(record).some(key => typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(record, key))) {
+      reject(task.path)
+    }
+    const output: Record<string, unknown> = {}
+    assign(task.destination, output)
+    ancestors.add(record)
+    tasks.push({ kind: 'leave', source: record })
+    const entries = Object.entries(record)
+    for (let index = entries.length - 1; index >= 0; index--) {
+      const entry = entries[index]
+      /* v8 ignore next -- the loop is bounded by the captured entry count. */
+      if (entry === undefined) continue
+      tasks.push({
+        kind: 'visit',
+        value: entry[1],
+        path: `${task.path}.${entry[0]}`,
+        destination: { kind: 'object', target: output, key: entry[0] },
+      })
+    }
+  }
+  return root
+}
+
+/** Copy and realm-materialize the shared annotation vocabulary. */
+function copyAnnotations(value: Record<string, unknown>, output: Record<string, unknown>, path: string): void {
+  if (Object.hasOwn(value, 'description')) output.description = value.description
+  if (Object.hasOwn(value, 'title')) output.title = value.title
+  if (Object.hasOwn(value, 'default')) output.default = cloneJson(value.default, `${path}.default`)
+  if (Object.hasOwn(value, 'examples')) output.examples = cloneJson(value.examples, `${path}.examples`)
+}
+
+/** Reject sandbox schema keys that the unified DSL would otherwise ignore. */
+function assertSchemaKeys(value: Record<string, unknown>, path: string, allowed: readonly string[]): void {
+  assertSchemaContainerKeys(value, path)
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw new Error(`harness.defineTool ${path}.${key} is not supported by the unified schema DSL`)
+  }
 }
 
 /**
  * Normalize a sandbox-provided `parameters` value into a fresh host-realm
- * SchemaSpec. Accepts the DSL directly, or the JSON-Schema-style
- * `{ type: 'object', properties, required: […] }` wrapper models write by
- * prior — the wrapper unwraps and its `required` array becomes per-property
- * flags (see the module doc).
+ * ParameterSchemaSpec. A raw JSON-Schema object wrapper retains its open root
+ * default, while the direct DSL is already an implicit open property map.
  */
-function normalizeSchemaSpec(value: unknown, path = 'parameters'): Record<string, unknown> {
+function normalizeParameterSchemaSpec(value: unknown, path = 'parameters'): {
+  spec: Record<string, unknown>
+  rootAnnotations?: Record<string, unknown>
+} {
   if (!isPlainRecord(value)) {
-    throw new Error(`harness.defineTool ${path} must be a SchemaSpec object`)
+    throw new Error(`harness.defineTool ${path} must be a ParameterSchemaSpec object`)
   }
-  let entries = value
-  const requiredNames = new Set<unknown>()
-  if (value.type === 'object' && isPlainRecord(value.properties)) {
-    if (Array.isArray(value.required)) {
-      for (const name of value.required) requiredNames.add(name)
+  if (value.type === 'object') {
+    assertSchemaKeys(value, path, ['type', 'properties', 'required', 'additionalProperties', ...ANNOTATION_KEYS])
+    if (!isPlainRecord(value.properties)) {
+      throw new Error(`harness.defineTool ${path}.properties must be an object of schemas`)
+    }
+    if (Object.hasOwn(value, 'additionalProperties') && value.additionalProperties !== true) {
+      throw new Error(`harness.defineTool ${path}.additionalProperties must be true or omitted because the implicit parameter root is open`)
+    }
+    if (Object.hasOwn(value, 'required') && value.required === undefined) {
+      throw new Error(`harness.defineTool ${path}.required must be an array of declared property names`)
+    }
+    const required = normalizeRequiredNames(value.required, value.properties, `${path}.required`)
+    const rootAnnotations: Record<string, unknown> = {}
+    copyAnnotations(value, rootAnnotations, path)
+    return {
+      spec: normalizePropertyMap(value.properties, path, required, true),
+      ...(Object.keys(rootAnnotations).length === 0 ? {} : { rootAnnotations }),
     }
-    entries = value.properties
   }
-  const spec: Record<string, unknown> = {}
-  for (const [key, prop] of Object.entries(entries)) {
-    spec[key] = normalizeSchemaProp(prop, `${path}.${key}`, requiredNames.has(key))
-  }
-  return spec
+  return { spec: normalizePropertyMap(value, path, new Set(), false) }
 }
 
-/** Normalize one property: `integer` → `number`, `required: false` → absent, nested wrappers unwrapped recursively. */
-function normalizeSchemaProp(value: unknown, path: string, forceRequired = false): Record<string, unknown> {
-  if (!isPlainRecord(value)) {
-    throw new Error(`harness.defineTool ${path} must be a SchemaSpec property object`)
+/** Validate raw required names and return their lookup set. */
+function normalizeRequiredNames(value: unknown, properties: Record<string, unknown>, path: string): Set<string> {
+  if (value === undefined) return new Set()
+  if (!isDensePlainArray(value)) {
+    throw new Error(`harness.defineTool ${path} must be an array of declared property names`)
   }
-  const type = value.type === 'integer' ? 'number' : value.type
-  if (!SCHEMA_TYPES.has(type)) {
-    throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES} (got ${JSON.stringify(value.type)})`)
-  }
-  // On an object property a JSON-Schema-style `required` ARRAY names required
-  // children (handled by the nested unwrap below); everywhere else `required`
-  // must be a boolean, and `false` means optional.
-  const nestedRequiredArray = type === 'object' && Array.isArray(value.required)
-  if (value.required !== undefined && typeof value.required !== 'boolean' && !nestedRequiredArray) {
-    throw new Error(`harness.defineTool ${path}.required must be a boolean when present`)
-  }
-  const prop: Record<string, unknown> = { type }
-  if (forceRequired || value.required === true) prop.required = true
-  if (typeof value.description === 'string') prop.description = value.description
-  if (Array.isArray(value.enum)) prop.enum = [...value.enum as unknown[]]
-  if (value.default !== undefined) prop.default = value.default
-  if (value.properties !== undefined) {
-    if (type !== 'object') {
-      throw new Error(`harness.defineTool ${path}.properties is only valid for type "object"`)
+  const names = new Set<string>()
+  for (let index = 0; index < value.length; index++) {
+    const name = value[index]
+    if (typeof name !== 'string') {
+      throw new Error(`harness.defineTool ${path} must be an array of declared property names`)
     }
-    // Re-wrap so the nested unwrap applies a nested `required` array too.
-    prop.properties = normalizeSchemaSpec(
-      { type: 'object', properties: value.properties, required: value.required },
-      `${path}.properties`,
-    )
+    names.add(name)
+    if (!Object.hasOwn(properties, name)) throw new Error(`harness.defineTool ${path} names undeclared property ${JSON.stringify(name)}`)
   }
-  if (value.items !== undefined) {
-    if (type !== 'array') {
-      throw new Error(`harness.defineTool ${path}.items is only valid for type "array"`)
+  return names
+}
+
+/** Mutable holder used only while one normalized property-map root is unresolved. */
+interface NormalizeRoot {
+  value?: Record<string, unknown>
+}
+
+/** Where a normalized value node is installed. */
+type NormalizeValueDestination =
+  | { kind: 'property'; target: Record<string, unknown>; key: string }
+  | { kind: 'item'; target: Record<string, unknown> }
+  | { kind: 'one-of'; target: Record<string, unknown>[]; index: number }
+
+/** Where a normalized property map is installed. */
+type NormalizeMapDestination =
+  | { kind: 'root'; holder: NormalizeRoot }
+  | { kind: 'properties'; target: Record<string, unknown> }
+
+/** Deferred work for stack-safe sandbox schema normalization. */
+type NormalizeTask =
+  | {
+    kind: 'map'
+    entries: Record<string, unknown>
+    path: string
+    requiredNames: ReadonlySet<string>
+    raw: boolean
+    destination: NormalizeMapDestination
+  }
+  | {
+    kind: 'value'
+    value: unknown
+    path: string
+    forceRequired: boolean
+    raw: boolean
+    parameterProperty: boolean
+    destination: NormalizeValueDestination
+  }
+  | { kind: 'leave'; value: object }
+
+/** Install one normalized node without `__proto__` assignment semantics. */
+function assignNormalizedValue(destination: NormalizeValueDestination, value: Record<string, unknown>): void {
+  if (destination.kind === 'property') {
+    Object.defineProperty(destination.target, destination.key, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+  } else if (destination.kind === 'item') {
+    destination.target.items = value
+  } else {
+    destination.target[destination.index] = value
+  }
+}
+
+/** Install one normalized property map at its root or containing object. */
+function assignNormalizedMap(destination: NormalizeMapDestination, value: Record<string, unknown>): void {
+  if (destination.kind === 'root') destination.holder.value = value
+  else destination.target.properties = value
+}
+
+/** Normalize one implicit property map and all descendants with explicit work frames. */
+function normalizePropertyMap(
+  entries: Record<string, unknown>,
+  path: string,
+  requiredNames: ReadonlySet<string>,
+  raw: boolean,
+): Record<string, unknown> {
+  const holder: NormalizeRoot = {}
+  const ancestors = new Set<object>()
+  const tasks: NormalizeTask[] = [{
+    kind: 'map',
+    entries,
+    path,
+    requiredNames,
+    raw,
+    destination: { kind: 'root', holder },
+  }]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      ancestors.delete(task.value)
+      continue
+    }
+    if (task.kind === 'map') {
+      if (ancestors.has(task.entries)) throw new Error(`harness.defineTool ${task.path} is circular`)
+      assertSchemaContainerKeys(task.entries, task.path)
+      ancestors.add(task.entries)
+      const spec: Record<string, unknown> = {}
+      assignNormalizedMap(task.destination, spec)
+      tasks.push({ kind: 'leave', value: task.entries })
+      const mapEntries = Object.entries(task.entries)
+      for (let index = mapEntries.length - 1; index >= 0; index--) {
+        const entry = mapEntries[index]
+        /* v8 ignore next -- the loop is bounded by the captured entry count. */
+        if (entry === undefined) continue
+        tasks.push({
+          kind: 'value',
+          value: entry[1],
+          path: `${task.path}.${entry[0]}`,
+          forceRequired: task.requiredNames.has(entry[0]),
+          raw: task.raw,
+          parameterProperty: true,
+          destination: { kind: 'property', target: spec, key: entry[0] },
+        })
+      }
+      continue
+    }
+
+    const { value, path } = task
+    if (!isPlainRecord(value)) {
+      throw new Error(`harness.defineTool ${path} must be a ParameterSchemaSpec property object`)
+    }
+    assertSchemaContainerKeys(value, path)
+    if (ancestors.has(value)) throw new Error(`harness.defineTool ${path} is circular`)
+    ancestors.add(value)
+    const requiredKey = task.parameterProperty && !task.raw ? ['required'] : []
+    if (task.parameterProperty && task.raw && Object.hasOwn(value, 'required') && value.type !== 'object') {
+      throw new Error(`harness.defineTool ${path}.required belongs to the containing raw object schema`)
+    }
+    if (task.parameterProperty && !task.raw && Object.hasOwn(value, 'required') && value.required !== true) {
+      throw new Error(`harness.defineTool ${path}.required must be true when present`)
+    }
+    const prop: Record<string, unknown> = {}
+    assignNormalizedValue(task.destination, prop)
+    tasks.push({ kind: 'leave', value })
+    if (task.forceRequired || value.required === true) prop.required = true
+    copyAnnotations(value, prop, path)
+
+    if (Object.hasOwn(value, 'oneOf')) {
+      assertSchemaKeys(value, path, ['oneOf', ...requiredKey, ...ANNOTATION_KEYS])
+      if (!isDensePlainArray(value.oneOf) || value.oneOf.length < 2) {
+        throw new Error(`harness.defineTool ${path}.oneOf must contain at least two schemas`)
+      }
+      const oneOf: Record<string, unknown>[] = []
+      prop.oneOf = oneOf
+      for (let index = value.oneOf.length - 1; index >= 0; index--) {
+        tasks.push({
+          kind: 'value',
+          value: value.oneOf[index],
+          path: `${path}.oneOf[${index}]`,
+          forceRequired: false,
+          raw: task.raw,
+          parameterProperty: false,
+          destination: { kind: 'one-of', target: oneOf, index },
+        })
+      }
+      continue
+    }
+
+    if (task.raw && !Object.hasOwn(value, 'type')) {
+      assertSchemaKeys(value, path, ANNOTATION_KEYS)
+      prop.type = 'json'
+      continue
+    }
+    if (!SCHEMA_TYPES.has(value.type) || task.raw && value.type === 'json') {
+      throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES} (got ${JSON.stringify(value.type)})`)
+    }
+    const type = value.type
+    prop.type = type
+
+    switch (type) {
+      case 'object': {
+        assertSchemaKeys(value, path, ['type', 'properties', 'additionalProperties', ...requiredKey, ...(task.raw ? ['required'] : []), ...ANNOTATION_KEYS])
+        if (!task.raw && (!Object.hasOwn(value, 'additionalProperties') || typeof value.additionalProperties !== 'boolean')) {
+          throw new Error(`harness.defineTool ${path}.additionalProperties must be explicitly true or false`)
+        }
+        if (task.raw && Object.hasOwn(value, 'additionalProperties') && typeof value.additionalProperties !== 'boolean') {
+          throw new Error(`harness.defineTool ${path}.additionalProperties must be a boolean`)
+        }
+        if (task.raw && Object.hasOwn(value, 'required') && value.required === undefined) {
+          throw new Error(`harness.defineTool ${path}.required must be an array of declared property names`)
+        }
+        prop.additionalProperties = task.raw ? value.additionalProperties ?? true : value.additionalProperties
+        if (Object.hasOwn(value, 'properties')) {
+          const properties = value.properties
+          if (!isPlainRecord(properties)) throw new Error(`harness.defineTool ${path}.properties must be an object of schemas`)
+          const nestedRequired = task.raw
+            ? normalizeRequiredNames(value.required, properties, `${path}.required`)
+            : new Set<string>()
+          tasks.push({
+            kind: 'map',
+            entries: properties,
+            path: `${path}.properties`,
+            requiredNames: nestedRequired,
+            raw: task.raw,
+            destination: { kind: 'properties', target: prop },
+          })
+        } else if (task.raw && value.required !== undefined) {
+          normalizeRequiredNames(value.required, {}, `${path}.required`)
+        }
+        break
+      }
+      case 'array':
+        assertSchemaKeys(value, path, ['type', 'items', ...requiredKey, ...ANNOTATION_KEYS])
+        if (Object.hasOwn(value, 'items')) {
+          tasks.push({
+            kind: 'value',
+            value: value.items,
+            path: `${path}.items`,
+            forceRequired: false,
+            raw: task.raw,
+            parameterProperty: false,
+            destination: { kind: 'item', target: prop },
+          })
+        }
+        break
+      case 'string':
+      case 'number':
+      case 'integer':
+      case 'boolean':
+      case 'null':
+        assertSchemaKeys(value, path, ['type', 'enum', 'const', ...requiredKey, ...ANNOTATION_KEYS])
+        if (Object.hasOwn(value, 'enum')) {
+          if (!isDensePlainArray(value.enum) || value.enum.length === 0) {
+            throw new Error(`harness.defineTool ${path}.enum must be a non-empty array`)
+          }
+          prop.enum = cloneJson(value.enum, `${path}.enum`)
+        }
+        if (Object.hasOwn(value, 'const')) prop.const = cloneJson(value.const, `${path}.const`)
+        break
+      case 'json':
+        assertSchemaKeys(value, path, ['type', ...requiredKey, ...ANNOTATION_KEYS])
+        break
+      /* v8 ignore next 2 -- SCHEMA_TYPES narrows this closed switch before dispatch. */
+      default:
+        throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES}`)
     }
-    prop.items = normalizeSchemaProp(value.items, `${path}.items`)
   }
-  return prop
+  /* v8 ignore next -- the root map task assigns before scheduling descendants. */
+  return holder.value ?? {}
 }
 
 function markDynamicTool(tool: ToolDefinition): DynamicToolDefinition {
@@ -127,60 +513,75 @@ const RETURN_PREVIEW_LIMIT = 120
  * (`String(…)` for the un-stringifiable undefined case), truncated to
  * {@link RETURN_PREVIEW_LIMIT}.
  */
-function describeReturn(value: unknown): string {
-  // JSON.stringify is TYPED as always returning string, but it yields
-  // undefined for an undefined input (the routed forgot-return case) — the
-  // assertion widens the type back to the runtime truth.
-  const json = JSON.stringify(value) as string | undefined
-  if (json === undefined) return String(value)
+function describeReturn(value: JsonValue): string {
+  // The caller has already crossed cloneJson, so this value is lossless JSON
+  // and serialization cannot produce undefined.
+  const json = JSON.stringify(value)
   return json.length > RETURN_PREVIEW_LIMIT ? `${json.slice(0, RETURN_PREVIEW_LIMIT)}…` : json
 }
 
 /**
- * Validate a round-tripped `execute` return against the two shapes
- * {@link ToolExecuteReturn} allows: an ARRAY of content blocks, or
- * `{ content: blocks, meta? }`. The registry trusts the shape blindly — it
- * spreads `result.content`, so an unvalidated `{ content: 'ok' }` would enter
- * the session log as `['o','k']` and silently corrupt the next model request —
- * so a wrong shape fails THIS call with a teaching error instead.
+ * Validate and host-materialize a sandbox renderer's content blocks.
  */
-function assertExecuteReturn(value: unknown): ToolExecuteReturn {
+function assertRenderedContent(value: JsonValue): ContentBlock[] {
   if (Array.isArray(value) && value.every(isContentBlockShape)) {
-    return value as ToolExecuteReturn
-  }
-  if (isPlainRecord(value) && Array.isArray(value.content) && value.content.every(isContentBlockShape)) {
-    return value as ToolExecuteReturn
+    return value as unknown as ContentBlock[]
   }
   throw new Error(
-    `execute returned ${describeReturn(value)} — a tool's execute must return an ARRAY of content blocks, never a bare string:\n`
-    + '  ✓ return [{ type: \'text\', text: someString }]\n'
-    + '  ✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }',
+    `output.render returned ${describeReturn(value)} — it must return an ARRAY of content blocks:\n`
+    + '  ✓ return [{ type: \'text\', text: String(value) }]',
   )
 }
 
 /**
  * The `harness.defineTool` handed into the sandbox: the real DSL, with `parameters` normalized
- * into a fresh host-realm SchemaSpec (JSON-Schema wrapper unwrapped, `integer` mapped,
- * `required: false` dropped) and the tool's `execute` return normalized into the host realm
+ * into a fresh host-realm ParameterSchemaSpec (raw object wrappers unwrapped,
+ * required arrays mapped, and explicit DSL object openness enforced) and the tool's `execute` return normalized into the host realm
  * via a JSON round-trip. Non-JSON or wrong-shape output fails that call instead of poisoning
  * the session log.
- * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper.
+ * @param options - the standard `defineTool` options; `parameters` may be the ParameterSchemaSpec DSL or a JSON-Schema-style wrapper.
  * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts.
  */
-export function sandboxDefineTool(options: Parameters<typeof defineTool>[0]): ToolDefinition {
-  const parameters = normalizeSchemaSpec((options as { parameters?: unknown }).parameters)
-  const tool = defineTool({ ...options, parameters } as Parameters<typeof defineTool>[0])
-  const execute = tool.execute.bind(tool)
+export function sandboxDefineTool(options: unknown): ToolDefinition {
+  if (!isPlainRecord(options)) throw new Error('harness.defineTool options must be an object')
+  const normalized = normalizeParameterSchemaSpec(options.parameters)
+  if (!isPlainRecord(options.output)) {
+    throw new Error('harness.defineTool output must declare { schema, render, presentationMeta? }')
+  }
+  const output = options.output
+  if (typeof output.render !== 'function') throw new Error('harness.defineTool output.render must be a function')
+  if (output.presentationMeta !== undefined && typeof output.presentationMeta !== 'function') {
+    throw new Error('harness.defineTool output.presentationMeta must be a function when present')
+  }
+  if (typeof options.execute !== 'function') throw new Error('harness.defineTool execute must be a function')
+  const schema = cloneJson(output.schema, 'output.schema')
+  const rawExecute = options.execute as (args: unknown, exec: unknown) => Promise<unknown>
+  const rawRender = output.render as (args: unknown, value: unknown) => unknown
+  const rawPresentationMeta = output.presentationMeta as ((args: unknown, value: unknown) => unknown) | undefined
+  const erasedDefineTool = defineTool as unknown as (definition: unknown) => ToolDefinition
+  const tool = erasedDefineTool({
+    ...options,
+    parameters: normalized.spec,
+    output: {
+      schema,
+      render(args: unknown, value: unknown): ContentBlock[] {
+        return assertRenderedContent(cloneJson(rawRender(args, value), 'output.render result') as JsonValue)
+      },
+      ...rawPresentationMeta !== undefined ? {
+        presentationMeta(args: unknown, value: unknown): JsonValue {
+          return cloneJson(rawPresentationMeta(args, value), 'output.presentationMeta result') as JsonValue
+        },
+      } : {},
+    },
+    async execute(args: unknown, exec: unknown): Promise<JsonValue> {
+      return cloneJson(await rawExecute(args, exec), 'execute result') as JsonValue
+    },
+  })
+  const parameters = { ...tool.parameters, ...normalized.rootAnnotations }
+  assertSupportedJsonSchema(parameters)
   return markDynamicTool({
     ...tool,
-    async execute(args, exec) {
-      // JSON.stringify yields NO JSON for an undefined (or function/symbol)
-      // return despite its string-typed signature — route that into
-      // assertExecuteReturn's teaching error rather than letting JSON.parse
-      // throw its cryptic '"undefined" is not valid JSON'.
-      const json = JSON.stringify(await execute(args, exec)) as string | undefined
-      return assertExecuteReturn(json === undefined ? undefined : JSON.parse(json) as unknown)
-    },
+    parameters,
   })
 }
 
diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts
index 4fc5bd4328..15fd735468 100644
--- a/packages/cordis/tool-cordis/src/index.ts
+++ b/packages/cordis/tool-cordis/src/index.ts
@@ -13,7 +13,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { STATE_LABELS } from './fiber-state.ts'
 import { isPlugin, pluginName } from './guard.ts'
 import { EVENT_API, INHERITED_CTX_API, SERVICE_API, TYPE_API } from './api-catalog.ts'
-import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools } from './inspect.ts'
+import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools, providedServices } from './inspect.ts'
 import { missingServices, mountDynamic, type DynamicMount } from './mount.ts'
 import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts'
 import { createSandbox, evaluateMountCode } from './sandbox.ts'
@@ -76,7 +76,11 @@ export function apply(ctx: Context, config: Config): void {
         description: 'Exact service key or event name whose original JSDoc to include; valid only with what:"api" or what:"events".',
       },
     },
-    execute(args, exec): Promise<{ type: 'text'; text: string }[]> {
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    execute(args, exec): Promise<string> {
       if (args.name !== undefined && args.what !== 'api' && args.what !== 'events') {
         throw new Error('name is valid only with what:"api" or what:"events"')
       }
@@ -94,7 +98,7 @@ export function apply(ctx: Context, config: Config): void {
       const text = selected
         .map(([heading, body]) => `## ${heading}\n${body().join('\n')}`)
         .join('\n\n')
-      return Promise.resolve([{ type: 'text', text }])
+      return Promise.resolve(text)
     },
     presentCall: presentInspectCall,
   }))
@@ -119,13 +123,14 @@ export function apply(ctx: Context, config: Config): void {
       + '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 } }, async execute(args) { … } }))` '
+      + '{ 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\'|\'boolean\'|\'object\'|\'array\', '
-      + 'required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style '
-      + '{ type: \'object\', properties, required: […] } wrapper and type \'integer\' are also accepted and normalized. A '
-      + 'tool\'s `execute` MUST return an ARRAY of content blocks, e.g. `return '
-      + '[{ type: \'text\', text: someString }]` — never a bare string. '
+      + '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. '
       + 'Mounts 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. '
@@ -157,6 +162,32 @@ export function apply(ctx: Context, config: Config): void {
         description: 'Body of an async JS function; must `return` the plugin to mount.',
       },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          pluginName: { type: 'string', required: true },
+          state: {
+            type: 'string',
+            required: true,
+            enum: ['pending', 'loading', 'active', 'failed', 'disposed', 'unloading'],
+          },
+          provides: { type: 'array', required: true, items: { type: 'string' } },
+          waitingFor: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => {
+        const note = value.waitingFor.length > 0
+          ? ` — waiting for service(s): ${value.waitingFor.join(', ')} (activates when provided)`
+          : ''
+        return [{
+          type: 'text',
+          text: `mounted ${value.id} (plugin "${value.pluginName}", state: ${value.state}${note})`,
+        }]
+      },
+    },
     async execute(args) {
       const id = `dyn-${nextId++}`
       const sandbox = createSandbox(id)
@@ -180,10 +211,13 @@ export function apply(ctx: Context, config: Config): void {
       // it mounted but tell the model what it is waiting for.
       const missing = missingServices(ctx, fiber)
       const state = STATE_LABELS[fiber.state]
-      const note = missing.length > 0
-        ? ` — waiting for service(s): ${missing.join(', ')} (activates when provided)`
-        : ''
-      return [{ type: 'text', text: `mounted ${id} (plugin "${pluginName(evaluated)}", state: ${state}${note})` }]
+      return {
+        id,
+        pluginName: pluginName(evaluated),
+        state,
+        provides: providedServices(ctx, fiber),
+        waitingFor: missing,
+      }
     },
     presentCall: presentMountCall,
   }))
@@ -202,6 +236,17 @@ export function apply(ctx: Context, config: Config): void {
         description: 'The dynamic mount id returned by cordis_mount (e.g. "dyn-1").',
       },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          pluginName: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `unmounted ${value.id} (plugin "${value.pluginName}")` }],
+    },
     async execute(args) {
       const mount = mounts.get(args.id)
       if (!mount) {
@@ -209,7 +254,7 @@ export function apply(ctx: Context, config: Config): void {
       }
       await mount.fiber.dispose()
       mounts.delete(args.id)
-      return [{ type: 'text', text: `unmounted ${args.id} (plugin "${mount.pluginName}")` }]
+      return { id: args.id, pluginName: mount.pluginName }
     },
     presentCall: presentUnmountCall,
   }))
diff --git a/packages/cordis/tool-cordis/src/inspect.ts b/packages/cordis/tool-cordis/src/inspect.ts
index 7196f370ce..cdcad29699 100644
--- a/packages/cordis/tool-cordis/src/inspect.ts
+++ b/packages/cordis/tool-cordis/src/inspect.ts
@@ -33,8 +33,13 @@ function withinFiber(fiber: Fiber, root: Fiber): boolean {
   }
 }
 
-/** The service names provided by a mount's fiber subtree, sorted. */
-function providedBy(ctx: Context, fiber: Fiber): string[] {
+/**
+ * Return the service names provided by a mount's fiber subtree.
+ * @param ctx - the runtime whose service registrations are inspected.
+ * @param fiber - the root of the mounted fiber subtree.
+ * @returns the provided service names in lexical order.
+ */
+export function providedServices(ctx: Context, fiber: Fiber): string[] {
   return liveImpls(ctx)
     .filter(impl => withinFiber(impl.fiber, fiber))
     .map(impl => impl.name)
@@ -96,7 +101,7 @@ export function describeTools(ctx: Context, scope?: ScopeKey): string[] {
 export function describeDynamic(ctx: Context, mounts: ReadonlyMap<string, DynamicMount>): string[] {
   if (mounts.size === 0) return ['(no dynamic plugins mounted)']
   return [...mounts].map(([id, mount]) => {
-    const provides = providedBy(ctx, mount.fiber)
+    const provides = providedServices(ctx, mount.fiber)
     const waiting = missingServices(ctx, mount.fiber)
     const providesNote = provides.length > 0 ? ` — provides: ${provides.join(', ')}` : ''
     const waitingNote = waiting.length > 0 ? ` — waiting for: ${waiting.join(', ')}` : ''
diff --git a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts
index dcfdb815c4..b2e515b4c8 100644
--- a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts
+++ b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { call, CONSUMER_CODE, PROVIDER_CODE, setup, text } from './helpers.ts'
+import { call, CONSUMER_CODE, CONTENT_OUTPUT_CODE, PROVIDER_CODE, setup, text } from './helpers.ts'
 
 /**
  * Cross-mount composition through ordinary cordis provide/inject semantics:
@@ -116,6 +116,7 @@ describe('cross-mount provide/inject', () => {
               name: 'answer',
               description: 'Read the provided primitive services.',
               parameters: {},
+              ${CONTENT_OUTPUT_CODE}
               async execute() {
                 return [{ type: 'text', text: ctx.answer + '/' + ctx.get('answer') + '/' + ctx.nothing }]
               },
diff --git a/packages/cordis/tool-cordis/tests/helpers.ts b/packages/cordis/tool-cordis/tests/helpers.ts
index e945249814..b049c6c1fa 100644
--- a/packages/cordis/tool-cordis/tests/helpers.ts
+++ b/packages/cordis/tool-cordis/tests/helpers.ts
@@ -47,6 +47,13 @@ export const LISTENER_CODE = `
   }
 `
 
+/** Explicit content-array output declaration for dynamic-tool behavior fixtures. */
+export const CONTENT_OUTPUT_CODE = `
+              output: {
+                schema: { type: 'array', items: { type: 'json' } },
+                render(_args, value) { return value },
+              },`
+
 /** Mount code for a self-made tool: registers `reverse_text` via the sandbox's harness helpers. */
 export const REVERSE_TOOL_CODE = `
   return {
@@ -57,8 +64,14 @@ export const REVERSE_TOOL_CODE = `
         name: 'reverse_text',
         description: 'Reverse a string.',
         parameters: { text: { type: 'string', required: true } },
+        output: {
+          schema: { type: 'string' },
+          render(_args, value) {
+            return [{ type: 'text', text: value }]
+          },
+        },
         async execute(args) {
-          return [{ type: 'text', text: args.text.split('').reverse().join('') }]
+          return args.text.split('').reverse().join('')
         },
       }))
     },
@@ -85,8 +98,14 @@ export const CONSUMER_CODE = `
         name: 'greet',
         description: 'Greet someone via the greeter service.',
         parameters: { name: { type: 'string', required: true } },
+        output: {
+          schema: { type: 'string' },
+          render(_args, value) {
+            return [{ type: 'text', text: value }]
+          },
+        },
         async execute(args) {
-          return [{ type: 'text', text: ctx.greeter.greet(args.name) }]
+          return ctx.greeter.greet(args.name)
         },
       }))
     },
@@ -99,8 +118,9 @@ export function dummyTool(name: string): ToolDefinition {
     name,
     description: 'test trigger',
     parameters: { type: 'object' as const, properties: {} },
-    async execute(): Promise<[]> {
-      return []
+    output: { schema: { type: 'null' }, render: () => [] },
+    async execute(): Promise<null> {
+      return null
     },
   }
 }
diff --git a/packages/cordis/tool-cordis/tests/inspect.spec.ts b/packages/cordis/tool-cordis/tests/inspect.spec.ts
index 4d986d4f3e..18b4d04df7 100644
--- a/packages/cordis/tool-cordis/tests/inspect.spec.ts
+++ b/packages/cordis/tool-cordis/tests/inspect.spec.ts
@@ -16,6 +16,8 @@ describe('cordis_inspect', () => {
     const result = await call(ctx, 'cordis_inspect', {})
     expect(result.isError).toBe(false)
     const report = text(result)
+    if (result.isError) throw new Error('expected cordis_inspect success')
+    expect(result.value).toBe(report)
     for (const heading of ['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) {
       expect(report).toContain(`## ${heading}`)
     }
@@ -59,6 +61,8 @@ describe('cordis_inspect', () => {
     // generated TYPE_API — a consumer can see field types, not just names).
     expect(report).toContain('type shapes (referenced by the signatures above')
     expect(report).toContain('export interface ToolExecution')
+    expect(report).toContain('export class Session')
+    expect(report).toContain('export interface SessionSurface')
     // A type only reachable through a NOT-live service (e.g. bash) is scoped out.
     expect(report).not.toContain('export interface BashRunResult')
     // The inherited ctx surface closes the section.
@@ -76,7 +80,7 @@ describe('cordis_inspect', () => {
     expect(report).toContain('- tools — Tool registry and execution pipeline.')
     expect(report).toContain('/**')
     expect(report).toContain('Register globally or in the calling agent scope.')
-    expect(report).toContain('@param definition - the tool schema')
+    expect(report).toContain('@param definition - tool schema, execution, and optional finalization/presentation callbacks')
     expect(report).toContain('@returns the exact disposer')
     expect(report).toContain('register(definition: ToolDefinition)')
     expect(report).toContain('type shapes (referenced by the signatures above')
diff --git a/packages/cordis/tool-cordis/tests/integration.spec.ts b/packages/cordis/tool-cordis/tests/integration.spec.ts
index d68f6be349..7f917e5b3c 100644
--- a/packages/cordis/tool-cordis/tests/integration.spec.ts
+++ b/packages/cordis/tool-cordis/tests/integration.spec.ts
@@ -47,7 +47,7 @@ describe('cordis tools through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-cordis'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }])
+    agent.followup([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }])
     await waitForIdle(ctx, agent)
 
     const log = agent.session.events
diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts
index 2ddee8dbca..a354de0b37 100644
--- a/packages/cordis/tool-cordis/tests/mount.spec.ts
+++ b/packages/cordis/tool-cordis/tests/mount.spec.ts
@@ -1,7 +1,8 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { isJsonValue } from '@deepseek-ai/dsh-session'
+import { sandboxDefineTool } from '../src/guard.ts'
 import { syntaxErrorContext } from '../src/sandbox.ts'
-import { call, dummyTool, LISTENER_CODE, REVERSE_TOOL_CODE, setup, text } from './helpers.ts'
+import { call, CONTENT_OUTPUT_CODE, dummyTool, LISTENER_CODE, REVERSE_TOOL_CODE, setup, text } from './helpers.ts'
 
 /**
  * The `cordis_mount` success/failure family: real plugins land on a genuine
@@ -14,12 +15,48 @@ afterEach(() => {
 })
 
 describe('cordis_mount', () => {
+  it.each([
+    [42, 'options must be an object'],
+    [{ parameters: {} }, 'output must declare { schema, render, presentationMeta? }'],
+    [{ parameters: {}, output: { schema: { type: 'json' } }, execute: async (): Promise<null> => null }, 'output.render must be a function'],
+    [{ parameters: {}, output: { schema: { type: 'json' }, render: () => [] }, execute: true }, 'execute must be a function'],
+    [{
+      parameters: {},
+      output: { schema: { type: 'json' }, render: () => [], presentationMeta: true },
+      execute: async (): Promise<null> => null,
+    }, 'output.presentationMeta must be a function'],
+  ])('rejects an invalid dynamic tool declaration before registration: %j', (definition, message) => {
+    expect(() => sandboxDefineTool(definition)).toThrow(message)
+  })
+
+  it('bounds the preview of an invalid dynamic renderer return', () => {
+    const definition = sandboxDefineTool({
+      name: 'invalid-renderer',
+      description: 'invalid renderer',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: () => ['x'.repeat(500)],
+      },
+      execute: async () => 'ok',
+    })
+    expect(() => definition.output.render({}, 'ok')).toThrow(/output\.render returned \["x+…/)
+  })
+
   it('mounts a listener plugin that observes real events, tagged-logging through to the host console', async () => {
     const ctx = await setup()
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
 
     const result = await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected cordis_mount success')
+    expect(result.value).toEqual({
+      id: 'dyn-1',
+      pluginName: 'change-logger',
+      state: 'active',
+      provides: [],
+      waitingFor: [],
+    })
     expect(text(result)).toContain('mounted dyn-1 (plugin "change-logger", state: active)')
 
     // Fire a REAL tools/change by registering a tool; the mounted listener logs.
@@ -44,6 +81,8 @@ describe('cordis_mount', () => {
     expect(ctx.tools.schemas().map(schema => schema.name)).toContain('reverse_text')
     const reversed = await call(ctx, 'reverse_text', { text: 'harness' })
     expect(reversed.isError).toBe(false)
+    if (reversed.isError) throw new Error('expected dynamic tool success')
+    expect(reversed.value).toBe('ssenrah')
     expect(text(reversed)).toBe('ssenrah')
   })
 
@@ -55,7 +94,7 @@ describe('cordis_mount', () => {
     expect(isJsonValue({ content: reversed.content, isError: reversed.isError })).toBe(true)
   })
 
-  it('threads the { content, meta } object return form through to the registry result', async () => {
+  it('projects presentation metadata from a dynamic canonical value', async () => {
     const ctx = await setup()
     await call(ctx, 'cordis_mount', {
       code: `
@@ -67,8 +106,13 @@ describe('cordis_mount', () => {
               name: 'meta_tool',
               description: 'attaches a private presentation payload',
               parameters: {},
+              output: {
+                schema: { type: 'string' },
+                render(_args, value) { return [{ type: 'text', text: value }] },
+                presentationMeta() { return { kind: 'demo' } },
+              },
               async execute() {
-                return { content: [{ type: 'text', text: 'ok' }], meta: { kind: 'demo' } }
+                return 'ok'
               },
             }))
           },
@@ -77,20 +121,20 @@ describe('cordis_mount', () => {
     })
     const result = await call(ctx, 'meta_tool', {})
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected dynamic tool success')
+    expect(result.value).toBe('ok')
     expect(text(result)).toBe('ok')
     expect(result.meta).toEqual({ kind: 'demo' })
   })
 
   it.each([
-    ['a bare string', 'return \'ok\'', '"ok"'],
-    ['an object whose content is a string', 'return { content: \'ok\' }', '{"content":"ok"}'],
-    ['an array of non-objects', 'return [\'ok\']', '["ok"]'],
-    ['blocks missing the type tag', 'return [{ text: \'hi\' }]', '[{"text":"hi"}]'],
-    ['object-form blocks missing the type tag', 'return { content: [{ text: \'hi\' }] }', '{"content":[{"text":"hi"}]}'],
-    ['undefined — a forgotten return', 'return undefined', 'undefined'],
-  ])('rejects an execute return of %s as that one call\'s teaching error', async (_label, returnStatement, preview) => {
-    // The registry spreads result.content, so { content: 'ok' } would become ['o','k']; reject
-    // it as this call's error before it corrupts the next request.
+    ['a bare string', 'return \'ok\'', 'returned invalid output: "value" must be an array'],
+    ['an object whose content is a string', 'return { content: \'ok\' }', 'returned invalid output: "value" must be an array'],
+    ['an array of non-objects', 'return [\'ok\']', 'output.render returned ["ok"]'],
+    ['blocks missing the type tag', 'return [{ text: \'hi\' }]', 'output.render returned [{"text":"hi"}]'],
+    ['object-form blocks missing the type tag', 'return { content: [{ text: \'hi\' }] }', 'returned invalid output: "value" must be an array'],
+    ['undefined — a forgotten return', 'return undefined', 'execute result must be lossless JSON data'],
+  ])('rejects an execute return of %s against its declared output', async (_label, returnStatement, diagnostic) => {
     const ctx = await setup()
     await call(ctx, 'cordis_mount', {
       code: `
@@ -102,6 +146,7 @@ describe('cordis_mount', () => {
               name: 'bad_return_tool',
               description: 'returns a wrong shape',
               parameters: {},
+              ${CONTENT_OUTPUT_CODE}
               async execute() { ${returnStatement} },
             }))
           },
@@ -112,12 +157,10 @@ describe('cordis_mount', () => {
     expect(result.isError).toBe(true)
     expect(result.content).toHaveLength(1)
     expect(result.content[0]!.type).toBe('text')
-    expect(text(result)).toContain(`execute returned ${preview}`)
-    expect(text(result)).toContain('must return an ARRAY of content blocks')
-    expect(text(result)).toContain('✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }')
+    expect(text(result)).toContain(diagnostic)
   })
 
-  it('truncates a huge invalid execute return in the teaching error', async () => {
+  it('does not echo a huge schema-invalid canonical value in the diagnostic', async () => {
     const ctx = await setup()
     await call(ctx, 'cordis_mount', {
       code: `
@@ -129,6 +172,7 @@ describe('cordis_mount', () => {
               name: 'huge_return_tool',
               description: 'returns a huge wrong shape',
               parameters: {},
+              ${CONTENT_OUTPUT_CODE}
               async execute() { return 'x'.repeat(500) },
             }))
           },
@@ -137,7 +181,7 @@ describe('cordis_mount', () => {
     })
     const result = await call(ctx, 'huge_return_tool', {})
     expect(result.isError).toBe(true)
-    expect(text(result)).toContain('…')
+    expect(text(result)).toContain('returned invalid output')
     expect(text(result)).not.toContain('x'.repeat(200))
   })
 
@@ -156,14 +200,18 @@ describe('cordis_mount', () => {
               description: 'written in the JSON-Schema dialect',
               parameters: {
                 type: 'object',
+                title: 'Raw parameters',
+                default: { text: 'default' },
+                examples: [{ text: 'example' }],
                 properties: {
                   text: { type: 'string', description: 'the text' },
                   count: { type: 'integer', default: 1 },
                   mode: { type: 'string', enum: ['fast', 'slow'] },
-                  extra: { type: 'string', required: false },
+                  extra: { type: 'string' },
                 },
                 required: ['text'],
               },
+              ${CONTENT_OUTPUT_CODE}
               async execute(args) { return [{ type: 'text', text: args.text + ':' + (args.count ?? 0) }] },
             }))
           },
@@ -173,14 +221,19 @@ describe('cordis_mount', () => {
     expect(result.isError).toBe(false)
 
     // The registered schema is canonical JSON Schema derived from the DSL:
-    // the required array survived, integer became number, extra is optional.
+    // the required array survived, integer stayed integer, extra is optional.
     const schema = ctx.tools.schemas().find(s => s.name === 'json_schema_tool')!
     const parameters = schema.parameters as {
       properties: Record<string, { type: string; enum?: string[]; default?: unknown }>
       required?: string[]
     }
     expect(parameters.required).toEqual(['text'])
-    expect(parameters.properties.count!.type).toBe('number')
+    expect(parameters).toMatchObject({
+      title: 'Raw parameters',
+      default: { text: 'default' },
+      examples: [{ text: 'example' }],
+    })
+    expect(parameters.properties.count!.type).toBe('integer')
     expect(parameters.properties.count!.default).toBe(1)
     expect(parameters.properties.mode!.enum).toEqual(['fast', 'slow'])
     // Arg validation enforces the normalized spec: text required, extra not.
@@ -202,8 +255,12 @@ describe('cordis_mount', () => {
               name: 'nested_json_schema_tool',
               description: 'nested dialect',
               parameters: {
-                cfg: { type: 'object', properties: { label: { type: 'string' } }, required: ['label'] },
+                type: 'object',
+                properties: {
+                  cfg: { type: 'object', properties: { label: { type: 'string' } }, required: ['label'] },
+                },
               },
+              ${CONTENT_OUTPUT_CODE}
               async execute(args) { return [{ type: 'text', text: args.cfg.label }] },
             }))
           },
@@ -217,14 +274,198 @@ describe('cordis_mount', () => {
     expect(text(await call(ctx, 'nested_json_schema_tool', { cfg: { label: 'hi' } }))).toBe('hi')
   })
 
+  it('normalizes every unified DSL node and lossless annotation shape across the sandbox realm', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'unified-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'unified_schema_tool',
+              description: 'all unified nodes',
+              parameters: {
+                any: {
+                  type: 'json',
+                  title: 'Any JSON',
+                  default: { nested: [1, 'x', null] },
+                  examples: [{ ok: true }],
+                },
+                choice: {
+                  oneOf: [{ type: 'string', const: 'x' }, { type: 'null' }],
+                  required: true,
+                },
+                flags: { type: 'array' },
+                closed: { type: 'object', additionalProperties: false },
+                count: { type: 'number', enum: [1, 2], const: 1 },
+              },
+              ${CONTENT_OUTPUT_CODE}
+              async execute(args) { return [{ type: 'text', text: String(args.choice) }] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    const schema = ctx.tools.schemas().find(s => s.name === 'unified_schema_tool')!
+    expect(schema.parameters).toMatchObject({
+      properties: {
+        any: { title: 'Any JSON', default: { nested: [1, 'x', null] }, examples: [{ ok: true }] },
+        choice: { oneOf: [{ type: 'string', const: 'x' }, { type: 'null' }] },
+        flags: { type: 'array' },
+        closed: { type: 'object', additionalProperties: false },
+        count: { type: 'number', enum: [1, 2], const: 1 },
+      },
+      required: ['choice'],
+    })
+  })
+
+  it('normalizes and snapshots deeply nested sandbox schemas and annotations stack-safely', async () => {
+    const ctx = await setup()
+    const depth = 5_000
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'deep-unified-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            let choice = { type: 'string' }
+            let example = 'leaf'
+            for (let index = 0; index < ${depth}; index++) {
+              choice = { oneOf: [choice, { type: 'null' }] }
+              example = [example]
+            }
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'deep_unified_schema_tool',
+              description: 'deep unified nodes',
+              parameters: {
+                choice: { ...choice, required: true },
+                any: { type: 'json', default: example },
+              },
+              ${CONTENT_OUTPUT_CODE}
+              async execute() { return [] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+
+    const parameters = ctx.tools.schemas().find(s => s.name === 'deep_unified_schema_tool')!.parameters as {
+      properties: Record<string, Record<string, unknown>>
+    }
+    let choice = parameters.properties.choice!
+    let choiceDepth = 0
+    while (Array.isArray(choice.oneOf)) {
+      choice = choice.oneOf[0] as Record<string, unknown>
+      choiceDepth++
+    }
+    let example: unknown = parameters.properties.any!.default
+    let exampleDepth = 0
+    while (Array.isArray(example)) {
+      example = example[0]
+      exampleDepth++
+    }
+    expect({ choiceDepth, choice, exampleDepth, example }).toEqual({
+      choiceDepth: depth,
+      choice: { type: 'string' },
+      exampleDepth: depth,
+      example: 'leaf',
+    })
+  })
+
+  it('normalizes unconstrained and closed nested nodes from a raw JSON Schema wrapper', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'raw-unified-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'raw_unified_schema_tool',
+              description: 'raw unified nodes',
+              parameters: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                  any: { description: 'unconstrained' },
+                  cfg: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: { label: { type: 'string' } },
+                    required: ['label'],
+                  },
+                  choice: { oneOf: [{ type: 'boolean' }, { type: 'null' }] },
+                },
+              },
+              ${CONTENT_OUTPUT_CODE}
+              async execute() { return [] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    expect(ctx.tools.schemas().find(s => s.name === 'raw_unified_schema_tool')!.parameters).toMatchObject({
+      properties: {
+        any: {},
+        cfg: { additionalProperties: false, required: ['label'] },
+        choice: { oneOf: [{ type: 'boolean' }, { type: 'null' }] },
+      },
+    })
+  })
+
   it.each([
-    ['parameters: 42', 'must be a SchemaSpec object'],
-    ['parameters: { text: 42 }', 'parameters.text must be a SchemaSpec property object'],
-    ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type: \'string\' | \'number\' | \'boolean\' | \'object\' | \'array\' (got "str")'],
-    ['parameters: { text: { type: \'string\', required: \'yes\' } }', 'parameters.text.required must be a boolean when present'],
-    ['parameters: { text: { type: \'string\', properties: {} } }', 'parameters.text.properties is only valid for type "object"'],
-    ['parameters: { text: { type: \'string\', items: { type: \'string\' } } }', 'parameters.text.items is only valid for type "array"'],
-  ])('rejects a malformed SchemaSpec (%s) with a teaching error', async (parameters, message) => {
+    ['parameters: 42', 'must be a ParameterSchemaSpec object'],
+    ['parameters: Object.defineProperty({}, \'text\', { value: { type: \'string\' } })', 'parameters must contain only own enumerable string keys'],
+    ['parameters: { text: 42 }', 'parameters.text must be a ParameterSchemaSpec property object'],
+    ['parameters: { text: Object.defineProperty({ type: \'string\' }, \'minimum\', { value: 1 }) }', 'parameters.text must contain only own enumerable string keys'],
+    ['parameters: { text: { type: \'string\', [Symbol(\'hidden\')]: true } }', 'parameters.text must contain only own enumerable string keys'],
+    ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type: \'string\' | \'number\' | \'integer\' | \'boolean\' | \'null\' | \'object\' | \'array\' | \'json\' (got "str")'],
+    ['parameters: { text: { type: \'string\', required: \'yes\' } }', 'parameters.text.required must be true when present'],
+    ['parameters: { text: { type: \'string\', properties: {} } }', 'parameters.text.properties is not supported by the unified schema DSL'],
+    ['parameters: { text: { type: \'string\', items: { type: \'string\' } } }', 'parameters.text.items is not supported by the unified schema DSL'],
+    ['parameters: { text: { type: \'object\', properties: {} } }', 'parameters.text.additionalProperties must be explicitly true or false'],
+    ['parameters: { text: { type: \'object\', additionalProperties: \'no\' } }', 'parameters.text.additionalProperties must be explicitly true or false'],
+    ['parameters: { type: \'object\' }', 'parameters.properties must be an object of schemas'],
+    ['parameters: { type: \'object\', properties: {}, additionalProperties: false }', 'parameters.additionalProperties must be true or omitted'],
+    ['parameters: { type: \'object\', properties: {}, required: \'text\' }', 'parameters.required must be an array of declared property names'],
+    ['parameters: { type: \'object\', properties: {}, required: undefined }', 'parameters.required must be an array of declared property names'],
+    ['parameters: { type: \'object\', properties: {}, required: [42] }', 'parameters.required must be an array of declared property names'],
+    ['parameters: (() => { const required = []; required.length = 1; return { type: \'object\', properties: {}, required } })()', 'parameters.required must be an array of declared property names'],
+    ['parameters: (() => { const required = []; required.length = 1; required.extra = true; return { type: \'object\', properties: {}, required } })()', 'parameters.required must be an array of declared property names'],
+    ['parameters: (() => { class Names extends Array { *[Symbol.iterator]() {} }; const required = new Names(); required[0] = \'text\'; required.length = 1; return { type: \'object\', properties: { text: { type: \'string\' } }, required } })()', 'parameters.required must be an array of declared property names'],
+    ['parameters: { type: \'object\', properties: {}, required: [\'text\'] }', 'parameters.required names undeclared property "text"'],
+    ['parameters: { type: \'object\', properties: { text: { type: \'string\', required: true } } }', 'parameters.text.required belongs to the containing raw object schema'],
+    ['parameters: { type: \'object\', properties: { text: { oneOf: \'bad\' } } }', 'parameters.text.oneOf must contain at least two schemas'],
+    ['parameters: { type: \'object\', properties: { text: { type: \'json\' } } }', 'parameters.text must declare a valid type'],
+    ['parameters: { type: \'object\', properties: { cfg: { type: \'object\', additionalProperties: \'no\' } } }', 'parameters.cfg.additionalProperties must be a boolean'],
+    ['parameters: { type: \'object\', properties: { cfg: { type: \'object\', properties: 42 } } }', 'parameters.cfg.properties must be an object of schemas'],
+    ['parameters: { type: \'object\', properties: { cfg: { type: \'object\', required: [\'label\'] } } }', 'parameters.cfg.required names undeclared property "label"'],
+    ['parameters: { type: \'object\', properties: { cfg: { type: \'object\', required: undefined } } }', 'parameters.cfg.required must be an array of declared property names'],
+    ['parameters: { value: { oneOf: \'bad\' } }', 'parameters.value.oneOf must contain at least two schemas'],
+    ['parameters: { value: { oneOf: new (class Branches extends Array {})({ type: \'string\' }, { type: \'null\' }) } }', 'parameters.value.oneOf must contain at least two schemas'],
+    ['parameters: { value: { oneOf: Object.assign([{ type: \'string\' }, { type: \'null\' }], { extra: true }) } }', 'parameters.value.oneOf must contain at least two schemas'],
+    ['parameters: { value: { type: \'string\', enum: \'bad\' } }', 'enum must be a non-empty array'],
+    ['parameters: { value: { type: \'string\', enum: new (class Values extends Array {})(\'a\', \'b\') } }', 'parameters.value.enum must be a non-empty array'],
+    ['parameters: { value: { type: \'json\', default: -0 } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: Infinity } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: () => 1 } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: (() => { const v = {}; v.self = v; return v })() } }', 'parameters.value.default.self must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: Array(2) } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: Object.assign([1], { extra: true }) } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: (() => { const v = Array(1); v.extra = true; return v })() } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: Object.defineProperty({}, \'hidden\', { value: true }) } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: { [Symbol(\'hidden\')]: true } } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: new (class DefaultValue { constructor() { this.ok = true } })() } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: new (class DefaultList extends Array {})() } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: { value: { type: \'json\', default: new Date(0) } }', 'parameters.value.default must be lossless JSON data'],
+    ['parameters: (() => { const p = Object.create(null); const C = function C() {}; Object.defineProperty(C, \'name\', { value: \'Object\' }); C.prototype = p; Object.defineProperty(p, \'constructor\', { value: C }); return Object.create(p) })()', 'must be a ParameterSchemaSpec object'],
+    ['parameters: (() => { const p = Object.create(null); const C = function C() {}; Object.defineProperty(C, \'name\', { value: \'Object\' }); C.prototype = p; const r = Proxy.revocable(C, {}); Object.defineProperty(p, \'constructor\', { value: r.proxy }); r.revoke(); return Object.create(p) })()', 'must be a ParameterSchemaSpec object'],
+    ['parameters: Object.create(Object.create(null))', 'must be a ParameterSchemaSpec object'],
+  ])('rejects a malformed ParameterSchemaSpec (%s) with a teaching error', async (parameters, message) => {
     const ctx = await setup()
     const result = await call(ctx, 'cordis_mount', {
       code: `
@@ -236,6 +477,7 @@ describe('cordis_mount', () => {
               name: 'bad_schema_tool',
               description: 'bad',
               ${parameters},
+              ${CONTENT_OUTPUT_CODE}
               async execute() { return [] },
             }))
           },
@@ -246,7 +488,83 @@ describe('cordis_mount', () => {
     expect(text(result)).toContain(message)
   })
 
-  it('accepts a nested object/array SchemaSpec (the DSL recursion)', async () => {
+  it.each([
+    [
+      `
+        const parameters = {}
+        const item = { type: 'array' }
+        item.items = item
+        parameters.item = item
+      `,
+      'parameters.item.items is circular',
+    ],
+    [
+      `
+        const parameters = {}
+        const item = { type: 'object', additionalProperties: true, properties: parameters }
+        parameters.item = item
+      `,
+      'parameters.item.properties is circular',
+    ],
+  ])('rejects circular sandbox schemas without exhausting the call stack', async (declaration, message) => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'circular-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            ${declaration}
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'circular_schema_tool',
+              description: 'circular',
+              parameters,
+              async execute() { return [] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain(message)
+  })
+
+  it('preserves literal __proto__ keys in sandbox schemas and annotations', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'proto-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'proto_schema_tool',
+              description: 'literal JSON keys',
+              parameters: {
+                ['__proto__']: { type: 'string', required: true },
+                value: { type: 'json', default: { ['__proto__']: { safe: true } } },
+              },
+              ${CONTENT_OUTPUT_CODE}
+              async execute() { return [] },
+            }))
+          },
+        }
+      `,
+    })
+
+    expect(result.isError).toBe(false)
+    const parameters = ctx.tools.schemas().find(schema => schema.name === 'proto_schema_tool')!.parameters as {
+      properties: Record<string, { default?: unknown }>
+      required?: string[]
+    }
+    expect(Object.hasOwn(parameters.properties, '__proto__')).toBe(true)
+    expect(parameters.required).toContain('__proto__')
+    const defaultValue = parameters.properties.value!.default as Record<string, unknown>
+    expect(Object.hasOwn(defaultValue, '__proto__')).toBe(true)
+    expect(defaultValue.__proto__).toEqual({ safe: true })
+  })
+
+  it('accepts a nested object/array ParameterSchemaSpec (the DSL recursion)', async () => {
     const ctx = await setup()
     const result = await call(ctx, 'cordis_mount', {
       code: `
@@ -258,9 +576,10 @@ describe('cordis_mount', () => {
               name: 'nested_schema_tool',
               description: 'nested',
               parameters: {
-                item: { type: 'object', required: true, properties: { label: { type: 'string', required: true } } },
+                item: { type: 'object', additionalProperties: true, required: true, properties: { label: { type: 'string', required: true } } },
                 tags: { type: 'array', items: { type: 'string' } },
               },
+              ${CONTENT_OUTPUT_CODE}
               async execute(args) { return [{ type: 'text', text: args.item.label }] },
             }))
           },
@@ -284,6 +603,7 @@ describe('cordis_mount', () => {
               name: 'raw_dynamic_tool',
               description: 'raw',
               parameters: { type: 'object', properties: {} },
+              ${CONTENT_OUTPUT_CODE}
               async execute() { return [] },
             })
           },
@@ -337,6 +657,14 @@ describe('cordis_mount', () => {
       code: 'return { name: \'waiter\', inject: [\'no-such-service\'], apply(ctx) {} }',
     })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected pending cordis_mount success')
+    expect(result.value).toEqual({
+      id: 'dyn-1',
+      pluginName: 'waiter',
+      state: 'pending',
+      provides: [],
+      waitingFor: ['no-such-service'],
+    })
     expect(text(result)).toContain('state: pending')
     expect(text(result)).toContain('waiting for service(s): no-such-service')
     // Unmounting a pending mount works like any other.
@@ -397,6 +725,7 @@ describe('cordis_mount', () => {
               name: 'cordis_mount',
               description: 'dup',
               parameters: {},
+              ${CONTENT_OUTPUT_CODE}
               async execute() { return [] },
             }))
           },
@@ -543,6 +872,7 @@ describe('cordis_mount', () => {
               name: 'probe_instanceof',
               description: 'report instanceof checks across realms',
               parameters: { items: { type: 'array', required: true, items: { type: 'string' } } },
+              ${CONTENT_OUTPUT_CODE}
               async execute(args) {
                 const checks = {
                   hostArray: args.items instanceof Array,
diff --git a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts
index c27d34d4c3..05a33848c0 100644
--- a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts
+++ b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { call, setup, text } from './helpers.ts'
+import { call, CONTENT_OUTPUT_CODE, setup, text } from './helpers.ts'
 
 /**
  * The sandbox context façade is a whitelist, not a pass-through proxy. Mounted code reaches only
@@ -51,6 +51,7 @@ describe('sandbox context façade — escape surface is closed', () => {
               name: 'smuggled',
               description: 'raw, unguarded',
               parameters: { type: 'object', properties: {} },
+              ${CONTENT_OUTPUT_CODE}
               async execute() { return [] },
             })
           },
@@ -87,6 +88,7 @@ describe('sandbox context façade — escape surface is closed', () => {
               name: 'smuggled_via_service',
               description: 'raw, unguarded',
               parameters: { type: 'object', properties: {} },
+              ${CONTENT_OUTPUT_CODE}
               async execute() { return [] },
             })
           },
@@ -116,6 +118,7 @@ describe('sandbox context façade — escape surface is closed', () => {
               name: 'do_fetch',
               description: 'awaits the host async service',
               parameters: {},
+              ${CONTENT_OUTPUT_CODE}
               async execute() {
                 const value = await ctx.hostAsync.grab()
                 return [{ type: 'text', text: value }]
@@ -203,6 +206,7 @@ describe('sandbox context façade — inject gate on services', () => {
               name: 'greet_undeclared',
               description: 'uses greeter without declaring it',
               parameters: { n: { type: 'string', required: true } },
+              ${CONTENT_OUTPUT_CODE}
               async execute(args) { return [{ type: 'text', text: ctx.greeter.greet(args.n) }] },
             }))
           },
@@ -235,6 +239,7 @@ describe('sandbox tools façade — get is a read-only schema view', () => {
               name: 'report_view',
               description: 'reports the shape of a tool view',
               parameters: {},
+              ${CONTENT_OUTPUT_CODE}
               async execute() {
                 const view = ctx.tools.get('cordis_mount')
                 return [{ type: 'text', text: JSON.stringify({
@@ -270,6 +275,7 @@ describe('sandbox tools façade — get is a read-only schema view', () => {
               name: 'probe_unknown',
               description: 'reports whether an unknown tool resolves',
               parameters: {},
+              ${CONTENT_OUTPUT_CODE}
               async execute() {
                 return [{ type: 'text', text: String(ctx.tools.get('no_such_tool') === undefined) }]
               },
diff --git a/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts b/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts
index 718a213968..92e5ee7a66 100644
--- a/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts
+++ b/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts
@@ -26,6 +26,8 @@ describe('cordis_unmount', () => {
 
     const result = await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected cordis_unmount success')
+    expect(result.value).toEqual({ id: 'dyn-1', pluginName: 'change-logger' })
     expect(text(result)).toContain('unmounted dyn-1')
 
     // Immediately after the awaited unmount, the listener must be gone — no
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 1b89f288a8..47250c354f 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -50,9 +50,9 @@ Configured agents start automatically. A model call requires both `provider` and
 
 ### Internal concrete driver
 
-The concrete `Agent` class, its `Inbox`, `runLoop`, and instance-bound publication/start controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy.
+The concrete `ReactLoopAgent` adapter, its `Inbox`, `runLoop`, and instance-bound publication/start controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy.
 
-Each concrete `send()` materializes content, resolved source, and attached contexts once as a detached, deeply frozen lossless-JSON FIFO item. If claimed, it is the sole ordinary message in its turn; its contexts are the prompt waterfall's default additional contexts and therefore materialize only after admission. Absent or `separate` placement appends an independent `context/message`; `prompt-prefix` placement bakes the context, the stable `## My request:` delimiter, and effective request into one `user/message`, whose model-hidden envelope retains display content and context descriptors. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`; its next checkpoint applies the same separate-or-prefix placement to `steering/message`, while policy can still stop before another step. Steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. Open-turn `inject()` uses the same accepted-value boundary but defers in a FIFO while the current step executes assistant tool calls; successful batches place it after all results, and interrupted batches drain it before turn close. Malformed data throws before enqueue or append.
+`ReactLoopAgent.send()` implements the public fully resolved acceptance path. The `followup()`/`queue()`/`steer()`/`inject()` helpers resolve every optional field before delegating to it; direct callers provide mandatory content, source, contexts, metadata, target, and wakeup facts through `ResolvedAgentInput`. `followup()` and `queue()` join the ordinary FIFO, respectively waking or leaving an idle driver parked. If claimed, an ordinary item is the sole message in its turn, and its contexts are the prompt waterfall's default additional contexts that materialize only after admission. Absent or `separate` placement appends an independent injected `user/message`; `prompt-prefix` placement bakes the context, the stable `## My request:` delimiter, and effective request into one `user/message`, whose model-hidden envelope retains display content and context descriptors. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` or equivalent `send()` routing enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`; its next checkpoint applies the same separate-or-prefix placement to `steering/message`, while policy can still stop before another step. Steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. `inject()` and non-waking next-step acceptance require an empty context tuple, bypass both FIFOs, and append durable context directly: an open-turn injection defers in a FIFO while the current step executes assistant tool calls (successful batches place it after all results, interrupted batches drain it before turn close), and an idle injection wraps a one-shot `injection` turn. Every FIFO enqueue publishes `agent/inbox/enqueue`; the driver's claims publish `agent/inbox/dequeue`, and `cancel()` without `keepInbox` publishes `agent/inbox/discard`. Malformed data throws before enqueue or append.
 
 ### Loop lifecycle (`loop.ts`)
 
@@ -67,7 +67,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` → `tools/result` pipeline; exact 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 event catalog](../../../docs/cordis-catalog/events.md)
 - Compaction: pressure on `agent/post-step`; canonical context overflow on `agent/request-error`
 - Transient model recovery: `dsh-llm-retry` on `agent/request-error`, with finite code-specific budgets and non-surface `llm/retry` status events
 - 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/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index 91efbf7782..e09acfff40 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -6,15 +6,25 @@
  * @module dsh-agent-loop/agent
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
-import { agentEvents } from '@deepseek-ai/dsh-agent'
-import type { AgentCancelCause, AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import { agentEvents, AgentMessageId } from '@deepseek-ai/dsh-agent'
+import type {
+  Agent,
+  AgentCancelCause,
+  AgentOptions,
+  AgentStatus,
+  CancelOptions,
+  HookContext,
+  InjectOptions,
+  ResolvedAgentInput,
+  SendOptions,
+} from '@deepseek-ai/dsh-agent'
 import { deepFreeze, errorChain } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { snapshotJsonValue, type Session, type SessionId } from '@deepseek-ai/dsh-session'
 import { DISPOSED_INTERRUPT_REASON, TurnCancellation } from './cancellation.ts'
-import { Inbox, type InboxMessage } from './inbox.ts'
+import { Inbox, agentMessage, type InboxMessage } from './inbox.ts'
 import { isTurnOpen, lastTurnNumber, runLoop } from './loop.ts'
 
 /** Sessions already claimed by a concrete driver construction. */
@@ -190,19 +200,17 @@ export class ReactLoopAgent implements Agent {
     for (const resolve of waiters) resolve()
   }
 
-  private resolveSource(options?: SendOptions): MessageSource {
-    return options?.source ?? { kind: 'user' }
-  }
-
   /**
    * Accept one public message payload as a detached record. Lossless-JSON
    * materialization reads every nested field once; deep freeze prevents later
    * caller mutation before an inbox or deferred-injection queue drains it.
    */
-  private acceptMessage(content: ContentBlock[], options?: SendOptions): InboxMessage {
-    const source = this.resolveSource(options)
-    const contexts = options?.contexts ?? []
-    const accepted = snapshotJsonValue({ content, source, contexts })
+  private snapshotMessage(id: AgentMessageId, input: ResolvedAgentInput): InboxMessage {
+    const { content, source, contexts, wakeup, meta } = input
+    const accepted = snapshotJsonValue({
+      id, content, source, contexts, wakeup,
+      ...meta !== undefined ? { meta } : {},
+    })
     if (accepted === undefined) {
       throw new TypeError('agent message content, source, and contexts must be losslessly JSON-serializable')
     }
@@ -223,33 +231,81 @@ export class ReactLoopAgent implements Agent {
     if (this._status === 'disposed') throw new Error(`agent "${this.id}" is disposed`)
   }
 
-  send(content: ContentBlock[], options?: SendOptions): void {
+  /** Accept one fully resolved agent input through the concrete driver's routing matrix. */
+  send(input: ResolvedAgentInput): AgentMessageId {
     this.assertNotDisposed()
-    const accepted = this.acceptMessage(content, options)
-    this.#inbox.enqueue(accepted)
-    const info = { source: accepted.source, contexts: accepted.contexts, steering: false } as const
-    agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
+    const id = AgentMessageId(randomUUID())
+    const { target, wakeup } = input
+    // next-step/no-wakeup is injection: durable context without running the model.
+    if (target === 'next-step' && !wakeup) { this.injectContext(input); return id }
+    // next-step/wakeup is steering into the running turn; idle falls back to a
+    // waking ordinary turn (there is no active turn to attach to).
+    const steering = target === 'next-step' && this._status === 'running'
+    const accepted = this.snapshotMessage(id, input)
+    if (steering) {
+      this.#inbox.steer(accepted)
+    } else {
+      this.#inbox.enqueue(accepted, wakeup)
+    }
+    agentEvents(this.loopCtx, this).emit('agent/inbox/enqueue', agentMessage(accepted, steering))
+    return id
   }
 
-  steer(content: ContentBlock[], options?: SendOptions): void {
-    this.assertNotDisposed()
-    if (this._status !== 'running') { this.send(content, options); return }
-    const accepted = this.acceptMessage(content, options)
-    this.#inbox.steer(accepted)
-    const info = { source: accepted.source, contexts: accepted.contexts, steering: true } as const
-    agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
+  followup(content: ContentBlock[], options?: SendOptions): AgentMessageId {
+    return this.send({
+      content,
+      target: 'next-turn',
+      wakeup: true,
+      source: options?.source ?? { kind: 'user' },
+      contexts: options?.contexts ?? [],
+      meta: options?.meta,
+    })
   }
 
-  inject(content: ContentBlock[], options?: InjectOptions): void {
-    this.assertNotDisposed()
-    const source = this.resolveSource(options)
-    const context = {
+  queue(content: ContentBlock[], options?: SendOptions): AgentMessageId {
+    return this.send({
+      content,
+      target: 'next-turn',
+      wakeup: false,
+      source: options?.source ?? { kind: 'user' },
+      contexts: options?.contexts ?? [],
+      meta: options?.meta,
+    })
+  }
+
+  steer(content: ContentBlock[], options?: SendOptions): AgentMessageId {
+    return this.send({
+      content,
+      target: 'next-step',
+      wakeup: true,
+      source: options?.source ?? { kind: 'user' },
+      contexts: options?.contexts ?? [],
+      meta: options?.meta,
+    })
+  }
+
+  inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId {
+    return this.send({
+      content,
+      target: 'next-step',
+      wakeup: false,
+      source: options?.source ?? { kind: 'plugin', plugin: '' },
+      contexts: [],
+      meta: options?.meta,
+    })
+  }
+
+  /** The `next-step`/no-wakeup injection path: durable context, no FIFO, no run. */
+  private injectContext(input: Extract<ResolvedAgentInput, { target: 'next-step'; wakeup: false }>): void {
+    const { content, source, meta } = input
+    // Detach and validate the payload before any append, so malformed input
+    // cannot open a one-shot turn or otherwise mutate the session.
+    const accepted = this.acceptContext({
       content,
       source,
-      ...options?.meta !== undefined ? { meta: options.meta } : {},
-    }
+      ...meta !== undefined ? { meta } : {},
+    })
     if (isTurnOpen(this.session)) {
-      const accepted = this.acceptContext(context)
       // Provider protocols require every assistant tool-call batch to be
       // followed only by its tool results. Historical interrupted batches do
       // not own new context; only the currently executing batch may defer it.
@@ -257,27 +313,29 @@ export class ReactLoopAgent implements Agent {
         this.deferredInjections.push(accepted)
         return
       }
-      this.session.append('context/message', accepted, { surfaceOp: 'append' })
+      this.session.append('user/message', accepted, { surfaceOp: 'append' })
       return
     }
     // No turn open: wrap the injection in a one-shot turn so every event stays
-    // turn-enclosed (the durability/replay boundary is the turn).
+    // turn-enclosed (the durability/replay boundary is the turn). The payload is
+    // validated above, but `Session.append` can still reject a turn/start
+    // pre-commit (append re-entrancy from a session/event listener, or an
+    // internal-dispatch veto), so the finally owes a turn/end only when
+    // turn/start actually committed.
     const turn = lastTurnNumber(this.session) + 1
-    // Once turn/start enters the log, a turn/end is owed even if the message
-    // append fails acceptance or pre-commit validation. The finally re-checks
-    // the log and closes only a turn that actually opened; post-commit observers
-    // are contained by Session and cannot create a false append failure.
     try {
       this.session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-      this.session.append('context/message', context, { surfaceOp: 'append' })
+      this.session.append('user/message', accepted, { surfaceOp: 'append' })
     } finally {
       // Close the turn if turn/start made it into the log. A pre-commit veto
       // must escape rather than being mistaken for a committed turn/end.
       if (isTurnOpen(this.session)) {
         this.session.append('turn/end', { turn, reason: { kind: 'completed' } })
       }
-      // Decide the durability checkpoint from the log: an accepted one-shot
-      // turn must be flushed even when its message append was the failing step.
+      // Checkpoint only an accepted one-shot turn: a turn/start rejected
+      // pre-commit recorded nothing, so it owes no flush (and a spurious flush
+      // would emit a phantom-turn agent/error). The payload is validated up
+      // front, so a committed turn/start is always followed by its user/message.
       const turnRecorded = this.session.events.some(e => e.type === 'turn/start' && e.data.turn === turn)
       // Keep inject() synchronous: report checkpoint failures live instead of
       // rejecting the caller, and track the task so disposal still drains it.
@@ -301,7 +359,7 @@ export class ReactLoopAgent implements Agent {
   private drainDeferredInjections(): void {
     const pending = this.deferredInjections.splice(0)
     for (const accepted of pending) {
-      this.session.append('context/message', accepted, { surfaceOp: 'append' })
+      this.session.append('user/message', accepted, { surfaceOp: 'append' })
     }
   }
 
@@ -325,10 +383,14 @@ export class ReactLoopAgent implements Agent {
     }
   }
 
-  cancel(cause?: AgentCancelCause): void {
+  cancel(cause?: AgentCancelCause, options?: CancelOptions): void {
     const resolvedCause = cause ?? { kind: 'user' }
+    const keepInbox = options?.keepInbox ?? false
     const cancellation = this.turnCancellation
-    const preRun = cancellation === undefined && (this.#inbox.hasQueued || this.#inbox.hasSteering)
+    // keepInbox preserves pending work, so un-started items must not arm the
+    // pre-run cancel path that would otherwise drop the next queued turn.
+    const preRun = !keepInbox && cancellation === undefined
+      && (this.#inbox.hasQueued || this.#inbox.hasSteering)
     if (cancellation !== undefined || preRun) {
       if (preRun) this.preRunCancelled = true
       // Coordination consumers must update their own state before this call
@@ -336,9 +398,24 @@ export class ReactLoopAgent implements Agent {
       // contained by the fused dispatcher and cannot veto cancellation.
       agentEvents(this.loopCtx, this).emit('agent/cancel-requested', resolvedCause)
     }
-    // Clear work already present before abort observers run. A replacement
-    // synchronously enqueued by an observer belongs to the next turn.
-    this.#inbox.clear()
+    if (!keepInbox) {
+      // Snapshot before clearing so the discard notification carries the exact
+      // dropped items; a replacement synchronously enqueued by an
+      // `agent/cancel-requested` observer belongs to the next turn, not here.
+      const discarded = this.#inbox.pending()
+      // Clear work already present before abort observers run.
+      this.#inbox.clear()
+      if (discarded.length > 0) {
+        const items = discarded.map(({ message, steering }) => agentMessage(message, steering))
+        agentEvents(this.loopCtx, this).emit('agent/inbox/discard', items)
+      }
+      // No idle-waiter settle here: a `whenIdle` waiter exists only while the
+      // agent is `running` or a waking item is queued, and neither is left
+      // quiescent by clearing the inbox — a lone quiet item takes `whenIdle`'s
+      // fast path (no waiter), a waking item keeps the woken driver running,
+      // and a running agent owns its own idle transition (including the
+      // post-turn flush window).
+    }
     cancellation?.request(resolvedCause)
   }
 
@@ -349,7 +426,9 @@ export class ReactLoopAgent implements Agent {
    */
   whenIdle(): Promise<void> {
     if (this._status === 'disposed') return this.done
-    if (this._status !== 'running' && !this.#inbox.hasQueued) return Promise.resolve()
+    // A lone quiet (`wakeup:false`) queued item leaves the agent quiescent — the
+    // driver stays parked — so gate on hasWakingQueued, not hasQueued.
+    if (this._status !== 'running' && !this.#inbox.hasWakingQueued) return Promise.resolve()
     // Agent-owned waiters survive concurrent fiber disposal.
     return new Promise<void>((resolve) => {
       this.idleWaiters.push(() => {
@@ -407,8 +486,21 @@ export class ReactLoopAgent implements Agent {
    */
   private [stopDriver](): Promise<void> | void {
     if (this._status !== 'disposed') {
+      // Snapshot any still-pending inbox items, then CLEAR and mark disposed
+      // BEFORE emitting the discard — mirroring cancel()'s snapshot→clear→emit
+      // order so a re-entrant followup()/cancel() from a discard listener throws
+      // `disposed` (or finds an empty inbox) instead of leaking or double-
+      // discarding an id. `followup()` emits enqueue unconditionally, so the discard
+      // is unconditional too (even on an unpublished rollback) to keep every
+      // enqueued id matched.
+      const discarded = this.#inbox.pending()
+      this.#inbox.clear()
       this._status = 'disposed'
       this.resolveDisposed()
+      if (discarded.length > 0) {
+        const items = discarded.map(({ message, steering }) => agentMessage(message, steering))
+        agentEvents(this.loopCtx, this).emit('agent/inbox/discard', items)
+      }
       // Release whenIdle waiters BEFORE the (guarded) event emit — they are
       // internal state that must settle even if a listener throws below. Each
       // waiter chains `done`, so it resolves only once the loop actually exits.
diff --git a/packages/core/agent-loop/src/inbox.ts b/packages/core/agent-loop/src/inbox.ts
index 6c8a20e3d1..0f93884515 100644
--- a/packages/core/agent-loop/src/inbox.ts
+++ b/packages/core/agent-loop/src/inbox.ts
@@ -1,54 +1,91 @@
 /**
  * Per-agent message inbox: queued and steering FIFOs. Purely an in-memory
- * mechanism of the loop driver — the public surface is `Agent.send()` and
- * `Agent.steer()`.
+ * mechanism of the loop driver — callers use `Agent`'s intent-named delivery
+ * methods instead.
  *
  * @module dsh-agent-loop/inbox
  */
 
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
-import type { HookContext } from '@deepseek-ai/dsh-agent'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { AgentMessage, AgentMessageId, HookContext } from '@deepseek-ai/dsh-agent'
 
-/** One message waiting in an agent's inbox. */
+/** One message waiting in an agent's inbox; `id` is the value its accepting delivery method returned. */
 export interface InboxMessage {
+  id: AgentMessageId
   content: ContentBlock[]
   source: MessageSource
   contexts: HookContext[]
+  /** Whether the item is marked to wake the driver or force a continuation. */
+  wakeup: boolean
+  /** Opaque durable JSON state retained on the durable message but hidden from the model. */
+  meta?: JsonValue
+}
+
+/**
+ * Build the `agent/inbox/*` event payload for one inbox item.
+ * @param message - the accepted inbox record.
+ * @param steering - whether the item is in the steering FIFO (`next-step`).
+ * @returns the live-event message for enqueue/dequeue/discard.
+ */
+export function agentMessage(message: InboxMessage, steering: boolean): AgentMessage {
+  // Frozen: the fused emitter passes this exact object to every listener in
+  // turn, so one listener must not be able to mutate a field (`id`, `steering`,
+  // `content`, …) a later listener then observes. `message` is already a frozen
+  // inbox record, so its nested fields need no re-clone.
+  return Object.freeze({
+    id: message.id, content: message.content, source: message.source,
+    contexts: message.contexts, steering, wakeup: message.wakeup,
+  })
 }
 
 /**
  * Per-agent inbox: a queued FIFO (dequeued once per turn start) and a steering FIFO
  * (drained between steps of a running turn). Purely an in-memory mechanism of
- * the loop — the public surface is `Agent.send()` / `Agent.steer()`.
+ * the loop — the public surface is `Agent`'s intent-named delivery methods.
  */
 export class Inbox {
   private queuedMessages: InboxMessage[] = []
   private steeringMessages: InboxMessage[] = []
   private wakeup: (() => void) | undefined
 
-  /** True while queued messages are pending — read by the idle wait's fast path and the loop's turn-start checks. */
+  /** True while any queued message is pending — read by cancellation's discard snapshot and the turn-start dequeue guard. */
   get hasQueued(): boolean {
     return this.queuedMessages.length > 0
   }
 
+  /**
+   * True while a queued message wants to wake the driver — the "should the loop
+   * run" signal read by the idle wait's fast path, the loop's idle-publish
+   * check, and `whenIdle`. A `wakeup:false` (quiet) item alone leaves this
+   * false, so the driver stays parked until a waking follow-up (or a waking item
+   * ahead of it in FIFO order) drives the loop; the quiet item then rides along.
+   */
+  get hasWakingQueued(): boolean {
+    return this.queuedMessages.some(message => message.wakeup)
+  }
+
   /** True while steering messages are pending — read by cancellation and the loop's stop-override check. */
   get hasSteering(): boolean {
     return this.steeringMessages.length > 0
   }
 
   /**
-   * Add a message to the queued FIFO and wake a parked {@link waitForQueued}.
+   * Add a message to the queued FIFO, waking a parked {@link waitForQueued}
+   * unless the item opted out. A non-waking item still runs once any woken
+   * item or later wakeup drives the parked loop.
    * @param message - the message to queue for the next turn start.
+   * @param wake - whether to wake a parked idle wait (default true).
    */
-  enqueue(message: InboxMessage): void {
+  enqueue(message: InboxMessage, wake = true): void {
     this.queuedMessages.push(message)
-    this.wakeup?.()
+    if (wake) this.wakeup?.()
   }
 
   /**
    * Add a message to the steering FIFO. Deliberately no wakeup: steering is
    * drained between steps of a running turn, never by the idle wait —
-   * `Agent.steer()` on an idle agent falls back to `send()` instead.
+   * `Agent.steer()` on an idle agent falls back to a waking ordinary turn instead.
    * @param message - the message to inject between steps of the running turn.
    */
   steer(message: InboxMessage): void {
@@ -71,6 +108,18 @@ export class Inbox {
     return this.steeringMessages.splice(0)
   }
 
+  /**
+   * Snapshot the pending items (queued then steering, FIFO order) without
+   * removing them — the discard notification's payload source.
+   * @returns the pending items paired with whether each is steering.
+   */
+  pending(): { message: InboxMessage; steering: boolean }[] {
+    return [
+      ...this.queuedMessages.map(message => ({ message, steering: false })),
+      ...this.steeringMessages.map(message => ({ message, steering: true })),
+    ]
+  }
+
   /**
    * Discard all pending messages (queued + steering) without delivering them —
    * used by `cancel()`, which drops un-started work rather than draining it into
@@ -88,7 +137,7 @@ export class Inbox {
    *   loop can exit).
    */
   waitForQueued(cancel: Promise<void>): Promise<void> {
-    if (this.hasQueued) return Promise.resolve()
+    if (this.hasWakingQueued) return Promise.resolve()
     const { promise, resolve } = Promise.withResolvers<void>()
     this.wakeup = resolve
     void cancel.then(resolve)
diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts
index 1cfd913b77..4324deca8d 100644
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -5,11 +5,12 @@
  * @module dsh-agent-loop/loop
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
 import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, LlmFailure, Message } from '@deepseek-ai/dsh-llm'
 import { isDeepStrictEqual } from 'node:util'
 import { BlockAssembler, HarnessError, LlmError, assertNever, deepFreeze, errorChain, llmFailureOf, markAgentLoopRequest } from '@deepseek-ai/dsh-llm'
-import { agentEvents, agentInterruptReasonOf, assembleContextFor } from '@deepseek-ai/dsh-agent'
+import { agentEvents, agentInterruptReasonOf, assembleContextFor, AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
 import type { PromptMessageData, Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
@@ -19,7 +20,7 @@ import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
 import { executeToolCalls } from './tool-calls.ts'
-import type { Inbox } from './inbox.ts'
+import { agentMessage, type Inbox, type InboxMessage } from './inbox.ts'
 import type { TurnCancellation } from './cancellation.ts'
 
 /** Normalize thrown values while preserving an existing error code. */
@@ -201,9 +202,11 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
   while (!handle.isDisposed()) {
     // An idle listener can enqueue and cancel replacement work before the next
     // wait is installed. Consume that empty marker before parking the driver.
+    // A quiet (`wakeup:false`) item alone must not un-park the loop, so gate on
+    // hasWakingQueued, not hasQueued.
     if (handle.isPreRunCancelled()) {
       handle.clearPreRunCancel()
-      if (!handle.inbox.hasQueued) {
+      if (!handle.inbox.hasWakingQueued) {
         handle.settleIdle()
         handle.setStatus('idle')
         continue
@@ -217,7 +220,7 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
     // a replacement prompt still runs before the eventual idle transition.
     if (handle.isPreRunCancelled()) {
       handle.clearPreRunCancel()
-      if (!handle.inbox.hasQueued) {
+      if (!handle.inbox.hasWakingQueued) {
         // Settle before publishing idle: the already-idle path has no status
         // transition, while an idle listener can register waiters for new work.
         handle.settleIdle()
@@ -234,10 +237,11 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
     }
 
     // A synchronous `running` listener can cancel before `runTurn`; balance the
-    // status only when no replacement prompt was queued by that listener.
+    // status only when no waking replacement prompt was queued by that listener
+    // (a lone quiet item parks at idle rather than driving a turn).
     if (cancellation.signal.aborted) {
       handle.clearTurnCancellation(cancellation)
-      if (!handle.inbox.hasQueued) {
+      if (!handle.inbox.hasWakingQueued) {
         handle.setStatus('idle')
         continue
       }
@@ -260,12 +264,22 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
       handle.clearTurnCancellation(cancellation)
     }
 
-    // Late steering becomes queued input unless terminal policy stopped the turn.
-    for (const message of handle.inbox.drainSteering()) {
-      if (!terminalStopped) handle.inbox.enqueue(message)
+    // Late steering (arriving after runTurn returns, e.g. during the post-turn
+    // flush) becomes queued input — unless terminal policy stopped the turn, in
+    // which case it is dropped and must publish a discard so its enqueue is
+    // still matched (the invariant only catches a NEGATIVE count, not a leak).
+    const lateSteering = handle.inbox.drainSteering()
+    if (terminalStopped) {
+      if (lateSteering.length > 0) {
+        events.emit('agent/inbox/discard', lateSteering.map(message => agentMessage(message, true)))
+      }
+    } else {
+      for (const message of lateSteering) handle.inbox.enqueue(message)
     }
 
-    if (!handle.inbox.hasQueued) handle.setStatus('idle')
+    // Park at idle unless a waking item still wants the model to run; a lone
+    // quiet (`wakeup:false`) item stays queued but does not keep the loop busy.
+    if (!handle.inbox.hasWakingQueued) handle.setStatus('idle')
   }
 }
 
@@ -279,10 +293,14 @@ async function runTurn(
   const drainSteering = (): boolean => {
     const messages = handle.inbox.drainSteering()
     for (const message of messages) {
+      events.emit('agent/inbox/dequeue', agentMessage(message, true))
       const prepared = preparePromptMessage(message.content, message.source, message.contexts)
-      session.append('steering/message', { turn, ...prepared.data }, { surfaceOp: 'append' })
+      session.append('steering/message', {
+        turn, ...prepared.data,
+        ...message.meta === undefined ? {} : { meta: message.meta },
+      }, { surfaceOp: 'append' })
       for (const context of prepared.separateContexts) {
-        session.append('context/message', {
+        session.append('user/message', {
           content: context.content,
           source: context.source,
           ...context.meta === undefined ? {} : { meta: context.meta },
@@ -296,6 +314,7 @@ async function runTurn(
   const message = handle.inbox.dequeueQueued()
   /* v8 ignore next 3 -- invariant guard: runLoop only calls runTurn when hasQueued */
   if (!message) throw new Error('runTurn invariant violated: no queued message at turn start')
+  events.emit('agent/inbox/dequeue', agentMessage(message, false))
   const trigger: TurnTrigger = { kind: 'message', source: message.source }
 
   let reason: TurnEndReason = { kind: 'completed' }
@@ -361,7 +380,10 @@ async function runTurn(
       // `allow.content` REPLACES the prompt bytes (a rewrite); absent keeps them.
       const content = promptDecision.content ?? message.content
       const prepared = preparePromptMessage(content, message.source, promptDecision.additionalContexts ?? [])
-      session.append('user/message', prepared.data, { surfaceOp: 'append' })
+      session.append('user/message', {
+        ...prepared.data,
+        ...message.meta === undefined ? {} : { meta: message.meta },
+      }, { surfaceOp: 'append' })
       // Separate contexts still enter THIS turn through inject(). Prefix
       // contexts are already baked into the user/message with their durable
       // display envelope, so appending them again would duplicate model input.
@@ -536,9 +558,21 @@ async function runTurn(
         break
       }
 
-      // A continuation reason becomes next-step steering.
+      // A continuation reason becomes next-step steering. Publish the same
+      // enqueue event a public steer would, so the inbox ledger stays balanced
+      // (every FIFO entry has a matching enqueue before its dequeue/discard).
       if (decision.action === 'continue' && decision.reason) {
-        handle.inbox.steer({ content: decision.reason.content, source: decision.reason.source, contexts: [] })
+        // Detach and freeze the listener-owned reason like a public steer, so an
+        // enqueue listener or the producer cannot mutate the durable/model-visible
+        // steering message before it drains.
+        const item: InboxMessage = deepFreeze({
+          id: AgentMessageId(randomUUID()),
+          content: structuredClone(decision.reason.content),
+          source: structuredClone(decision.reason.source),
+          contexts: [], wakeup: true,
+        })
+        handle.inbox.steer(item)
+        events.emit('agent/inbox/enqueue', agentMessage(item, true))
       }
       let shouldContinue = decision.action === 'continue'
 
@@ -562,7 +596,13 @@ async function runTurn(
       if (terminalStop) {
         terminalStopped = true
         // Terminal stop discards steering but preserves ordinary queued prompts.
-        handle.inbox.drainSteering()
+        // Publish a discard for every dropped steering item so the enqueue ⇒
+        // dequeue-or-discard ledger stays balanced (the outstanding-count
+        // invariant and correlation consumers must not be left with dangling ids).
+        const dropped = handle.inbox.drainSteering()
+        if (dropped.length > 0) {
+          events.emit('agent/inbox/discard', dropped.map(item => agentMessage(item, true)))
+        }
         shouldContinue = false
       }
 
diff --git a/packages/core/agent-loop/src/tool-calls.ts b/packages/core/agent-loop/src/tool-calls.ts
index 64c6c69cf6..b6e83d7b23 100644
--- a/packages/core/agent-loop/src/tool-calls.ts
+++ b/packages/core/agent-loop/src/tool-calls.ts
@@ -219,7 +219,10 @@ function appendSkippedToolCall(session: Session, turn: number, step: number, blo
   appendToolResult(session, turn, step, block, {
     content: [{ type: 'text', text: 'Error: tool call aborted before dispatch' }],
     isError: true,
-    error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    error: {
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    },
   }, callSeq)
 }
 
@@ -245,7 +248,7 @@ function appendToolResult(
     callId: block.id,
     content: result.content,
     isError: result.isError,
-    ...result.error ? { error: result.error } : {},
+    ...result.error?.info ? { error: result.error.info } : {},
     // The tool's private presentation payload (e.g. a result-time diff),
     // persisted so a UI bridge reproduces the card on replay.
     ...result.meta !== undefined ? { meta: result.meta } : {},
diff --git a/packages/core/agent-loop/tests/agent-initiator.spec.ts b/packages/core/agent-loop/tests/agent-initiator.spec.ts
index 70c02bbeed..a2359562a8 100644
--- a/packages/core/agent-loop/tests/agent-initiator.spec.ts
+++ b/packages/core/agent-loop/tests/agent-initiator.spec.ts
@@ -6,7 +6,7 @@ import LlmService, { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
 const testToolSignal = new AbortController().signal
@@ -41,7 +41,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string): void {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 /** Adapter that holds both drivers at the same awaited continuation. */
@@ -189,7 +189,7 @@ describe('AgentLoop initiator scope', () => {
     ctx.on('agent/turn-stop', (subject, _turn, signal) => {
       if (subject === agent) capture(signal)
     })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'observe',
       description: 'observe explicit turn state',
       parameters: {},
@@ -232,7 +232,7 @@ describe('AgentLoop initiator scope', () => {
     let parentWhileChildDriverActive: Agent | undefined
     let child: Agent | undefined
 
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'spawn-child',
       description: 'create one child agent',
       parameters: {},
@@ -244,7 +244,7 @@ describe('AgentLoop initiator scope', () => {
           setup: (agentCtx) => {
             parentDuringSetup = ctx.agents.requireInitiator()
             explicitChild = agentCtx.agent
-            agentCtx.tools.register(defineTool({
+            agentCtx.tools.register(defineContentToolFixture({
               name: 'observe-child',
               description: 'observe child execution identity',
               parameters: {},
@@ -292,7 +292,7 @@ describe('AgentLoop initiator scope', () => {
     let directAmbient: Agent | undefined
     let captured: Agent | undefined
 
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'agentless-probe',
       description: 'observe an agentless call',
       parameters: {},
@@ -302,7 +302,7 @@ describe('AgentLoop initiator scope', () => {
         return [{ type: 'text', text: 'ok' }]
       },
     }))
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'capability-request',
       description: 'call the test capability transport',
       parameters: { path: { type: 'string' } },
diff --git a/packages/core/agent-loop/tests/agent.spec.ts b/packages/core/agent-loop/tests/agent.spec.ts
index 2cb3191f83..08b77711f9 100644
--- a/packages/core/agent-loop/tests/agent.spec.ts
+++ b/packages/core/agent-loop/tests/agent.spec.ts
@@ -48,7 +48,7 @@ function waitForStatus(ctx: Context, agent: Agent, expected: Agent['status']): P
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 describe('Agent', () => {
@@ -83,7 +83,41 @@ describe('Agent', () => {
     await ctx.fiber.dispose()
   })
 
-  it('send() throws after disposal', async () => {
+  it('send exposes the fully resolved delivery path without applying helper defaults', async () => {
+    const adapter = new MockAdapter([textResponse('accepted')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const enqueued = Promise.withResolvers<{ id: string; source: unknown; wakeup: boolean }>()
+    ctx.on('agent/inbox/enqueue', (subject, message) => {
+      if (subject === agent) enqueued.resolve(message)
+    })
+
+    const id = agent.send({
+      content: [{ type: 'text', text: 'advanced input' }],
+      source: { kind: 'plugin', plugin: 'advanced-caller' },
+      contexts: [],
+      meta: { caller: 'advanced' },
+      target: 'next-turn',
+      wakeup: true,
+    })
+    await waitForIdle(ctx, agent)
+
+    expect(await enqueued.promise).toMatchObject({
+      id,
+      source: { kind: 'plugin', plugin: 'advanced-caller' },
+      wakeup: true,
+    })
+    expect(agent.session.events.find(event => event.type === 'user/message'))
+      .toMatchObject({
+        data: {
+          source: { kind: 'plugin', plugin: 'advanced-caller' },
+          meta: { caller: 'advanced' },
+        },
+      })
+    await ctx.fiber.dispose()
+  })
+
+  it('followup() throws after disposal', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
     let agent!: Agent
@@ -95,7 +129,28 @@ describe('Agent', () => {
     await fiber.dispose()
     await driverDone(agent)
 
-    expect(() => { agent.send([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
+    expect(() => { agent.followup([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
+  })
+
+  it('disposal discards still-pending inbox items so every id gets a terminal event', async () => {
+    const adapter = new MockAdapter(['hang'])
+    const ctx = await harness(adapter)
+    let agent!: Agent
+    const discarded: string[] = []
+    ctx.on('agent/inbox/discard', (subject, messages) => {
+      if (subject === agent) discarded.push(...messages.map(m => m.id))
+    })
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
+    }, { inject: ['agentLoop'] }))
+
+    // A quiet (non-waking) item stays parked in the inbox; disposal must drop it
+    // WITH a discard so its enqueued id is not left dangling forever.
+    const id = agent.queue([{ type: 'text', text: 'never runs' }])
+    await fiber.dispose()
+    await driverDone(agent)
+
+    expect(discarded).toEqual([id])
   })
 
   it('steer() throws after disposal', async () => {
@@ -139,7 +194,7 @@ describe('Agent', () => {
     agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     agent.inject([{ type: 'text', text: 'mid' }], { source: { kind: 'plugin', plugin: 'p' } })
     expect(agent.session.events.filter(e => e.type === 'turn/start')).toHaveLength(1)
-    expect(agent.session.events.at(-1)!.type).toBe('context/message')
+    expect(agent.session.events.at(-1)!.type).toBe('user/message')
 
     // Close the turn; now inject must wrap its own one-shot injection turn.
     agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
@@ -151,6 +206,16 @@ describe('Agent', () => {
     expect(agent.session.events.at(-1)!.type).toBe('turn/end') // turn-enclosed
   })
 
+  it('inject() defaults its source to an empty plugin, never user', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    agent.inject([{ type: 'text', text: 'no explicit source' }])
+    const injected = agent.session.events.at(-1)!
+    expect(injected.type === 'user/message' && injected.data.source).toEqual({ kind: 'plugin', plugin: '' })
+  })
+
   it('idle inject() contains a failing flush (logs, does not throw into the caller)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
@@ -167,24 +232,54 @@ describe('Agent', () => {
     warn.mockRestore()
   })
 
-  it('idle inject() closes its one-shot turn AND still checkpoints even if the append throws', async () => {
+  it('idle inject() validates its payload BEFORE opening a turn, so invalid input appends nothing', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let flushes = 0
     ctx.on('session/flush', () => { flushes += 1 })
 
-    // Non-serializable injected content makes Session.append throw AFTER
-    // turn/start was recorded. The turn/end must still be appended (finally),
-    // AND the durability checkpoint must still fire — the balanced turn is in
-    // memory and a crash before the next turn/dispose would otherwise lose it.
+    // Non-serializable injected content is rejected by the up-front snapshot
+    // BEFORE any append (the unified send contract: invalid input throws before
+    // mutating the log). No one-shot turn opens and no durability checkpoint fires.
     expect(() => {
       agent.inject([{ type: 'text', text: 'x', bad: 1n } as never], { source: { kind: 'plugin', plugin: 'p' } })
-    }).toThrow(/non-JSON-serializable/)
-    const types = agent.session.events.map(e => e.type)
-    expect(types).toEqual(['turn/start', 'turn/end']) // balanced, no open turn
-    await new Promise(r => setTimeout(r, 10)) // let the fire-and-forget flush run
-    expect(flushes).toBe(1) // checkpoint fired despite the throw
+    }).toThrow(/losslessly JSON-serializable/)
+    expect(agent.session.events).toHaveLength(0)
+    await new Promise(r => setTimeout(r, 10)) // give any (erroneous) flush a chance
+    expect(flushes).toBe(0) // nothing was appended, so no checkpoint
+  })
+
+  it('idle inject() re-entered from a session/event listener is rejected pre-commit and opens no turn', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    let flushes = 0
+    ctx.on('session/flush', () => { flushes += 1 })
+    // Injecting from inside a session/event listener re-enters Session.append,
+    // which rejects pre-commit — so turn/start never commits. The finally sees
+    // no open turn (closes nothing) and no recorded turn (no checkpoint), and
+    // the reentrant throw is contained by Session's post-commit dispatch.
+    // Fire on turn/end: at that instant the outer one-shot turn is closed (no
+    // turn open), so the reentrant inject takes the idle one-shot-turn path and
+    // its turn/start append re-enters Session and is rejected pre-commit.
+    let reentered = false
+    ctx.on('session/event', (_s, event) => {
+      if (!reentered && event.type === 'turn/end') {
+        reentered = true
+        agent.inject([{ type: 'text', text: 'reentrant' }], { source: { kind: 'plugin', plugin: 'p' } })
+      }
+    })
+
+    agent.inject([{ type: 'text', text: 'outer' }], { source: { kind: 'plugin', plugin: 'p' } })
+    // The outer injection's own one-shot turn is balanced; the reentrant one
+    // opened no turn (its turn/start was rejected pre-commit).
+    const turnStarts = agent.session.events.filter(e => e.type === 'turn/start')
+    expect(turnStarts).toHaveLength(1)
+    const injected = agent.session.events.filter(e => e.type === 'user/message')
+    expect(injected).toHaveLength(1) // the reentrant user/message never committed
+    await new Promise(r => setTimeout(r, 10))
+    expect(flushes).toBe(1) // only the outer accepted turn checkpointed
   })
 
   it('idle inject() still checkpoints when a listener throws on the synthetic turn/end', async () => {
@@ -202,7 +297,7 @@ describe('Agent', () => {
 
     expect(() => { agent.inject([{ type: 'text', text: 'notice' }], { source: { kind: 'plugin', plugin: 'p' } }) }).not.toThrow()
     const types = agent.session.events.map(e => e.type)
-    expect(types).toEqual(['turn/start', 'context/message', 'turn/end']) // balanced
+    expect(types).toEqual(['turn/start', 'user/message', 'turn/end']) // balanced
     await new Promise(r => setTimeout(r, 10))
     expect(flushes).toBe(1) // checkpoint fired despite the throwing turn/end listener
   })
@@ -234,13 +329,11 @@ describe('Agent', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    // A non-serializable source makes the turn/start append throw BEFORE the
-    // event is pushed (Session.append validates before push), so NO turn opens.
-    // The finally's isTurnOpen() guard sees no open turn and appends nothing —
-    // the log stays empty, not left with a dangling turn/start.
+    // A non-serializable source is rejected by the up-front snapshot BEFORE any
+    // append, so NO turn opens and the log stays empty.
     expect(() => {
       agent.inject([{ type: 'text', text: 'x' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
-    }).toThrow(/non-JSON-serializable/)
+    }).toThrow(/losslessly JSON-serializable/)
     expect(agent.session.events).toHaveLength(0)
   })
 
@@ -397,7 +490,7 @@ describe('Agent', () => {
     const { agent } = prepared
     prepared.markPublished()
     const dispose = prepared.startDriver()
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await new Promise(r => setTimeout(r, 30))
     expect(agent.status).toBe('running')
 
diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts
index 162d3b552a..32418fe112 100644
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -11,7 +11,7 @@ import { Context } from 'cordis'
 import LlmService, { type Message } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
@@ -33,7 +33,7 @@ async function harness(adapter: MockAdapter) {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 /** Resolve on the agent's next idle transition (event-based, not status poll). */
@@ -63,7 +63,7 @@ describe('Agent.cancel()', () => {
     ctx.on('agent/cancel-requested', (subject, cause) => {
       if (subject !== agent) return
       seen.push(`first:${cause.kind}`)
-      subject.send([{ type: 'text', text: 'queued by cancel observer' }])
+      subject.followup([{ type: 'text', text: 'queued by cancel observer' }])
       throw new Error('observer failed')
     })
     ctx.on('agent/cancel-requested', (subject, cause) => {
@@ -98,6 +98,57 @@ describe('Agent.cancel()', () => {
     expect(agent.session.events.some(e => e.type === 'turn/end')).toBe(true)
   })
 
+  it('cancel({ keepInbox: true }) preserves queued work and emits no discard', async () => {
+    const adapter = new MockAdapter([textResponse('reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const discards: unknown[] = []
+    ctx.on('agent/inbox/discard', (subject, items) => { if (subject === agent) discards.push(items) })
+
+    // Queue a turn WITHOUT waking the driver, so it sits in the inbox.
+    agent.queue([{ type: 'text', text: 'preserved' }])
+    // keepInbox cancel: no active turn, work preserved, no discard event.
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    expect(discards).toEqual([])
+
+    // The preserved item still runs once the driver is woken by a later send.
+    send(agent, 'wake it')
+    await waitForIdle(ctx, agent)
+    expect(userTexts(agent)).toEqual(['preserved', 'wake it'])
+  })
+
+  it('a lone queued message leaves the agent parked at idle', async () => {
+    const adapter = new MockAdapter([textResponse('reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    // A quiet item alone must NOT wake the driver: no turn runs and whenIdle
+    // resolves (the agent is quiescent), leaving the item queued.
+    agent.queue([{ type: 'text', text: 'quiet' }])
+    await agent.whenIdle()
+    expect(agent.status).toBe('idle')
+    expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
+
+    // A later waking send drives the loop, and the quiet item rides along first.
+    send(agent, 'wake')
+    await waitForIdle(ctx, agent)
+    expect(userTexts(agent)).toEqual(['quiet', 'wake'])
+  })
+
+  it('cancelling a parked quiet item settles a pending whenIdle() without a later send', async () => {
+    const adapter = new MockAdapter([textResponse('reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.queue([{ type: 'text', text: 'quiet' }])
+    const idle = agent.whenIdle()
+    // Cancel reaches quiescence with no status transition and no waking send;
+    // whenIdle must still resolve (previously it hung until the next send).
+    agent.cancel({ kind: 'user' })
+    await idle
+    expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
+  })
+
   it('pre-step cancel drops the about-to-start turn (no turn is opened)', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
@@ -365,7 +416,7 @@ describe('Agent.cancel()', () => {
     ])
     const ctx = await harness(adapter)
     let executions = 0
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'danger',
       description: 'must not run after cancellation',
       parameters: {},
@@ -952,7 +1003,7 @@ describe('Agent.cancel()', () => {
         })
         break
       case 'tool':
-        ctx.tools.register(defineTool({
+        ctx.tools.register(defineContentToolFixture({
           name: 'blocked',
           description: 'wait for cancellation',
           parameters: {},
diff --git a/packages/core/agent-loop/tests/config-session-id.spec.ts b/packages/core/agent-loop/tests/config-session-id.spec.ts
index 2103dd6831..d144127498 100644
--- a/packages/core/agent-loop/tests/config-session-id.spec.ts
+++ b/packages/core/agent-loop/tests/config-session-id.spec.ts
@@ -98,7 +98,7 @@ describe('config-driven session id', () => {
       first = ctx.agents.get(SessionId('config-exact-reload'))
     }
     expect(first).toBeDefined()
-    first!.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
+    first!.followup([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
     await waitForIdle(ctx, first!)
     await firstLoop.dispose()
 
@@ -110,7 +110,7 @@ describe('config-driven session id', () => {
     }
     expect(second).toBeDefined()
     expect(JSON.stringify(second!.session.deriveMessages())).toContain('remember me')
-    second!.send([{ type: 'text', text: 'continue' }], { source: { kind: 'user' } })
+    second!.followup([{ type: 'text', text: 'continue' }], { source: { kind: 'user' } })
     await waitForIdle(ctx, second!)
     await ctx.sessions.flush(second!.session)
     const loaded = await ctx.sessionPersistence.load(SessionId('config-exact-reload'))
@@ -335,7 +335,7 @@ describe('config-driven session id', () => {
     expect(a1.id).toBe(a1.session.id)
     expect(a1.session.id).toMatch(idPattern)
     expect(ctx1.agents.get(SessionId('cfg'))).toBeUndefined()
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -354,7 +354,7 @@ describe('config-driven session id', () => {
     expect(a2.id).toBe(a2.session.id)
     expect(a2.session.id).toMatch(idPattern)
     expect(a2.session.id).not.toBe(a1.session.id)
-    a2.send([{ type: 'text', text: 'q2' }], { source: { kind: 'user' } })
+    a2.followup([{ type: 'text', text: 'q2' }], { source: { kind: 'user' } })
     await waitForIdle(ctx2, a2)
     await ctx2.fiber.dispose()
   })
@@ -375,7 +375,7 @@ describe('config-driven session id', () => {
     await ctx1.plugin(SessionPersistenceJsonl, { root })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('first')]))
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('sticky-1') })).agent
-    a1.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts
index 3a9ca87d68..2b85691151 100644
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import LlmService, { CallId, ContentBlock, MessageSource, ProviderRequestId, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool, TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH, type PostToolDecision } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture, TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH, type PostToolDecision } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent, type ContinuationDecision, type HookContext } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
 import { prepareReactLoopAgent } from '../src/agent.ts'
@@ -50,7 +50,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 describe('session log records what agent/step-result actually produced', () => {
@@ -60,7 +60,7 @@ describe('session log records what agent/step-result actually produced', () => {
     const adapter = new MockAdapter([original, textResponse('done')])
     const ctx = await harness(adapter)
     const executed: string[] = []
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'injected-tool',
       description: '',
       parameters: {},
@@ -229,7 +229,7 @@ describe('abort during tool execution ends the turn', () => {
     const ctx = await harness(adapter)
     const executed: string[] = []
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'aborter',
       description: '',
       parameters: {},
@@ -250,7 +250,7 @@ describe('abort during tool execution ends the turn', () => {
         source: { kind: 'plugin', plugin: 'abort-test' },
       }],
     }))
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'second',
       description: '',
       parameters: {},
@@ -275,7 +275,9 @@ describe('abort during tool execution ends the turn', () => {
           order.push(`tool/result:${event.data.callId}:${outcome}`)
           break
         }
-        case 'context/message': order.push('context/message'); break
+        // Injected context is a plugin-sourced user/message; the direct human
+        // prompt (user source) is not tracked in this ordering.
+        case 'user/message': if (event.data.source.kind !== 'user') order.push('context/message'); break
         case 'steering/message': order.push('steering/message'); break
         case 'step/end': order.push('step/end'); break
         case 'turn/end': {
@@ -332,7 +334,7 @@ describe('abort during tool execution ends the turn', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'aborter', {})])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a-abort-injection'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'aborter',
       description: '',
       parameters: {},
@@ -354,13 +356,14 @@ describe('abort during tool execution ends the turn', () => {
     await waitForIdle(ctx, agent)
 
     const events = [...agent.session.events]
+    const isInjected = (e: SessionEvent): e is SessionEvent<'user/message'> => e.type === 'user/message' && e.data.source.kind !== 'user'
     expect(events
-      .filter(event => event.type === 'tool/result' || event.type === 'context/message'
+      .filter(event => event.type === 'tool/result' || isInjected(event)
         || event.type === 'step/end' || event.type === 'turn/end')
-      .map(event => event.type))
+      .map(event => isInjected(event) ? 'context/message' : event.type))
       .toEqual(['tool/result', 'context/message', 'context/message', 'step/end', 'turn/end'])
     expect(events
-      .filter(event => event.type === 'context/message')
+      .filter(isInjected)
       .map(event => event.data.content))
       .toEqual([
         [{ type: 'text', text: 'accepted before abort' }],
@@ -378,7 +381,7 @@ describe('abort during tool execution ends the turn', () => {
     ] satisfies StreamChunk[]])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a-later-abort-context'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'first',
       description: '',
       parameters: {},
@@ -386,7 +389,7 @@ describe('abort during tool execution ends the turn', () => {
         return [{ type: 'text', text: 'first done' }]
       },
     }))
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'aborter',
       description: '',
       parameters: {},
@@ -410,12 +413,13 @@ describe('abort during tool execution ends the turn', () => {
     await waitForIdle(ctx, agent)
 
     const events = [...agent.session.events]
+    const isInjected = (e: SessionEvent): e is SessionEvent<'user/message'> => e.type === 'user/message' && e.data.source.kind !== 'user'
     expect(events
-      .filter(event => event.type === 'tool/result' || event.type === 'context/message'
+      .filter(event => event.type === 'tool/result' || isInjected(event)
         || event.type === 'step/end' || event.type === 'turn/end')
-      .map(event => event.type))
+      .map(event => isInjected(event) ? 'context/message' : event.type))
       .toEqual(['tool/result', 'tool/result', 'context/message', 'step/end', 'turn/end'])
-    expect(events.find(event => event.type === 'context/message')?.data.content)
+    expect(events.find(isInjected)?.data.content)
       .toEqual([{ type: 'text', text: 'accepted after first result' }])
   })
 
@@ -427,7 +431,7 @@ describe('abort during tool execution ends the turn', () => {
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
       agent = inner.agentLoop.create(SessionId('a-dispose-injection'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'waiter',
       description: '',
       parameters: {},
@@ -456,7 +460,7 @@ describe('abort during tool execution ends the turn', () => {
     await fiber.dispose()
 
     expect(agent.session.events
-      .filter(event => event.type === 'context/message')
+      .filter((event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind !== 'user')
       .map(event => event.data.content))
       .toEqual([
         [{ type: 'text', text: 'accepted before disposal' }],
@@ -479,7 +483,7 @@ describe('abort during tool execution ends the turn', () => {
     ])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'aborter',
       description: '',
       parameters: {},
@@ -488,7 +492,7 @@ describe('abort during tool execution ends the turn', () => {
         return [{ type: 'text', text: 'done' }]
       },
     }))
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'second',
       description: '',
       parameters: {},
@@ -507,7 +511,7 @@ describe('abort during tool execution ends the turn', () => {
     send(agent, 'start a text-only turn')
     await waitForIdle(ctx, agent)
 
-    expect(agent.session.events.find(event => event.type === 'context/message')?.data.content)
+    expect(agent.session.events.find((event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind !== 'user')?.data.content)
       .toEqual([{ type: 'text', text: 'new turn context' }])
     expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('new turn context')
   })
@@ -763,11 +767,11 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     expect(agent.session.deriveMessages().at(-1)?.content).toEqual([{ type: 'text', text: 'routed' }])
   })
 
-  it('agent/queued carries the resolved source; steering/message records its source', async () => {
+  it('agent/inbox/enqueue carries the resolved source; steering/message records its source', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'noop',
       description: '',
       parameters: {},
@@ -778,7 +782,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     }))
 
     const queuedSources: { source: MessageSource; contexts: HookContext[]; steering: boolean }[] = []
-    ctx.on('agent/queued', (_agent, _content, info) => void queuedSources.push(info))
+    ctx.on('agent/inbox/enqueue', (_agent, info) => void queuedSources.push({ source: info.source, contexts: info.contexts, steering: info.steering }))
 
     send(agent, 'go') // no explicit source → default {kind:'user'} must be visible
     await waitForIdle(ctx, agent)
@@ -800,11 +804,11 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     let notifiedContent: ContentBlock[] | undefined
     let notifiedSource: MessageSource | undefined
     let notifiedContexts: HookContext[] | undefined
-    ctx.on('agent/queued', (subject, acceptedContent, info) => {
+    ctx.on('agent/inbox/enqueue', (subject, info) => {
       if (subject !== agent || info.steering) return
       // Retain the exact notification references: cloning here would test the
       // listener's copy rather than the event/inbox ownership boundary.
-      notifiedContent = acceptedContent
+      notifiedContent = info.content
       notifiedSource = info.source
       notifiedContexts = info.contexts
     })
@@ -814,7 +818,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
       source: { kind: 'plugin', plugin: 'context-source' },
       meta: { version: 1 },
     }]
-    agent.send(content, { source, contexts })
+    agent.followup(content, { source, contexts })
     content[0]!.text = 'caller-mutated-send'
     source.plugin = 'caller-mutated-source'
     contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-context' }
@@ -850,7 +854,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     const agent = ctx.agentLoop.create(SessionId('owned-steer'), { provider: 'mock', model: 'mock' })
     const entered = Promise.withResolvers<undefined>()
     const release = Promise.withResolvers<undefined>()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'gate',
       description: '',
       parameters: {},
@@ -863,14 +867,14 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     let notifiedContent: ContentBlock[] | undefined
     let notifiedSource: MessageSource | undefined
     let notifiedContexts: HookContext[] | undefined
-    ctx.on('agent/queued', (subject, acceptedContent, info) => {
+    ctx.on('agent/inbox/enqueue', (subject, info) => {
       if (subject !== agent || !info.steering) return
-      notifiedContent = acceptedContent
+      notifiedContent = info.content
       notifiedSource = info.source
       notifiedContexts = info.contexts
     })
 
-    agent.send([{ type: 'text', text: 'start' }])
+    agent.followup([{ type: 'text', text: 'start' }])
     await entered.promise
     expect(agent.status).toBe('running')
     const content = [{ type: 'text' as const, text: 'accepted-steer' }]
@@ -951,7 +955,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     expect(request).not.toContain('caller-mutated-steering-context-without-meta')
 
     const steeringIndex = agent.session.events.findIndex(event => event.type === 'steering/message')
-    const contextIndex = agent.session.events.findIndex(event => event.type === 'context/message'
+    const contextIndex = agent.session.events.findIndex(event => event.type === 'user/message'
       && event.data.source.kind === 'plugin' && event.data.source.plugin === 'steering-context')
     expect(steeringIndex).toBeGreaterThanOrEqual(0)
     expect(contextIndex).toBe(steeringIndex + 1)
@@ -987,7 +991,7 @@ describe('turn numbering continues across seeded sessions', () => {
 
     const turns: number[] = []
     ctx2.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
-    forked.send([{ type: 'text', text: 'continue' }])
+    forked.followup([{ type: 'text', text: 'continue' }])
     await new Promise<void>((resolve) => {
       ctx2.on('agent/status', (subject, status) => {
         if (subject === forked && status === 'idle') resolve()
@@ -1497,7 +1501,7 @@ describe('tool result call identity', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo',
       description: 'echo',
       parameters: { x: { type: 'number' } },
diff --git a/packages/core/agent-loop/tests/coverage-edges.spec.ts b/packages/core/agent-loop/tests/coverage-edges.spec.ts
index 7d4e79238e..f8ff5a74b9 100644
--- a/packages/core/agent-loop/tests/coverage-edges.spec.ts
+++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts
@@ -4,7 +4,7 @@ import LlmService, { CallId, LlmError, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -38,7 +38,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 describe('inbox acceptance', () => {
@@ -47,13 +47,13 @@ describe('inbox acceptance', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let queued = 0
-    ctx.on('agent/queued', () => { queued += 1 })
+    ctx.on('agent/inbox/enqueue', () => { queued += 1 })
 
     expect(() => {
-      agent.send([{ type: 'text', text: 'first', bad: 1n } as never])
+      agent.followup([{ type: 'text', text: 'first', bad: 1n } as never])
     }).toThrow(/losslessly JSON-serializable/)
     expect(() => {
-      agent.send([{ type: 'text', text: 'first' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
+      agent.followup([{ type: 'text', text: 'first' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
     }).toThrow(/losslessly JSON-serializable/)
     expect(queued).toBe(0)
     expect(agent.session.events).toHaveLength(0)
@@ -77,7 +77,7 @@ describe('tool JSON parse', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo',
       description: 'echo tool',
       parameters: { input: { type: 'string' } },
@@ -110,7 +110,7 @@ describe('tool JSON parse', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'noarg',
       description: 'no-arg tool',
       parameters: {},
@@ -259,7 +259,7 @@ describe('structured tool error propagation (the runtime-validation Agent Note,
     ])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'boom',
       description: 'always fails',
       parameters: {},
diff --git a/packages/core/agent-loop/tests/inbox-invariant.spec.ts b/packages/core/agent-loop/tests/inbox-invariant.spec.ts
new file mode 100644
index 0000000000..0d907f26d7
--- /dev/null
+++ b/packages/core/agent-loop/tests/inbox-invariant.spec.ts
@@ -0,0 +1,155 @@
+/**
+ * Regression: the dsh-agent FIFO-conservation invariant must stay balanced on
+ * the loop-authored continuation-reason steering path. A continue-with-reason
+ * decision enters the steering FIFO and later drains (or is discarded by
+ * cancel); both must be matched by an enqueue event so the invariant's
+ * outstanding count never goes negative.
+ * @module dsh-agent-loop/tests/inbox-invariant
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter, textResponse } from './mock-adapter.ts'
+
+async function harness(adapter: MockAdapter) {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(AgentInvariant)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') { dispose(); resolve() }
+    })
+  })
+}
+
+describe('inbox FIFO-conservation invariant', () => {
+  it('stays balanced when a continuation reason enters and drains the steering FIFO', async () => {
+    const adapter = new MockAdapter([textResponse('step 1'), textResponse('step 2')])
+    const ctx = await harness(adapter)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    let forced = false
+    ctx.on('agent/turn-continuation', async (_agent, _turn, _default, _signal, next) => {
+      if (forced) return next()
+      forced = true
+      return { action: 'continue' as const, reason: { content: [{ type: 'text', text: 'keep going' }], source: { kind: 'plugin', plugin: 'loop' } } }
+    })
+
+    agent.followup([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(2)
+    // The continuation reason drained as a steering/message on the second step.
+    expect(agent.session.events.some(e => e.type === 'steering/message')).toBe(true)
+    // No invariant violation was logged.
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
+  })
+
+  it('stays balanced when cancel discards a pending continuation reason', async () => {
+    const adapter = new MockAdapter([textResponse('only step')])
+    const ctx = await harness(adapter)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    // Force a continuation reason, then cancel from the same checkpoint so the
+    // reason sits in the steering FIFO when the inbox is discarded.
+    ctx.on('agent/turn-continuation', async (subject, _turn, _default, _signal, next) => {
+      if (subject !== agent) return next()
+      queueMicrotask(() => { agent.cancel({ kind: 'user' }) })
+      return { action: 'continue' as const, reason: { content: [{ type: 'text', text: 'keep going' }], source: { kind: 'plugin', plugin: 'loop' } } }
+    })
+
+    agent.followup([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
+  })
+
+  it('stays balanced when a terminal stop discards pending steering', async () => {
+    const adapter = new MockAdapter([textResponse('done')])
+    const ctx = await harness(adapter)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    const discards: number[] = []
+    ctx.on('agent/inbox/discard', (subject, messages) => { if (subject === agent) discards.push(messages.length) })
+
+    // A continuation reason enqueues a steering item; a terminal stop then drops
+    // it. The drop must emit a discard so the enqueue ⇒ dequeue-or-discard
+    // ledger stays balanced (no dangling outstanding id).
+    ctx.on('agent/turn-continuation', async (subject, _turn, _default, _signal, next) => {
+      if (subject !== agent) return next()
+      return { action: 'continue' as const, reason: { content: [{ type: 'text', text: 'keep going' }], source: { kind: 'plugin', plugin: 'loop' } } }
+    })
+    let stopped = false
+    ctx.on('agent/turn-stop', (subject) => {
+      if (subject !== agent || stopped) return undefined
+      stopped = true
+      return { action: 'stop' as const }
+    })
+
+    agent.followup([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(discards).toEqual([1]) // the dropped steering item was reported
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
+  })
+
+  it('stays balanced when late steering lands after a terminal stop (post-turn flush window)', async () => {
+    const adapter = new MockAdapter([textResponse('done')])
+    const ctx = await harness(adapter)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    let enqueues = 0
+    const discards: number[] = []
+    ctx.on('agent/inbox/enqueue', (subject) => { if (subject === agent) enqueues += 1 })
+    ctx.on('agent/inbox/discard', (subject, messages) => { if (subject === agent) discards.push(messages.length) })
+
+    // Terminal-stop the turn, then steer during the post-turn flush window
+    // (status is still running). That late steer is drained by runLoop and
+    // dropped because the turn terminally stopped; it must still be discarded so
+    // its enqueue is matched (the drain sits on a different code path than the
+    // in-turn terminal-stop drop).
+    ctx.on('agent/turn-stop', subject => (subject === agent ? { action: 'stop' as const } : undefined))
+    let steered = false
+    ctx.on('session/flush', (session) => {
+      if (session !== agent.session || steered) return
+      steered = true
+      agent.steer([{ type: 'text', text: 'late' }], { source: { kind: 'plugin', plugin: 'late' } })
+    })
+
+    agent.followup([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    // The prompt plus the late steer both enqueued; both are matched (the prompt
+    // dequeued, the late steer discarded) so no id is left outstanding.
+    expect(enqueues).toBe(2)
+    expect(discards).toEqual([1])
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
+  })
+})
diff --git a/packages/core/agent-loop/tests/inbox.spec.ts b/packages/core/agent-loop/tests/inbox.spec.ts
index 99cae1ae77..289cd2f6d5 100644
--- a/packages/core/agent-loop/tests/inbox.spec.ts
+++ b/packages/core/agent-loop/tests/inbox.spec.ts
@@ -1,10 +1,20 @@
 import { describe, expect, it } from 'vitest'
-import { Inbox } from '../src/inbox.ts'
+import { AgentMessageId } from '@deepseek-ai/dsh-agent'
+import { Inbox, agentMessage } from '../src/inbox.ts'
 
 function message(text: string) {
-  return { content: [{ type: 'text' as const, text }], source: { kind: 'user' as const }, contexts: [] }
+  return { id: AgentMessageId(text), content: [{ type: 'text' as const, text }], source: { kind: 'user' as const }, contexts: [], wakeup: true }
 }
 
+describe('agentMessage', () => {
+  it('returns a frozen payload so a listener cannot mutate it for later listeners', () => {
+    const payload = agentMessage(message('m'), false)
+    expect(Object.isFrozen(payload)).toBe(true)
+    expect(() => { (payload as { id: string }).id = 'mutated' }).toThrow()
+    expect(payload.id).toBe(AgentMessageId('m'))
+  })
+})
+
 function resolverPair() {
   let r!: () => void
   const p = new Promise<void>((resolve) => { r = resolve })
@@ -25,6 +35,32 @@ describe('Inbox', () => {
     expect(inbox.dequeueQueued()).toBeUndefined()
   })
 
+  it('enqueue(msg, false) queues without waking a parked waiter', async () => {
+    const inbox = new Inbox()
+    let woke = false
+    const waiter = inbox.waitForQueued(new Promise(() => {})).then(() => { woke = true })
+    inbox.enqueue(message('quiet'), false)
+    // The item is queued, but the parked waiter was not resolved by it.
+    expect(inbox.hasQueued).toBe(true)
+    await Promise.resolve()
+    expect(woke).toBe(false)
+    // A later waking enqueue resolves the same waiter.
+    inbox.enqueue(message('loud'))
+    await waiter
+    expect(woke).toBe(true)
+  })
+
+  it('pending() snapshots queued then steering without removing them', () => {
+    const inbox = new Inbox()
+    inbox.enqueue(message('q'))
+    inbox.steer(message('s'))
+    const pending = inbox.pending()
+    expect(pending.map(p => p.steering)).toEqual([false, true])
+    // Snapshot does not drain the FIFOs.
+    expect(inbox.hasQueued).toBe(true)
+    expect(inbox.hasSteering).toBe(true)
+  })
+
   it('pushes and drains steering messages separately from queued', () => {
     const inbox = new Inbox()
     inbox.steer(message('steer'))
diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts
index 42a2808170..de721b1653 100644
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import LlmService, { CallId, type Message } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent, type ContinuationDecision, type PromptDecision, type SessionStartSource } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -42,7 +42,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 function events(agent: Agent): SessionEvent[] {
@@ -87,7 +87,7 @@ describe('agent/prompt-submit', () => {
     expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('original')
   })
 
-  it('allow with additionalContexts injects separate context/message events into the turn', async () => {
+  it('allow with additionalContexts injects separate injected-context user messages into the turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -107,12 +107,12 @@ describe('agent/prompt-submit', () => {
     await waitForIdle(ctx, agent)
 
     const log = events(agent)
-    const userMsg = log.find(e => e.type === 'user/message')
-    const ctxMsg = log.find(e => e.type === 'context/message')
+    const userMsg = log.find(e => e.type === 'user/message' && e.data.source.kind === 'user')
+    const ctxMsg = log.find(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
     expect(userMsg).toBeDefined()
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.content).toEqual([{ type: 'text', text: '<system-reminder>extra ctx</system-reminder>' }])
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.meta).toEqual(meta)
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.content).toEqual([{ type: 'text', text: '<system-reminder>extra ctx</system-reminder>' }])
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.meta).toEqual(meta)
     const sent = JSON.stringify(adapter.requests[0]!.messages)
     expect(sent).toContain('extra ctx')
   })
@@ -128,7 +128,7 @@ describe('agent/prompt-submit', () => {
         ? downstream
         : { ...downstream, content: [{ type: 'text', text: 'rewritten request' }] }
     })
-    agent.send([{ type: 'text', text: 'original request' }], {
+    agent.followup([{ type: 'text', text: 'original request' }], {
       contexts: [{
         content: [{ type: 'text', text: 'untrusted prefix' }],
         source: { kind: 'plugin', plugin: 'prefix' },
@@ -155,7 +155,7 @@ describe('agent/prompt-submit', () => {
         }],
       },
     })
-    expect(log.some(event => event.type === 'context/message')).toBe(false)
+    expect(log.some(event => event.type === 'user/message' && event.data.source.kind === 'plugin')).toBe(false)
     expect(adapter.requests[0]?.messages.at(-1)).toEqual({
       role: 'user',
       content: [
@@ -203,7 +203,7 @@ describe('agent/prompt-submit', () => {
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
 
-    agent.send([{ type: 'text', text: 'do something' }], {
+    agent.followup([{ type: 'text', text: 'do something' }], {
       contexts: [{ content: [{ type: 'text', text: 'must be dropped' }], source: { kind: 'plugin', plugin: 'test' } }],
     })
     await waitForIdle(ctx, agent)
@@ -215,7 +215,6 @@ describe('agent/prompt-submit', () => {
     expect(log.some(e => e.type === 'turn/start')).toBe(true)
     expect(log.some(e => e.type === 'turn/end')).toBe(true)
     expect(log.some(e => e.type === 'user/message')).toBe(false)
-    expect(log.some(e => e.type === 'context/message')).toBe(false)
     expect(log.some(e => e.type === 'step/start')).toBe(false)
     // the veto is recorded durably as a prompt/blocked in the open turn
     const blocked = log.find(e => e.type === 'prompt/blocked')
@@ -340,8 +339,8 @@ describe('agent/session-start', () => {
     // the injected context reached the model on the first (only) request
     expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('session preamble')
     // and is recorded with the plugin source, never mislabeled as a user prompt
-    const ctxMsg = events(agent).find(e => e.type === 'context/message')
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
+    const ctxMsg = events(agent).find(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
   })
 
   it('a throwing session-start listener does not abort agent construction', async () => {
@@ -399,7 +398,7 @@ describe('agent/session-prefix', () => {
       textResponse('again'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
@@ -521,7 +520,7 @@ describe('agent/session-prefix', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
@@ -574,7 +573,7 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
   it('a stop decision ends the turn even when the step had tool calls', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', { text: 'hi' })])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
@@ -604,7 +603,7 @@ describe('tool additionalContexts buffering across a step', () => {
     ]
     const adapter = new MockAdapter([twoCalls, textResponse('done')])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
@@ -624,29 +623,28 @@ describe('tool additionalContexts buffering across a step', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    // Event order in the log: both tool/results, THEN both context/messages —
+    // Event order in the log: both tool/results, THEN both injected contexts —
     // never interleaved (which would break tool-call/result adjacency).
-    const types = events(agent).map(e => e.type)
-    const firstResult = types.indexOf('tool/result')
-    const lastResult = types.lastIndexOf('tool/result')
-    const firstCtx = types.indexOf('context/message')
+    const injected = events(agent).filter(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
+    const seqs = events(agent)
+    const firstResult = seqs.findIndex(e => e.type === 'tool/result')
+    const lastResult = seqs.map(e => e.type).lastIndexOf('tool/result')
+    const firstCtx = seqs.findIndex(e => e === injected[0])
     expect(firstResult).toBeGreaterThanOrEqual(0)
     expect(lastResult).toBeGreaterThan(firstResult) // two results
     expect(firstCtx).toBeGreaterThan(lastResult)    // context only after ALL results
     // both contexts present
-    const ctxTexts = events(agent)
-      .filter(e => e.type === 'context/message')
-      .flatMap(e => (e.type === 'context/message' ? e.data.content : []))
+    const ctxTexts = injected
+      .flatMap(e => (e.type === 'user/message' ? e.data.content : []))
       .map(b => (b.type === 'text' ? b.text : ''))
     expect(ctxTexts).toEqual(['ctx-c1', 'ctx-c2'])
-    const contextEvents = events(agent).filter(e => e.type === 'context/message')
-    expect(contextEvents.map(e => e.type === 'context/message' && e.data.meta)).toEqual([{ callId: 'c1' }, { callId: 'c2' }])
+    expect(injected.map(e => e.type === 'user/message' && e.data.meta)).toEqual([{ callId: 'c1' }, { callId: 'c2' }])
   })
 
   it('appends multiple contexts deferred by one composite tool after its outer result', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'composite', {}), textResponse('done')])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'composite', description: 'composite', parameters: {},
       async execute(_args, exec) {
         exec.deferContext({ content: [{ type: 'text', text: 'nested-a' }], source: { kind: 'plugin', plugin: 'a' }, meta: { order: 1 } })
@@ -661,14 +659,14 @@ describe('tool additionalContexts buffering across a step', () => {
 
     const log = events(agent)
     const resultIndex = log.findIndex(event => event.type === 'tool/result')
-    const contextEvents = log.filter(event => event.type === 'context/message')
+    const contextEvents = log.filter(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
     expect(resultIndex).toBeGreaterThanOrEqual(0)
     expect(log.findIndex(event => event === contextEvents[0])).toBeGreaterThan(resultIndex)
-    expect(contextEvents.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+    expect(contextEvents.map(event => event.type === 'user/message' && event.data.source)).toEqual([
       { kind: 'plugin', plugin: 'a' },
       { kind: 'plugin', plugin: 'b' },
     ])
-    expect(contextEvents.map(event => event.type === 'context/message' && event.data.meta)).toEqual([{ order: 1 }, { order: 2 }])
+    expect(contextEvents.map(event => event.type === 'user/message' && event.data.meta)).toEqual([{ order: 1 }, { order: 2 }])
   })
 })
 
@@ -677,7 +675,7 @@ describe('tools/pre-execute gate (native-plugin permission pattern, end-to-end t
     const adapter = new MockAdapter([toolCallResponse('c1', 'danger', {}), textResponse('ok')])
     const ctx = await harness(adapter)
     let ran = false
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'danger', description: 'danger', parameters: {},
       async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] },
     }))
@@ -739,7 +737,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', { text: 'hi' }), textResponse('done')])
     const ctx = await harness(adapter)
     await ctx.plugin(NativeGuard)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
@@ -750,13 +748,13 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
 
     const log = events(agent)
     // session-start preamble injected
-    expect(log.some(e => e.type === 'context/message'
+    expect(log.some(e => e.type === 'user/message' && e.data.source.kind === 'plugin'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('policy active (started: startup)')))).toBe(true)
-    // prompt allowed → user/message recorded
-    expect(log.some(e => e.type === 'user/message')).toBe(true)
+    // prompt allowed → user-sourced user/message recorded
+    expect(log.some(e => e.type === 'user/message' && e.data.source.kind === 'user')).toBe(true)
     // tool ran (echo allowed) and post-execute attached "audited" context
     expect(log.some(e => e.type === 'tool/result' && !e.data.isError)).toBe(true)
-    expect(log.some(e => e.type === 'context/message'
+    expect(log.some(e => e.type === 'user/message' && e.data.source.kind === 'plugin'
       && e.data.content.some(b => b.type === 'text' && b.text === 'audited'))).toBe(true)
     // NO hook/* events — a native plugin needs none
     expect(log.some(e => e.type.startsWith('hook/'))).toBe(false)
diff --git a/packages/core/agent-loop/tests/invariant.spec.ts b/packages/core/agent-loop/tests/invariant.spec.ts
index aa8bd5d6d5..cb0dcd2384 100644
--- a/packages/core/agent-loop/tests/invariant.spec.ts
+++ b/packages/core/agent-loop/tests/invariant.spec.ts
@@ -42,7 +42,7 @@ describe('request-reconstruction invariant', () => {
 
   it('uses the step boundary rather than content appended afterward', async () => {
     const { ctx, session, boundary } = await requestSetup()
-    session.append('context/message', { content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' } }, { surfaceOp: 'append' })
+    session.append('user/message', { content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' } }, { surfaceOp: 'append' })
     const options = loopRequest({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
     expect(() => { dispatch(ctx, options) }).not.toThrow()
   })
diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts
index 5eaaa2ea5a..8875b51d67 100644
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { CallId, StreamChunk } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, TurnEndReason, type JsonValue } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture, defineTool } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -42,7 +42,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 describe('agent loop', () => {
@@ -89,7 +89,7 @@ describe('agent loop', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo',
       description: 'echo back',
       parameters: { text: { type: 'string' } },
@@ -118,22 +118,27 @@ describe('agent loop', () => {
     const types = agent.session.events.map(e => e.type)
     expect(types).toContain('tool/call')
     expect(types).toContain('tool/result')
+    const durableResult = agent.session.events.find(event => event.type === 'tool/result')
+    expect(durableResult?.type === 'tool/result' && 'value' in durableResult.data).toBe(false)
   })
 
-  it('threads a tool-attached meta (execute object return) onto the tool/result event', async () => {
+  it('persists presentation metadata projected from the canonical value', async () => {
     const adapter = new MockAdapter([
       toolCallResponse('c1', 'writer', { path: 'a.txt' }, 'writing'),
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    // A tool that returns the { content, meta } object form: the loop must
-    // persist `meta` on the tool/result event so a UI reproduces the card on replay.
     ctx.tools.register(defineTool({
       name: 'writer',
       description: 'writes a file',
       parameters: { path: { type: 'string' } },
+      output: {
+        schema: { type: 'string' },
+        render: () => [{ type: 'text', text: 'ok' }],
+        presentationMeta: (_args, value) => ({ diffs: [{ path: value, oldText: null, newText: 'x' }] }),
+      },
       async execute() {
-        return { content: [{ type: 'text', text: 'ok' }], meta: { diffs: [{ path: 'a.txt', oldText: null, newText: 'x' }] } }
+        return 'a.txt'
       },
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -152,7 +157,7 @@ describe('agent loop', () => {
     // projecting this agent's configured model, so the model knows its own name.
     const ctx = await harness(adapter, 'You are a test agent on {{model}}.')
     ctx.systemPrompt.section({ name: 'tool:noop', order: 100, text: 'Use the noop tool wisely.' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'noop',
       description: 'does nothing',
       parameters: {},
@@ -248,7 +253,7 @@ describe('agent loop', () => {
     ['BigInt', { n: 1n }],
     ['Map', new Map([['key', 'value']])],
     ['class instance', new (class ResultMeta { x = 1 })()],
-  ])('normalizes non-JSON tool meta (%s) before the durable result commit', async (_kind, meta) => {
+  ])('rejects non-JSON presentation metadata (%s) before the durable result commit', async (_kind, meta) => {
     const adapter = new MockAdapter([
       toolCallResponse('bad-meta-call', 'bad-meta', {}, 'calling'),
       textResponse('recovered'),
@@ -258,7 +263,12 @@ describe('agent loop', () => {
       name: 'bad-meta',
       description: 'returns invalid durable metadata',
       parameters: {},
-      execute: () => Promise.resolve({ content: [{ type: 'text' as const, text: 'apparent success' }], meta }),
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+        presentationMeta: () => meta as unknown as JsonValue,
+      },
+      execute: () => Promise.resolve('apparent success'),
     }))
     const agent = ctx.agentLoop.create(SessionId('bad-meta-agent'), { provider: 'mock', model: 'mock' })
 
@@ -271,15 +281,16 @@ describe('agent loop', () => {
       expect(result.data.callId).toBe('bad-meta-call')
       expect(result.data.isError).toBe(true)
       expect(result.data.meta).toBeUndefined()
+      expect(result.data.error).toEqual({ name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' })
       expect(result.data.content).toEqual([{
         type: 'text',
-        text: 'Error: tool result must be losslessly JSON-serializable',
+        text: 'Error: tool "bad-meta" returned invalid output: output.presentationMeta returned non-lossless JSON',
       }])
     }
     // The normalized failure was durably logged and fed back to the model; the
     // turn continued normally instead of failing after an apparent success.
     expect(adapter.requests).toHaveLength(2)
-    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('losslessly JSON-serializable')
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('output.presentationMeta returned non-lossless JSON')
   })
 
   it('omits the system field when a system-prompt/assemble veto empties the assembly', async () => {
@@ -326,7 +337,7 @@ describe('agent loop', () => {
     const ctx = await harness(adapter)
 
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'slow',
       description: '',
       parameters: {},
@@ -380,7 +391,7 @@ describe('agent loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.inject([{ type: 'text', text: 'file changed: a.ts' }], { source: { kind: 'plugin', plugin: 'watcher' } })
-    // The idle inject records a self-contained turn (turn/start → context/message
+    // The idle inject records a self-contained turn (turn/start → user/message
     // → turn/end) so the event stays turn-enclosed, but does NOT run the model.
     await new Promise(r => setTimeout(r, 20))
     expect(agent.status).toBe('idle')
@@ -416,8 +427,8 @@ describe('agent loop', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    const contextEvent = agent.session.events.find(event => event.type === 'context/message')
-    expect(contextEvent?.type === 'context/message' && contextEvent.data).toMatchObject({ meta })
+    const contextEvent = agent.session.events.find(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
+    expect(contextEvent?.type === 'user/message' && contextEvent.data).toMatchObject({ meta })
     const requestText = JSON.stringify(adapter.requests[0]!.messages)
     expect(requestText).toContain('Additional instructions from: pkg/AGENTS.md')
     expect(requestText).not.toContain('<context source=')
@@ -432,7 +443,7 @@ describe('agent loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let visibleDuringTool = false
     const meta = { kind: 'deferred-test', version: 1 }
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'noticer',
       description: 'injects a notice',
       parameters: {},
@@ -445,7 +456,7 @@ describe('agent loop', () => {
         })
         first.text = 'mutated after inject'
         agent.inject([{ type: 'text', text: 'second notice' }], { source: { kind: 'plugin', plugin: 'x' } })
-        visibleDuringTool = agent.session.events.some(e => e.type === 'context/message')
+        visibleDuringTool = agent.session.events.some(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
         return [{ type: 'text', text: 'ok' }]
       },
     }))
@@ -462,13 +473,13 @@ describe('agent loop', () => {
     const ts0 = turnStarts[0]!
     expect(ts0.type === 'turn/start' && ts0.data.trigger.kind).toBe('message')
     const result = agent.session.events.find(e => e.type === 'tool/result')!
-    const contexts = agent.session.events.filter(e => e.type === 'context/message')
+    const contexts = agent.session.events.filter(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
     expect(contexts).toHaveLength(2)
     expect(result.seq).toBeLessThan(contexts[0]!.seq)
-    expect(contexts[0]?.type === 'context/message' && contexts[0].data).toMatchObject({
+    expect(contexts[0]?.type === 'user/message' && contexts[0].data).toMatchObject({
       meta,
     })
-    expect(contexts.flatMap(event => event.type === 'context/message' ? event.data.content : []))
+    expect(contexts.flatMap(event => event.type === 'user/message' ? event.data.content : []))
       .toEqual([
         { type: 'text', text: 'mid-turn notice' },
         { type: 'text', text: 'second notice' },
@@ -494,7 +505,7 @@ describe('agent loop', () => {
     ])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('invalid-context'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'invalid-injector',
       description: 'attempts an invalid context injection',
       parameters: {},
@@ -512,7 +523,29 @@ describe('agent loop', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    expect(agent.session.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(agent.session.events.some(event => event.type === 'user/message' && event.data.source.kind === 'plugin')).toBe(false)
+  })
+
+  it('preserves SendOptions.meta on the durable user/message and steering/message', async () => {
+    const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineContentToolFixture({
+      name: 'noop', description: '', parameters: {},
+      async execute() {
+        // Running steer carries its own meta onto the durable steering/message.
+        agent.steer([{ type: 'text', text: 's' }], { source: { kind: 'plugin', plugin: 'p' }, meta: { steer: 1 } })
+        return []
+      },
+    }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.followup([{ type: 'text', text: 'go' }], { meta: { prompt: 1 } })
+    await waitForIdle(ctx, agent)
+
+    const user = agent.session.events.find(e => e.type === 'user/message')
+    expect(user?.type === 'user/message' && user.data.meta).toEqual({ prompt: 1 })
+    const steering = agent.session.events.find(e => e.type === 'steering/message')
+    expect(steering?.type === 'steering/message' && steering.data.meta).toEqual({ steer: 1 })
   })
 
   it('agent/turn-continuation can force-continue (/loop pattern) and force-stop', async () => {
@@ -541,7 +574,7 @@ describe('agent loop', () => {
   it('agent/turn-continuation can veto continuation despite tool calls (budget-guard pattern)', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', { text: 'x' })])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo',
       description: '',
       parameters: { text: { type: 'string' } },
@@ -589,7 +622,7 @@ describe('agent loop', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo', description: 'echo', parameters: {},
       async execute() { return [{ type: 'text', text: 'echoed' }] },
     }))
@@ -621,7 +654,7 @@ describe('agent loop', () => {
     ctx.on('agent/pre-step', (subject) => {
       if (subject === agent && !injected) {
         injected = true
-        subject.session.append('context/message', {
+        subject.session.append('user/message', {
           content: [{ type: 'text', text: 'INJECTED-IN-PRE-STEP' }],
           source: { kind: 'plugin', plugin: 'test' },
         }, { surfaceOp: 'append' })
@@ -639,7 +672,7 @@ describe('agent loop', () => {
     // And the injected event sits BEFORE the first step/start in the log —
     // the seam fired outside the step.
     const events = agent.session.events
-    const injectedSeq = events.find(e => e.type === 'context/message')!.seq
+    const injectedSeq = events.find(e => e.type === 'user/message' && e.data.source.kind === 'plugin')!.seq
     const firstStepStartSeq = events.find(e => e.type === 'step/start')!.seq
     expect(injectedSeq).toBeLessThan(firstStepStartSeq)
   })
@@ -781,7 +814,7 @@ describe('agent loop', () => {
     ]])
     const ctx = await harness(adapter)
     let executions = 0
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo',
       description: '',
       parameters: { text: { type: 'string' } },
@@ -821,7 +854,7 @@ describe('agent loop', () => {
       { type: 'finish', reason: { kind: 'max-tokens' } },
     ]])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo',
       description: '',
       parameters: { text: { type: 'string' } },
@@ -908,7 +941,7 @@ describe('agent loop', () => {
       textResponse('continued after tool call'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo',
       description: '',
       parameters: { text: { type: 'string' } },
@@ -1017,13 +1050,13 @@ describe('agent loop', () => {
     expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('turn-end listener message')
   })
 
-  it('keeps a reentrant agent/queued send as the next independent turn', async () => {
+  it('keeps a reentrant agent/inbox/enqueue send as the next independent turn', async () => {
     const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let nested = false
-    ctx.on('agent/queued', (subject) => {
+    ctx.on('agent/inbox/enqueue', (subject) => {
       if (subject !== agent || nested) return
       nested = true
       send(agent, 'queued listener message')
@@ -1050,9 +1083,9 @@ describe('agent loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const idle = waitForIdle(ctx, agent)
-    agent.send([{ type: 'text', text: 'user message' }])
+    agent.followup([{ type: 'text', text: 'user message' }])
     await Promise.resolve()
-    agent.send(
+    agent.followup(
       [{ type: 'text', text: 'plugin message' }],
       { source: { kind: 'plugin', plugin: 'test' } },
     )
@@ -1240,7 +1273,7 @@ describe('agent loop', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'echo',
       description: '',
       parameters: { text: { type: 'string' } },
diff --git a/packages/core/agent-loop/tests/properties.spec.ts b/packages/core/agent-loop/tests/properties.spec.ts
index 85efda0e4e..593b32ab38 100644
--- a/packages/core/agent-loop/tests/properties.spec.ts
+++ b/packages/core/agent-loop/tests/properties.spec.ts
@@ -115,7 +115,7 @@ describe('agent loop scheduling properties', () => {
           const { seen: trace } = recordStatus(ctx, agent)
           const idle = nextIdle(ctx, agent)
           // Send all in one synchronous tick: they queue before the loop wakes.
-          for (const text of texts) agent.send([{ type: 'text', text }])
+          for (const text of texts) agent.followup([{ type: 'text', text }])
           await idle
 
           // No message lost: every send appears as a user/message, in order.
@@ -142,7 +142,7 @@ describe('agent loop scheduling properties', () => {
           const agent = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
           for (const text of texts) {
             const idle = nextIdle(ctx, agent)
-            agent.send([{ type: 'text', text }])
+            agent.followup([{ type: 'text', text }])
             await idle
           }
           // Each send was drained at a separate turn start: N turns, 1..N.
@@ -171,7 +171,7 @@ describe('agent loop scheduling properties', () => {
           for (const step of steps) {
             const idle = nextIdle(ctx, agent)
             lastIdle = idle
-            agent.send([{ type: 'text', text: step.text }])
+            agent.followup([{ type: 'text', text: step.text }])
             if (step.settle) await idle
           }
           await lastIdle
diff --git a/packages/core/agent-loop/tests/request-cache.e2e.ts b/packages/core/agent-loop/tests/request-cache.e2e.ts
index 36d88feaa9..37079b8565 100644
--- a/packages/core/agent-loop/tests/request-cache.e2e.ts
+++ b/packages/core/agent-loop/tests/request-cache.e2e.ts
@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -45,7 +45,7 @@ async function loopHarness(): Promise<Context> {
   await created.plugin(AgentRegistry)
   await created.plugin(AgentLoop, { agents: [] })
   await created.plugin(LlmDeepSeek)
-  created.tools.register(defineTool({
+  created.tools.register(defineContentToolFixture({
     name: 'lookup',
     description: 'Look up the stored value for a key.',
     parameters: { key: { type: 'string', description: 'The key to look up.' } },
@@ -73,10 +73,10 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('log-derived request cache hits (
     const agent = ctx.agentLoop.create(SessionId('cache-e2e'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     // Turn 1: forces a tool call → at least two steps (two model requests).
-    agent.send([{ type: 'text', text: 'Look up the key "deploy-color" with the lookup tool and tell me the value.' }])
+    agent.followup([{ type: 'text', text: 'Look up the key "deploy-color" with the lookup tool and tell me the value.' }])
     await waitForIdle(ctx, agent)
     // Turn 2: a follow-up over the same (longer) prefix.
-    agent.send([{ type: 'text', text: 'Thanks. Repeat that value one more time.' }])
+    agent.followup([{ type: 'text', text: 'Thanks. Repeat that value one more time.' }])
     await waitForIdle(ctx, agent)
 
     const usages = [...agent.session.events]
diff --git a/packages/core/agent-loop/tests/request-reconstruction.spec.ts b/packages/core/agent-loop/tests/request-reconstruction.spec.ts
index aad90a7dde..a73218f345 100644
--- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts
+++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts
@@ -11,7 +11,7 @@ import LlmService from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -41,7 +41,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 /** Assert `previous` is a strict value-prefix of `current`. */
@@ -53,7 +53,7 @@ function expectPrefixExtension(previous: GenerateOptions, current: GenerateOptio
 }
 
 function registerEcho(ctx: Context) {
-  ctx.tools.register(defineTool({
+  ctx.tools.register(defineContentToolFixture({
     name: 'echo',
     description: 'echo back',
     parameters: { text: { type: 'string' } },
@@ -118,7 +118,7 @@ describe('request stability across the loop', () => {
       preStep()
       const session = agent.session
       const nodes = session.surface.nodes
-      session.append('context/message', {
+      session.append('user/message', {
         content: [{ type: 'text', text: '[summary of turn 1]' }],
         source: { kind: 'plugin', plugin: 'test-compact' },
       }, {
@@ -180,7 +180,7 @@ describe('request stability across the loop', () => {
     const first = adapter.requests[0]!
     // The inject landed in the log after the boundary: not in THIS request…
     expect(first.messages.some(m => m.content.some(b => b.type === 'text' && b.text.includes('[late context]')))).toBe(false)
-    expect(agent.session.events.some(e => e.type === 'context/message')).toBe(true)
+    expect(agent.session.events.some(e => e.type === 'user/message' && e.data.source.kind === 'plugin')).toBe(true)
 
     send(agent, 'second')
     await waitForIdle(ctx, agent)
diff --git a/packages/core/agent-loop/tests/request-recovery.spec.ts b/packages/core/agent-loop/tests/request-recovery.spec.ts
index 1e6bc14548..1fc44e3431 100644
--- a/packages/core/agent-loop/tests/request-recovery.spec.ts
+++ b/packages/core/agent-loop/tests/request-recovery.spec.ts
@@ -11,7 +11,7 @@ import LlmService, {
 import type { GenerateOptions, LlmFailure, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { PostToolDecision } from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -114,7 +114,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent): void {
-  agent.send([{ type: 'text', text: 'go' }])
+  agent.followup([{ type: 'text', text: 'go' }])
 }
 
 function contextError(message = 'context too large'): LlmError {
@@ -133,7 +133,7 @@ describe('agent post-step and request-error lifecycle', () => {
     ]
     const adapter = new FailureScriptAdapter([twoCalls, textResponse('done')])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'work',
       description: 'do work',
       parameters: {},
@@ -154,12 +154,15 @@ describe('agent post-step and request-error lifecycle', () => {
     const agent = ctx.agentLoop.create(SessionId('post-step-order'), { provider: 'mock', model: 'mock' })
     const order: string[] = []
     ctx.on('session/event', (_session, event) => {
+      // Injected context is a plugin-sourced user/message; the direct human
+      // prompt (user source) stays untracked as before.
+      const isInjected = event.type === 'user/message' && event.data.source.kind !== 'user'
       if (
         event.type === 'assistant/message' || event.type === 'tool/call'
-        || event.type === 'tool/result' || event.type === 'context/message'
+        || event.type === 'tool/result' || isInjected
         || event.type === 'steering/message' || event.type === 'step/end'
       ) {
-        if (!('step' in event.data) || event.data.step === 1) order.push(event.type)
+        if (!('step' in event.data) || event.data.step === 1) order.push(isInjected ? 'context/message' : event.type)
       }
     })
     ctx.on('agent/post-step', (subject, turn, step, signal) => {
@@ -222,7 +225,7 @@ describe('agent post-step and request-error lifecycle', () => {
       textResponse('must not continue'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'work',
       description: 'do work',
       parameters: {},
@@ -271,7 +274,7 @@ describe('agent post-step and request-error lifecycle', () => {
       expect({ turn, step, code: error.code }).toEqual({ turn: 1, step: 1, code: CONTEXT_WINDOW_EXCEEDED_CODE })
       expect(facts.code).toBe(CONTEXT_WINDOW_EXCEEDED_CODE)
       attempts.push(history.length)
-      subject.session.append('context/message', {
+      subject.session.append('user/message', {
         content: [{ type: 'text', text: 'RECOVERY SURFACE MUTATION' }],
         source: { kind: 'plugin', plugin: 'test-recovery' },
       }, { surfaceOp: 'append' })
@@ -288,7 +291,7 @@ describe('agent post-step and request-error lifecycle', () => {
     const ends = agent.session.events.filter(event => event.type === 'step/end')
     expect(starts.map(event => event.data.step)).toEqual([1, 2])
     expect(ends.map(event => event.data.step)).toEqual([1, 2])
-    const recovery = agent.session.events.find(event => event.type === 'context/message')!
+    const recovery = agent.session.events.find(event => event.type === 'user/message' && event.data.source.kind === 'plugin')!
     expect(ends[0]!.seq).toBeLessThan(recovery.seq)
     expect(recovery.seq).toBeLessThan(starts[1]!.seq)
   })
@@ -535,7 +538,7 @@ describe('agent post-step and request-error lifecycle', () => {
       contextError('later overflow'),
     ])
     const resetCtx = await harness(reset)
-    resetCtx.tools.register(defineTool({
+    resetCtx.tools.register(defineContentToolFixture({
       name: 'work',
       description: 'continue',
       parameters: {},
diff --git a/packages/core/agent-loop/tests/resume.spec.ts b/packages/core/agent-loop/tests/resume.spec.ts
index 5c64bb92f9..a9bd0a0355 100644
--- a/packages/core/agent-loop/tests/resume.spec.ts
+++ b/packages/core/agent-loop/tests/resume.spec.ts
@@ -111,6 +111,27 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     await ctx.fiber.dispose()
   })
 
+  it('resume cannot crash-repair a turn owned by a live agent', async () => {
+    const { ctx } = await persistentHarness(new MockAdapter([textResponse('unused')]))
+    const sessionId = SessionId('live-resume-race')
+    const first = (await ctx.agents.create({ sessionId })).agent
+    first.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await ctx.sessions.flush(first.session)
+
+    await expect(ctx.agents.resume({ resumeSessionId: sessionId }))
+      .rejects.toThrow(/live turn is open/)
+
+    first.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    await ctx.sessions.flush(first.session)
+    const loaded = await ctx.sessionPersistence.load(sessionId)
+    expect(loaded.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
+    expect(loaded.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'completed' } },
+    })
+    await ctx.fiber.dispose()
+  })
+
   it('createAgent works without meta (no cwd)', async () => {
     const adapter = new MockAdapter([textResponse('hi')])
     const { ctx } = await persistentHarness(adapter)
@@ -125,7 +146,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('nocwd-sess') })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -153,7 +174,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     ctx1.on('agent/session-start', (_agent, source) => void sources1.push(source))
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('start-sess') })).agent
     expect(sources1).toEqual(['startup'])
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -459,7 +480,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
     // Let inject()'s fire-and-forget flush settle (NO explicit flush/dispose).
@@ -482,7 +503,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
     await ctx1.sessions.flush(a1.session)
@@ -510,7 +531,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('first answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'first question' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'first question' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     const events1 = [...a1.session.events]
     const seqs1 = events1.map(e => e.seq)
@@ -537,7 +558,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     expect(a2.session.deriveMessages()).toEqual(replay.deriveMessages())
 
     // …and a new turn continues numbering (turn 2) with contiguous seqs.
-    a2.send([{ type: 'text', text: 'second question' }], { source: { kind: 'user' } })
+    a2.followup([{ type: 'text', text: 'second question' }], { source: { kind: 'user' } })
     await waitForIdle(ctx2, a2)
     const allSeqs = a2.session.events.map(e => e.seq)
     expect(allSeqs).toEqual(allSeqs.map((_, i) => i)) // 0..N contiguous, no duplicates
diff --git a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
index 73ee48f7a6..8844e5c1a3 100644
--- a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
+++ b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
@@ -3,7 +3,7 @@ import { Context, symbols, type EffectMeta, type Fiber } from 'cordis'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
 
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -172,10 +172,10 @@ describe('agent scope lifecycle', () => {
     const handle = await ctx.agents.create({ sessionId: SessionId('s1'), agentOptions: { provider: 'mock', model: 'mock' } })
     const { agent } = handle
     agent.ctx.systemPrompt.section({ name: 'deployment:persona', order: 0, text: 'You run tests.' })
-    agent.ctx.tools.register({
+    agent.ctx.tools.register(defineContentToolFixture({
       name: 'mine', description: 'scoped', parameters: {},
       execute: () => Promise.resolve(text('ran')),
-    })
+    }))
 
     const scopedAssembly = await ctx.systemPrompt.assemble(assembleContextFor(agent))
     expect(scopedAssembly.sections.find(s => s.name === 'deployment:persona')?.text).toBe('You run tests.')
@@ -203,11 +203,11 @@ describe('agent scope lifecycle', () => {
       if (event.type === 'user/message') heard.push('a-sees:user-message')
     })
 
-    b.send(text('for b'))
+    b.followup(text('for b'))
     await waitForIdle(ctx, b)
     expect(heard).toEqual([]) // nothing of b's leaked into a's scope
 
-    a.send(text('for a'))
+    a.followup(text('for a'))
     await waitForIdle(ctx, a)
     expect(heard).toContain('a-sees:a:running')
     expect(heard).toContain('a-sees:user-message')
@@ -587,12 +587,12 @@ describe('agent scope lifecycle', () => {
         sessionId: SessionId('dependency-origin-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
         setup: (agentCtx) => {
-          agentCtx.tools.register({
+          agentCtx.tools.register(defineContentToolFixture({
             name: 'dependency-origin-tool',
             description: 'proves AgentLoop dependency origin',
             parameters: {},
             execute: () => Promise.resolve(text('ok')),
-          })
+          }))
           agentCtx.systemPrompt.section({
             name: 'dependency-origin-section',
             order: 1,
@@ -934,7 +934,7 @@ describe('agent scope lifecycle', () => {
         if (event.type === 'turn/start') { off(); resolve() }
       })
     })
-    agent.send(text('work'))
+    agent.followup(text('work'))
     await turnOpen
     await owner.dispose()
     expect(order).toEqual(['turn-end', 'disposed(listed=false)', 'session-still-stored=true'])
diff --git a/packages/core/agent-loop/tests/tool-calls.spec.ts b/packages/core/agent-loop/tests/tool-calls.spec.ts
index 35985c9185..0e7f1313cb 100644
--- a/packages/core/agent-loop/tests/tool-calls.spec.ts
+++ b/packages/core/agent-loop/tests/tool-calls.spec.ts
@@ -9,7 +9,7 @@ import { CallId, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import LlmService from '@deepseek-ai/dsh-llm'
-import ToolRegistry, { defineTool, TOOL_ABORTED_BEFORE_DISPATCH, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture, TOOL_ABORTED_BEFORE_DISPATCH, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse } from './mock-adapter.ts'
@@ -61,7 +61,7 @@ function multiCall(calls: { id: string; name: string; args: object }[]): StreamC
 function gatedTool(name: string, parallel: boolean) {
   const gates = new Map<string, () => void>()
   const started: string[] = []
-  const tool = defineTool({
+  const tool = defineContentToolFixture({
     name,
     description: `gated ${name}`,
     parameters: { id: { type: 'string', required: true } },
@@ -105,7 +105,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 3)
     expect(gated.started).toEqual(['1', '2', '3'])
     gated.release('1'); gated.release('2'); gated.release('3')
@@ -123,17 +123,17 @@ describe('tool-call scheduler: grouping and barriers', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'r', description: 'read', parameters: { id: { type: 'string', required: true } },
       isConcurrencySafe: () => true,
       async execute(args) { order.push(`r-start-${args.id}`); order.push(`r-end-${args.id}`); return [{ type: 'text', text: 'r' }] },
     }))
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'w', description: 'write', parameters: { id: { type: 'string', required: true } },
       async execute(args) { order.push(`w-${args.id}`); return [{ type: 'text', text: 'w' }] },
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(order).toEqual(['r-start-A1', 'r-end-A1', 'w-A2', 'r-start-A3', 'r-end-A3'])
@@ -150,14 +150,14 @@ describe('tool-call scheduler: grouping and barriers', () => {
     ])
     const ctx = await harness(adapter)
     const replacement = gatedExclusiveTool('x')
-    const disposeSafe = ctx.tools.register(defineTool({
+    const disposeSafe = ctx.tools.register(defineContentToolFixture({
       name: 'x',
       description: 'initially safe',
       parameters: { id: { type: 'string', required: true } },
       isConcurrencySafe: () => true,
       async execute(args) { return [{ type: 'text', text: `old-${args.id}` }] },
     }))
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'replace',
       description: 'replace x',
       parameters: { id: { type: 'string', required: true } },
@@ -169,7 +169,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => replacement.started.length === 1)
     await new Promise(r => setTimeout(r, 5))
     expect(replacement.started).toEqual(['1'])
@@ -200,7 +200,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
     })
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => initial.started.length === 2)
     initial.release('1')
     await until(() => events(agent).some(event =>
@@ -226,7 +226,7 @@ describe('tool-call scheduler: model-order results despite out-of-order settleme
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     gated.release('2')
     await new Promise(r => setTimeout(r, 5))
@@ -248,7 +248,7 @@ describe('tool-call scheduler: model-order results despite out-of-order settleme
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     gated.release('2'); gated.release('1')
     await waitForIdle(ctx, agent)
@@ -294,7 +294,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     await new Promise(r => setTimeout(r, 5))
     expect(gated.started).toEqual(['1', '2'])
@@ -323,7 +323,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 1)
     await new Promise(r => setTimeout(r, 5))
     expect(gated.started).toEqual(['1'])
@@ -349,7 +349,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 1)
     await new Promise(r => setTimeout(r, 5))
     expect(gated.started).toEqual(['1'])
@@ -376,7 +376,7 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
     ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => { post.push(String(exec.callId)); return next() })
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 3)
     gated.release('3'); gated.release('2'); gated.release('1')
     await waitForIdle(ctx, agent)
@@ -397,17 +397,17 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
       ({ kind: 'accept', additionalContexts: [{ content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } }] }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     gated.release('2'); gated.release('1')
     await waitForIdle(ctx, agent)
 
     const log = events(agent)
-    const contextTexts = log.filter(e => e.type === 'context/message')
-      .map(e => (e.data.content[0] as { text: string }).text)
+    const contextTexts = log.filter(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
+      .map(e => ((e.data as { content: { text: string }[] }).content[0]!).text)
     expect(contextTexts).toEqual(['ctx-c1', 'ctx-c2'])
     const lastResult = log.findLastIndex(e => e.type === 'tool/result')
-    const firstContext = log.findIndex(e => e.type === 'context/message')
+    const firstContext = log.findIndex(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
     expect(lastResult).toBeLessThan(firstContext)
   })
 
@@ -435,7 +435,7 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
     })
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 1)
     gated.release('1')
     await waitForIdle(ctx, agent)
@@ -465,7 +465,7 @@ describe('tool-call scheduler: abort handling', () => {
       }
     })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(gated.started).toEqual([])
@@ -497,7 +497,7 @@ describe('tool-call scheduler: abort handling', () => {
       return next()
     })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(gated.started).toEqual([])
@@ -527,7 +527,7 @@ describe('tool-call scheduler: abort handling', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     agent.cancel({ kind: 'user' })
     gated.release('1')
@@ -539,15 +539,20 @@ describe('tool-call scheduler: abort handling', () => {
       .toEqual([CallId('c1'), CallId('c2'), CallId('c3'), CallId('c4')])
     expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId))
       .toEqual([CallId('c1'), CallId('c2'), CallId('c3'), CallId('c4')])
-    expect(events(agent).filter(e => e.type === 'tool/result').slice(-2).map(e => e.data))
+    expect(events(agent).filter(e => e.type === 'tool/result').slice(-2).map(e => ({
+      callId: e.data.callId,
+      isError: e.data.isError,
+      errorInfo: e.data.error,
+    })))
       .toEqual([
-        expect.objectContaining({ callId: CallId('c3'), isError: true, error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } }),
-        expect.objectContaining({ callId: CallId('c4'), isError: true, error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } }),
+        { callId: CallId('c3'), isError: true, errorInfo: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
+        { callId: CallId('c4'), isError: true, errorInfo: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
       ])
-    const settled = events(agent).filter(e => e.type === 'tool/result' || e.type === 'context/message')
+    const settled = events(agent).filter(e => e.type === 'tool/result'
+      || (e.type === 'user/message' && e.data.source.kind === 'plugin'))
     expect(settled.map(e => e.type))
-      .toEqual(['tool/result', 'tool/result', 'tool/result', 'tool/result', 'context/message', 'context/message'])
-    expect(settled.filter(e => e.type === 'context/message')
+      .toEqual(['tool/result', 'tool/result', 'tool/result', 'tool/result', 'user/message', 'user/message'])
+    expect(settled.filter(e => e.type === 'user/message')
       .map(e => (e.data.content[0] as { text: string }).text))
       .toEqual(['ctx-c1', 'ctx-c2'])
   })
@@ -565,7 +570,7 @@ describe('tool-call scheduler: abort handling', () => {
     const gated = gatedParallelTool('p')
     const exclusive: string[] = []
     ctx.tools.register(gated.tool)
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'x',
       description: 'exclusive',
       parameters: { id: { type: 'string', required: true } },
@@ -573,7 +578,7 @@ describe('tool-call scheduler: abort handling', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     agent.cancel({ kind: 'user' })
     gated.release('1')
diff --git a/packages/core/agent-loop/tests/tool-order.spec.ts b/packages/core/agent-loop/tests/tool-order.spec.ts
index bf78208a42..a39961bfbf 100644
--- a/packages/core/agent-loop/tests/tool-order.spec.ts
+++ b/packages/core/agent-loop/tests/tool-order.spec.ts
@@ -12,7 +12,7 @@ import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
 import SystemPrompt, { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import type { Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -42,7 +42,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function registerNamed(ctx: Context, name: string) {
-  ctx.tools.register(defineTool({
+  ctx.tools.register(defineContentToolFixture({
     name,
     description: `the ${name} tool`,
     parameters: {},
@@ -58,7 +58,7 @@ async function runTurn(registrationOrder: string[], toolOrder?: SystemPromptConf
   const ctx = await harness(adapter, toolOrder)
   for (const name of registrationOrder) registerNamed(ctx, name)
   const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-  agent.send([{ type: 'text', text: 'go' }])
+  agent.followup([{ type: 'text', text: 'go' }])
   await waitForIdle(ctx, agent)
   return { ctx, agent, adapter }
 }
@@ -100,7 +100,7 @@ describe('loop-level canonical tool order', () => {
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(0)
     expect(errors.map(e => e.message)).toEqual(['toolOrder lists unregistered tool "ghost"; known tools: alpha'])
diff --git a/packages/core/agent-loop/tests/turn-stop.spec.ts b/packages/core/agent-loop/tests/turn-stop.spec.ts
index c0516415c0..44e1fd8a7b 100644
--- a/packages/core/agent-loop/tests/turn-stop.spec.ts
+++ b/packages/core/agent-loop/tests/turn-stop.spec.ts
@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent, type ContinuationStop } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -34,12 +34,12 @@ async function harness(adapter: MockAdapter): Promise<Context> {
 }
 
 function send(agent: Agent, text = 'go'): Promise<void> {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
   return agent.whenIdle()
 }
 
 function registerEcho(ctx: Context): void {
-  ctx.tools.register(defineTool({
+  ctx.tools.register(defineContentToolFixture({
     name: 'echo',
     description: 'echo',
     parameters: { text: { type: 'string' } },
@@ -116,7 +116,7 @@ describe('agent/turn-stop', () => {
     ctx.on('session/flush', (session) => {
       if (session !== agent.session || queued) return
       queued = true
-      agent.send([{ type: 'text', text: 'ordinary queued follow-up' }])
+      agent.followup([{ type: 'text', text: 'ordinary queued follow-up' }])
     })
 
     await send(agent)
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index b040d8cbdc..511ce32235 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -48,18 +48,20 @@ The lifecycle edges have two important local caveats. `agent/created` runs after
 
 Most interception points are cooperative waterfalls returning seam-specific decisions. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. The signal remains authoritative through terminal policy and is retired immediately before `turn/end` publication, so terminal observers and the following durability flush cannot cancel completed turn work. `agent/pre-step` and `agent/post-step` are serial checkpoints around a step's durable work, while `agent/request-error` is the failed-model-request recovery waterfall: it receives the exact error, normalized failure facts, immutable prior-retried facts, and signal after the failed step closes; a retry opens a new numbered step. `agent/turn-stop` is the terminal serial fold: it runs after ordinary continuation and steering folding, and a returned stop remains in force through turn close and flush so later steering cannot create an extra step or turn. Ordinary queued prompts remain intact. Effective broad cancellation first emits the observe-only `agent/cancel-requested` with its resolved typed cause, then clears queues and aborts; notification failures are contained and cannot veto the stop. 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.
 
-`PromptDecision.additionalContexts` is an array so every context keeps its own source, metadata, and placement. `SendOptions.contexts` binds the same shape to one queued message before prompt interception: the default allow decision carries it forward, while a blocked prompt records no context. Absent or `separate` placement writes an independent `context/message`; `prompt-prefix` writes the context, `## My request:` delimiter, and effective prompt into one `user/message` or `steering/message`, whose model-hidden envelope retains the direct prompt and context descriptors for human replay. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; the returned allow is authoritative. A `ContinuationDecision` reason is narrower: it becomes a `steering/message` without attached context metadata.
+`PromptDecision.additionalContexts` is an array so every context keeps its own source, metadata, and placement. `SendOptions.contexts` binds the same shape to one queued message before prompt interception: the default allow decision carries it forward, while a blocked prompt records no context. Absent or `separate` placement writes an independent injected `user/message` (plugin/goal source); `prompt-prefix` writes the context, `## My request:` delimiter, and effective prompt into one `user/message` or `steering/message`, whose model-hidden envelope retains the direct prompt and context descriptors for human replay. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; the returned allow is authoritative. A `ContinuationDecision` reason is narrower: it becomes a `steering/message` without attached context metadata.
 
 Turn and step boundaries and the model token stream are durable `session/event` facts rather than mirrored `agent/*` notifications. Consumers read `turn/*`, `step/*`, and `assistant/chunk` from the session feed; tool policy and outcome observation belong to the complete pipeline documented by [`dsh-tools`](../tools/README.md).
 
 ### Agent interface (`types.ts`)
 
-The handle every plugin programs against:
+`Agent` is a structural interface. `followup()`, `queue()`, `steer()`, and `inject()` name common caller intents; `send(ResolvedAgentInput)` exposes the same acceptance path when a caller already has exact routing facts ([decision](../../../.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.md)). Every `ResolvedAgentInput` field is mandatory, and its discriminated union excludes attached contexts from non-waking next-step injection. FIFO acceptance returns an opaque `AgentMessageId` carried by that item's `agent/inbox/enqueue`/`dequeue`/`discard` events. The driver snapshots content, resolved source, attached contexts, and model-hidden metadata as one detached, deeply frozen lossless-JSON record before notification and enqueue; invalid data throws synchronously. The helpers apply defaults: omitting `options.source` on `followup()`, `queue()`, or `steer()` attests direct human input as `{ kind: 'user' }`, so every non-human producer labels its content.
 
-- `agent.send(content, options?)` — queue one independent FIFO item. If claimed, that item becomes the sole ordinary message in its turn; a claimed FIFO successor waits for that turn's checkpoint to settle. Broad cancellation, disposal, or a pre-start failure may instead drop it without a turn. Omitting `options.source` attests direct human input as `{ kind: 'user' }` and may authorize policy consumers, so plugins, schedulers, and other non-human producers provide their own source. Content, resolved source, and `options.contexts` become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input. After admission, separate contexts become `context/message` events, while prompt-prefix contexts are baked before the effective request in the same `user/message`; a block or replacement of the default additional-context decision can discard them. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
-- `agent.steer(content, options?)` — while running, queue steering for the next checkpoint without dispatching `agent/prompt-submit`; when idle, delegate to `send()`. Attached contexts remain in the same frozen record; separate contexts append immediately after the steering event, while prompt-prefix contexts are baked into that steering event. Both survive late-steering conversion to queued input and disappear with their message on cancellation or terminal discard. Policy can still stop before another step; after turn close and its checkpoint, remaining steering becomes later queued input unless terminal turn policy, cancellation, or disposal discards it.
-- `agent.inject(content, options?)` — accept detached in-session context without running the model; the next request sees its `context/message` with `content` rendered verbatim as a user-role message. `options.meta` persists opaque JSON state without rendering it. While a turn is open it joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)).
-- `agent.cancel(cause?)` — cancel ALL pending work: an omitted cause means `{ kind: 'user' }`; TypeScript restricts callers to the `user | parent` union, and an active holder copies its discriminant into a detached frozen signal reason before aborting. An effective call emits `agent/cancel-requested` with the cause before clearing queued and steering work; observers may synchronize state but cannot veto cancellation. The same-process typed seam adds no runtime validation or compatibility fallback for untyped callers. Repeated active-turn cancellation is first-wins for the signal, and idle cancellation is a safe no-op with no notification. ACP maps to `user`, while in-process parent propagation maps to `parent`. The cause is runtime-only; durable `turn/end` stays coarse `aborted`.
+- `agent.followup(content, options?)` — queue one independent FIFO message as its own turn and wake the driver. After admission, separate contexts become injected `user/message` events, while prompt-prefix contexts are baked before the effective request in the same `user/message`; a block or replacement of the default additional-context decision can discard them. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
+- `agent.queue(content, options?)` — queue the same ordinary message without waking an idle driver. A lone queued item leaves `whenIdle()` resolved and rides along before the next waking message.
+- `agent.steer(content, options?)` — while running, queue steering for the next checkpoint without dispatching `agent/prompt-submit`; while idle, create a waking ordinary turn. Attached contexts remain in the same frozen record; separate contexts append immediately after the steering event, while prompt-prefix contexts are baked into that event. Both survive late-steering conversion to queued input and disappear with their message on cancellation or terminal discard. Policy can still stop before another step; after turn close and its checkpoint, remaining steering becomes later queued input unless terminal turn policy, cancellation, or disposal discards it.
+- `agent.inject(content, options?)` — accept detached in-session context without running the model; the next request sees its `user/message` (default plugin source) with `content` rendered verbatim as a user-role message. `InjectOptions` deliberately has no attached contexts. `options.meta` persists opaque JSON state without rendering it. While a turn is open the injection joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)). Injection bypasses the FIFOs and emits no `agent/inbox/*` event.
+- `agent.send(input)` — accept a fully specified route without helper defaults. `next-turn` targets the ordinary FIFO; `next-step` with wakeup targets steering and falls back to a waking ordinary turn while idle; `next-step` without wakeup is injection and requires `contexts: []`. Callers provide `meta: undefined` explicitly when they have no metadata.
+- `agent.cancel(cause?, options?)` — cancel the active turn and, unless `options.keepInbox`, ALL pending work: an omitted cause means `{ kind: 'user' }`; TypeScript restricts callers to the `user | parent` union, and an active holder copies its discriminant into a detached frozen signal reason before aborting. An effective call emits `agent/cancel-requested` with the cause before clearing queued and steering work; dropped items are reported on `agent/inbox/discard`, and observers may synchronize state but cannot veto cancellation. `keepInbox: true` aborts the turn but preserves queued and steering items (no discard, and un-started work is not dropped). The same-process typed seam adds no runtime validation or compatibility fallback for untyped callers. Repeated active-turn cancellation is first-wins for the signal, and idle cancellation is a safe no-op with no notification. ACP maps to `user`, while in-process parent propagation maps to `parent`. The cause is runtime-only; durable `turn/end` stays coarse `aborted`.
 - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly.
 - `agent.session`, `agent.status`, `agent.options`, `agent.id`
 
@@ -77,7 +79,7 @@ The handle every plugin programs against:
 
 #### What the model sees
 
-`send`, `steer`, and `inject` feed the owning session. `agent/prompt-submit`, `agent/session-prefix`, and other declared events let plugins block a prompt or add request material; this interface contributes no fixed prose itself.
+The four intent helpers and fully resolved `send` path feed the owning session. `agent/prompt-submit`, `agent/session-prefix`, and other declared events let plugins block a prompt or add request material; this interface contributes no fixed prose itself.
 
 #### Token effect
 
@@ -107,6 +109,6 @@ Prefix-stable while an agent's scoped registrations are unchanged. Setup or relo
 - **Ambient identity may outlive liveness** — consumers still check `agent.status`, cancellation, and the owning capability contract before lifecycle-sensitive work.
 - **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.
-- **No public step-only abort** — `cancel()` clears ALL pending work (queued + steering + in-flight); an abort that preserves queued prompts returns only with a named consumer ([stop-surface Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
+- **`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)).
 - **`HookContext` carries exactly one `MessageSource`** — contributions from several plugins merged onto one tool call collapse under one source; mixed provenance is unrepresentable.
 - **`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/src/invariant.ts b/packages/core/agent/src/invariant.ts
index 1902f3e746..a5a7725707 100644
--- a/packages/core/agent/src/invariant.ts
+++ b/packages/core/agent/src/invariant.ts
@@ -24,6 +24,27 @@ const install: InvariantInstaller = (ctx, fail) => {
     }
     lastStatus.set(agent, status)
   }, { global: true })
+
+  // Inbox FIFO conservation: an item leaves the inbox (dequeue) or is dropped
+  // (discard) only after it entered (enqueue), so the live outstanding count
+  // per agent can never go negative. Injection bypasses the FIFOs entirely and
+  // never appears on these events.
+  const outstanding = new WeakMap<Agent, number>()
+  ctx.on('agent/inbox/enqueue', (agent) => {
+    outstanding.set(agent, (outstanding.get(agent) ?? 0) + 1)
+  }, { global: true })
+  ctx.on('agent/inbox/dequeue', (agent) => {
+    const count = outstanding.get(agent) ?? 0
+    if (count <= 0) fail('agent/inbox/dequeue without a matching prior enqueue')
+    outstanding.set(agent, count - 1)
+  }, { global: true })
+  ctx.on('agent/inbox/discard', (agent, items) => {
+    const count = outstanding.get(agent) ?? 0
+    if (items.length > count) {
+      fail(`agent/inbox/discard dropped ${items.length} items but only ${count} were outstanding`)
+    }
+    outstanding.set(agent, count - items.length)
+  }, { global: true })
 }
 
 /**
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index dc78d76ef5..0f442e3f88 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -6,6 +6,7 @@
  */
 
 import type { Context } from 'cordis'
+import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { ContentBlock, LlmCallConfig, LlmFailure, Message, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { JsonValue, Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -26,8 +27,9 @@ export interface AgentOptions {
 }
 
 /**
- * Message options. An omitted source attests direct human input as `{ kind: 'user' }`
- * and may authorize policy consumers, so non-human producers must label their content.
+ * Options for {@link Agent.followup}, {@link Agent.queue}, and {@link Agent.steer}.
+ * An omitted source attests direct human input as `{ kind: 'user' }` and may
+ * authorize policy consumers, so non-human producers must label their content.
  */
 export interface SendOptions {
   source?: MessageSource
@@ -37,19 +39,71 @@ export interface SendOptions {
    * records them directly at its next checkpoint.
    */
   contexts?: HookContext[]
+  /** Opaque JSON state retained on the durable message but hidden from the model. */
+  meta?: JsonValue
 }
 
 /** Options specific to durable synthetic context injection. */
-export interface InjectOptions extends Omit<SendOptions, 'contexts'> {
-  /** Opaque JSON state retained in the session event but hidden from the model. */
+export interface InjectOptions {
+  /** Defaults to `{ kind: 'plugin', plugin: '' }`; non-human producers should identify themselves. */
+  source?: MessageSource
+  /** Opaque JSON state retained on the durable message but hidden from the model. */
   meta?: JsonValue
 }
 
+/**
+ * Opaque id assigned to one accepted agent input. FIFO inputs carry the same id
+ * on their `agent/inbox/*` events; injection bypasses those events.
+ */
+export type AgentMessageId = Branded<'AgentMessageId'>
+
+/**
+ * Brand a string as an {@link AgentMessageId}.
+ * @param id - the generated message id.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function AgentMessageId(id: string): AgentMessageId {
+  return id as AgentMessageId
+}
+
+/**
+ * One accepted FIFO message, carried by the `agent/inbox/*` live events. `id`
+ * is the value returned by the accepting helper or {@link Agent.send},
+ * stable across this message's enqueue, dequeue, and discard events. Source
+ * defaults, when applicable, are already applied, so these are the exact values
+ * the item was accepted with.
+ * `steering` is true for an item drained between steps; otherwise it is claimed
+ * at a turn boundary. `SendOptions.meta` is intentionally omitted: it is durable
+ * model-hidden state that lands on the eventual `user/message`/
+ * `steering/message`, not live-event routing data.
+ */
+export interface AgentMessage {
+  /** The id returned by the accepting helper or {@link Agent.send}. */
+  id: AgentMessageId
+  content: ContentBlock[]
+  source: MessageSource
+  contexts: HookContext[]
+  /** Whether the item joined the steering FIFO rather than the queued FIFO. */
+  steering: boolean
+  /** Whether the item wakes the driver or requests another step. */
+  wakeup: boolean
+}
+
+/** Options for {@link Agent.cancel}. */
+export 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
+}
+
 /**
  * An agent's lifecycle state, emitted on every transition as `agent/status`:
  * `idle` (parked, waiting for queued work), `running` (the driver is draining
  * work and may be closing or checkpointing a turn), `disposed` (terminal — no
- * transition leaves it, and `send`/`steer`/`inject` throw).
+ * transition leaves it, and every delivery method throws).
  */
 export type AgentStatus = 'idle' | 'running' | 'disposed'
 
@@ -58,8 +112,8 @@ export interface HookContext {
   content: ContentBlock[]
   source: MessageSource
   /**
-   * Model placement. Absent or `separate` records an independent
-   * `context/message`; `prompt-prefix` prepends this context and a stable
+   * Model placement. Absent or `separate` records an independent injected
+   * `user/message`; `prompt-prefix` prepends this context and a stable
    * request delimiter to the same user-role message as its attached prompt.
    */
   placement?: 'separate' | 'prompt-prefix'
@@ -67,6 +121,22 @@ export interface HookContext {
   meta?: JsonValue
 }
 
+/**
+ * Fully specified input for {@link Agent.send}. Unlike the intent-named
+ * helpers, this form applies no defaults: callers provide content, source,
+ * contexts, metadata (including explicit `undefined`), target, and wakeup.
+ * The union excludes attached contexts from non-waking next-step injection.
+ */
+export type ResolvedAgentInput = {
+  content: ContentBlock[]
+  source: MessageSource
+  meta: JsonValue | undefined
+} & (
+  | { target: 'next-turn'; wakeup: boolean; contexts: HookContext[] }
+  | { target: 'next-step'; wakeup: true; contexts: HookContext[] }
+  | { target: 'next-step'; wakeup: false; contexts: [] }
+)
+
 /**
  * Prompt interception result. `allow.content` replaces the prompt. Each
  * `additionalContexts` entry follows its declared placement: separate context
@@ -113,54 +183,90 @@ export type AgentInterruptReason = AgentCancelCause | { readonly kind: 'disposed
 export 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
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
   /**
-   * Queue one detached, frozen lossless-JSON item. If claimed, it is the sole
-   * ordinary message in its FIFO-ordered turn; the next claimed item waits for
-   * that turn's checkpoint.
-   * Attached contexts share the same snapshot and ownership boundary. Invalid
-   * input throws synchronously before notification or enqueue.
+   * Queue an ordinary message as its own FIFO-ordered turn and wake the driver.
+   * Content, resolved source, and attached contexts are detached, validated,
+   * and frozen together; invalid input throws synchronously before notification
+   * or enqueue.
+   * @param content - the prompt content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
    */
-  send(content: ContentBlock[], options?: SendOptions): void
+  followup(content: ContentBlock[], options?: SendOptions): AgentMessageId
 
   /**
-   * Submit steering while the agent is `running`. An open turn records it at
-   * the next steering checkpoint before a request or continuation decision;
-   * policy may stop before another step. After turn close and its checkpoint,
-   * any remainder is queued for a later turn; terminal `agent/turn-stop`,
-   * cancellation, or disposal may discard it. Uses the same synchronous
-   * snapshot-and-validation boundary as {@link send}; when idle, delegates to it.
+   * Queue an ordinary message without waking an idle driver. The item retains
+   * FIFO order and is claimed only after another input wakes the driver. A lone
+   * queued item leaves `whenIdle()` resolved.
+   * @param content - the prompt content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
    */
-  steer(content: ContentBlock[], options?: SendOptions): void
+  queue(content: ContentBlock[], options?: SendOptions): AgentMessageId
+
+  /**
+   * Submit steering into the running turn and request another step. An open turn
+   * records it at the next steering checkpoint before a request or continuation
+   * decision; policy may stop before another step. After turn close and its
+   * checkpoint, any remainder is queued for a later turn; terminal
+   * `agent/turn-stop`, cancellation, or disposal may discard it. Idle steering
+   * becomes a waking ordinary turn.
+   * @param content - the steering content blocks.
+   * @param options - source, attached contexts, and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
+   */
+  steer(content: ContentBlock[], options?: SendOptions): AgentMessageId
 
   /**
    * Append detached model-facing context without running the model. An open-turn
    * injection joins at the current log position unless the current tool batch is
-   * executing; then it waits FIFO until that batch settles and drains before turn
-   * close even when interrupted. Idle injection uses a one-shot turn and durability
-   * checkpoint. Disposal awaits idle checkpoints; flush failures report through `agent/error`.
+   * executing; then it waits FIFO until that batch settles and drains before
+   * turn close even when interrupted. Idle injection uses a one-shot turn and
+   * durability checkpoint. Disposal awaits idle checkpoints; flush failures
+   * report through `agent/error`. An omitted source defaults to
+   * `{ kind: 'plugin', plugin: '' }`.
+   * @param content - the injected context content blocks.
+   * @param options - source and durable model-hidden meta.
+   * @returns the accepted injection's {@link AgentMessageId}; injection emits no `agent/inbox/*` events.
    */
-  inject(content: ContentBlock[], options?: InjectOptions): void
+  inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId
 
   /**
-   * Clear all queued and steering work, including items waiting to start, 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. Omission means `{ kind: 'user' }`. Idle cancellation is a no-op
-   * and does not arm later work. The active turn snapshots and freezes the cause.
-   * @param cause - the stable caller intent carried by the current turn signal.
+   * Accept one fully specified input through the same snapshot and routing path
+   * as the four intent-named helpers. `next-turn` targets the ordinary FIFO;
+   * `next-step`/wakeup targets steering (falling back to an ordinary waking turn
+   * while idle); and `next-step` without wakeup injects durable context without
+   * running the model. Every field is mandatory and no source or routing default
+   * is applied. Invalid input throws synchronously before notification, enqueue,
+   * or append.
+   * @param input - the resolved content, attribution, context, metadata, and routing facts.
+   * @returns the accepted input's {@link AgentMessageId}, carried by FIFO lifecycle events when applicable.
    */
-  cancel(cause?: AgentCancelCause): void
+  send(input: ResolvedAgentInput): AgentMessageId
+
+  /**
+   * 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. Omitted cause
+   * means `{ kind: 'user' }`. Idle cancellation is a no-op and does not arm
+   * later work. The active turn snapshots and freezes the cause.
+   * @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>
-
 }
 
 declare module 'cordis' {
@@ -187,8 +293,8 @@ declare module 'cordis' {
      */
     'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
     /**
-     * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does
-     * not enter `running` synchronously; drive lifecycle from this event.
+     * Agent status changed (`idle` ⇄ `running`, or → `disposed`). A waking
+     * delivery 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.
@@ -196,15 +302,42 @@ declare module 'cordis' {
      */
     'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
     /**
-     * Detached, frozen content entered the agent's inbox. Source defaults have
-     * already been applied, so these are the exact values retained for the log.
-     * @param agent - the agent whose inbox received the message.
-     * @param content - the accepted content blocks retained by the inbox.
-     * @param info - the accepted source, contexts, and whether it entered as steering.
+     * A detached, frozen item entered the agent's inbox (queued or steering
+     * FIFO). Source defaults are already applied, so `message` holds the exact
+     * accepted values. This is the enqueue-time live signal; the durable record
+     * is the eventual `user/message`/`steering/message`. Injection through
+     * `agent.inject()` or equivalent `send()` routing bypasses the FIFOs
+     * and does not emit this.
+     * @param agent - the agent whose inbox received the item.
+     * @param message - the accepted message (its returned `id`, content, source, contexts, steering, and wakeup facts).
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; contexts: HookContext[]; steering: boolean }): void
+    'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void
+    /**
+     * 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 message - the claimed message (matching the `id` from its `agent/inbox/enqueue`).
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+     * @mode emit
+     */
+    'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void
+    /**
+     * Pending inbox items were dropped without delivering them, so every
+     * enqueued id receives exactly one terminal `agent/inbox/dequeue` OR
+     * `agent/inbox/discard`. Emitters: `cancel()` without `keepInbox` (after
+     * `agent/cancel-requested`, before the abort); a terminal `agent/turn-stop`
+     * dropping pending steering (in-turn and on the post-turn late-steering
+     * drain); and disposal of any still-pending items (before
+     * `agent/status('disposed')`). Fires once per drop with every dropped item.
+     * @param agent - the agent whose inbox items were dropped.
+     * @param messages - the discarded messages 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/discard'(this: Scoped<Agent>, agent: Agent, messages: AgentMessage[]): void
     /**
      * Effective broad cancellation was requested, before queued/steering work
      * is cleared or the active turn is aborted. This observe-only notification
diff --git a/packages/core/agent/tests/agent.spec.ts b/packages/core/agent/tests/agent.spec.ts
index 509ad14a22..b5b0424957 100644
--- a/packages/core/agent/tests/agent.spec.ts
+++ b/packages/core/agent/tests/agent.spec.ts
@@ -3,13 +3,24 @@ import { Context, Service, symbols } from 'cordis'
 import type { Events } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry, {
+  AgentMessageId,
   agentEvents,
   agentInterruptReasonOf,
 } from '@deepseek-ai/dsh-agent'
 
-import type { Agent, AgentCancelCause, AgentFactory, ContinuationStop, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent'
+import type {
+  Agent,
+  AgentCancelCause,
+  AgentFactory,
+  ContinuationStop,
+  CreateAgentOptions,
+  InjectOptions,
+  ResolvedAgentInput,
+  ResumeAgentOptions,
+  SendOptions,
+} from '@deepseek-ai/dsh-agent'
 
-function stubAgent(rawId: string): Agent {
+function stubAgent(rawId: string, overrides: Partial<Agent> = {}): Agent {
   const id = SessionId(rawId)
   return {
     id,
@@ -17,15 +28,34 @@ function stubAgent(rawId: string): Agent {
     session: new Session(id),
     status: 'idle',
     ctx: new Context(),
-    send() {},
-    steer() {},
-    inject() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
+    inject: () => AgentMessageId('stub'),
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle() { return Promise.resolve() },
+    ...overrides,
   }
 }
 
 describe('AgentRegistry', () => {
+  it('keeps helper options semantic and makes advanced input fully specified', () => {
+    type OptionalInputKey = {
+      [Key in keyof ResolvedAgentInput]-?: Record<never, never> extends Pick<ResolvedAgentInput, Key>
+        ? Key
+        : never
+    }[keyof ResolvedAgentInput]
+
+    expectTypeOf<'target' extends keyof SendOptions ? true : false>().toEqualTypeOf<false>()
+    expectTypeOf<'wakeup' extends keyof SendOptions ? true : false>().toEqualTypeOf<false>()
+    expectTypeOf<'contexts' extends keyof InjectOptions ? true : false>().toEqualTypeOf<false>()
+    expectTypeOf<Parameters<Agent['send']>[0]>().toEqualTypeOf<ResolvedAgentInput>()
+    expectTypeOf<OptionalInputKey>().toEqualTypeOf<never>()
+    expectTypeOf<Extract<ResolvedAgentInput, { target: 'next-step'; wakeup: false }>['contexts']>()
+      .toEqualTypeOf<[]>()
+  })
+
   it('allows terminal stop policy to cooperate asynchronously with turn cancellation', () => {
     type TurnStopListener = Events['agent/turn-stop']
     type AsyncTurnStopListener = () => Promise<ContinuationStop | undefined>
@@ -56,7 +86,7 @@ describe('AgentRegistry', () => {
   it('rejects an agent whose registry and session identities differ', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
-    const agent = { ...stubAgent('agent-id'), session: new Session(SessionId('session-id')) }
+    const agent = stubAgent('agent-id', { session: new Session(SessionId('session-id')) })
 
     expect(() => ctx.agents.enter(agent, undefined))
       .toThrow('agent id "agent-id" does not match session id "session-id"')
diff --git a/packages/core/agent/tests/invariant.spec.ts b/packages/core/agent/tests/invariant.spec.ts
index 3c0d147b9a..453752c402 100644
--- a/packages/core/agent/tests/invariant.spec.ts
+++ b/packages/core/agent/tests/invariant.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 { AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
 import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -56,3 +56,41 @@ describe('agent status invariants', () => {
     expect(() => { ctx.emit(scopeTarget(b, b), 'agent/status', b, 'running') }).not.toThrow()
   })
 })
+
+describe('agent inbox invariants', () => {
+  const info = (steering: boolean) => ({ id: AgentMessageId('m'), content: [], source: { kind: 'user' as const }, contexts: [], steering, wakeup: true })
+
+  it('accepts a dequeue and a discard covered by prior enqueues', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('i1')
+    const at = scopeTarget(agent, agent)
+    expect(() => {
+      ctx.emit(at, 'agent/inbox/enqueue', agent, info(false))
+      ctx.emit(at, 'agent/inbox/enqueue', agent, info(true))
+      ctx.emit(at, 'agent/inbox/dequeue', agent, info(false))
+      ctx.emit(at, 'agent/inbox/discard', agent, [info(true)])
+    }).not.toThrow()
+  })
+
+  it('rejects a dequeue with no outstanding item', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('i2')
+    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/inbox/dequeue', agent, info(false)) })
+      .toThrow(/without a matching prior enqueue/)
+  })
+
+  it('rejects a discard larger than the outstanding count', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('i3')
+    const at = scopeTarget(agent, agent)
+    ctx.emit(at, 'agent/inbox/enqueue', agent, info(false))
+    expect(() => { ctx.emit(at, 'agent/inbox/discard', agent, [info(false), info(true)]) })
+      .toThrow(/dropped 2 items but only 1 were outstanding/)
+  })
+
+  it('accepts an empty discard against a fresh agent', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('i4')
+    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/inbox/discard', agent, []) }).not.toThrow()
+  })
+})
diff --git a/packages/core/scope/src/scoped-events.generated.ts b/packages/core/scope/src/scoped-events.generated.ts
index 5988b58145..a12b0a513e 100644
--- a/packages/core/scope/src/scoped-events.generated.ts
+++ b/packages/core/scope/src/scoped-events.generated.ts
@@ -12,10 +12,12 @@ const scopedSubjectResolvers: Readonly<Record<string, ScopedSubjectResolver | nu
   'agent/created': args => args[0],
   'agent/disposed': args => args[0],
   'agent/error': args => args[0],
+  'agent/inbox/dequeue': args => args[0],
+  'agent/inbox/discard': args => args[0],
+  'agent/inbox/enqueue': args => args[0],
   'agent/post-step': args => args[0],
   'agent/pre-step': args => args[0],
   'agent/prompt-submit': args => args[0],
-  'agent/queued': args => args[0],
   'agent/request': args => args[0],
   'agent/request-error': args => args[0],
   'agent/session-prefix': args => args[0],
diff --git a/packages/core/scope/tests/invariant.spec.ts b/packages/core/scope/tests/invariant.spec.ts
index 2d93bcddc5..ca0841165b 100644
--- a/packages/core/scope/tests/invariant.spec.ts
+++ b/packages/core/scope/tests/invariant.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { Events } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import { AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import * as ScopeInvariant from '@deepseek-ai/dsh-scope/invariant'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -42,7 +42,9 @@ describe('scoped-dispatch invariants', () => {
       'agent/created': [agent],
       'agent/disposed': [agent],
       'agent/status': [agent, 'idle'],
-      'agent/queued': [agent, [], { source: { kind: 'user' }, contexts: [], steering: false }],
+      'agent/inbox/enqueue': [agent, { id: AgentMessageId('m'), content: [], source: { kind: 'user' }, contexts: [], steering: false, wakeup: true }],
+      'agent/inbox/dequeue': [agent, { id: AgentMessageId('m'), content: [], source: { kind: 'user' }, contexts: [], steering: false, wakeup: true }],
+      'agent/inbox/discard': [agent, []],
       'agent/cancel-requested': [agent, { kind: 'user' }],
       'agent/session-start': [agent, 'startup'],
       'agent/pre-step': [agent, 1, 1, signal],
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index c574174a20..a01bb21cc0 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -46,7 +46,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
 ### Lossless JSON utilities
 
-Durable values need one accepted representation, not a check followed by a second read. `isJsonValue(value)` is the boolean predicate; `snapshotJsonValue(value)` recursively validates and copies a plain value in one pass, returning `undefined` for invalid input and propagating a throwing getter. The snapshot helper accepts finite JSON numbers except `-0` (JSON rewrites it to `0`), dense ordinary arrays, and plain or null-prototype objects; it rejects cycles, unsupported scalars, and exotic prototypes before normalization.
+Durable values need one accepted representation, not a check followed by a second read. `isJsonValue(value)` is the boolean predicate; `snapshotJsonValue(value)` iteratively validates and copies a plain value in one pass, returning `undefined` for invalid input and propagating a throwing getter. The snapshot helper accepts finite JSON numbers except `-0` (JSON rewrites it to `0`), dense ordinary arrays, and plain or null-prototype objects; it rejects cycles, unsupported scalars, and exotic prototypes before normalization without imposing a call-stack depth limit.
 
 ### Chunk-row storage codec (`chunk-rows.ts`)
 
@@ -64,7 +64,9 @@ Providers stream token-sized deltas, so a raw log stores hundreds of `assistant/
 
 `request/header` records a full canonical snapshot of the non-history request envelope with reason `initial`, `resume`, or `change`. `foldRequestHeader()` selects the latest snapshot; legacy delta events and the removed `fallback` reason are rejected. `messagePrefix` remains separate from derived history. See the [reconstructable-requests Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
 
-`context/message` renders its `content` verbatim as a user-role message, and may attach JSON `meta` for replayable plugin state; metadata remains durable but is excluded from `deriveMessages()`. A `user/message` or `steering/message` with prompt-prefix context keeps the exact combined model bytes in `content` and stores a model-hidden `envelope` containing the direct `displayContent` and prefix context source/metadata descriptors. `displayPromptContent()` selects the human-facing prompt without changing derived history.
+A `user/message` renders its `content` verbatim as a user-role message whether it is a direct human prompt (`user` source), a synthetic injection (`plugin`/`goal` source), or an admitted goal round — `source` is the only channel that tells them apart. It may attach JSON `meta` for replayable plugin state; metadata remains durable but is excluded from `deriveMessages()`. A `user/message` or `steering/message` with prompt-prefix context keeps the exact combined model bytes in `content` and stores a model-hidden `envelope` containing the direct `displayContent` and prefix context source/metadata descriptors. `displayPromptContent()` selects the human-facing prompt without changing derived history.
+
+`tool/result` persists the model-facing content, optional internal failure identity, and optional presentation metadata. A tool's successful canonical `value` and human-readable canonical failure message remain execution-local; rendered error content is the replay-authoritative message. This preserves the existing event shape and does not change `SESSION_FORMAT_VERSION`.
 
 ### Session event vocabulary (`types.ts`)
 
@@ -97,7 +99,7 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 
 #### What the model sees
 
-The model receives projections of `user/message`, `assistant/message`, `tool/result`, `context/message`, and `steering/message` surface entries verbatim: each is a user- or assistant-role message carrying its content blocks unchanged. A prompt envelope changes only human presentation; its prefix context and request delimiter are already present in the event content. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
+The model receives projections of `user/message`, `assistant/message`, `tool/result`, and `steering/message` surface entries verbatim: each is a user- or assistant-role message carrying its content blocks unchanged. A prompt envelope changes only human presentation; its prefix context and request delimiter are already present in the event content. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
 
 #### Token effect
 
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index 9c5831bb18..5a6b274b3e 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -129,8 +129,10 @@ function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHe
   if (record.id !== id) {
     throw new Error(`session header id "${String(record.id)}" does not match session id "${id}"`)
   }
-  if (typeof record.createdAt !== 'number' || !Number.isFinite(record.createdAt)) {
-    throw new Error('session header createdAt must be a finite number')
+  if (typeof record.createdAt !== 'number'
+    || !Number.isSafeInteger(record.createdAt)
+    || record.createdAt < 0) {
+    throw new Error('session header createdAt must be a non-negative safe integer')
   }
   if (record.cwd !== undefined) {
     if (typeof record.cwd !== 'string') throw new Error('session header cwd must be a string')
@@ -532,10 +534,10 @@ export class Session {
     // trace/replay data.
 
     switch (event.type) {
-      // Injected context, ordinary prompts, and mid-turn steering project
+      // Ordinary prompts, injected context, and mid-turn steering project
       // identically in user role: the event's model-facing content stays
       // verbatim. A prompt envelope is model-hidden display metadata; its
-      // prefix bytes are already present in content. context's `source`/`meta`
+      // prefix bytes are already present in content. The message's `source`/`meta`
       // and steering's `turn` are also log-only. Do NOT
       // re-add per-type framing (e.g. `<context>`/`<steering>`) here: framing is
       // caller-owned — a producer bakes it into `content`, as workspace-context
@@ -544,7 +546,6 @@ export class Session {
       // verbatim pass-through. See the deferred design note in
       // ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md
       case 'user/message':
-      case 'context/message':
       case 'steering/message': {
         return { role: 'user', content: event.data.content }
       }
diff --git a/packages/core/session/src/json.ts b/packages/core/session/src/json.ts
index 35874a49e5..43e9f0625f 100644
--- a/packages/core/session/src/json.ts
+++ b/packages/core/session/src/json.ts
@@ -3,82 +3,179 @@
 /**
  * A value that round-trips losslessly through JSON: `null`, a boolean, a finite
  * number other than negative zero, a string, an array of such values, or a
- * plain object whose values are such values. TypeScript cannot distinguish
- * `-0` from `number`, so {@link isJsonValue} and {@link snapshotJsonValue}
- * enforce that last numeric detail at runtime. Use this type for a payload that
- * must survive session-log persistence and replay byte-identically — e.g. a
- * tool's private presentation `meta`.
+ * plain object whose values are such values. Arrays may carry only their dense
+ * indexed elements; extra own properties would be discarded by JSON. TypeScript
+ * cannot distinguish `-0` from `number`, so {@link isJsonValue} and
+ * {@link snapshotJsonValue} enforce these details at runtime. Use this type for
+ * a payload that must survive session-log persistence and replay byte-identically
+ * — e.g. a tool's private presentation `meta`.
  */
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
 
+/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
+function hasIntrinsicConstructor(prototype: object, name: 'Array' | 'Object'): boolean {
+  const descriptor = Object.getOwnPropertyDescriptor(prototype, 'constructor')
+  const constructor: unknown = descriptor?.value
+  if (typeof constructor !== 'function') return false
+  try {
+    return constructor.name === name
+      && constructor.prototype === prototype
+      && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`
+  } catch {
+    return false
+  }
+}
+
+/** Whether a candidate is one realm's intrinsic `Object.prototype`. */
+function isIntrinsicObjectPrototype(value: object): boolean {
+  return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, 'Object')
+}
+
+/** Whether an array uses one realm's intrinsic `Array.prototype`, not a subclass or forged prototype. */
+function hasPlainArrayPrototype(value: unknown[]): boolean {
+  const prototype: unknown = Object.getPrototypeOf(value)
+  if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, 'Array')) return false
+  const objectPrototype: unknown = Object.getPrototypeOf(prototype)
+  return typeof objectPrototype === 'object'
+    && objectPrototype !== null
+    && isIntrinsicObjectPrototype(objectPrototype)
+}
+
+/** Whether an object is a plain or null-prototype record from any JavaScript realm. */
+function hasPlainObjectPrototype(value: object): boolean {
+  const prototype: unknown = Object.getPrototypeOf(value)
+  return prototype === null
+    || typeof prototype === 'object' && isIntrinsicObjectPrototype(prototype)
+}
+
+/** Return every JSON-visible object key, or reject own data JSON would discard. */
+function enumerableStringKeys(value: object): string[] | undefined {
+  const keys = Reflect.ownKeys(value)
+  if (keys.some(key => typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(value, key))) return undefined
+  return keys as string[]
+}
+
+type SnapshotDestination =
+  | { kind: 'root' }
+  | { kind: 'array'; target: JsonValue[]; index: number }
+  | { kind: 'object'; target: { [key: string]: JsonValue }; key: string }
+
+type JsonWalkTask =
+  | { kind: 'visit'; value: unknown; destination?: SnapshotDestination }
+  | { kind: 'array-item'; source: unknown[]; index: number; target?: JsonValue[] }
+  | { kind: 'object-property'; source: Record<string, unknown>; key: string; target?: { [key: string]: JsonValue } }
+  | { kind: 'leave'; source: object }
+
+/** Validate lossless JSON iteratively, optionally materializing a detached snapshot. */
+function walkJsonValue(value: unknown, detach: boolean): JsonValue | true | undefined {
+  const ancestors = new Set<object>()
+  let root: JsonValue | undefined
+  const assign = (destination: SnapshotDestination | undefined, item: JsonValue): void => {
+    if (destination === undefined) return
+    if (destination.kind === 'root') {
+      root = item
+    } else if (destination.kind === 'array') {
+      destination.target[destination.index] = item
+    } else {
+      Object.defineProperty(destination.target, destination.key, {
+        value: item,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      })
+    }
+  }
+
+  const tasks: JsonWalkTask[] = [{
+    kind: 'visit',
+    value,
+    ...(detach ? { destination: { kind: 'root' } as const } : {}),
+  }]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      ancestors.delete(task.source)
+      continue
+    }
+    if (task.kind === 'array-item') {
+      if (!Object.prototype.hasOwnProperty.call(task.source, task.index)) return undefined
+      tasks.push({
+        kind: 'visit',
+        value: task.source[task.index],
+        ...(task.target === undefined ? {} : { destination: { kind: 'array', target: task.target, index: task.index } as const }),
+      })
+      continue
+    }
+    if (task.kind === 'object-property') {
+      tasks.push({
+        kind: 'visit',
+        value: task.source[task.key],
+        ...(task.target === undefined ? {} : { destination: { kind: 'object', target: task.target, key: task.key } as const }),
+      })
+      continue
+    }
+
+    const current = task.value
+    if (current === null) {
+      assign(task.destination, null)
+      continue
+    }
+    if (typeof current === 'boolean' || typeof current === 'string') {
+      assign(task.destination, current)
+      continue
+    }
+    if (typeof current === 'number') {
+      if (!Number.isFinite(current) || Object.is(current, -0)) return undefined
+      assign(task.destination, current)
+      continue
+    }
+    if (typeof current !== 'object') return undefined
+    if (ancestors.has(current)) return undefined
+
+    if (Array.isArray(current)) {
+      if (!hasPlainArrayPrototype(current)) return undefined
+      const length = current.length
+      if (Reflect.ownKeys(current).length !== length + 1) return undefined
+      const target = detach ? [] as JsonValue[] : undefined
+      if (target !== undefined) assign(task.destination, target)
+      ancestors.add(current)
+      tasks.push({ kind: 'leave', source: current })
+      for (let index = length - 1; index >= 0; index--) {
+        tasks.push({ kind: 'array-item', source: current, index, ...(target === undefined ? {} : { target }) })
+      }
+      continue
+    }
+
+    if (!hasPlainObjectPrototype(current)) return undefined
+    const keys = enumerableStringKeys(current)
+    if (keys === undefined) return undefined
+    const target = detach ? {} as { [key: string]: JsonValue } : undefined
+    if (target !== undefined) assign(task.destination, target)
+    ancestors.add(current)
+    tasks.push({ kind: 'leave', source: current })
+    for (let index = keys.length - 1; index >= 0; index--) {
+      const key = keys[index]
+      /* v8 ignore next -- the loop is bounded by the captured key count. */
+      if (key === undefined) return undefined
+      tasks.push({ kind: 'object-property', source: current as Record<string, unknown>, key, ...(target === undefined ? {} : { target }) })
+    }
+  }
+  return detach ? root : true
+}
+
 /**
  * Validate and detach lossless JSON in one read per property, so a stateful
- * getter cannot change between validation and copying. Accepts ordinary arrays,
- * plain or null-prototype objects, and JSON scalars; rejects sparse, cyclic,
- * exotic, negative-zero, and non-finite values. Getter throws propagate.
+ * getter cannot change between validation and copying. Traversal is iterative,
+ * so valid nesting is bounded by available memory rather than the JavaScript
+ * call stack. Accepts ordinary arrays, plain or null-prototype objects, and JSON
+ * scalars; rejects sparse, cyclic, exotic, negative-zero, and non-finite values.
+ * Getter throws propagate.
  *
  * @param value - the candidate value to validate and detach.
  * @returns the detached snapshot, or `undefined` when the value is not
  *   losslessly JSON-serializable.
  */
 export function snapshotJsonValue<T>(value: T): T | undefined {
-  const ancestors = new Set<object>()
-
-  const visit = (current: unknown): JsonValue | undefined => {
-    if (current === null) return null
-    switch (typeof current) {
-      case 'boolean':
-      case 'string':
-        return current
-      case 'number':
-        return Number.isFinite(current) && !Object.is(current, -0) ? current : undefined
-      case 'bigint':
-      case 'function':
-      case 'symbol':
-      case 'undefined':
-        return undefined
-      case 'object':
-        break
-    }
-
-    if (ancestors.has(current)) return undefined
-    ancestors.add(current)
-    try {
-      if (Array.isArray(current)) {
-        if (Object.getPrototypeOf(current) !== Array.prototype) return undefined
-        const length = current.length
-        const snapshot: JsonValue[] = []
-        for (let index = 0; index < length; index++) {
-          if (!Object.prototype.hasOwnProperty.call(current, index)) return undefined
-          const item = visit(current[index])
-          if (item === undefined) return undefined
-          snapshot.push(item)
-        }
-        return snapshot
-      }
-
-      const prototype = Object.getPrototypeOf(current) as unknown
-      if (prototype !== Object.prototype && prototype !== null) return undefined
-      const snapshot: { [key: string]: JsonValue } = {}
-      for (const key of Object.keys(current)) {
-        const item = visit((current as Record<string, unknown>)[key])
-        if (item === undefined) return undefined
-        // Define the key as data so a JSON field literally named "__proto__"
-        // cannot mutate the snapshot's prototype through ordinary assignment.
-        Object.defineProperty(snapshot, key, {
-          value: item,
-          enumerable: true,
-          configurable: true,
-          writable: true,
-        })
-      }
-      return snapshot
-    } finally {
-      ancestors.delete(current)
-    }
-  }
-
-  return visit(value) as T | undefined
+  return walkJsonValue(value, true) as T | undefined
 }
 
 /**
@@ -86,45 +183,8 @@ export function snapshotJsonValue<T>(value: T): T | undefined {
  * detaching it. Only own enumerable string properties participate; `toJSON`
  * is ignored and getters run, so persistence boundaries use the snapshotter.
  * @param value - the candidate event data to test.
- * @param seen - current recursion path; callers omit it.
  * @returns whether `value` survives JSON round-trip losslessly.
  */
-export function isJsonValue(value: unknown, seen: Set<object> = new Set()): boolean {
-  if (value === null) return true
-  switch (typeof value) {
-    case 'boolean':
-    case 'string':
-      return true
-    case 'number':
-      return Number.isFinite(value) && !Object.is(value, -0)
-    case 'bigint':
-    case 'function':
-    case 'symbol':
-    case 'undefined':
-      return false
-    case 'object':
-      break // handled below
-  }
-  // object
-  if (seen.has(value)) return false // circular
-  seen.add(value)
-  try {
-    if (Array.isArray(value)) {
-      if (Object.getPrototypeOf(value) !== Array.prototype) return false
-      // Reject sparse arrays: a hole is skipped by `every`/`forEach` but
-      // JSON.stringify writes it as `null`, so `[1, , 3]` would round-trip
-      // lossily. Require every index 0..length-1 to be an OWN property.
-      for (let i = 0; i < value.length; i++) {
-        if (!Object.prototype.hasOwnProperty.call(value, i)) return false
-        if (!isJsonValue(value[i], seen)) return false
-      }
-      return true
-    }
-    // Plain object only (reject Map/Set/Date/class instances).
-    const proto = Object.getPrototypeOf(value) as unknown
-    if (proto !== Object.prototype && proto !== null) return false
-    return Object.values(value).every(v => isJsonValue(v, seen))
-  } finally {
-    seen.delete(value)
-  }
+export function isJsonValue(value: unknown): boolean {
+  return walkJsonValue(value, false) === true
 }
diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts
index 9095c8388b..fc275129f9 100644
--- a/packages/core/session/src/surface.ts
+++ b/packages/core/session/src/surface.ts
@@ -15,14 +15,13 @@ const SURFACE_EVENT_TYPES = new Set<string>([
   'user/message',
   'assistant/message',
   'tool/result',
-  'context/message',
   'steering/message',
 ])
 
 /**
  * Whether an event type can join the model-visible surface.
  * @param type - event type to test.
- * @returns true for one of the five message-producing event types.
+ * @returns true for one of the four message-producing event types.
  */
 export function isSurfaceEligibleType(type: string): boolean {
   return SURFACE_EVENT_TYPES.has(type)
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index 37c174ea12..d909d51452 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -36,7 +36,7 @@ export interface SessionHeader {
   readonly version: number
   /** The session's id (mirrors the {@link Session}'s id). */
   readonly id: SessionId
-  /** Unix epoch milliseconds when the session was created. */
+  /** Non-negative safe-integer Unix epoch milliseconds when the session was created. */
   readonly createdAt: number
   /** Absolute working directory the session was created in (if any). */
   readonly cwd?: string
@@ -84,11 +84,12 @@ export interface TurnTriggerMap {
   message: { kind: 'message'; source: MessageSource }
   /**
    * An out-of-band context injection (`agent.inject()`) made while the agent
-   * was idle. The loop wraps the injected `context/message` in a one-shot turn
-   * (`turn/start` → `context/message` → `turn/end`) so every event in the log
-   * stays turn-enclosed — the durability/replay boundary is the turn, and a
-   * bare event between turns would otherwise be indistinguishable from a crash
-   * tail on reload.
+   * was idle. The loop wraps the injected `user/message` (a non-`user` source,
+   * plugin by default) in a one-shot turn (`turn/start` → `user/message` →
+   * `turn/end`) so every event in the log stays turn-enclosed — the
+   * durability/replay boundary is the turn, and a bare event between turns would
+   * otherwise be indistinguishable from a crash tail on reload. The trigger's
+   * `source` mirrors that message's producer.
    */
   injection: { kind: 'injection'; source: MessageSource }
 }
@@ -201,7 +202,13 @@ export interface PromptMessageEnvelope {
   prefixContexts: PromptPrefixContext[]
 }
 
-/** Shared payload for ordinary and steering prompt messages. */
+/**
+ * Shared payload for user, injected-context, and steering prompt messages. A
+ * direct human prompt, a synthetic `agent.inject()` context, and mid-turn
+ * steering all project into the model transcript as verbatim user-role content;
+ * they are told apart by `source` (a non-`user` kind marks injected context),
+ * not by event type. `meta` carries durable model-hidden producer state.
+ */
 export interface PromptMessageData {
   /** Exact model-facing blocks, including any baked prompt-prefix contexts. */
   content: ContentBlock[]
@@ -209,6 +216,15 @@ export interface PromptMessageData {
   source: MessageSource
   /** Present only when prompt-prefix contexts were baked into `content`. */
   envelope?: PromptMessageEnvelope
+  /**
+   * Opaque durable JSON state retained on the event but hidden from the model
+   * projection. It is the intended channel for a future framing directive (a
+   * producer declares the frame, a dedicated renderer applies it — see the
+   * deferred note in
+   * ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md),
+   * so the surface keeps projecting `content` verbatim rather than wrapping it.
+   */
+  meta?: JsonValue
 }
 
 /**
@@ -236,29 +252,21 @@ export interface SessionEventMap {
   'step/start': { turn: number; step: number }
   /** Closes step `step` of turn `turn`. */
   'step/end': { turn: number; step: number }
-  /** A user-visible prompt (the queued message claimed for this turn). */
+  /**
+   * 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 admitted goal continuation round. All three
+   * project their `content` verbatim; `source` (with a non-`user` kind marking
+   * injected context) is the only channel that tells them apart. An idle
+   * injection wraps this event in a one-shot turn so the log stays turn-enclosed.
+   */
   'user/message': PromptMessageData
   /**
    * Durable record of a prompt veto and its reason. It is log-only: the blocked
    * prompt never enters the model-visible surface, and its turn runs zero steps.
    */
   'prompt/blocked': { content: ContentBlock[]; source: MessageSource; reason: string }
-  /**
-   * In-session context injection (file-change notices, subdir AGENTS.md,
-   * skill content, cron notifications, …). Rendered into the derived history
-   * as a synthetic user-role message carrying `content` verbatim — NOT a
-   * user prompt. `meta` is durable JSON state omitted from the model
-   * projection; it is also the intended channel for any future framing
-   * directive (a producer declares the frame, a dedicated renderer applies it —
-   * see the deferred note in
-   * ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md),
-   * so the surface keeps projecting `content` verbatim rather than wrapping it.
-   */
-  'context/message': {
-    content: ContentBlock[]
-    source: MessageSource
-    meta?: JsonValue
-  }
   /** Raw stream chunk — token-level replay fidelity. */
   'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
   /**
@@ -275,15 +283,25 @@ export interface SessionEventMap {
    */
   'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
   /**
-   * A completed tool call's model-facing result, plus an optional tool-private
-   * `meta` presentation payload. `meta` is opaque to the core (`unknown` — the
-   * producing tool owns its shape and reads it back in `presentResult`) but MUST
-   * be JSON-serializable: `Session.append` runtime-validates all event data with
-   * `isJsonValue`, so a non-serializable `meta` is rejected at the source, and the
-   * durable log reproduces the identical card on replay. Absent unless the tool
-   * attaches one (e.g. `dsh-tool-fs` carries its result-time contextual diff here).
+   * 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; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
+  'tool/result': {
+    turn: number
+    step: number
+    callId: CallId
+    content: ContentBlock[]
+    isError: boolean
+    error?: { name: string; code: string }
+    meta?: JsonValue
+  }
   /** Steering content injected between steps of a running turn. */
   'steering/message': PromptMessageData & { turn: number }
   /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
@@ -321,7 +339,6 @@ export type SurfaceEventType =
   | 'user/message'
   | 'assistant/message'
   | 'tool/result'
-  | 'context/message'
   | 'steering/message'
 
 /**
@@ -339,7 +356,7 @@ export type SurfaceEvent = SessionEvent<SurfaceEventType> & { surfaceOp: Surface
  * How a session event entered the ordered surface. Only valid on
  * {@link SurfaceEventType} events.
  *
- * - `'append'`: added to the tail — normal path for user/assistant/tool/context
+ * - `'append'`: added to the tail — normal path for user/assistant/tool/steering
  *   messages.
  * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
@@ -374,7 +391,7 @@ export interface SurfaceIntent {
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
  * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`, `context/message`, `steering/message`).
+ * `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.
diff --git a/packages/core/session/tests/derived-cache.spec.ts b/packages/core/session/tests/derived-cache.spec.ts
index 96d1f7048c..c2ff24936b 100644
--- a/packages/core/session/tests/derived-cache.spec.ts
+++ b/packages/core/session/tests/derived-cache.spec.ts
@@ -38,7 +38,7 @@ describe('derived-message cache', () => {
     expect(beforeReplace).toHaveLength(2)
 
     const nodes = session.surface.nodes
-    session.append('context/message', {
+    session.append('user/message', {
       content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' },
     }, { surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, sourceEventSeqs: [nodes[0]!, nodes[1]!] })
 
diff --git a/packages/core/session/tests/json.spec.ts b/packages/core/session/tests/json.spec.ts
index 4fb06fd744..d81266440e 100644
--- a/packages/core/session/tests/json.spec.ts
+++ b/packages/core/session/tests/json.spec.ts
@@ -1,5 +1,17 @@
+import { runInNewContext } from 'node:vm'
 import { describe, expect, it } from 'vitest'
-import { isJsonValue, snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import { isJsonValue, snapshotJsonValue, type JsonValue } from '@deepseek-ai/dsh-session'
+
+function objectWithForgedIntrinsicPrototype(revoked = false): Record<string, unknown> {
+  const prototype = Object.create(null) as Record<string, unknown>
+  const ForgedObject = function ForgedObject(): void {}
+  Object.defineProperty(ForgedObject, 'name', { value: 'Object' })
+  ForgedObject.prototype = prototype
+  const constructor = revoked ? Proxy.revocable(ForgedObject, {}) : undefined
+  if (constructor !== undefined) constructor.revoke()
+  Object.defineProperty(prototype, 'constructor', { value: constructor?.proxy ?? ForgedObject })
+  return Object.assign(Object.create(prototype) as Record<string, unknown>, { value: 1 })
+}
 
 describe('snapshotJsonValue', () => {
   it('copies the complete JSON scalar vocabulary and rejects unsupported scalars', () => {
@@ -36,6 +48,22 @@ describe('snapshotJsonValue', () => {
     expect(Object.getPrototypeOf(snapshot.list[0])).toBe(Object.prototype)
   })
 
+  it('accepts intrinsic plain containers from another JavaScript realm', () => {
+    const foreign = runInNewContext('({ object: { nested: [1] }, array: [2, { ok: true }] })') as {
+      object: { nested: number[] }
+      array: JsonValue[]
+    }
+
+    expect(isJsonValue(foreign.object)).toBe(true)
+    expect(isJsonValue(foreign.array)).toBe(true)
+    const objectSnapshot = snapshotJsonValue(foreign.object)!
+    const arraySnapshot = snapshotJsonValue(foreign.array)!
+    expect(objectSnapshot).toEqual({ nested: [1] })
+    expect(arraySnapshot).toEqual([2, { ok: true }])
+    expect(Object.getPrototypeOf(objectSnapshot)).toBe(Object.prototype)
+    expect(Object.getPrototypeOf(arraySnapshot)).toBe(Array.prototype)
+  })
+
   it('reads each object value and array slot once while materializing', () => {
     class Exotic {
       readonly accepted = false
@@ -63,19 +91,64 @@ describe('snapshotJsonValue', () => {
     expect(arrayReads).toBe(1)
   })
 
-  it('rejects exotic containers, sparse arrays, cycles, and invalid children', () => {
+  it('accepts deeply nested valid JSON without using the JavaScript call stack', () => {
+    let value: JsonValue = 'leaf'
+    for (let depth = 0; depth < 5_000; depth++) value = [value]
+
+    expect(isJsonValue(value)).toBe(true)
+    let cursor: JsonValue | undefined = snapshotJsonValue(value)
+    for (let depth = 0; depth < 5_000; depth++) {
+      expect(Array.isArray(cursor)).toBe(true)
+      cursor = Array.isArray(cursor) ? cursor[0] : undefined
+    }
+    expect(cursor).toBe('leaf')
+  })
+
+  it('rejects exotic containers, sparse or decorated arrays, cycles, and invalid children', () => {
     class ExoticObject {
       readonly value = 1
     }
     class ExoticArray extends Array<number> {}
     const sparse = new Array<number>(1)
+    const compensatedSparse = new Array<number>(1)
+    Object.defineProperty(compensatedSparse, 'extra', { value: true })
+    const decorated = [1]
+    Object.defineProperty(decorated, 'extra', { value: true })
+    const symbolDecorated = [1]
+    Object.defineProperty(symbolDecorated, Symbol('extra'), { value: true })
+    const hiddenObject = Object.defineProperty({}, 'hidden', { value: true })
+    const symbolObject = { [Symbol('extra')]: true }
+    const customPrototype = Object.create(null) as Record<string, unknown>
+    const customPrototypeObject = Object.assign(Object.create(customPrototype) as Record<string, unknown>, { value: 1 })
+    const forgedIntrinsicObject = objectWithForgedIntrinsicPrototype()
+    const revokedIntrinsicObject = objectWithForgedIntrinsicPrototype(true)
+    const forgedPrototype: unknown[] = []
+    Object.setPrototypeOf(forgedPrototype, null)
+    const forgedArray = [1]
+    Object.setPrototypeOf(forgedArray, forgedPrototype)
     const cyclic: Record<string, unknown> = {}
     cyclic.self = cyclic
+    const foreignExotics = runInNewContext(`(() => {
+      class Box { constructor() { this.value = 1 } }
+      class List extends Array {}
+      return [new Box(), new List(1)]
+    })()`) as [object, unknown[]]
 
     expect(snapshotJsonValue(new ExoticObject())).toBeUndefined()
     expect(snapshotJsonValue(new Map([['value', 1]]))).toBeUndefined()
     expect(snapshotJsonValue(new ExoticArray(1))).toBeUndefined()
+    expect(snapshotJsonValue(foreignExotics[0])).toBeUndefined()
+    expect(snapshotJsonValue(foreignExotics[1])).toBeUndefined()
     expect(snapshotJsonValue(sparse)).toBeUndefined()
+    expect(snapshotJsonValue(compensatedSparse)).toBeUndefined()
+    expect(snapshotJsonValue(decorated)).toBeUndefined()
+    expect(snapshotJsonValue(symbolDecorated)).toBeUndefined()
+    expect(snapshotJsonValue(hiddenObject)).toBeUndefined()
+    expect(snapshotJsonValue(symbolObject)).toBeUndefined()
+    expect(snapshotJsonValue(customPrototypeObject)).toBeUndefined()
+    expect(snapshotJsonValue(forgedIntrinsicObject)).toBeUndefined()
+    expect(snapshotJsonValue(revokedIntrinsicObject)).toBeUndefined()
+    expect(snapshotJsonValue(forgedArray)).toBeUndefined()
     expect(snapshotJsonValue(cyclic)).toBeUndefined()
     expect(snapshotJsonValue([undefined])).toBeUndefined()
     expect(snapshotJsonValue({ value: undefined })).toBeUndefined()
@@ -133,16 +206,40 @@ describe('isJsonValue', () => {
     expect(isJsonValue(nullPrototype)).toBe(true)
   })
 
-  it('rejects sparse arrays, invalid children, exotic objects, and cycles', () => {
+  it('rejects sparse or decorated arrays, invalid children, exotic objects, and cycles', () => {
     class Exotic {
       readonly value = 1
     }
     class ExoticArray extends Array<number> {}
     const sparse = new Array<number>(1)
+    const compensatedSparse = new Array<number>(1)
+    Object.defineProperty(compensatedSparse, 'extra', { value: true })
+    const decorated = Object.assign([1], { extra: true })
+    const symbolDecorated = [1]
+    Object.defineProperty(symbolDecorated, Symbol('extra'), { value: true })
+    const hiddenObject = Object.defineProperty({}, 'hidden', { value: true })
+    const symbolObject = { [Symbol('extra')]: true }
+    const customPrototype = Object.create(null) as Record<string, unknown>
+    const customPrototypeObject = Object.assign(Object.create(customPrototype) as Record<string, unknown>, { value: 1 })
+    const forgedIntrinsicObject = objectWithForgedIntrinsicPrototype()
+    const revokedIntrinsicObject = objectWithForgedIntrinsicPrototype(true)
+    const forgedPrototype: unknown[] = []
+    Object.setPrototypeOf(forgedPrototype, null)
+    const forgedArray = [1]
+    Object.setPrototypeOf(forgedArray, forgedPrototype)
     const cyclic: Record<string, unknown> = {}
     cyclic.self = cyclic
 
     expect(isJsonValue(sparse)).toBe(false)
+    expect(isJsonValue(compensatedSparse)).toBe(false)
+    expect(isJsonValue(decorated)).toBe(false)
+    expect(isJsonValue(symbolDecorated)).toBe(false)
+    expect(isJsonValue(hiddenObject)).toBe(false)
+    expect(isJsonValue(symbolObject)).toBe(false)
+    expect(isJsonValue(customPrototypeObject)).toBe(false)
+    expect(isJsonValue(forgedIntrinsicObject)).toBe(false)
+    expect(isJsonValue(revokedIntrinsicObject)).toBe(false)
+    expect(isJsonValue(forgedArray)).toBe(false)
     expect(isJsonValue(new ExoticArray(1))).toBe(false)
     expect(isJsonValue([undefined])).toBe(false)
     expect(isJsonValue({ value: undefined })).toBe(false)
diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts
index d880153dd3..e649214a29 100644
--- a/packages/core/session/tests/session.spec.ts
+++ b/packages/core/session/tests/session.spec.ts
@@ -62,7 +62,7 @@ describe('Session', () => {
       turn: 1,
       trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'before' } },
     })
-    session.append('context/message', {
+    session.append('user/message', {
       content: [{ type: 'text', text: 'before' }],
       source: { kind: 'plugin', plugin: 'before' },
     }, { surfaceOp: 'append' })
@@ -82,7 +82,7 @@ describe('Session', () => {
       turn: 3,
       trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'after' } },
     })
-    session.append('context/message', {
+    session.append('user/message', {
       content: [{ type: 'text', text: 'after' }],
       source: { kind: 'plugin', plugin: 'after' },
     }, { surfaceOp: 'append' })
@@ -117,9 +117,9 @@ describe('Session', () => {
       .toThrow('seed turn/end at index 1 uses unsupported reason-bearing aborted format')
   })
 
-  it('renders context and steering messages as plain user content', () => {
+  it('renders injected-context and steering messages as plain user content', () => {
     const session = new Session(SessionId('s2'))
-    session.append('context/message', {
+    session.append('user/message', {
       content: [{ type: 'text', text: 'file changed: a.ts' }],
       source: { kind: 'plugin', plugin: 'watcher' },
     }, { surfaceOp: 'append' })
@@ -172,7 +172,7 @@ describe('Session', () => {
       version: 1,
       changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md', digest: 'abc123' }],
     }
-    session.append('context/message', {
+    session.append('user/message', {
       content: [{ type: 'text', text: '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>' }],
       source: { kind: 'plugin', plugin: 'workspace-context' },
       meta,
@@ -183,7 +183,7 @@ describe('Session', () => {
       content: [{ type: 'text', text: '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>' }],
     }])
     const event = session.events[0]
-    expect(event?.type === 'context/message' && event.data.meta).toEqual(meta)
+    expect(event?.type === 'user/message' && event.data.meta).toEqual(meta)
   })
 
   it('replays identically from a seeded event log', () => {
@@ -757,7 +757,7 @@ describe('Session', () => {
       { header: 1, error: /not a plain JSON record/ },
       { header: null, error: /not a plain JSON record/ },
       { header: { ...base, version: 1 }, error: /header version/ },
-      { header: { ...base, createdAt: '123' }, error: /createdAt must be a finite number/ },
+      { header: { ...base, createdAt: '123' }, error: /createdAt must be a non-negative safe integer/ },
       { header: { ...base, cwd: 1 }, error: /header cwd must be a string/ },
       { header: { ...base, cwd: 'relative' }, error: /header cwd must be an absolute path/ },
       { header: { ...base, parentSession: 1 }, error: /header parentSession must be a string/ },
@@ -962,7 +962,7 @@ describe('SessionStore', () => {
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('plain'))
     expect(session.header).toMatchObject({ version: SESSION_FORMAT_VERSION, id: 'plain' })
-    expect(typeof session.header.createdAt).toBe('number')
+    expect(Number.isSafeInteger(session.header.createdAt)).toBe(true)
     expect(session.header.cwd).toBeUndefined()
     expect(session.header.parentSession).toBeUndefined()
   })
@@ -1001,7 +1001,10 @@ describe('SessionStore', () => {
       { meta: { parentSession: 1n }, error: /header is not losslessly JSON-serializable/ },
       { meta: { cwd: 1 }, error: /header cwd must be a string/ },
       { meta: { parentSession: 1 }, error: /header parentSession must be a string/ },
-      { meta: { createdAt: '123' }, error: /header createdAt must be a finite number/ },
+      { meta: { createdAt: '123' }, error: /header createdAt must be a non-negative safe integer/ },
+      { meta: { createdAt: 1.5 }, error: /header createdAt must be a non-negative safe integer/ },
+      { meta: { createdAt: -1 }, error: /header createdAt must be a non-negative safe integer/ },
+      { meta: { createdAt: Number.MAX_SAFE_INTEGER + 1 }, error: /header createdAt must be a non-negative safe integer/ },
       { meta: { seedLength: '1' }, error: /seedLength must be a non-negative safe integer/ },
       { meta: { seedLength: 0.5 }, error: /seedLength must be a non-negative safe integer/ },
       { meta: { seedLength: -1 }, error: /seedLength must be a non-negative safe integer/ },
diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts
index b7cbe11b11..cfb84f4e18 100644
--- a/packages/core/session/tests/surface.spec.ts
+++ b/packages/core/session/tests/surface.spec.ts
@@ -444,9 +444,9 @@ describe('deriveMessages with surface', () => {
     expect(messages[0]!.content[0]).toMatchObject({ type: 'text', text: 'compacted' })
   })
 
-  it('context/message and steering/message appear on surface', () => {
+  it('injected-context and steering/message appear on surface', () => {
     const s = new Session(SessionId('ctx'))
-    s.append('context/message', { content: [{ type: 'text', text: 'file changed' }], source: { kind: 'plugin', plugin: 'watcher' } }, { surfaceOp: 'append' })
+    s.append('user/message', { content: [{ type: 'text', text: 'file changed' }], source: { kind: 'plugin', plugin: 'watcher' } }, { surfaceOp: 'append' })
     s.append('steering/message', { turn: 1, content: [{ type: 'text', text: 'focus' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     const messages = s.deriveMessages()
     expect(messages).toHaveLength(2)
@@ -524,7 +524,6 @@ describe('surface type guards', () => {
     expect(isSurfaceEligibleType('user/message')).toBe(true)
     expect(isSurfaceEligibleType('assistant/message')).toBe(true)
     expect(isSurfaceEligibleType('tool/result')).toBe(true)
-    expect(isSurfaceEligibleType('context/message')).toBe(true)
     expect(isSurfaceEligibleType('steering/message')).toBe(true)
     expect(isSurfaceEligibleType('turn/start')).toBe(false)
     expect(isSurfaceEligibleType('assistant/chunk')).toBe(false)
@@ -568,7 +567,7 @@ describe('SurfaceManager.replaceGeneration', () => {
     expect(s.surface.replaceGeneration).toBe(0)
 
     const nodes = s.surface.nodes
-    s.append('context/message', {
+    s.append('user/message', {
       content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' },
     }, { surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, sourceEventSeqs: [nodes[0]!, nodes[1]!] })
     expect(s.surface.replaceGeneration).toBe(1)
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 823060f728..089017d545 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -1,6 +1,6 @@
 # dsh-tools
 
-Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the extensible allow/deny gate) → monotonic registered guards → `tools/execute` (an around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the result, attach context) → the observe-only `tools/result` notification. The registry also owns HOW its tools are presented to the model — its `mode` config selects native function calling, [Code Mode](#code-mode), or both.
+Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the extensible allow/deny gate) → monotonic registered guards → `tools/execute` (an around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the result, attach context) → the definition-owned `finalizeContent` boundary → the observe-only `tools/result` notification. The registry also owns HOW its tools are presented to the model — its `mode` config selects native function calling, [Code Mode](#code-mode), or both.
 
 ## Service: `ToolRegistry` (ctx key: `tools`)
 
@@ -15,7 +15,7 @@ tools:
 
 ### Public API
 
-- `ctx.tools.register(definition: ToolDefinition): () => void` Register a trusted typed same-process definition. 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. `timeoutMs`, when present, must be positive and finite. Disposed with the calling fiber.
+- `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.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)).
@@ -33,18 +33,18 @@ Cancellation is cooperative and quiescent. Every typed invocation supplies a cal
 
 ### Live events
 
-The live registry pipeline has three transformable waterfalls followed by 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 [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.
 
 ### Key types
 
-- `ToolDefinition` — `ToolSchema` + `execute(args, exec)`, whose async work must cooperatively stop through `exec.signal`, plus optional presentation callbacks, cooperative `timeoutMs`, and optional per-call `isConcurrencySafe(args)` classification.
+- `ToolDefinition` — `ToolSchema` + mandatory `output { schema, render, presentationMeta? }` + `execute(args, exec)`, optional final-content and presentation callbacks, cooperative `timeoutMs`, and optional per-call `isConcurrencySafe(args)` classification. A body returns only the canonical JSON value declared by the output schema and cooperatively stops through `exec.signal`. `finalizeContent(exec, result)` runs exactly once for every normalized result, including failures that bypass post-policy, and can replace only `content`; it must be synchronous and total.
 - `ToolExecutionInput` — the caller-supplied call description: `{ callId, name, arguments, signal, agent?, parent? }`; `signal` is required and readonly, callers may pass an enclosing execution's opaque token as `parent`, and callers never choose the new execution's own token.
 - `ToolExecutionToken` — a fresh branded `Symbol` assigned by the registry. It supports equality correlation only and never crosses a model, log, or worker boundary.
 - `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)`. Composite tools use it to ferry context produced by nested dispatches to the outer result even when the tool later throws or cancellation wins; it never injects immediately.
-- `ToolExecutionResult` — losslessly JSON-serializable outcome: `{ content, isError, error?, additionalContexts?, meta? }`. Call identity stays on the immutable `ToolExecution` supplied alongside the result instead of being duplicated on the outcome. The registry materializes and freezes the complete post-policy value before final observation. On failure with a `HarnessError`, `error: { name, code }` carries the structured failure class alongside the model-facing text. `additionalContexts` preserves each deferred or post-execute `HookContext` with its own source and durable JSON metadata; the loop buffers the array and appends each entry as a `context/message` after all `tool/result`s in the step.
+- `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 `HookContext` 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.
-- `PostToolDecision` — `{kind:'accept', content?, additionalContexts?}` (keep the call successful, optionally replacing the model-facing content) | `{kind:'block', feedback, additionalContexts?}` (turn it into an `isError` whose content is the corrective feedback). Accept preserves tool-deferred contexts before decision contexts; block discards tool-deferred contexts and exposes only contexts explicitly supplied by the blocking decision.
+- `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").
 
@@ -52,8 +52,8 @@ The live registry pipeline has three transformable waterfalls followed by the ob
 
 - 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 core dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal.
-- `tools/post-execute` may replace content, block with feedback, or attach ordered contexts; `tools/result` observes the immutable final outcome.
+- `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).
 - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas.
 
@@ -76,27 +76,30 @@ ctx.tools.register(defineTool({
     offset: { type: 'number' },
     limit: { type: 'number' },
   },
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   async execute(args, exec) {
     // args is typed: { path: string; offset?: number; limit?: number }
-    const text = await readFile(args.path, { encoding: 'utf8', signal: exec.signal })
-    return [{ type: 'text', text }]
+    return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
   },
 }))
 ```
 
-The helper converts the author-facing `SchemaSpec` (with `required: true` as a per-property boolean) to standard JSON Schema for the wire format and uses the same typed spec for execute/presentation validation. Raw JSON-Schema tool definitions (from MCP servers) are still accepted by the registry directly.
+The unified schema DSL uses `ParameterSchemaSpec` for the implicit open parameter object and `ValueSchemaSpec` for any JSON-value root. It supports `string`, `number`, `integer`, `boolean`, `null`, `array`, `object`, author-only `json`, and exact-one `oneOf`; scalar `enum`/`const` values are type-correct. Every explicit DSL object declares `additionalProperties: true | false`, while the implicit parameter root and raw JSON Schema keep the standard open default. Schema records accept only own enumerable string keys, and schema arrays must be dense ordinary arrays. Compilation, validation, registry detachment, and schema-to-TypeScript rendering use explicit work stacks, so runtime processing of valid deep schemas is memory-bounded rather than call-stack-bounded; `InferValue` preserves exact types through 16 container levels and then falls back to `JsonValue` so TypeScript itself remains stack-safe.
 
-A `defineTool` definition validates model arguments before execution and turns missing required values, wrong primitives, invalid enum members, and nested violations into `ToolArgsError` (`INVALID_ARGS`) for the normal error-result path. Extra keys are allowed, defaults are not applied, and object or array fields without `properties` or `items` receive only a type check. Raw-registered tools own their validation.
+A `defineTool` definition validates model arguments before execution and turns missing required values, wrong primitives, invalid enum members, and nested violations into `ToolArgsError` (`INVALID_ARGS`) for the normal error-result path. It also infers the body return and pure output projectors from `output.schema`; the registry snapshots and validates the returned lossless JSON before presentation. The implicit parameter root is open; an explicit object accepts extra keys only with `additionalProperties: true`, and a closed object with no declared properties accepts only `{}`. Raw JSON Schema objects remain open unless they explicitly set `additionalProperties: false`. Defaults are not applied; open objects without `properties` and arrays without `items` receive only a container type check. Raw-registered tools own input validation but still declare and receive registry-enforced output.
 
-See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, and `schemaSpecToJsonSchema` in the public API for details.
+See `defineTool`, `validateArgs`, `ToolArgsError`, `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, `InferArgs`, `valueSchemaSpecToJsonSchema`, and `parameterSchemaSpecToJsonSchema` in the public API for details.
 
 Optional `timeoutMs` must be positive and finite; it is policy metadata, not model-visible schema.
 
 Optional `isConcurrencySafe(args)` receives typed, softly validated arguments. Exact `true` permits concurrent dispatch/body execution; invalid input and all other outcomes remain exclusive. Opted-in bodies do not mutate parent-owned state, and shared-state races must commute or fail closed. The [parallel tool-call Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md) owns the full safety contract.
 
-### Structured-output schema subset
+### Enforced raw JSON Schema subset
 
-`StructuredOutputSchema` is the object-rooted raw JSON Schema subset used by subagents and workflows for machine-readable results. It accepts one scalar `type`, object `properties`/`required`/boolean `additionalProperties`, array `items`, and scalar `enum`/`const`. The annotations `description`, `title`, `default`, and `examples` are ignored but must remain JSON data. Type arrays, undeclared required keys, and unsupported keywords fail through `OutputSchemaError` rather than being ignored; `validateStructuredValue()` returns path-qualified violations without throwing.
+`JsonSchemaNode` is the raw counterpart shared by tool outputs, Code Mode generation, subagents, and workflows. It permits any JSON root, an annotation-only unconstrained JSON node, and exact-one `oneOf`; annotations must remain lossless JSON. `assertSupportedJsonSchema()` rejects unsupported constructs, while `validateJsonSchemaValue()` returns path-qualified violations. Subagents and workflows retain their caller-defined object-root requirement through `assertObjectJsonSchema()` and `ObjectJsonSchema`, not through a limitation in the shared vocabulary.
 
 ### Tool-owned UI presentation
 
@@ -105,15 +108,16 @@ Tools optionally own pure `presentCall()` and `presentResult()` render intents,
 - Call views are `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`, `{ card: 'terminal', title, description?, cwd? }`, or `{ card: 'diff', title, diffs, locations? }`.
 - Result views are `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }`, or `{ card: 'diff', title?, diffs }`.
 
-Returning `undefined` selects generic fallback. Presenters depend only on their arguments because UIs call them during live streaming and log replay. Result presentation may read JSON-serializable `result.meta`, which persists with the result; `defineTool` soft-validates older logged arguments and falls back instead of crashing replay. `dsh-tool-bash` and `dsh-tool-fs` are the reference implementations; the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns the rationale.
+Returning `undefined` selects generic fallback. Presenters depend only on their arguments and the durable result because UIs call them during live streaming and log replay. `output.presentationMeta(args, value)` derives JSON metadata for direct surface calls; that metadata persists with `tool/result` and returns to `presentResult`, while the canonical value itself remains execution-local and is never replayed. Nested Code dispatches do not compute metadata. `defineTool` soft-validates older logged arguments and falls back instead of crashing replay. `dsh-tool-bash` and `dsh-tool-fs` are the reference implementations; the [canonical-output Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) owns the value/presentation split and the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns card vocabulary.
 
 ### Code Mode
 
-Under `code` or `both`, the registry exposes the reserved `run_code` transport and a deterministic TypeScript SDK for the current scope; only program output re-enters model context. Each JSON-normalized binding re-enters the complete tool pipeline sequentially with logged correlation to the outer call. Denials reject that binding, ordinary side effects are not rolled back, and sub-call `additionalContexts` are deferred through the parent result to preserve call/result adjacency. Run settlement aborts and drains outstanding bindings; failures surface as `CodeRunFailedError`. See the [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) and [code-runtime seam](../../code-runtime/README.md). Try `pnpm run demo:code-mode`.
+Under `code` or `both`, the registry exposes the reserved `run_code` transport and a deterministic TypeScript SDK for the current scope; only the program's outer logs and return value re-enter model context. The SDK declares exact `ToolArgsMap` and `ToolOutputMap` entries for every visible tool, and each binding resolves to the tool's canonical JSON value. Each lossless-JSON binding call re-enters the complete tool pipeline sequentially with logged correlation to the outer call. Denials and other failed results reject with the real program-visible `ToolCallError` carrying only `toolName` and `message`; Native content and internal error codes stay outside the Code contract. Ordinary side effects are not rolled back, and sub-call `additionalContexts` are deferred through the parent result to preserve call/result adjacency. Run settlement aborts and drains outstanding bindings; runtime failures surface as `CodeRunFailedError`. See the [Code Mode foundation](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md), [typed-return contract](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md), and [code-runtime seam](../../code-runtime/README.md). Try `pnpm run demo:code-mode`.
 
-- **The SDK section** (`tools:sdk`, order 150): a lazy prompt section regenerating, at each assembly, a `declare const tools: {...}` TypeScript declaration of the calling scope's visible end capabilities (exotic names via quoted keys), plus fixed usage instructions. Deterministic — lexicographic tool order, byte-identical text for an unchanged tool set (prefix-cache-friendly). The codegen (`jsonSchemaToTs`, exported) is total: constructs outside the `defineTool` subset degrade to `unknown`, never throw.
-- **The dispatch bridge** (`run_code`'s execute): every binding call is JSON-normalized before dispatch (a value that does not survive — `BigInt`, circulars — rejects that one call, so the dispatched form and logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes underlying calls one at a time in submission order), given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A denial reaches the program as a binding rejection, and each sub-call is logged as a `tool/code-dispatch` session event with deterministic id `<parent>:code:<n>`; `deriveMessages()` does not surface that event. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. Every sub-call `additionalContexts` entry is deferred through the outer `ToolRunContext` in dispatch order; the loop appends those contexts only after the parent `run_code` result, preserving adjacency and retaining each source/meta even when the program later fails.
+- **The SDK section** (`tools:sdk`, order 150): a lazy prompt section regenerating, at each assembly, `JsonValue`, exact `ToolArgsMap` / `ToolOutputMap`, `ToolName`, the `ToolCallError` declaration, and a mapped `tools` namespace for the calling scope's visible end capabilities (exotic names via quoted keys), plus fixed usage instructions. Deterministic — lexicographic tool order, byte-identical text for an unchanged tool set (prefix-cache-friendly). The codegen (`jsonSchemaToTs`, exported) handles every unified schema construct and degrades unsupported raw constructs to `unknown`, never throwing during prompt assembly.
+- **The dispatch bridge** (`run_code`'s execute): every binding call is snapshotted as lossless JSON before dispatch (`undefined`, `BigInt`, cycles, sparse arrays, `-0`, and exotic objects reject that one call), serialized through a per-run queue (even `Promise.all` executes underlying calls one at a time in submission order), given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A success returns the final canonical value after policy; a failure reaches the worker as one message and becomes `ToolCallError(toolName, message)`. Each sub-call is logged as a `tool/code-dispatch` session event with deterministic id `<parent>:code:<n>` and a bounded Native-content summary; `deriveMessages()` does not surface that event or persist the value. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. Every sub-call `additionalContexts` entry is deferred through the outer `ToolRunContext` in dispatch order; the loop appends those contexts only after the parent `run_code` result, preserving adjacency and retaining each source/meta even when the program later fails.
 - **Settlement discipline**: the bridge owns a run-scoped abort that follows the outer signal in and fires when the run settles for any reason, so a budget expiry aborts an in-flight sub-tool instead of orphaning it; the bridge then drains its queue BEFORE returning, so every `tool/code-dispatch` lands inside the open turn. A failed run throws `CodeRunFailedError` (`code: 'CODE_RUN_FAILED'`, message = the failure kind + captured logs), which the pipeline converts to a structured `isError` the model self-corrects from.
+- **Result boundary**: intermediate binding values cross the worker boundary whole and have no per-binding byte cap. `run_code` returns canonical `{ logs: string[], result?: JsonValue }`; strings render raw, every other present JSON root renders through a stack-safe pretty JSON traversal whose total indentation is capped at ten characters (deeper subtrees stay compact), `null` remains explicit, and absent `result` means the program returned `undefined`. The worker's configurable `maxOutputBytes` (default 64 MiB) applies only to the combined serialized outer log-array, completion-value, or failure-message payloads; fixed result-envelope syntax and presentation whitespace are outside that ledger. Invalid and over-limit completions fail explicitly, and only this outer result is eligible for ordinary spill.
 
 ### Parallel execution
 
@@ -148,8 +152,8 @@ Code Mode exposes the generated [`run_code` schema](../../../docs/tool-catalog.m
 
 Pass `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:
 
-- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.
-- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.
+- 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.
+- 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.
 - Calls execute sequentially, even under `Promise.all`.
 - 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.
 
@@ -182,8 +186,8 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **Concurrency policy is not an event seam** — `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).
-- **`defineTool`'s schema DSL is a deliberate subset** — string/number/boolean/object/array with string-only `enum`; `validateArgs` tolerates extra keys and preserves `default` as a model-visible JSON Schema annotation without applying it during validation; dynamic Cordis mounts may supply defaults even though first-party definitions do not, while raw-registered JSON-Schema tools validate their own input.
+- **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.
 - **Code Mode is TypeScript-only and the presentation mode is service-wide** — `mode: code`/`both` rejects prompt assembly unless `ctx.codeRuntime.language === 'typescript'`; scoped restrictions/shadows still choose each agent's visible bindings, but one tool cannot be native-only while another is code-only.
-- **Code Mode bindings return text only** — non-text content blocks in a sub-call result collapse to `[<type> content]` placeholders.
+- **Code Mode intermediate values are execution-local and unbounded by bytes** — they cannot be reconstructed from session replay and may exhaust process or worker memory; only the outer `run_code` output has the worker's configurable hard cap.
 - **`run_code` state is fresh per run** — a persistent REPL-style kernel is rejected for the MVP (cross-call state would be invisible to the log); see [the Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md).
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index 01af0e4857..30e85c3ad7 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -6,11 +6,11 @@
  */
 
 import { parse } from 'node:path'
-import { inspect } from 'node:util'
 import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { CodeBindingFunction, CodeRunResult, CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
-import type {} from '@deepseek-ai/dsh-session'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { defineTool } from './schema.ts'
 import type { ToolDefinition, ToolRegistry } from './index.ts'
 
@@ -62,10 +62,7 @@ export class CodeRunFailedError extends HarnessError {
  */
 const SUMMARY_MAX_CHARS = 200
 
-/** Bounded inspect for rendering a program's completion value into the model-facing text. */
-const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 } as const
-
-/** Join a result's text blocks; a non-text block becomes a placeholder (an MVP limitation, stated in the SDK instructions). */
+/** Join Native content for the bounded durable sub-dispatch summary; non-text blocks become diagnostic placeholders. */
 function textOf(content: ContentBlock[]): string {
   return content
     .map((block) => {
@@ -88,47 +85,120 @@ function summarize(text: string, cwd: string | undefined): string {
 }
 
 /**
- * JSON-normalize one binding call's argument into TWO independent parses of the same canonical
- * text: `dispatched` goes to the tool, `logged` to the `tool/code-dispatch` event — identical
- * by construction (the runtime's structured-clone boundary is wider than JSON; the session log
- * accepts only JSON), and separate objects, so a tool mutating its args can neither desync the
- * log from what was dispatched nor re-poison the append.
+ * Snapshot one binding call's argument as lossless JSON, then snapshot that
+ * detached value again so dispatch and logging stay independent without
+ * reintroducing structured-clone's platform-specific nesting limit.
  */
 function jsonNormalizeArgs(value: unknown): { dispatched: unknown; logged: unknown } {
-  if (value === undefined) {
-    throw new Error('tool arguments must be JSON-serializable (call the tool with an arguments object, e.g. `{}`)')
-  }
-  let text: string | undefined
+  let snapshot: JsonValue | undefined
   try {
-    text = JSON.stringify(value)
+    snapshot = snapshotJsonValue(value) as JsonValue | undefined
   } catch (error: unknown) {
-    throw new Error(`tool arguments must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`)
+    throw new Error(`tool arguments must be lossless JSON: ${error instanceof Error ? error.message : String(error)}`)
   }
-  // JSON.stringify's lib type claims `string`, but a bare function or symbol
-  // root really yields `undefined` at runtime — the guard is live.
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  if (text === undefined) throw new Error('tool arguments must be JSON-serializable (got a value JSON cannot represent)')
-  return { dispatched: JSON.parse(text) as unknown, logged: JSON.parse(text) as unknown }
+  if (snapshot === undefined) {
+    throw new Error('tool arguments must be lossless JSON (call the tool with an arguments object, e.g. `{}`)')
+  }
+  const logged = snapshotJsonValue(snapshot)
+  /* v8 ignore next -- snapshot is already a detached lossless JSON value. */
+  if (logged === undefined) {
+    throw new Error('tool arguments could not be detached for durable logging')
+  }
+  return { dispatched: snapshot, logged }
 }
 
-/** Render the program's completion value for the model-facing result text (`''` when the program returned nothing). */
-function renderValue(value: unknown): string {
-  if (value === undefined) return ''
-  return typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS)
+/** Two-space JSON presentation, matching the existing shallow `run_code` text contract. */
+const JSON_INDENT = '  '
+
+/**
+ * ECMAScript caps `JSON.stringify`'s `space` string at ten characters. The
+ * renderer also caps TOTAL indentation there, compacting deeper subtrees, so
+ * formatted output remains linear in the canonical JSON size.
+ */
+const MAX_JSON_INDENT_CHARS = 10
+
+/** A pending fragment in the iterative JSON presentation traversal. */
+type JsonRenderTask =
+  | { kind: 'text'; text: string }
+  | { kind: 'value'; value: JsonValue; depth: number; compact: boolean }
+
+/** Render one non-string JSON root without recursive traversal or unbounded indentation growth. */
+function renderJsonValue(value: Exclude<JsonValue, string>): string {
+  const chunks: string[] = []
+  const tasks: JsonRenderTask[] = [{ kind: 'value', value, depth: 0, compact: false }]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'text') {
+      chunks.push(task.text)
+      continue
+    }
+
+    const current = task.value
+    if (current === null || typeof current === 'boolean' || typeof current === 'number') {
+      chunks.push(String(current))
+      continue
+    }
+    if (typeof current === 'string') {
+      chunks.push(JSON.stringify(current))
+      continue
+    }
+
+    const compact = task.compact || (task.depth + 1) * JSON_INDENT.length > MAX_JSON_INDENT_CHARS
+    const childDepth = task.depth + 1
+    if (Array.isArray(current)) {
+      chunks.push('[')
+      if (current.length === 0) {
+        chunks.push(']')
+        continue
+      }
+      tasks.push({ kind: 'text', text: compact ? ']' : `\n${JSON_INDENT.repeat(task.depth)}]` })
+      for (let index = current.length - 1; index >= 0; index--) {
+        const item = current[index]
+        /* v8 ignore next -- canonical JsonValue arrays are dense. */
+        if (item === undefined) throw new Error('cannot render a sparse JSON array')
+        tasks.push({ kind: 'value', value: item, depth: childDepth, compact })
+        tasks.push({
+          kind: 'text',
+          text: compact
+            ? index === 0 ? '' : ','
+            : `${index === 0 ? '\n' : ',\n'}${JSON_INDENT.repeat(childDepth)}`,
+        })
+      }
+      continue
+    }
+
+    const keys = Object.keys(current)
+    chunks.push('{')
+    if (keys.length === 0) {
+      chunks.push('}')
+      continue
+    }
+    tasks.push({ kind: 'text', text: compact ? '}' : `\n${JSON_INDENT.repeat(task.depth)}}` })
+    for (let index = keys.length - 1; index >= 0; index--) {
+      const key = keys[index]
+      /* v8 ignore next -- the loop is bounded by the captured key count. */
+      if (key === undefined) throw new Error('cannot render a missing JSON object key')
+      const item = current[key]
+      /* v8 ignore next -- canonical JsonValue records contain no undefined properties. */
+      if (item === undefined) throw new Error('cannot render an undefined JSON object property')
+      tasks.push({ kind: 'value', value: item, depth: childDepth, compact })
+      tasks.push({
+        kind: 'text',
+        text: compact
+          ? `${index === 0 ? '' : ','}${JSON.stringify(key)}:`
+          : `${index === 0 ? '\n' : ',\n'}${JSON_INDENT.repeat(childDepth)}${JSON.stringify(key)}: `,
+      })
+    }
+  }
+  return chunks.join('')
 }
 
-/** The run_code result's `meta` payload (JSON-serializable; `presentResult` narrows it back). */
-interface RunCodeMeta {
-  logs: CodeRunResult['logs']
+/** Render one present program completion value for the model-facing result text. */
+function renderValue(value: JsonValue): string {
+  return typeof value === 'string' ? value : renderJsonValue(value)
 }
 
-/** Soft-narrow a result `meta` back to {@link RunCodeMeta} (replay may carry older shapes; presentation must not throw). */
-function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined {
-  if (typeof meta !== 'object' || meta === null) return undefined
-  const m = meta as Record<string, unknown>
-  if (!Array.isArray(m.logs) || !m.logs.every(log => typeof log === 'string')) return undefined
-  return m as unknown as RunCodeMeta
-}
+/** Canonical value returned by the outer Code Mode transport. */
+type RunCodeOutput = { logs: string[]; result?: JsonValue }
 
 /**
  * Build the `run_code` {@link ToolDefinition}: one required `code` parameter,
@@ -152,7 +222,22 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
     parameters: {
       code: { type: 'string', required: true, description: 'The program: the body of an async TypeScript function.' },
     },
-    async execute(args, exec) {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          logs: { type: 'array', required: true, items: { type: 'string' } },
+          result: { type: 'json' },
+        },
+      },
+      render: (_args, value) => {
+        const rendered = value.result === undefined ? '' : renderValue(value.result)
+        const parts = [value.logs.join('\n'), rendered].filter(part => part.length > 0)
+        return [{ type: 'text', text: parts.length > 0 ? parts.join('\n') : '(run_code completed with no output)' }]
+      },
+    },
+    async execute(args, exec): Promise<RunCodeOutput> {
       const runtime = requireRuntime()
 
       // The run-scoped abort: follows the outer signal in, and fires when the
@@ -184,7 +269,7 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
       // would be narrowed away by control flow analysis.
       const runOver = (): boolean => runController.signal.aborted
 
-      const binding = (name: string): CodeBindingFunction => async (rawArgs: unknown): Promise<unknown> => {
+      const binding = (name: string): CodeBindingFunction => async (rawArgs: unknown): Promise<JsonValue> => {
         if (runOver()) {
           throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`)
         }
@@ -215,7 +300,9 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
             isError: result.isError,
             resultSummary: summarize(text, exec.agent.session.header.cwd),
           })
-          return { text, isError: result.isError }
+          return result.isError
+            ? { isError: true as const, message: result.error.message }
+            : { isError: false as const, value: result.value }
         })
         // A budget expiry or outer cancel that lands while this call was in
         // flight already aborted the dispatch; stop the program now rather
@@ -223,11 +310,11 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
         if (runOver()) {
           throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} result discarded`)
         }
-        // A failed tool call REJECTS — real code signals failure by throwing,
-        // so try/catch and Promise.all short-circuiting behave as models
-        // expect (the error text is the tool's model-facing result text).
-        if (outcome.isError) throw new Error(outcome.text)
-        return outcome.text
+        // The worker turns a binding rejection into ToolCallError and adds
+        // only the binding name. Native content and internal error metadata
+        // stay outside the program-facing failure contract.
+        if (outcome.isError) throw new Error(outcome.message)
+        return outcome.value
       }
 
       // Null-prototype + defineProperty, mirroring the worker-side namespace
@@ -250,7 +337,11 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
         try {
           result = await runtime.run({
             program: args.code,
-            bindings: [{ global: 'tools', functions }],
+            bindings: [{
+              global: 'tools',
+              functions,
+              errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
+            }],
             signal: runController.signal,
           })
         } finally {
@@ -264,12 +355,9 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
           const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join('\n')}` : ''
           throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}`)
         }
-        const rendered = renderValue(result.value)
-        const parts = [result.logs.join('\n'), rendered].filter(part => part.length > 0)
-        const meta: RunCodeMeta = { logs: result.logs }
         return {
-          content: [{ type: 'text', text: parts.length > 0 ? parts.join('\n') : '(run_code completed with no output)' }],
-          meta,
+          logs: result.logs,
+          ...result.value !== undefined ? { result: result.value } : {},
         }
       } finally {
         exec.signal.removeEventListener('abort', onOuterAbort)
@@ -282,17 +370,8 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
       kind: 'execute',
       rawInput: args.code,
     }),
-    // Title omitted on the result: an update replaces only the fields it
-    // carries, so the pending card's program title persists through
-    // completion; the captured output rides as body content.
-    presentResult: (_args, result) => {
-      const meta = asRunCodeMeta(result.meta)
-      if (!meta) return undefined
-      const output = meta.logs.join('\n')
-      return {
-        card: 'generic',
-        ...output.length > 0 ? { content: [{ type: 'text' as const, text: output }] } : {},
-      }
-    },
+    // Deliberately no presentResult: the generic surface fallback keeps this
+    // title and reads durable result content without duplicating a large raw
+    // result into the host view payload.
   })
 }
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 11f57995e9..468944fa2f 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -12,40 +12,60 @@ import type { CallId, ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
 import { assertNever, deepFreeze, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { Agent, HookContext } from '@deepseek-ai/dsh-agent'
 import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 import type { ToolProviderResult } from '@deepseek-ai/dsh-system-prompt'
 import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
 // Type-only: makes `ctx.get('approval')` resolve to the ApprovalService
 // augmentation. The seam stays optional at runtime — see `serviceAsk`.
 import type {} from '@deepseek-ai/dsh-user-approval'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
+import { assertSupportedJsonSchema, validateJsonSchemaValue } from './json-schema.ts'
+import type { JsonSchemaNode } from './json-schema.ts'
 import { createRunCodeTool, RUN_CODE_NAME, SDK_SECTION_ORDER } from './code-mode.ts'
 import { renderToolsSdk } from './ts-types.ts'
+import type { ToolSdkSchema } from './ts-types.ts'
 
 export {
   defineTool,
-  schemaSpecToJsonSchema,
+  valueSchemaSpecToJsonSchema,
+  parameterSchemaSpecToJsonSchema,
   validateArgs,
   ToolArgsError,
-  type SchemaSpec,
-  type SchemaProp,
-  type SchemaType,
+  type ValueSchemaAnnotations,
+  type StringValueSchemaSpec,
+  type NumberValueSchemaSpec,
+  type IntegerValueSchemaSpec,
+  type BooleanValueSchemaSpec,
+  type NullValueSchemaSpec,
+  type ArrayValueSchemaSpec,
+  type ObjectValueSchemaSpec,
+  type JsonValueSchemaSpec,
+  type OneOfValueSchemaSpec,
+  type ValueSchemaSpec,
+  type ParameterPropertySpec,
+  type ParameterSchemaSpec,
+  type ParameterJsonSchema,
+  type InferValue,
   type InferArgs,
   type DefineToolOptions,
-  type JsonSchemaObject,
 } from './schema.ts'
 
 export {
-  assertSupportedOutputSchema,
-  validateStructuredValue,
-  OutputSchemaError,
-  type StructuredOutputSchema,
-  type StructuredSchemaNode,
-  type StructuredSchemaType,
-  type StructuredScalar,
+  assertSupportedJsonSchema,
+  assertObjectJsonSchema,
+  validateJsonSchemaValue,
+  JsonSchemaError,
+  type JsonSchemaNode,
+  type ObjectJsonSchema,
+  type JsonSchemaType,
+  type JsonSchemaScalar,
 } from './json-schema.ts'
 
+export type { JsonValue } from '@deepseek-ai/dsh-session'
+
 export { CodeRunFailedError, RUN_CODE_NAME } from './code-mode.ts'
 export { jsonSchemaToTs, renderToolsSdk } from './ts-types.ts'
+export { defineContentToolFixture, type ContentToolFixtureOptions } from './testing.ts'
 
 // The render-intent vocabulary a tool declares via `presentCall`/`presentResult`
 // lives in its own UI-facing module; re-export it so `@deepseek-ai/dsh-tools`
@@ -124,21 +144,43 @@ declare module 'cordis' {
   }
 }
 
-/** Tool output, optionally with lossless-JSON presentation metadata persisted for replay. */
-export type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown }
+/** Tool-owned canonical output contract used after the body returns a JSON value. */
+export interface ToolOutputDefinition {
+  /** Raw supported JSON Schema enforced against every successful canonical value. */
+  readonly schema: JsonSchemaNode
+  /** Pure projection from validated arguments and value to Native/model content. */
+  render(args: unknown, value: JsonValue): ContentBlock[]
+  /** Pure replayable presentation projection, computed only for surface calls. */
+  presentationMeta?(args: unknown, value: JsonValue): JsonValue
+}
 
 /** A registered tool: its schema plus the execution function. */
 export interface ToolDefinition extends ToolSchema {
+  /** Mandatory canonical output declaration. */
+  readonly output: ToolOutputDefinition
   /**
-   * Run one accepted call. Async work must observe or forward `exec.signal` and
-   * settle only after its owned work reaches quiescence. The registry preserves
-   * caller cancellation through around-dispatch signal replacement and does
-   * not abandon this promise, but it cannot hard-kill same-process code.
+   * Run one accepted call and return only its canonical lossless-JSON value.
+   * Async work must observe or forward `exec.signal` and settle only after its
+   * owned work reaches quiescence. The registry preserves caller cancellation
+   * through around-dispatch signal replacement and does not abandon this
+   * promise, but it cannot hard-kill same-process code.
    * @param args - losslessly snapshotted, frozen model arguments.
    * @param exec - execution identity, cancellation signal, and context deferral.
-   * @returns model-facing content plus optional private presentation metadata.
+   * @returns the canonical value declared by `output.schema`.
    */
-  execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>
+  execute(args: unknown, exec: ToolRunContext): Promise<unknown>
+  /**
+   * Synchronous last-mile transform for model-facing content. The registry
+   * snapshots this callback when execution starts and invokes it exactly once
+   * for every normalized outcome, including pipeline failures that bypass
+   * `tools/post-execute`, immediately before lossless materialization.
+   * Returning `undefined` preserves the content; every other result field
+   * remains registry-owned. The callback must be total and must not throw.
+   * @param exec - immutable execution identity and arguments.
+   * @param result - complete normalized outcome before materialization.
+   * @returns replacement content, or `undefined` to preserve it.
+   */
+  finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
   /**
    * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
    * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it
@@ -173,7 +215,7 @@ export interface ToolDefinition extends ToolSchema {
   presentCall?(args: unknown): ToolCallView | undefined
   /**
    * Optional: how to present the COMPLETED state, given the same `args` and the
-   * `result` (`execute`'s content + whether it errored). Returns a
+   * durable result projection (`content`, failure state, and optional `meta`). Returns a
    * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
    * pending title and render the raw result content. Pure and side-effect-free
    * for the same replay reason.
@@ -183,17 +225,16 @@ export interface ToolDefinition extends ToolSchema {
 
 /** The completed outcome handed to {@link ToolDefinition.presentResult}. */
 export interface ToolResult {
-  /** The model-facing content `execute` returned (or the error text on failure). */
+  /** The final model-facing content (or the rendered error text on failure). */
   content: ContentBlock[]
   /** Whether the call failed. */
   isError: boolean
   /**
-   * The tool-private presentation payload the tool attached from `execute` (via
-   * the object return form), threaded verbatim from the `tool/result` event.
-   * Opaque (`unknown`); the tool narrows it back to its own shape. Absent when
-   * the tool attached none.
+   * The tool-private presentation payload projected by its output declaration
+   * and threaded verbatim from the `tool/result` event. Absent when the tool
+   * declared no projector or the call was nested under a composite transport.
    */
-  meta?: unknown
+  meta?: JsonValue
 }
 
 declare const toolExecutionTokenBrand: unique symbol
@@ -301,9 +342,9 @@ export interface ToolRegistryScheduler {
   prepare(exec: ToolExecutionInput): Promise<ScheduledToolPreparation>
   /** Run only the around-dispatch/body stage. */
   dispatch(exec: ToolRunContext): Promise<ScheduledToolDispatch>
-  /** Run ordered post-execute finalization, then materialize and notify the final outcome. */
+  /** Run post-execute and definition-owned content finalization, then materialize and notify. */
   finalize(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult>
-  /** Materialize and notify a final outcome that must bypass post-execute. */
+  /** Run definition-owned content finalization, then materialize and notify without post-execute. */
   finish(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult
 }
 
@@ -325,6 +366,14 @@ export interface ToolErrorInfo {
   code: string
 }
 
+/** Canonical failure detail; internal routing information remains optional. */
+export interface ToolFailure {
+  /** Human-readable failure message without the Native `Error: ` envelope. */
+  message: string
+  /** Internal error class/code used by policy and durable diagnostics. */
+  info?: ToolErrorInfo
+}
+
 /**
  * Thrown (internally) when the model requests a tool that isn't registered.
  * Extends {@link HarnessError} (`code: 'UNKNOWN_TOOL'`) so an unknown-tool
@@ -338,30 +387,73 @@ export class ToolNotFoundError extends HarnessError {
   }
 }
 
-/** The outcome of one tool call. */
-export interface ToolExecutionResult {
-  content: ContentBlock[]
-  isError: boolean
-  /**
-   * Set when the call failed with a {@link HarnessError}: machine-routable
-   * `{ name, code }` for retry/sandbox plugins and replay. The model-facing
-   * text in `content` is always present; this is extra structure for code.
-   */
-  error?: ToolErrorInfo
-  /**
-   * Model-facing context for the next request, separate from this tool result. The loop
-   * accepts it into the active-batch FIFO, then appends after recorded results even if interrupted.
-   */
-  additionalContexts?: HookContext[]
-  /**
-   * The tool-private presentation payload from a successful `execute` (the object
-   * return form). Threaded onto the `tool/result` session event and back into
-   * {@link ToolResult} for `presentResult`. Opaque (`unknown`); absent when the
-   * tool attached none or the call failed.
-   */
-  meta?: unknown
+/** Thrown when a tool body or post-policy value violates its declared output. */
+export class ToolOutputError extends HarnessError {
+  /** Schema/value violations in validation order. */
+  readonly violations: string[]
+
+  constructor(toolName: string, violations: string[]) {
+    super(`tool "${toolName}" returned invalid output: ${violations.join('; ')}`, 'INVALID_TOOL_OUTPUT')
+    this.name = 'ToolOutputError'
+    this.violations = violations
+  }
 }
 
+/** Convert one projector exception into the canonical invalid-output failure. */
+function projectionError(toolName: string, projector: 'render' | 'presentationMeta', error: unknown): ToolOutputError {
+  return new ToolOutputError(toolName, [`output.${projector} failed: ${errorMessage(error)}`])
+}
+
+/** Snapshot one projector result before later durable-result materialization. */
+function snapshotProjection<T>(toolName: string, projector: 'render' | 'presentationMeta', candidate: T): T {
+  try {
+    const detached = snapshotJsonValue(candidate)
+    if (detached === undefined) {
+      throw new ToolOutputError(toolName, [`output.${projector} returned non-lossless JSON`])
+    }
+    return detached
+  } catch (error: unknown) {
+    if (error instanceof ToolOutputError) throw error
+    throw projectionError(toolName, projector, error)
+  }
+}
+
+/** Snapshot one body or policy value into the canonical invalid-output failure class. */
+function snapshotToolValue(toolName: string, candidate: unknown): JsonValue {
+  try {
+    const detached = snapshotJsonValue(candidate)
+    if (detached === undefined) throw new ToolOutputError(toolName, ['value is not lossless JSON'])
+    return detached as JsonValue
+  } catch (error: unknown) {
+    if (error instanceof ToolOutputError) throw error
+    throw new ToolOutputError(toolName, [`value snapshot failed: ${errorMessage(error)}`])
+  }
+}
+
+/** Successful canonical tool execution, including its Native/model projection. */
+export interface ToolExecutionSuccess {
+  readonly isError: false
+  /** Execution-local canonical value; deliberately omitted from durable events. */
+  readonly value: JsonValue
+  readonly content: ContentBlock[]
+  readonly error?: never
+  readonly meta?: JsonValue
+  readonly additionalContexts?: HookContext[]
+}
+
+/** Failed canonical tool execution; failures never carry a successful value. */
+export interface ToolExecutionFailure {
+  readonly isError: true
+  readonly error: ToolFailure
+  readonly value?: never
+  readonly content: ContentBlock[]
+  readonly meta?: JsonValue
+  readonly additionalContexts?: HookContext[]
+}
+
+/** The discriminated, execution-local outcome of one tool call. */
+export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure
+
 /**
  * Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
  * `ask` runs only after an approval service returns `allowed-once` and otherwise
@@ -374,11 +466,12 @@ export type PreToolDecision =
   | { kind: 'ask'; reason?: string }
 
 /**
- * Post-dispatch decision: accept or replace content, attach context for the next
- * request, or block by turning corrective feedback into an error result.
+ * Post-dispatch decision: accept, replace one projection, attach context for the
+ * next request, or block by turning corrective feedback into an error result.
  */
 export type PostToolDecision =
-  | { kind: 'accept'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
+  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: HookContext[] }
+  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: HookContext[] }
   | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: HookContext[] }
 
 /**
@@ -403,6 +496,23 @@ function errorMessage(error: unknown): string {
   }
 }
 
+/** Derive one failure message from policy feedback without changing its rendered blocks. */
+function failureMessageFromContent(content: ContentBlock[]): string {
+  const text = content
+    .map(block => block.type === 'text' ? block.text : `[${block.type} content]`)
+    .join('\n')
+  return text.length > 0 ? text : 'tool result blocked by post-execute policy'
+}
+
+/** Snapshot and freeze one durable tool-result projection or reject lossy data. */
+function materializePresentation<T>(candidate: T): T {
+  const detached = snapshotJsonValue(candidate)
+  if (detached === undefined) {
+    throw new TypeError('tool result must be losslessly JSON-serializable')
+  }
+  return deepFreeze(detached)
+}
+
 /** Structured `{ name, code }` for a thrown HarnessError, else undefined. */
 function errorInfo(error: unknown): ToolErrorInfo | undefined {
   try {
@@ -540,6 +650,8 @@ export class ToolRegistry extends Service {
   private deferredContexts = new WeakMap<ToolRunContext, HookContext[]>()
   /** Original caller cancellation, kept outside the wrapper-mutable execution object. */
   private cancellationStates = new WeakMap<ToolRunContext, ToolCancellationState>()
+  /** Definition-owned final content transform snapshotted before policy begins. */
+  private contentFinalizers = new WeakMap<ToolRunContext, ToolDefinition['finalizeContent']>()
   private readonly layers = new ScopedLayers(
     scope => new ToolLayer(scope),
     () => { this.ctx.emit('tools/change') },
@@ -569,7 +681,7 @@ export class ToolRegistry extends Service {
         // Regenerate from the calling scope's visible tools in stable order.
         text: (context) => {
           this.requireCodeRuntime()
-          return renderToolsSdk(this.schemas(context.scope).filter(schema => schema.name !== RUN_CODE_NAME))
+          return renderToolsSdk(this.sdkSchemas(context.scope))
         },
       })
     }
@@ -617,11 +729,18 @@ export class ToolRegistry extends Service {
   /**
    * 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 - the tool schema, execution, and optional presentation functions.
+   * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
    * @returns the exact disposer that unregisters the tool.
    */
   register(definition: ToolDefinition): () => void {
     const name = definition.name
+    const output = (definition as Partial<ToolDefinition>).output
+    if (output === undefined || typeof output !== 'object'
+      || typeof output.render !== 'function'
+      || (output.presentationMeta !== undefined && typeof output.presentationMeta !== 'function')) {
+      throw new TypeError(`tool "${name}" must declare output { schema, render, presentationMeta? }`)
+    }
+    assertSupportedJsonSchema(output.schema)
     const timeoutMs = definition.timeoutMs
     if (timeoutMs !== undefined
       && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
@@ -755,13 +874,34 @@ export class ToolRegistry extends Service {
     return [...this.view(scope).visible.values()].map(definition => this.schemaOf(definition, true))
   }
 
+  /** Project visible callable tools onto the generated Code Mode SDK contract. */
+  private sdkSchemas(scope?: ScopeKey): ToolSdkSchema[] {
+    return [...this.view(scope).visible.values()]
+      .filter(definition => definition.name !== RUN_CODE_NAME)
+      .map((definition): ToolSdkSchema => {
+        const output = snapshotJsonValue(definition.output.schema)
+        /* v8 ignore next -- registration already validated and retained this schema as lossless JSON. */
+        if (output === undefined) {
+          throw new Error(`tool "${definition.name}" output schema must be lossless JSON before SDK projection`)
+        }
+        return {
+          ...this.schemaOf(definition, true),
+          output,
+        }
+      })
+  }
+
   /** Project one definition onto the model-facing schema fields. */
   private schemaOf(definition: ToolDefinition, detachParameters: boolean): ToolSchema {
     const { name, description, parameters } = definition
+    const detached = detachParameters ? snapshotJsonValue(parameters) : parameters
+    if (detached === undefined) {
+      throw new Error(`tool "${name}" parameters must be lossless JSON before schema projection`)
+    }
     return {
       name,
       description,
-      parameters: detachParameters ? structuredClone(parameters) : parameters,
+      parameters: detached,
     }
   }
 
@@ -784,10 +924,11 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Execute through pre-policy, guards, around-dispatch, post-policy, 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
+   * 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
@@ -826,6 +967,8 @@ export class ToolRegistry extends Service {
     const agent = exec.agent
     const parent = exec.parent
     const signal = exec.signal
+    const definition = this.get(name, agent)
+    const finalizeContent = definition?.finalizeContent?.bind(definition)
     const base = {
       token,
       callId,
@@ -844,6 +987,7 @@ export class ToolRegistry extends Service {
       }
       const execution: MutableToolRunContext = { ...base, arguments: deepFreeze(detached) }
       this.deferredContexts.set(execution, deferredContexts)
+      this.contentFinalizers.set(execution, finalizeContent)
       this.cancellationStates.set(execution, {
         callerSignal: signal,
         bodyInvoked: false,
@@ -851,6 +995,7 @@ export class ToolRegistry extends Service {
       return { kind: 'ready', exec: execution }
     } catch (error: unknown) {
       const execution: MutableToolRunContext = { ...base, arguments: undefined }
+      this.contentFinalizers.set(execution, finalizeContent)
       return { kind: 'final-result', exec: execution, result: toolErrorResult(error) }
     }
   }
@@ -895,10 +1040,11 @@ export class ToolRegistry extends Service {
         return await next({
           kind: 'post-result',
           exec,
-          result: {
+          result: this.materializeFinalResult({
             content: [{ type: 'text', text: `Error: ${denialReason}` }],
             isError: true,
-          },
+            error: { message: denialReason },
+          }),
         })
       }
       if (this.callerCancelled(exec)) {
@@ -951,13 +1097,7 @@ export class ToolRegistry extends Service {
       if (!tool) throw new ToolNotFoundError(exec.name)
       state.bodyInvoked = true
       const returned = await tool.execute(exec.arguments, exec)
-      const content = Array.isArray(returned) ? returned : returned.content
-      const meta = Array.isArray(returned) ? undefined : returned.meta
-      const result: ToolExecutionResult = {
-        content,
-        isError: false,
-        ...meta !== undefined ? { meta } : {},
-      }
+      const result = this.createSuccessResult(exec, tool, returned)
       return isAborted(signal)
         ? toolAbortedResult(result)
         : result
@@ -984,18 +1124,19 @@ export class ToolRegistry extends Service {
         carrier, 'tools/execute', mutableExec,
         () => this.dispatchToolBody(mutableExec),
       )
+      const normalized = this.normalizeDispatchResult(exec, result)
       const deferredContexts = this.deferredContexts.get(exec)
       /* v8 ignore next -- dispatch only receives executions minted by this registry's prepare stage */
       if (deferredContexts === undefined) throw new Error('tool registry scheduler invariant violated: unprepared execution')
       const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0
-        ? result
-        : {
-          ...result,
+        ? normalized
+        : this.markCanonical(exec, {
+          ...normalized,
           additionalContexts: [
             ...deferredContexts,
-            ...result.additionalContexts ?? [],
+            ...normalized.additionalContexts ?? [],
           ],
-        }
+        })
       return {
         kind: 'post-result',
         result: this.callerCancelled(exec) && !resultWithDeferredContexts.isError
@@ -1008,7 +1149,8 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Run ordered post-execute, then materialize and notify the final outcome.
+   * Run ordered post-execute, then apply definition-owned content finalization,
+   * materialize, and notify the final outcome.
    * @param exec - the prepared execution.
    * @param result - dispatch/pre result that still needs post-execute.
    * @returns the materialized final result.
@@ -1029,16 +1171,23 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Materialize and notify a final result that must bypass post-execute.
+   * Materialize the candidate, apply definition-owned content finalization,
+   * then materialize and notify the authoritative result.
    * @param exec - the prepared execution.
    * @param result - final result.
    * @returns the materialized final result.
    * @internal
    */
   private finishScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult {
+    let materializedResult: ToolExecutionResult
+    try {
+      materializedResult = this.materializeFinalResult(result)
+    } catch (error: unknown) {
+      materializedResult = this.materializeFinalResult(toolErrorResult(error))
+    }
     let finalResult: ToolExecutionResult
     try {
-      finalResult = this.materializeFinalResult(result)
+      finalResult = this.materializeFinalResult(this.applyFinalContent(exec, materializedResult))
     } catch (error: unknown) {
       finalResult = this.materializeFinalResult(toolErrorResult(error))
     }
@@ -1046,6 +1195,14 @@ export class ToolRegistry extends Service {
     return finalResult
   }
 
+  /** Apply the snapshotted tool-owned content transform without exposing other result fields. */
+  private applyFinalContent(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult {
+    const finalizeContent = this.contentFinalizers.get(exec)
+    if (finalizeContent === undefined) return result
+    const content = finalizeContent(exec, result)
+    return content === undefined ? result : { ...result, content }
+  }
+
   /** Notify observers without exposing a mutation or error channel into the outcome. */
   private notifyResult(exec: ToolExecution, result: ToolExecutionResult): void {
     // Freeze the registry's live object before observers receive its readonly
@@ -1139,32 +1296,113 @@ export class ToolRegistry extends Service {
     )
     const decisionContexts = decision.additionalContexts ?? []
     if (decision.kind === 'block') {
-      return {
+      const message = failureMessageFromContent(decision.feedback)
+      return this.markCanonical(exec, {
         content: decision.feedback,
         isError: true,
+        error: { message },
         ...decisionContexts.length > 0 ? { additionalContexts: decisionContexts } : {},
-      }
+      })
+    }
+    if (Object.hasOwn(decision, 'content') && Object.hasOwn(decision, 'value')) {
+      throw new TypeError('tools/post-execute accept decision cannot replace both value and content')
     }
-    // Accept: replace content if supplied, preserve the dispatched outcome, and
-    // append decision contexts after contexts deferred by the tool body.
     const additionalContexts = [
       ...result.additionalContexts ?? [],
       ...decisionContexts,
     ]
-    return {
-      ...result,
-      ...decision.content ? { content: decision.content } : {},
-      ...additionalContexts.length > 0 ? { additionalContexts } : {},
+    if (Object.hasOwn(decision, 'value')) {
+      if (result.isError) {
+        throw new TypeError('tools/post-execute cannot replace the value of a failed result')
+      }
+      const tool = this.get(exec.name, exec.agent)
+      if (tool === undefined) throw new ToolNotFoundError(exec.name)
+      const replaced = this.createSuccessResult(exec, tool, decision.value)
+      return this.markCanonical(exec, {
+        ...replaced,
+        ...additionalContexts.length > 0 ? { additionalContexts } : {},
+      })
     }
+    return this.markCanonical(exec, {
+      ...result,
+      ...decision.content !== undefined ? { content: decision.content } : {},
+      ...additionalContexts.length > 0 ? { additionalContexts } : {},
+    })
+  }
+
+  /** Registry-normalized results and the exact dispatch that validated each value. */
+  private readonly canonicalResults = new WeakMap<object, ToolExecutionToken>()
+
+  /** Mark one registry-normalized result as canonical only for its owning dispatch. */
+  private markCanonical<T extends ToolExecutionResult>(exec: ToolExecution, result: T): T {
+    this.canonicalResults.set(result, exec.token)
+    return result
+  }
+
+  /** Snapshot, validate, render, and optionally project one successful body value. */
+  private createSuccessResult(exec: ToolExecution, tool: ToolDefinition, candidate: unknown): ToolExecutionSuccess {
+    const detached = snapshotToolValue(tool.name, candidate)
+    const violations = validateJsonSchemaValue(tool.output.schema, detached, 'value')
+    if (violations.length > 0) throw new ToolOutputError(tool.name, violations)
+    const value = deepFreeze(detached)
+    let rendered: ContentBlock[]
+    try {
+      rendered = tool.output.render(exec.arguments, value)
+    } catch (error: unknown) {
+      throw projectionError(tool.name, 'render', error)
+    }
+    const content = snapshotProjection(tool.name, 'render', rendered)
+    let meta: JsonValue | undefined
+    if (exec.parent === undefined && tool.output.presentationMeta !== undefined) {
+      let projected: JsonValue
+      try {
+        projected = tool.output.presentationMeta(exec.arguments, value)
+      } catch (error: unknown) {
+        throw projectionError(tool.name, 'presentationMeta', error)
+      }
+      meta = snapshotProjection(tool.name, 'presentationMeta', projected)
+    }
+    return this.markCanonical(exec, this.materializeFinalResult({
+      isError: false,
+      value,
+      content,
+      ...meta !== undefined ? { meta } : {},
+    }) as ToolExecutionSuccess)
+  }
+
+  /** Normalize an around-dispatch wrapper's authored result through the owning output contract. */
+  private normalizeDispatchResult(exec: ToolExecution, result: ToolExecutionResult): ToolExecutionResult {
+    if (this.canonicalResults.get(result) === exec.token) return result
+    if (result.isError) {
+      return this.markCanonical(exec, {
+        isError: true,
+        error: result.error,
+        content: result.content,
+        ...result.meta !== undefined ? { meta: result.meta } : {},
+        ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
+      })
+    }
+    const tool = this.get(exec.name, exec.agent)
+    if (tool === undefined) throw new ToolNotFoundError(exec.name)
+    const normalized = this.createSuccessResult(exec, tool, result.value)
+    return this.markCanonical(exec, {
+      ...normalized,
+      ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
+    })
   }
 
   /** Materialize the authoritative commit outcome once, immediately before `tools/result`. */
   private materializeFinalResult(result: ToolExecutionResult): ToolExecutionResult {
-    const detached = snapshotJsonValue(result)
-    if (detached === undefined) {
-      throw new TypeError('tool result must be losslessly JSON-serializable')
+    const presentation = {
+      content: result.content,
+      ...result.meta !== undefined ? { meta: result.meta } : {},
+      ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
     }
-    return deepFreeze(detached)
+    if (result.isError) {
+      return materializePresentation({ isError: true as const, error: result.error, ...presentation })
+    }
+    const detached = materializePresentation({ isError: false as const, ...presentation })
+    return deepFreeze({ ...detached, value: result.value })
   }
 }
 
@@ -1175,10 +1413,11 @@ function createExecutionToken(): ToolExecutionToken {
 
 function toolErrorResult(error: unknown): ToolExecutionResult {
   const info = errorInfo(error)
+  const message = errorMessage(error)
   return {
-    content: [{ type: 'text', text: `Error: ${errorMessage(error)}` }],
+    content: [{ type: 'text', text: `Error: ${message}` }],
     isError: true,
-    ...info ? { error: info } : {},
+    error: { message, ...info ? { info } : {} },
   }
 }
 
@@ -1226,7 +1465,10 @@ function toolAbortedResult(prior?: ToolExecutionResult): ToolExecutionResult {
   return {
     content: [{ type: 'text', text: 'Error: tool call aborted' }],
     isError: true,
-    error: { name: 'AbortError', code: TOOL_ABORTED },
+    error: {
+      message: 'tool call aborted',
+      info: { name: 'AbortError', code: TOOL_ABORTED },
+    },
     ...additionalContexts.length > 0 ? { additionalContexts } : {},
   }
 }
@@ -1237,7 +1479,10 @@ function toolAbortedBeforeDispatchResult(prior?: ToolExecutionResult): ToolExecu
   return {
     content: [{ type: 'text', text: 'Error: tool call aborted before dispatch' }],
     isError: true,
-    error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    error: {
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    },
     ...additionalContexts.length > 0 ? { additionalContexts } : {},
   }
 }
diff --git a/packages/core/tools/src/json-schema.ts b/packages/core/tools/src/json-schema.ts
index e1a0dc43a6..9b6ca88d93 100644
--- a/packages/core/tools/src/json-schema.ts
+++ b/packages/core/tools/src/json-schema.ts
@@ -1,323 +1,656 @@
 /**
- * Structured-output JSON Schema subset for subagents and workflows. It supports
- * one scalar `type`; object `properties`/`required`/boolean
- * `additionalProperties`; array `items`; scalar `enum`/`const`; and JSON-valued
- * annotations. Unsupported or misplaced keywords reject rather than being
- * accepted without enforcement, and structured-output roots must be objects.
+ * Enforced JSON Schema subset shared by tool outputs, generated Code Mode
+ * types, subagents, and workflows. The subset accepts any JSON root, an
+ * annotation-only schema for unconstrained JSON, one scalar `type`, object
+ * `properties`/`required`/boolean `additionalProperties`, array `items`,
+ * type-correct scalar `enum`/`const`, and exact-one `oneOf`.
+ *
+ * Unsupported or misplaced keywords reject rather than being accepted without
+ * enforcement. Consumers that require an object root apply
+ * {@link assertObjectJsonSchema} at their own boundary.
  * @module dsh-tools/json-schema
  */
 
 import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm'
+import { isJsonValue, type JsonValue } from '@deepseek-ai/dsh-session'
 
-/** The scalar values `enum`/`const` may carry (finite numbers only). */
-export type StructuredScalar = string | number | boolean | null
+/** Scalar JSON values supported by `enum` and `const`. */
+export type JsonSchemaScalar = string | number | boolean | null
 
-/** The `type` keywords the subset accepts. */
-export type StructuredSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+/** Single-type keywords accepted by the enforced subset. */
+export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+
+/** Scalar-only schema types accepted by literal constraints. */
+type JsonSchemaScalarType = Exclude<JsonSchemaType, 'object' | 'array'>
 
 /**
- * One node of the structured-output schema subset. Recursive via `properties`
- * and `items`; see the module doc for the exact keyword semantics.
+ * One raw JSON Schema node in the enforced subset. The optional fields express
+ * the external wire shape; {@link assertSupportedJsonSchema} rejects invalid
+ * combinations before a caller treats the node as trusted.
  */
-export interface StructuredSchemaNode {
-  type: StructuredSchemaType
+export interface JsonSchemaNode {
+  /** Omit with no constraints for any JSON value, or use `oneOf`. */
+  type?: JsonSchemaType
+  /** Exactly one branch must validate; at least two branches are required. */
+  oneOf?: JsonSchemaNode[]
   /** Nested property schemas (`type: 'object'` only). */
-  properties?: Record<string, StructuredSchemaNode>
+  properties?: Record<string, JsonSchemaNode>
   /** Required property names; each must appear in `properties`. */
   required?: string[]
-  /** `false` rejects undeclared keys; absent/`true` allows them (JSON Schema default). */
+  /** `false` rejects undeclared keys; absent/`true` follows JSON Schema's open default. */
   additionalProperties?: boolean
-  /** Item schema (`type: 'array'` only); absent ⇒ any JSON items. */
-  items?: StructuredSchemaNode
-  /** Allowed values (scalar types only). */
-  enum?: StructuredScalar[]
-  /** The single allowed value (scalar types only). */
-  const?: StructuredScalar
+  /** Item schema (`type: 'array'` only); absent accepts any JSON item. */
+  items?: JsonSchemaNode
+  /** Allowed values for a scalar node. */
+  enum?: JsonSchemaScalar[]
+  /** The single allowed value for a scalar node. */
+  const?: JsonSchemaScalar
   /** Annotation, ignored for validation. */
   description?: string
   /** Annotation, ignored for validation. */
   title?: string
-  /** Annotation, ignored for validation (must still be JSON data). */
-  default?: unknown
-  /** Annotation, ignored for validation (must still be JSON data). */
-  examples?: unknown
+  /** Annotation, ignored for validation but required to be lossless JSON. */
+  default?: JsonValue
+  /** Annotation, ignored for validation but required to be lossless JSON. */
+  examples?: JsonValue
 }
 
-/** A structured-output schema: an OBJECT-rooted {@link StructuredSchemaNode}. */
-export type StructuredOutputSchema = StructuredSchemaNode & { type: 'object' }
+/** A consumer-constrained object-rooted schema. */
+export type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 
 /**
- * Thrown by {@link assertSupportedOutputSchema} when a schema falls outside the
- * supported subset. Extends {@link HarnessError} (`code: 'UNSUPPORTED_SCHEMA'`)
- * so seam code and tool results can route on it; `violations` lists every
- * offending path, not just the first.
+ * Thrown when a raw schema falls outside the enforced subset. `violations`
+ * lists every offending path instead of stopping at the first author error.
  */
-export class OutputSchemaError extends HarnessError {
-  /** The individual violation messages, in walk order. */
+export class JsonSchemaError extends HarnessError {
+  /** Individual schema violations in walk order. */
   readonly violations: string[]
 
   constructor(violations: string[]) {
-    super(`unsupported output schema: ${violations.join('; ')}`, 'UNSUPPORTED_SCHEMA')
-    this.name = 'OutputSchemaError'
+    super(`unsupported JSON schema: ${violations.join('; ')}`, 'UNSUPPORTED_SCHEMA')
+    this.name = 'JsonSchemaError'
     this.violations = violations
   }
 }
 
-/** The keywords the subset accepts, checked (`constraint`) or ignored (`annotation`). */
-const CONSTRAINT_KEYWORDS = new Set(['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const'])
+const CONSTRAINT_KEYWORDS = new Set([
+  'type',
+  'oneOf',
+  'properties',
+  'required',
+  'additionalProperties',
+  'items',
+  'enum',
+  'const',
+])
 const ANNOTATION_KEYWORDS = new Set(['description', 'title', 'default', 'examples'])
+const SCHEMA_TYPES: readonly JsonSchemaType[] = ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']
 
-const SCHEMA_TYPES: readonly StructuredSchemaType[] = ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']
-
-/**
- * Whether a value is a PLAIN JSON object — non-null, non-array, and with a
- * prototype chain of at most one link (`null`-proto, or any realm's
- * `Object.prototype`, whose own prototype is `null`). Realm-agnostic on
- * purpose: a schema materialized in another realm carries THAT realm's
- * `Object.prototype`, which an identity check would wrongly reject. Exotic
- * hosts (`Date`, `Map`, class instances) have longer chains and are rejected —
- * they would serialize lossily (`Date` → string, `Map` → `{}`) instead of
- * failing loud.
- */
-function isObjectLike(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
-  const proto: unknown = Object.getPrototypeOf(value)
-  return proto === null || Object.getPrototypeOf(proto) === null
-}
-
-/** Whether a value is a supported scalar (`enum`/`const` member): string, finite number, boolean, or null. */
-function isStructuredScalar(value: unknown): value is StructuredScalar {
-  return value === null || typeof value === 'string' || typeof value === 'boolean'
-    || (typeof value === 'number' && Number.isFinite(value))
-}
-
-/**
- * Whether a value is JSON data (annotation payloads only): scalars, arrays, and
- * object-likes of such values. Realm-agnostic on purpose (no prototype check) —
- * the schema may have been materialized from another realm; structural JSON-ness
- * is what the wire needs. Cycles are rejected via `seen`.
- */
-function isJsonData(value: unknown, seen: Set<object>): boolean {
-  if (isStructuredScalar(value)) return true
-  // The scalar check above already returned for null, so `object` here is a real object.
-  if (typeof value !== 'object') return false
-  if (seen.has(value)) return false
-  seen.add(value)
+/* jscpd:ignore-start -- this realm boundary mirrors the session-owned lossless-JSON intrinsic test */
+/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
+function hasIntrinsicConstructor(prototype: object, name: 'Array' | 'Object'): boolean {
+  const descriptor = Object.getOwnPropertyDescriptor(prototype, 'constructor')
+  const constructor: unknown = descriptor?.value
+  if (typeof constructor !== 'function') return false
   try {
-    if (Array.isArray(value)) return value.every(entry => isJsonData(entry, seen))
-    // A non-plain object (Date, Map, class instance) is NOT JSON data even when
-    // it has no enumerable values — it would serialize lossily, not loudly.
-    if (!isObjectLike(value)) return false
-    return Object.values(value).every(entry => isJsonData(entry, seen))
-  } finally {
-    seen.delete(value)
+    return constructor.name === name
+      && constructor.prototype === prototype
+      && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`
+  } catch {
+    return false
   }
 }
 
-/** Collect subset violations for one schema node (recursive walk). */
-function checkSchemaNode(node: unknown, path: string, violations: string[], seen: Set<object>): void {
-  if (!isObjectLike(node)) {
-    violations.push(`${path} must be a schema object`)
-    return
-  }
-  if (seen.has(node)) {
-    violations.push(`${path} is circular`)
-    return
-  }
-  seen.add(node)
+/** Whether a candidate is one realm's intrinsic `Object.prototype`. */
+function isIntrinsicObjectPrototype(value: object): boolean {
+  return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, 'Object')
+}
 
-  for (const key of Object.keys(node)) {
-    if (CONSTRAINT_KEYWORDS.has(key)) continue
-    if (ANNOTATION_KEYWORDS.has(key)) {
-      if (!isJsonData(node[key], new Set())) violations.push(`${path}.${key} annotation must be JSON data`)
+/**
+ * Test for a realm-agnostic plain JSON record without accepting arrays or
+ * exotic objects.
+ * @param value - candidate record from any JavaScript realm.
+ * @returns Whether the value has a plain-object prototype chain.
+ */
+export function isPlainJsonRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  try {
+    const prototype: unknown = Object.getPrototypeOf(value)
+    return prototype === null
+      || typeof prototype === 'object' && isIntrinsicObjectPrototype(prototype)
+  } catch {
+    return false
+  }
+}
+
+/** Whether an array uses one realm's intrinsic `Array.prototype`. */
+function hasPlainArrayPrototype(value: unknown[]): boolean {
+  const prototype: unknown = Object.getPrototypeOf(value)
+  if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, 'Array')) return false
+  const objectPrototype: unknown = Object.getPrototypeOf(prototype)
+  return typeof objectPrototype === 'object'
+    && objectPrototype !== null
+    && isIntrinsicObjectPrototype(objectPrototype)
+}
+/* jscpd:ignore-end */
+
+/** Return whether a record contains only own enumerable string keys. */
+function hasOnlyEnumerableStringKeys(value: object): boolean {
+  try {
+    return Reflect.ownKeys(value)
+      .every(key => typeof key === 'string' && Object.prototype.propertyIsEnumerable.call(value, key))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Test for an ordinary schema record whose keys survive JSON projection.
+ * @param value - candidate record from any JavaScript realm.
+ * @returns Whether the record has an intrinsic prototype and only own enumerable string keys.
+ */
+export function isJsonSchemaRecord(value: unknown): value is Record<string, unknown> {
+  return isPlainJsonRecord(value) && hasOnlyEnumerableStringKeys(value)
+}
+
+/**
+ * Test for a dense ordinary array with no JSON-invisible decorations.
+ * @param value - candidate array from any JavaScript realm.
+ * @returns Whether the array is intrinsic, dense, and undecorated.
+ */
+export function isPlainJsonArray(value: unknown): value is unknown[] {
+  if (!Array.isArray(value)) return false
+  try {
+    if (!hasPlainArrayPrototype(value) || Reflect.ownKeys(value).length !== value.length + 1) return false
+    for (let index = 0; index < value.length; index++) {
+      if (!Object.hasOwn(value, index)) return false
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Lossless finite JSON number, excluding negative zero. */
+function isJsonNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)
+}
+
+/** Whether a scalar is valid for one declared schema type. */
+function scalarMatches(type: JsonSchemaScalarType, value: unknown): value is JsonSchemaScalar {
+  switch (type) {
+    case 'string': return typeof value === 'string'
+    case 'number': return isJsonNumber(value)
+    case 'integer': return isJsonNumber(value) && Number.isInteger(value)
+    case 'boolean': return typeof value === 'boolean'
+    case 'null': return value === null
+    /* v8 ignore next -- JsonSchemaScalarType is closed; this retains compile-time exhaustiveness. */
+    default: return assertNever(type, 'JsonSchemaType')
+  }
+}
+
+/** Deferred work for the stack-safe raw-schema walk. */
+type SchemaWalkTask =
+  | { kind: 'enter'; node: unknown; path: string }
+  | { kind: 'leave'; node: object }
+  | { kind: 'one-of-tail'; node: Record<string, unknown>; path: string }
+  | { kind: 'object-tail'; node: Record<string, unknown>; path: string; properties: unknown }
+
+/** Keywords that are invalid beside `oneOf`. */
+const ONE_OF_SIBLING_KEYWORDS = ['properties', 'required', 'additionalProperties', 'items', 'enum', 'const'] as const
+
+/** Validate object-only fields after its property schemas have been visited. */
+function checkObjectSchemaTail(
+  node: Record<string, unknown>,
+  path: string,
+  properties: unknown,
+  violations: string[],
+): void {
+  const hasRequired = Object.hasOwn(node, 'required')
+  const required = hasRequired ? node.required : undefined
+  if (hasRequired) {
+    if (!isPlainJsonArray(required) || required.some(entry => typeof entry !== 'string')) {
+      violations.push(`${path}.required must be an array of strings`)
+    } else {
+      const declared = isJsonSchemaRecord(properties) ? properties : {}
+      for (const key of required as string[]) {
+        if (!Object.hasOwn(declared, key)) violations.push(`${path}.required names "${key}" which is not in properties`)
+      }
+    }
+  }
+  if (Object.hasOwn(node, 'additionalProperties') && typeof node.additionalProperties !== 'boolean') {
+    violations.push(`${path}.additionalProperties must be a boolean`)
+  }
+}
+
+/** Collect every violation for one raw schema tree without using the JavaScript call stack. */
+function checkSchemaNode(root: unknown, rootPath: string, violations: string[], seen: Set<object>): void {
+  const tasks: SchemaWalkTask[] = [{ kind: 'enter', node: root, path: rootPath }]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      seen.delete(task.node)
       continue
     }
-    violations.push(`${path}.${key} is not a supported keyword (subset: type/properties/required/additionalProperties/items/enum/const + annotations)`)
-  }
-  if (typeof node.description !== 'undefined' && typeof node.description !== 'string') {
-    violations.push(`${path}.description must be a string`)
-  }
-  if (typeof node.title !== 'undefined' && typeof node.title !== 'string') {
-    violations.push(`${path}.title must be a string`)
-  }
-
-  const type = node.type
-  if (typeof type !== 'string' || !(SCHEMA_TYPES as readonly unknown[]).includes(type)) {
-    violations.push(Array.isArray(type)
-      ? `${path}.type must be a single type string (type arrays are not supported)`
-      : `${path}.type must be one of ${SCHEMA_TYPES.join('/')}`)
-    seen.delete(node)
-    return
-  }
-  const schemaType = type as StructuredSchemaType
-
-  // Keywords that only make sense on one type are rejected elsewhere — an
-  // `items` on an object (or `properties` on a string) is a schema-author bug
-  // the subset surfaces rather than ignores.
-  const allowedFor: Record<string, StructuredSchemaType[]> = {
-    properties: ['object'],
-    required: ['object'],
-    additionalProperties: ['object'],
-    items: ['array'],
-    enum: ['string', 'number', 'integer', 'boolean', 'null'],
-    const: ['string', 'number', 'integer', 'boolean', 'null'],
-  }
-  for (const [key, types] of Object.entries(allowedFor)) {
-    if (key in node && !types.includes(schemaType)) {
-      violations.push(`${path}.${key} is not supported on type "${schemaType}"`)
+    if (task.kind === 'one-of-tail') {
+      for (const key of ONE_OF_SIBLING_KEYWORDS) {
+        if (Object.hasOwn(task.node, key)) violations.push(`${task.path}.${key} is not supported beside oneOf`)
+      }
+      continue
+    }
+    if (task.kind === 'object-tail') {
+      checkObjectSchemaTail(task.node, task.path, task.properties, violations)
+      continue
     }
-  }
 
-  switch (schemaType) {
-    case 'object': {
-      const properties = node.properties
-      if (properties !== undefined) {
-        if (!isObjectLike(properties)) {
-          violations.push(`${path}.properties must be an object of schemas`)
-        } else {
-          for (const [key, child] of Object.entries(properties)) {
-            checkSchemaNode(child, `${path}.properties.${key}`, violations, seen)
+    const { node, path } = task
+    if (!isJsonSchemaRecord(node)) {
+      violations.push(`${path} must be a schema object`)
+      continue
+    }
+    if (seen.has(node)) {
+      violations.push(`${path} is circular`)
+      continue
+    }
+    seen.add(node)
+    tasks.push({ kind: 'leave', node })
+
+    for (const key of Object.keys(node)) {
+      if (CONSTRAINT_KEYWORDS.has(key)) continue
+      if (ANNOTATION_KEYWORDS.has(key)) {
+        try {
+          if (!isJsonValue(node[key])) violations.push(`${path}.${key} annotation must be lossless JSON data`)
+        } catch {
+          violations.push(`${path}.${key} annotation must be lossless JSON data`)
+        }
+        continue
+      }
+      violations.push(`${path}.${key} is not a supported keyword (subset: type/oneOf/properties/required/additionalProperties/items/enum/const + annotations)`)
+    }
+    if (Object.hasOwn(node, 'description') && typeof node.description !== 'string') {
+      violations.push(`${path}.description must be a string`)
+    }
+    if (Object.hasOwn(node, 'title') && typeof node.title !== 'string') {
+      violations.push(`${path}.title must be a string`)
+    }
+
+    const hasType = Object.hasOwn(node, 'type')
+    const hasOneOf = Object.hasOwn(node, 'oneOf')
+    if (hasType && hasOneOf) {
+      violations.push(`${path} cannot declare both type and oneOf`)
+      continue
+    }
+    if (!hasType && !hasOneOf) {
+      for (const key of ONE_OF_SIBLING_KEYWORDS) {
+        if (Object.hasOwn(node, key)) violations.push(`${path}.${key} requires type or oneOf`)
+      }
+      continue
+    }
+
+    if (hasOneOf) {
+      const oneOf = node.oneOf
+      tasks.push({ kind: 'one-of-tail', node, path })
+      if (!isPlainJsonArray(oneOf) || oneOf.length < 2) {
+        violations.push(`${path}.oneOf must be an array of at least two schemas`)
+      } else {
+        for (let index = oneOf.length - 1; index >= 0; index--) {
+          tasks.push({ kind: 'enter', node: oneOf[index], path: `${path}.oneOf[${index}]` })
+        }
+      }
+      continue
+    }
+
+    const type = node.type
+    if (typeof type !== 'string' || !(SCHEMA_TYPES as readonly unknown[]).includes(type)) {
+      violations.push(Array.isArray(type)
+        ? `${path}.type must be a single type string (type arrays are not supported)`
+        : `${path}.type must be one of ${SCHEMA_TYPES.join('/')}`)
+      continue
+    }
+    const schemaType = type as JsonSchemaType
+    const allowedFor: Record<string, JsonSchemaType[]> = {
+      properties: ['object'],
+      required: ['object'],
+      additionalProperties: ['object'],
+      items: ['array'],
+      enum: ['string', 'number', 'integer', 'boolean', 'null'],
+      const: ['string', 'number', 'integer', 'boolean', 'null'],
+    }
+    for (const [key, types] of Object.entries(allowedFor)) {
+      if (Object.hasOwn(node, key) && !types.includes(schemaType)) {
+        violations.push(`${path}.${key} is not supported on type "${schemaType}"`)
+      }
+    }
+
+    switch (schemaType) {
+      case 'object': {
+        const properties = Object.hasOwn(node, 'properties') ? node.properties : undefined
+        tasks.push({ kind: 'object-tail', node, path, properties })
+        if (Object.hasOwn(node, 'properties')) {
+          if (!isJsonSchemaRecord(properties)) {
+            violations.push(`${path}.properties must be an object of schemas`)
+          } else {
+            const entries = Object.entries(properties)
+            for (let index = entries.length - 1; index >= 0; index--) {
+              const entry = entries[index]
+              /* v8 ignore next -- the loop is bounded by the captured entry count. */
+              if (entry === undefined) continue
+              tasks.push({ kind: 'enter', node: entry[1], path: `${path}.properties.${entry[0]}` })
+            }
           }
         }
+        break
       }
-      const required = node.required
-      if (required !== undefined) {
-        if (!Array.isArray(required) || required.some(entry => typeof entry !== 'string')) {
-          violations.push(`${path}.required must be an array of strings`)
-        } else {
-          const declared = isObjectLike(properties) ? properties : {}
-          // The guard above proved every entry is a string.
-          for (const key of required as string[]) {
-            // Own-property check: `in` would let inherited names (`toString`)
-            // satisfy the declared-in-properties contract via the prototype.
-            if (!Object.hasOwn(declared, key)) violations.push(`${path}.required names "${key}" which is not in properties`)
+      case 'array': {
+        if (Object.hasOwn(node, 'items')) tasks.push({ kind: 'enter', node: node.items, path: `${path}.items` })
+        break
+      }
+      case 'string':
+      case 'number':
+      case 'integer':
+      case 'boolean':
+      case 'null': {
+        const hasEnum = Object.hasOwn(node, 'enum')
+        const allowed = hasEnum ? node.enum : undefined
+        const enumValid = isPlainJsonArray(allowed)
+          && allowed.length > 0
+          && allowed.every(entry => scalarMatches(schemaType, entry))
+        if (hasEnum && !enumValid) {
+          violations.push(`${path}.enum must be a non-empty array of ${schemaType} values`)
+        }
+        const hasConst = Object.hasOwn(node, 'const')
+        const declaredConst = hasConst ? node.const : undefined
+        const constValid = scalarMatches(schemaType, declaredConst)
+        if (hasConst) {
+          if (!constValid) {
+            violations.push(`${path}.const must be a ${schemaType} value`)
+          } else if (enumValid && !allowed.includes(declaredConst)) {
+            violations.push(`${path}.const must be one of ${path}.enum when both are declared`)
           }
         }
+        break
       }
-      if (node.additionalProperties !== undefined && typeof node.additionalProperties !== 'boolean') {
-        violations.push(`${path}.additionalProperties must be a boolean`)
-      }
-      break
+      /* v8 ignore next -- schemaType was narrowed from the closed SCHEMA_TYPES table above. */
+      default: assertNever(schemaType, 'JsonSchemaType')
     }
-    case 'array': {
-      if (node.items !== undefined) checkSchemaNode(node.items, `${path}.items`, violations, seen)
-      break
-    }
-    case 'string':
-    case 'number':
-    case 'integer':
-    case 'boolean':
-    case 'null': {
-      const allowed = node.enum
-      if (allowed !== undefined) {
-        if (!Array.isArray(allowed) || allowed.length === 0 || !allowed.every(entry => isStructuredScalar(entry))) {
-          violations.push(`${path}.enum must be a non-empty array of scalars`)
-        }
-      }
-      if ('const' in node && !isStructuredScalar(node.const)) {
-        violations.push(`${path}.const must be a scalar`)
-      }
-      break
-    }
-    /* v8 ignore start -- defensive: schemaType was membership-checked against SCHEMA_TYPES above, so no runtime value reaches here */
-    default:
-      assertNever(schemaType, 'assertSupportedOutputSchema')
-    /* v8 ignore stop */
   }
-
-  seen.delete(node)
 }
 
 /**
- * Assert `schema` is a supported {@link StructuredOutputSchema} — object-rooted
- * and entirely within the enforced subset. Throws {@link OutputSchemaError}
- * (`UNSUPPORTED_SCHEMA`) listing EVERY violation; returns (and narrows) on
- * success. Call this at the seam boundary, before any child is created.
- * @param schema - the caller-supplied schema (unknown until asserted).
- * @returns nothing — the assertion signature narrows `schema` to
- * {@link StructuredOutputSchema} in the caller's scope on normal return.
+ * Assert that an arbitrary raw schema uses only the enforced subset.
+ * Annotation-only schemas are accepted as the standard unconstrained-JSON
+ * form; callers that require an object root use {@link assertObjectJsonSchema}.
+ * @param schema - untrusted raw JSON Schema.
+ * @returns Assertion that the schema belongs to the supported subset.
  */
-export function assertSupportedOutputSchema(schema: unknown): asserts schema is StructuredOutputSchema {
+export function assertSupportedJsonSchema(schema: unknown): asserts schema is JsonSchemaNode {
   const violations: string[] = []
   checkSchemaNode(schema, 'schema', violations, new Set())
-  if (violations.length === 0 && (schema as StructuredSchemaNode).type !== 'object') {
-    violations.push('schema.type must be "object" (structured output is object-rooted)')
-  }
-  if (violations.length > 0) throw new OutputSchemaError(violations)
+  if (violations.length > 0) throw new JsonSchemaError(violations)
 }
 
-/** Collect violations for one value against an (already asserted) schema node. */
-function checkValue(node: StructuredSchemaNode, value: unknown, path: string): string[] {
-  switch (node.type) {
-    case 'object': {
-      if (!isObjectLike(value)) return [`"${path}" must be an object`]
-      const violations: string[] = []
-      const properties = node.properties ?? {}
-      // Own-property discipline throughout: JSON carries own enumerable
-      // properties only, so an inherited `toString` must not satisfy
-      // `required`, dodge `additionalProperties: false`, or be validated as if
-      // the value carried it.
-      for (const key of node.required ?? []) {
-        if (!Object.hasOwn(value, key) || value[key] === undefined) violations.push(`missing required property "${path}.${key}"`)
-      }
-      for (const [key, child] of Object.entries(properties)) {
-        if (!Object.hasOwn(value, key) || value[key] === undefined) continue
-        violations.push(...checkValue(child, value[key], `${path}.${key}`))
-      }
-      if (node.additionalProperties === false) {
-        for (const key of Object.keys(value)) {
-          if (!Object.hasOwn(properties, key)) violations.push(`"${path}.${key}" is not a declared property (additionalProperties: false)`)
-        }
-      }
-      return violations
-    }
-    case 'array': {
-      if (!Array.isArray(value)) return [`"${path}" must be an array`]
-      if (!node.items) return []
-      const items = node.items
-      return value.flatMap((entry, index) => checkValue(items, entry, `${path}[${index}]`))
-    }
-    case 'string': {
-      if (typeof value !== 'string') return [`"${path}" must be a string`]
-      break
-    }
-    case 'number': {
-      if (typeof value !== 'number' || !Number.isFinite(value)) return [`"${path}" must be a finite number`]
-      break
-    }
-    case 'integer': {
-      if (typeof value !== 'number' || !Number.isInteger(value)) return [`"${path}" must be an integer`]
-      break
-    }
-    case 'boolean': {
-      if (typeof value !== 'boolean') return [`"${path}" must be a boolean`]
-      break
-    }
-    case 'null': {
-      if (value !== null) return [`"${path}" must be null`]
-      break
-    }
-    default:
-      return assertNever(node.type, 'validateStructuredValue')
+/**
+ * Assert the enforced subset plus the object-root constraint retained by
+ * subagent and workflow structured outputs.
+ * @param schema - untrusted caller-supplied schema.
+ * @returns Assertion that the schema belongs to the supported subset and has an object root.
+ */
+export function assertObjectJsonSchema(schema: unknown): asserts schema is ObjectJsonSchema {
+  const violations: string[] = []
+  checkSchemaNode(schema, 'schema', violations, new Set())
+  if (violations.length === 0
+    && (!isJsonSchemaRecord(schema) || !Object.hasOwn(schema, 'type') || schema.type !== 'object')) {
+    violations.push('schema.type must be "object" (structured output is object-rooted)')
   }
-  // Scalar constraint checks, shared by every scalar branch above.
-  if (node.enum && !node.enum.includes(value)) {
-    return [`"${path}" must be one of ${JSON.stringify(node.enum)}`]
+  if (violations.length > 0) throw new JsonSchemaError(violations)
+}
+
+/** Safely test the lossless JSON boundary when a getter may throw. */
+function safelyIsJsonValue(value: unknown): boolean {
+  try {
+    return isJsonValue(value)
+  } catch {
+    return false
   }
-  if ('const' in node && value !== node.const) {
-    return [`"${path}" must be ${JSON.stringify(node.const)}`]
+}
+
+/** Root-aware diagnostic path for the parameter validator's empty sentinel. */
+function diagnosticPath(path: string): string {
+  return path === '' ? 'arguments' : path
+}
+
+/** Append one object property without a leading dot at an implicit root. */
+function propertyPath(path: string, key: string): string {
+  return path === '' ? key : `${path}.${key}`
+}
+
+/** One child evaluation deferred by a container or exact-one union frame. */
+interface ValueChild {
+  readonly node: JsonSchemaNode
+  readonly value: unknown
+  readonly path: string
+}
+
+/** Explicit call frame for stack-safe schema-value validation. */
+interface ValueFrame {
+  readonly node: JsonSchemaNode
+  readonly value: unknown
+  readonly path: string
+  catches: boolean
+  phase: 'start' | 'children'
+  kind?: 'oneOf' | 'object' | 'array'
+  children: ValueChild[]
+  childIndex: number
+  violations: string[]
+  tailViolations: string[]
+  matches: number
+}
+
+/** The generic exception-containment diagnostic owned by one valid schema node. */
+function losslessValueViolation(path: string): string[] {
+  return [`"${diagnosticPath(path)}" must be a lossless JSON value`]
+}
+
+/** Append diagnostics without spreading a potentially wide child result as call arguments. */
+function appendViolations(target: string[], source: readonly string[]): void {
+  for (const violation of source) target.push(violation)
+}
+
+/** Initialize one validation frame with empty aggregation state. */
+function valueFrame(node: JsonSchemaNode, value: unknown, path: string): ValueFrame {
+  return {
+    node,
+    value,
+    path,
+    catches: false,
+    phase: 'start',
+    children: [],
+    childIndex: 0,
+    violations: [],
+    tailViolations: [],
+    matches: 0,
+  }
+}
+
+/** Validate one scalar node after its primitive type check. */
+function checkScalarValue(node: JsonSchemaNode, value: unknown, path: string): string[] {
+  const allowed = Object.hasOwn(node, 'enum') ? node.enum : undefined
+  if (allowed !== undefined && !allowed.includes(value as JsonSchemaScalar)) {
+    return [`"${diagnosticPath(path)}" must be one of ${JSON.stringify(allowed)}`]
+  }
+  if (Object.hasOwn(node, 'const') && value !== node.const) {
+    return [`"${diagnosticPath(path)}" must be ${JSON.stringify(node.const)}`]
   }
   return []
 }
 
-/**
- * Validate a value against an (already {@link assertSupportedOutputSchema}-
- * asserted) schema. Returns human-readable, path-qualified violation messages
- * — empty means valid. Total: never throws, however malformed the value.
- * @param schema - the asserted schema to check against.
- * @param value - the candidate value (e.g. parsed tool-call arguments).
- * @returns every violation found, in walk order (empty = valid).
- */
-export function validateStructuredValue(schema: StructuredOutputSchema, value: unknown): string[] {
-  return checkValue(schema, value, 'value')
+/** Validate one trusted schema/value pair with explicit frames rather than recursive calls. */
+function checkValue(schema: JsonSchemaNode, value: unknown, path: string): string[] {
+  const frames: ValueFrame[] = [valueFrame(schema, value, path)]
+  let rootResult: string[] | undefined
+
+  const receive = (result: string[]): void => {
+    const parent = frames.at(-1)
+    if (parent === undefined) {
+      rootResult = result
+      return
+    }
+    if (parent.kind === 'oneOf') {
+      if (result.length === 0) parent.matches++
+    } else {
+      appendViolations(parent.violations, result)
+    }
+  }
+  const finish = (result: string[]): void => {
+    frames.pop()
+    receive(result)
+  }
+
+  while (frames.length > 0) {
+    const frame = frames.at(-1)
+    /* v8 ignore next -- the loop condition guarantees a current frame. */
+    if (frame === undefined) break
+    try {
+      if (frame.phase === 'children') {
+        if (frame.childIndex < frame.children.length) {
+          const child = frame.children[frame.childIndex]
+          /* v8 ignore next -- childIndex is bounded by children.length. */
+          if (child === undefined) throw new Error('missing schema-value child frame')
+          frame.childIndex++
+          frames.push(valueFrame(child.node, child.value, child.path))
+          continue
+        }
+        if (frame.kind === 'oneOf') {
+          finish(frame.matches === 1 ? [] : [`"${diagnosticPath(frame.path)}" must match exactly one oneOf branch (matched ${frame.matches})`])
+          continue
+        }
+        appendViolations(frame.violations, frame.tailViolations)
+        if (frame.violations.length > 0) {
+          finish(frame.violations)
+        } else if (frame.kind === 'object') {
+          finish(safelyIsJsonValue(frame.value) ? [] : [`"${diagnosticPath(frame.path)}" must be a lossless JSON object`])
+        } else {
+          finish(safelyIsJsonValue(frame.value) ? [] : [`"${diagnosticPath(frame.path)}" must be a dense lossless JSON array`])
+        }
+        continue
+      }
+
+      const nodeType = Object.hasOwn(frame.node, 'type') ? frame.node.type : undefined
+      frame.catches = !(nodeType !== undefined && !(SCHEMA_TYPES as readonly unknown[]).includes(nodeType))
+      const oneOf = Object.hasOwn(frame.node, 'oneOf') ? frame.node.oneOf : undefined
+      if (oneOf !== undefined) {
+        frame.kind = 'oneOf'
+        frame.children = Array.from(oneOf, branch => ({ node: branch, value: frame.value, path: frame.path }))
+        frame.childIndex = 0
+        frame.matches = 0
+        frame.phase = 'children'
+        continue
+      }
+      if (nodeType === undefined) {
+        finish(safelyIsJsonValue(frame.value) ? [] : losslessValueViolation(frame.path))
+        continue
+      }
+
+      switch (nodeType) {
+        case 'object': {
+          if (!isPlainJsonRecord(frame.value)) {
+            finish([`"${diagnosticPath(frame.path)}" must be an object`])
+            break
+          }
+          const properties = Object.hasOwn(frame.node, 'properties') ? frame.node.properties ?? {} : {}
+          const violations: string[] = []
+          const required = Object.hasOwn(frame.node, 'required') ? frame.node.required ?? [] : []
+          for (const key of required) {
+            if (!Object.hasOwn(frame.value, key) || frame.value[key] === undefined) {
+              violations.push(`missing required property "${propertyPath(frame.path, key)}"`)
+            }
+          }
+          const children: ValueChild[] = []
+          for (const [key, child] of Object.entries(properties)) {
+            if (!Object.hasOwn(frame.value, key) || frame.value[key] === undefined) continue
+            children.push({ node: child, value: frame.value[key], path: propertyPath(frame.path, key) })
+          }
+          const tailViolations: string[] = []
+          if (Object.hasOwn(frame.node, 'additionalProperties') && frame.node.additionalProperties === false) {
+            for (const key of Object.keys(frame.value)) {
+              if (!Object.hasOwn(properties, key)) {
+                tailViolations.push(`"${propertyPath(frame.path, key)}" is not a declared property (additionalProperties: false)`)
+              }
+            }
+          }
+          frame.kind = 'object'
+          frame.children = children
+          frame.childIndex = 0
+          frame.violations = violations
+          frame.tailViolations = tailViolations
+          frame.phase = 'children'
+          break
+        }
+        case 'array': {
+          if (!Array.isArray(frame.value)) {
+            finish([`"${diagnosticPath(frame.path)}" must be an array`])
+            break
+          }
+          const items = Object.hasOwn(frame.node, 'items') ? frame.node.items : undefined
+          const children = items === undefined
+            ? []
+            : frame.value.flatMap((entry, index): ValueChild[] => [{ node: items, value: entry, path: `${frame.path}[${index}]` }])
+          frame.kind = 'array'
+          frame.children = children
+          frame.childIndex = 0
+          frame.violations = []
+          frame.phase = 'children'
+          break
+        }
+        case 'string':
+          finish(typeof frame.value === 'string'
+            ? checkScalarValue(frame.node, frame.value, frame.path)
+            : [`"${diagnosticPath(frame.path)}" must be a string`])
+          break
+        case 'number':
+          finish(typeof frame.value !== 'number'
+            ? [`"${diagnosticPath(frame.path)}" must be a number`]
+            : !isJsonNumber(frame.value)
+              ? [`"${diagnosticPath(frame.path)}" must be a finite JSON number`]
+              : checkScalarValue(frame.node, frame.value, frame.path))
+          break
+        case 'integer':
+          finish(!isJsonNumber(frame.value) || !Number.isInteger(frame.value)
+            ? [`"${diagnosticPath(frame.path)}" must be an integer`]
+            : checkScalarValue(frame.node, frame.value, frame.path))
+          break
+        case 'boolean':
+          finish(typeof frame.value === 'boolean'
+            ? checkScalarValue(frame.node, frame.value, frame.path)
+            : [`"${diagnosticPath(frame.path)}" must be a boolean`])
+          break
+        case 'null':
+          finish(frame.value === null
+            ? checkScalarValue(frame.node, frame.value, frame.path)
+            : [`"${diagnosticPath(frame.path)}" must be null`])
+          break
+        default:
+          finish(assertNever(nodeType, 'JsonSchemaType'))
+      }
+    } catch (error) {
+      let failed = frames.pop()
+      while (failed !== undefined && !failed.catches) failed = frames.pop()
+      if (failed === undefined) throw error
+      receive(losslessValueViolation(failed.path))
+    }
+  }
+
+  /* v8 ignore next -- every root frame finishes or throws. */
+  return rootResult ?? losslessValueViolation(path)
+}
+
+/**
+ * Validate a candidate value against an asserted raw schema. The function is
+ * total for arbitrary values and returns path-qualified violations.
+ * @param schema - a schema accepted by {@link assertSupportedJsonSchema}.
+ * @param value - the candidate JSON value.
+ * @param path - root label used in diagnostics.
+ * @returns All violations in walk order; empty means valid.
+ */
+export function validateJsonSchemaValue(schema: JsonSchemaNode, value: unknown, path = 'value'): string[] {
+  return checkValue(schema, value, path)
 }
diff --git a/packages/core/tools/src/schema.ts b/packages/core/tools/src/schema.ts
index f2b62669b1..c0f5ceb525 100644
--- a/packages/core/tools/src/schema.ts
+++ b/packages/core/tools/src/schema.ts
@@ -1,173 +1,465 @@
-/** Typed tool-parameter DSL with argument inference and JSON Schema output. @module dsh-tools/schema */
+/** Unified JSON-value schema DSL, inference, compilation, and typed tool helper. @module dsh-tools/schema */
 
-import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm'
-import type { ToolDefinition, ToolExecuteReturn, ToolRunContext, ToolResult } from './index.ts'
+import { HarnessError } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { ToolDefinition, ToolExecution, ToolExecutionResult, ToolRunContext, ToolResult } from './index.ts'
+import { assertSupportedJsonSchema, isJsonSchemaRecord, isPlainJsonArray, JsonSchemaError, validateJsonSchemaValue } from './json-schema.ts'
+import type { JsonSchemaNode, JsonSchemaScalar, ObjectJsonSchema } from './json-schema.ts'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
 
-// ---------------------------------------------------------------------------
-// SchemaSpec — the author-facing per-property type
-// ---------------------------------------------------------------------------
-
-/** Valid JSON Schema primitive types for tool parameters. */
-export type SchemaType = 'string' | 'number' | 'boolean' | 'object' | 'array'
-
-/** One schema-spec property entry. */
-export interface SchemaProp {
-  type: SchemaType
-  /** Per-property required flag (NOT the JSON Schema top-level required array). */
-  required?: true
-  /** Human-readable description, surfaced in the JSON Schema as well. */
+/** Annotation keywords shared by every author-facing schema node. */
+export interface ValueSchemaAnnotations {
+  /** Human-readable description projected into JSON Schema and generated types. */
   description?: string
-  /** Enum of allowed values (strings only). */
-  enum?: string[]
-  /**
-   * Model-visible JSON Schema default annotation. Validation does not apply it;
-   * dynamic tool mounts may supply it even though first-party definitions do not.
-   */
-  default?: unknown
-  /** Nested properties for type: 'object'. */
-  properties?: SchemaSpec
-  /** Items schema for type: 'array'. */
-  items?: SchemaProp
+  /** Human-readable title projected into JSON Schema. */
+  title?: string
+  /** Non-validating default annotation; it must be lossless JSON data. */
+  default?: JsonValue
+  /** Non-validating examples annotation; it must be lossless JSON data. */
+  examples?: JsonValue
+}
+
+/** String value schema with type-correct literal constraints. */
+export interface StringValueSchemaSpec extends ValueSchemaAnnotations {
+  type: 'string'
+  enum?: readonly string[]
+  const?: string
+}
+
+/** Finite JSON-number schema with type-correct literal constraints. */
+export interface NumberValueSchemaSpec extends ValueSchemaAnnotations {
+  type: 'number'
+  enum?: readonly number[]
+  const?: number
+}
+
+/** Integer schema with type-correct literal constraints. */
+export interface IntegerValueSchemaSpec extends ValueSchemaAnnotations {
+  type: 'integer'
+  enum?: readonly number[]
+  const?: number
+}
+
+/** Boolean value schema with type-correct literal constraints. */
+export interface BooleanValueSchemaSpec extends ValueSchemaAnnotations {
+  type: 'boolean'
+  enum?: readonly boolean[]
+  const?: boolean
+}
+
+/** Null value schema with type-correct literal constraints. */
+export interface NullValueSchemaSpec extends ValueSchemaAnnotations {
+  type: 'null'
+  enum?: readonly null[]
+  const?: null
+}
+
+/** Array value schema; omitted `items` accepts any lossless JSON item. */
+export interface ArrayValueSchemaSpec extends ValueSchemaAnnotations {
+  type: 'array'
+  items?: ValueSchemaSpec
 }
 
 /**
- * The author-facing parameter schema: a shallow map of property name to
- * {@link SchemaProp}. Required-ness is a per-property boolean (`required:
- * true`), not a separate array.
+ * Explicit object value schema. Openness is mandatory so a nested or output
+ * object never acquires an accidental JSON Schema default.
  */
-export type SchemaSpec = Record<string, SchemaProp>
+export interface ObjectValueSchemaSpec extends ValueSchemaAnnotations {
+  type: 'object'
+  properties?: ParameterSchemaSpec
+  additionalProperties: boolean
+}
 
-// ---------------------------------------------------------------------------
-// InferArgs — type-level mapping from SchemaSpec to TS argument type
-// ---------------------------------------------------------------------------
+/** Author-only unconstrained lossless JSON node. */
+export interface JsonValueSchemaSpec extends ValueSchemaAnnotations {
+  type: 'json'
+}
 
-/** Map a {@link SchemaType} to its TS primitive type. */
-type TypeOf<T extends SchemaType> =
-  T extends 'string' ? string :
-    T extends 'number' ? number :
-      T extends 'boolean' ? boolean :
-        T extends 'object' ? Record<string, unknown> :
-          T extends 'array' ? unknown[] :
-            never
+/** Exact-one union schema; at least two branches are required. */
+export interface OneOfValueSchemaSpec extends ValueSchemaAnnotations {
+  oneOf: readonly [ValueSchemaSpec, ValueSchemaSpec, ...ValueSchemaSpec[]]
+}
+
+/** One author-facing schema for any lossless JSON value root. */
+export type ValueSchemaSpec =
+  | StringValueSchemaSpec
+  | NumberValueSchemaSpec
+  | IntegerValueSchemaSpec
+  | BooleanValueSchemaSpec
+  | NullValueSchemaSpec
+  | ArrayValueSchemaSpec
+  | ObjectValueSchemaSpec
+  | JsonValueSchemaSpec
+  | OneOfValueSchemaSpec
+
+/** One implicit parameter-root property, optionally required. */
+export type ParameterPropertySpec = ValueSchemaSpec & { required?: true }
+
+/**
+ * Tool parameter schema. The map itself is an implicit open object root;
+ * requiredness remains a per-property `required: true` annotation.
+ */
+export type ParameterSchemaSpec = {
+  [key: string]: ParameterPropertySpec
+  [key: symbol]: never
+}
+
+/** Raw JSON Schema projection of the implicit parameter object. */
+export interface ParameterJsonSchema extends ObjectJsonSchema {
+  properties: Record<string, JsonSchemaNode>
+}
 
 /** Flatten an intersection into one object type for readable hovers. */
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
 
-/** Keys of `S` whose prop is marked `required: true`. */
-type RequiredKeys<S extends SchemaSpec> =
-  { [K in keyof S]: S[K] extends { required: true } ? K : never }[keyof S]
+/** String keys of one property map; runtime compilation rejects symbol keys. */
+type StringKeyOf<S> = Extract<keyof S, string>
 
-/**
- * The VALUE type of one {@link SchemaProp} — optionality is handled at the
- * key level by {@link InferArgs}, never here.
- * - `properties` on 'object' → recurse into the nested SchemaSpec
- * - `items` on 'array' → recurse into the item prop (arrays of objects work)
- * - otherwise → the primitive for `type`
- */
-type InferPropValue<P extends SchemaProp> =
-  P extends { type: 'object'; properties: infer Sub extends SchemaSpec } ? InferArgs<Sub> :
-    P extends { type: 'array'; items: infer Item extends SchemaProp } ? InferPropValue<Item>[] :
-      TypeOf<P['type']>
+/** Keys of a property map marked `required: true`. */
+type RequiredKeys<S> = {
+  [K in StringKeyOf<S>]: S[K] extends { required: true } ? K : never
+}[StringKeyOf<S>]
 
-/**
- * Infer the TS argument type for a complete {@link SchemaSpec}.
- *
- * Properties marked `required: true` are required keys; all others are
- * genuinely optional keys (`?`), so callers may omit them entirely.
- *
- * Example:
- * ```ts
- * type Args = InferArgs<{ path: { type: 'string'; required: true }; limit: { type: 'number' } }>
- * // → { path: string; limit?: number }
- * ```
- */
-export type InferArgs<S extends SchemaSpec> = Simplify<
-  & { [K in RequiredKeys<S>]: InferPropValue<S[K]> }
-  & { [K in Exclude<keyof S, RequiredKeys<S>>]?: InferPropValue<S[K]> }
+/** Infer the declared value of one parameter property without key optionality. */
+type InferProperty<P, Depth extends unknown[]> = InferValueAt<P, Depth>
+
+/** Infer an implicit property map into required and optional object keys. */
+type InferProperties<S, Depth extends unknown[]> = Simplify<
+  & { [K in RequiredKeys<S>]: InferProperty<S[K], Depth> }
+  & { [K in Exclude<StringKeyOf<S>, RequiredKeys<S>>]?: InferProperty<S[K], Depth> }
 >
 
-// ---------------------------------------------------------------------------
-// Runtime conversion: SchemaSpec → JSON Schema
-// ---------------------------------------------------------------------------
+/** Infer an explicit object node, including its declared openness. */
+type InferObject<S extends { additionalProperties: boolean }, Depth extends unknown[]> =
+  S extends { properties: infer P }
+    ? S['additionalProperties'] extends true
+      ? InferProperties<P, Depth> & Record<string, JsonValue>
+      : InferProperties<P, Depth>
+    : S['additionalProperties'] extends true
+      ? Record<string, JsonValue>
+      : Record<string, never>
+
+/** Infer a scalar node's literal constraint before its broad primitive type. */
+type InferScalar<S, Fallback> =
+  S extends { const: infer C } ? C :
+    S extends { enum: readonly (infer E)[] } ? E :
+      Fallback
+
+/** Add one schema-container level to bounded compile-time inference. */
+type NextInferenceDepth<Depth extends unknown[]> = [unknown, ...Depth]
+
+/** Infer one node without recursively checking it against the full author union. */
+type InferValueAt<S, Depth extends unknown[]> =
+  Depth['length'] extends 16 ? JsonValue :
+    S extends { type: 'string' } ? InferScalar<S, string> :
+      S extends { type: 'number' | 'integer' } ? InferScalar<S, number> :
+        S extends { type: 'boolean' } ? InferScalar<S, boolean> :
+          S extends { type: 'null' } ? null :
+            S extends { type: 'array' }
+              ? S extends { items: infer I } ? InferValueAt<I, NextInferenceDepth<Depth>>[] : JsonValue[]
+              : S extends { type: 'object'; additionalProperties: boolean }
+                ? InferObject<S, NextInferenceDepth<Depth>>
+                : S extends { type: 'json' } ? JsonValue :
+                  S extends { oneOf: readonly unknown[] }
+                    ? InferValueAt<S['oneOf'][number], NextInferenceDepth<Depth>>
+                    : never
 
 /**
- * Convert a single {@link SchemaProp} to its JSON Schema `properties` entry.
- * The per-property `required` flag is collected; the caller builds the
- * top-level `required` array.
+ * Infer the TypeScript value accepted by an author-facing value schema. Exact
+ * inference is bounded to 16 container levels, then falls back to `JsonValue`.
  */
-function propToJsonSchema(prop: SchemaProp): { schema: Record<string, unknown>; required: boolean } {
-  const result: Record<string, unknown> = { type: prop.type }
-  if (prop.description) result.description = prop.description
-  if (prop.enum) result.enum = prop.enum
-  if (prop.default !== undefined) result.default = prop.default
+export type InferValue<S> = InferValueAt<S, []>
 
-  const required = prop.required === true
+/** Infer the TypeScript argument object for an implicit parameter schema. */
+export type InferArgs<S> = InferProperties<S, []>
 
-  if (prop.type === 'object' && prop.properties) {
-    const nested = schemaSpecToJsonSchema(prop.properties)
-    result.properties = nested.properties
-    if (nested.required && nested.required.length > 0) {
-      result.required = nested.required
-    }
-  }
+const ANNOTATION_KEYS = ['description', 'title', 'default', 'examples'] as const
 
-  if (prop.type === 'array' && prop.items) {
-    const { schema: itemsSchema } = propToJsonSchema(prop.items)
-    result.items = itemsSchema
-  }
-
-  return { schema: result, required }
+/** Throw one author-schema violation through the shared schema error type. */
+function authorError(message: string): never {
+  throw new JsonSchemaError([message])
 }
 
-/** The return type of {@link schemaSpecToJsonSchema}. */
-export interface JsonSchemaObject {
-  type: 'object'
-  properties: Record<string, unknown>
+/** Copy own annotation fields for validation by the raw-schema boundary. */
+function copyAnnotations(source: Record<string, unknown>, target: JsonSchemaNode): void {
+  if (Object.hasOwn(source, 'description')) target.description = source.description as string
+  if (Object.hasOwn(source, 'title')) target.title = source.title as string
+  if (Object.hasOwn(source, 'default')) target.default = source.default as JsonValue
+  if (Object.hasOwn(source, 'examples')) target.examples = source.examples as JsonValue
+}
+
+/** Reject author-only keys outside one node's declared vocabulary. */
+function assertAuthorKeys(source: Record<string, unknown>, path: string, allowed: readonly string[]): void {
+  for (const key of Object.keys(source)) {
+    if (!allowed.includes(key)) authorError(`${path}.${key} is not supported by the value schema DSL`)
+  }
+}
+
+/** Compiled form of one implicit property map. */
+interface CompiledPropertyMap {
+  properties: Record<string, JsonSchemaNode>
   required?: string[]
 }
 
-/**
- * Convert a {@link SchemaSpec} to standard JSON Schema (`type: 'object'`,
- * `properties`, `required` array).
- *
- * This is a plain function — no schemastery or other framework dependency.
- * @param spec - the author-facing per-property schema to convert.
- * @returns the wire-format JSON Schema; the top-level `required` array is
- *   omitted entirely when no property is marked required.
- */
-export function schemaSpecToJsonSchema(spec: SchemaSpec): JsonSchemaObject {
-  const properties: Record<string, unknown> = {}
-  const required: string[] = []
-
-  for (const [key, prop] of Object.entries(spec)) {
-    const { schema, required: isRequired } = propToJsonSchema(prop)
-    properties[key] = schema
-    if (isRequired) required.push(key)
-  }
-
-  const result: JsonSchemaObject = {
-    type: 'object',
-    properties,
-  }
-  if (required.length > 0) result.required = required
-
-  return result
+/** Mutable holder used only while an iterative compilation root is unresolved. */
+interface CompileRoot<T> {
+  value?: T
 }
 
-// ---------------------------------------------------------------------------
-// Runtime validation: model-generated args ↔ SchemaSpec
-// ---------------------------------------------------------------------------
+/** Where one compiled value node is installed. */
+type NodeDestination =
+  | { kind: 'root'; holder: CompileRoot<JsonSchemaNode> }
+  | { kind: 'property'; target: Record<string, JsonSchemaNode>; key: string }
+  | { kind: 'item'; target: JsonSchemaNode }
+  | { kind: 'one-of'; target: JsonSchemaNode[]; index: number }
+
+/** Where one compiled property map is installed. */
+type PropertyMapDestination =
+  | { kind: 'root'; holder: CompileRoot<CompiledPropertyMap> }
+  | { kind: 'object'; target: JsonSchemaNode }
+
+/** Deferred work for stack-safe author-schema compilation. */
+type CompileTask =
+  | { kind: 'value'; input: unknown; path: string; allowRequired: boolean; destination: NodeDestination }
+  | { kind: 'property-map'; input: unknown; path: string; destination: PropertyMapDestination }
+  | {
+    kind: 'property'
+    property: unknown
+    path: string
+    key: string
+    properties: Record<string, JsonSchemaNode>
+    required: string[]
+  }
+  | {
+    kind: 'property-map-tail'
+    compiled: CompiledPropertyMap
+    required: string[]
+    destination: PropertyMapDestination
+  }
+  | { kind: 'leave'; input: object }
+
+/** Install a compiled node without giving `__proto__` assignment semantics. */
+function assignCompiledNode(destination: NodeDestination, node: JsonSchemaNode): void {
+  switch (destination.kind) {
+    case 'root':
+      destination.holder.value = node
+      break
+    case 'property':
+      Object.defineProperty(destination.target, destination.key, {
+        value: node,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      })
+      break
+    case 'item':
+      destination.target.items = node
+      break
+    case 'one-of':
+      destination.target[destination.index] = node
+      break
+  }
+}
+
+/** Install a compiled property map at its root or containing object node. */
+function assignCompiledPropertyMap(destination: PropertyMapDestination, compiled: CompiledPropertyMap): void {
+  if (destination.kind === 'root') {
+    destination.holder.value = compiled
+  } else {
+    destination.target.properties = compiled.properties
+  }
+}
+
+/** Execute an author-schema compilation task graph without recursive descent. */
+function runSchemaCompiler(initial: CompileTask): void {
+  const seen = new Set<object>()
+  const tasks: CompileTask[] = [initial]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      seen.delete(task.input)
+      continue
+    }
+    if (task.kind === 'property-map-tail') {
+      if (task.required.length > 0) {
+        task.compiled.required = task.required
+        if (task.destination.kind === 'object') task.destination.target.required = task.required
+      }
+      continue
+    }
+    if (task.kind === 'property') {
+      if (!isJsonSchemaRecord(task.property)) authorError(`${task.path} must be a value schema object`)
+      if (Object.hasOwn(task.property, 'required') && task.property.required !== true) {
+        authorError(`${task.path}.required must be true when present`)
+      }
+      if (Object.hasOwn(task.property, 'required') && task.property.required === true) task.required.push(task.key)
+      tasks.push({
+        kind: 'value',
+        input: task.property,
+        path: task.path,
+        allowRequired: true,
+        destination: { kind: 'property', target: task.properties, key: task.key },
+      })
+      continue
+    }
+    if (task.kind === 'property-map') {
+      if (!isJsonSchemaRecord(task.input)) authorError(`${task.path} must be an object of value schemas`)
+      if (seen.has(task.input)) authorError(`${task.path} is circular`)
+      seen.add(task.input)
+      const compiled: CompiledPropertyMap = { properties: {} }
+      const required: string[] = []
+      assignCompiledPropertyMap(task.destination, compiled)
+      tasks.push({ kind: 'leave', input: task.input })
+      tasks.push({ kind: 'property-map-tail', compiled, required, destination: task.destination })
+      const entries = Object.entries(task.input)
+      for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index]
+        /* v8 ignore next -- the loop is bounded by the captured entry count. */
+        if (entry === undefined) continue
+        tasks.push({
+          kind: 'property',
+          property: entry[1],
+          path: `${task.path}.${entry[0]}`,
+          key: entry[0],
+          properties: compiled.properties,
+          required,
+        })
+      }
+      continue
+    }
+
+    const { input, path } = task
+    if (!isJsonSchemaRecord(input)) authorError(`${path} must be a value schema object`)
+    if (seen.has(input)) authorError(`${path} is circular`)
+    seen.add(input)
+    const authorKeys = [...ANNOTATION_KEYS, ...(task.allowRequired ? ['required'] : [])]
+    const node: JsonSchemaNode = {}
+    assignCompiledNode(task.destination, node)
+    tasks.push({ kind: 'leave', input })
+
+    if (Object.hasOwn(input, 'oneOf')) {
+      assertAuthorKeys(input, path, [...authorKeys, 'oneOf', 'type'])
+      if (Object.hasOwn(input, 'type')) authorError(`${path} cannot declare both type and oneOf`)
+      if (!isPlainJsonArray(input.oneOf)) authorError(`${path}.oneOf must be an array of at least two value schemas`)
+      const branches: JsonSchemaNode[] = []
+      node.oneOf = branches
+      copyAnnotations(input, node)
+      for (let index = input.oneOf.length - 1; index >= 0; index--) {
+        tasks.push({
+          kind: 'value',
+          input: input.oneOf[index],
+          path: `${path}.oneOf[${index}]`,
+          allowRequired: false,
+          destination: { kind: 'one-of', target: branches, index },
+        })
+      }
+      continue
+    }
+
+    const inputType = Object.hasOwn(input, 'type') ? input.type : undefined
+    switch (inputType) {
+      case 'json':
+        assertAuthorKeys(input, path, [...authorKeys, 'type'])
+        copyAnnotations(input, node)
+        break
+      case 'object':
+        assertAuthorKeys(input, path, [...authorKeys, 'type', 'properties', 'additionalProperties'])
+        if (!Object.hasOwn(input, 'additionalProperties') || typeof input.additionalProperties !== 'boolean') {
+          authorError(`${path}.additionalProperties must be explicitly true or false`)
+        }
+        node.type = 'object'
+        copyAnnotations(input, node)
+        node.additionalProperties = input.additionalProperties
+        if (Object.hasOwn(input, 'properties')) {
+          tasks.push({
+            kind: 'property-map',
+            input: input.properties,
+            path: `${path}.properties`,
+            destination: { kind: 'object', target: node },
+          })
+        }
+        break
+      case 'array':
+        assertAuthorKeys(input, path, [...authorKeys, 'type', 'items'])
+        node.type = 'array'
+        copyAnnotations(input, node)
+        if (Object.hasOwn(input, 'items')) {
+          tasks.push({
+            kind: 'value',
+            input: input.items,
+            path: `${path}.items`,
+            allowRequired: false,
+            destination: { kind: 'item', target: node },
+          })
+        }
+        break
+      case 'string':
+      case 'number':
+      case 'integer':
+      case 'boolean':
+      case 'null':
+        assertAuthorKeys(input, path, [...authorKeys, 'type', 'enum', 'const'])
+        node.type = inputType
+        copyAnnotations(input, node)
+        if (Object.hasOwn(input, 'enum')) {
+          if (!isPlainJsonArray(input.enum)) authorError(`${path}.enum must be a non-empty array of scalar values`)
+          node.enum = Array.from(input.enum, entry => entry as JsonSchemaScalar)
+        }
+        if (Object.hasOwn(input, 'const')) node.const = input.const as JsonSchemaScalar
+        break
+      default:
+        authorError(`${path}.type must be string/number/integer/boolean/null/array/object/json, or use oneOf`)
+    }
+  }
+}
+
+/** Compile one implicit property map, collecting per-property requiredness. */
+function compilePropertyMap(input: unknown, path: string): CompiledPropertyMap {
+  const holder: CompileRoot<CompiledPropertyMap> = {}
+  runSchemaCompiler({ kind: 'property-map', input, path, destination: { kind: 'root', holder } })
+  /* v8 ignore next -- the root task assigns before scheduling any descendants. */
+  return holder.value ?? authorError(`${path} did not compile`)
+}
+
+/** Compile one author node without applying any consumer root restriction. */
+function compileValueSchema(input: unknown, path: string): JsonSchemaNode {
+  const holder: CompileRoot<JsonSchemaNode> = {}
+  runSchemaCompiler({ kind: 'value', input, path, allowRequired: false, destination: { kind: 'root', holder } })
+  /* v8 ignore next -- the root task assigns before scheduling any descendants. */
+  return holder.value ?? authorError(`${path} did not compile`)
+}
 
 /**
- * Thrown by a {@link defineTool} tool when the model-generated arguments don't
- * match the declared {@link SchemaSpec}. Extends {@link HarnessError}
- * (`code: 'INVALID_ARGS'`); the registry's execution pipeline catches it and
- * returns an `isError` ToolExecutionResult carrying the structured error, so
- * the model can self-correct and downstream plugins can route on the code.
+ * Compile one author-facing value schema to the enforced raw JSON Schema
+ * subset. The author-only `json` node becomes an annotation-only schema.
+ * @param spec - schema for any JSON-value root.
+ * @returns The asserted raw schema projection.
  */
+export function valueSchemaSpecToJsonSchema(spec: ValueSchemaSpec): JsonSchemaNode {
+  const schema = compileValueSchema(spec, 'schema')
+  assertSupportedJsonSchema(schema)
+  return schema
+}
+
+/**
+ * Compile the implicit open parameter object into raw JSON Schema.
+ * @param spec - per-property parameter definitions.
+ * @returns An object-rooted raw schema with no implicit-root openness override.
+ */
+export function parameterSchemaSpecToJsonSchema(spec: ParameterSchemaSpec): ParameterJsonSchema {
+  const compiled = compilePropertyMap(spec, 'parameters')
+  const schema: ParameterJsonSchema = {
+    type: 'object',
+    properties: compiled.properties,
+    ...(compiled.required === undefined ? {} : { required: compiled.required }),
+  }
+  assertSupportedJsonSchema(schema)
+  return schema
+}
+
+/** Invalid model-generated arguments for a typed tool. */
 export class ToolArgsError extends HarnessError {
-  /** The individual violation messages, in declaration order. */
+  /** Individual violations in schema-walk order. */
   readonly violations: string[]
 
   constructor(violations: string[]) {
@@ -177,155 +469,92 @@ export class ToolArgsError extends HarnessError {
   }
 }
 
-/** Whether a value is a non-null, non-array object (a JSON Schema `object`). */
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-/** Collect violations for one property value against its {@link SchemaProp}. */
-function checkValue(prop: SchemaProp, value: unknown, path: string): string[] {
-  switch (prop.type) {
-    case 'string': {
-      if (typeof value !== 'string') return [`"${path}" must be a string`]
-      break
-    }
-    case 'number': {
-      if (typeof value !== 'number') return [`"${path}" must be a number`]
-      break
-    }
-    case 'boolean': {
-      if (typeof value !== 'boolean') return [`"${path}" must be a boolean`]
-      break
-    }
-    case 'object': {
-      if (!isPlainObject(value)) return [`"${path}" must be an object`]
-      // Mirror the converter: an object without `properties` only type-checks.
-      return prop.properties ? checkSpec(prop.properties, value, path) : []
-    }
-    case 'array': {
-      if (!Array.isArray(value)) return [`"${path}" must be an array`]
-      // Mirror the converter: an array without `items` only type-checks.
-      if (!prop.items) return []
-      const items = prop.items
-      return value.flatMap((el, i) => checkValue(items, el, `${path}[${i}]`))
-    }
-    default: return assertNever(prop.type, 'validateArgs')
-  }
-  // Enum membership, checked uniformly: the converter emits `enum` for any
-  // type ([prop.enum]), so the validator must too. `enum` is `string[]`, so a
-  // non-string value can never be a member — it falls out here, consistent
-  // with the schema the model was given.
-  if (prop.enum && !(prop.enum as unknown[]).includes(value)) {
-    return [`"${path}" must be one of ${JSON.stringify(prop.enum)}`]
-  }
-  return []
-}
-
-/** Collect violations for an object value against a {@link SchemaSpec}. */
-function checkSpec(spec: SchemaSpec, value: unknown, path: string): string[] {
-  if (!isPlainObject(value)) return [`"${path || 'arguments'}" must be an object`]
-  const violations: string[] = []
-  for (const [key, prop] of Object.entries(spec)) {
-    const propPath = path ? `${path}.${key}` : key
-    const v = value[key]
-    if (v === undefined) {
-      // A required key absent OR present-but-undefined is a violation; an
-      // optional absent key is fine. `default` is NOT applied (validation only).
-      if (prop.required === true) violations.push(`missing required property "${propPath}"`)
-      continue
-    }
-    violations.push(...checkValue(prop, v, propPath))
-  }
-  return violations
-}
-
 /**
- * Validate model-generated `args` against a {@link SchemaSpec}, returning a
- * list of human-readable violation messages (empty = valid). Total — never
- * throws, regardless of how malformed `args` is.
- *
- * Semantics mirror {@link schemaSpecToJsonSchema} exactly: the top level must
- * be a non-array object; required keys come only from `required: true`; extra
- * keys are allowed (no `additionalProperties: false`); `default` is not
- * applied; an `object`/`array` prop without `properties`/`items` only
- * type-checks; `enum` is membership (strings only).
- * @param spec - the declared parameter schema to validate against.
- * @param args - the model-generated arguments, however malformed.
- * @returns the violation messages in declaration order; empty means valid.
+ * Validate model-generated arguments against an implicit parameter schema.
+ * @param spec - declared parameter schema.
+ * @param args - candidate arguments, however malformed.
+ * @returns Path-qualified violations; empty means valid.
  */
-export function validateArgs(spec: SchemaSpec, args: unknown): string[] {
-  return checkSpec(spec, args, '')
+export function validateArgs(spec: ParameterSchemaSpec, args: unknown): string[] {
+  return validateJsonSchemaValue(parameterSchemaSpecToJsonSchema(spec), args, '')
 }
 
-// ---------------------------------------------------------------------------
-// defineTool — typed helper for first-party plugin authors
-// ---------------------------------------------------------------------------
-
 /** Options for {@link defineTool}. */
-export interface DefineToolOptions<S extends SchemaSpec> {
+export interface DefineToolOptions<S extends ParameterSchemaSpec, O extends ValueSchemaSpec> {
   /** Tool name (must be unique). */
   readonly name: string
   /** Human-readable description sent to the model. */
   readonly description: string
-  /**
-   * Parameter schema using the per-property-required DSL. Converted to
-   * standard JSON Schema at runtime.
-   */
+  /** Per-property parameter schema compiled to an implicit open object root. */
   readonly parameters: S
-  /**
-   * Optional cooperative tool-call timeout budget in milliseconds. When given it
-   * must be a positive finite number; it is attached to the produced
-   * {@link ToolDefinition} for `@deepseek-ai/dsh-timeout-policy` to enforce and
-   * is never sent to the model.
-   */
+  /** Canonical output schema plus pure Native and presentation projections. */
+  readonly output: {
+    /** Schema enforced against every successful body or policy-replaced value. */
+    readonly schema: O
+    /** Pure Native/model rendering of one validated canonical value. */
+    render(args: InferArgs<S>, value: InferValue<NoInfer<O>>): ContentBlock[]
+    /** Pure replayable presentation metadata for direct surface calls. */
+    presentationMeta?(args: InferArgs<S>, value: InferValue<NoInfer<O>>): JsonValue
+  }
+  /** Optional positive cooperative timeout budget in milliseconds. */
   readonly timeoutMs?: number
   /**
-   * Optional pure synchronous classifier for sibling overlap. It receives typed
-   * arguments after soft validation; invalid input returns `false` without
-   * invoking it. See {@link ToolDefinition.isConcurrencySafe}.
+   * Pure classifier for sibling overlap.
    * @param args - typed validated arguments.
-   * @returns whether this call may join a parallel group.
+   * @returns Whether the call may join a parallel group.
    */
   isConcurrencySafe?(args: InferArgs<S>): boolean
   /**
-   * Tool execution function. `args` is typed as {@link InferArgs<S>} — zero
-   * casts needed. Returns either a bare {@link ContentBlock}`[]` (model-facing
-   * content only) or a `{ content, meta }` object to also attach a tool-private
-   * presentation payload (see {@link ToolExecuteReturn}).
+   * Execute the tool after argument validation.
+   * @param args - typed validated arguments.
+   * @param exec - execution identity, caller, cancellation, and nesting data.
+   * @returns The canonical value declared by `output.schema`.
    */
-  execute(args: InferArgs<S>, exec: ToolRunContext): Promise<ToolExecuteReturn>
+  execute(args: InferArgs<S>, exec: ToolRunContext): Promise<InferValue<NoInfer<O>>>
   /**
-   * Optional: how to present the PENDING state of one call in a UI (an editor
-   * tool-call card, a CLI log line). `args` is the typed, schema-validated
-   * argument shape — zero casts. Pure and side-effect-free: a UI may call it
-   * during live streaming AND a session-log replay, so depend only on `args`.
-   * The tool owns its presentation so a UI never special-cases tool names. See
-   * {@link ToolCallView}.
+   * Optional last-mile content transform for every normalized outcome. Unlike
+   * `execute`, arguments remain `unknown` because invalid-input failures also
+   * reach this callback. See {@link ToolDefinition.finalizeContent}.
+   * @param exec - immutable execution identity and arguments.
+   * @param result - complete normalized outcome before materialization.
+   * @returns replacement content, or `undefined` to preserve it.
+   */
+  finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
+  /**
+   * Pure pending-state presenter.
+   * @param args - typed validated arguments.
+   * @returns Tool-owned render intent, or `undefined` for the generic card.
    */
   presentCall?(args: InferArgs<S>): ToolCallView | undefined
   /**
-   * Optional: how to present the COMPLETED state, given the typed `args` and the
-   * `result`. Use it to reformat result content for a UI distinctly from the
-   * model-facing text (e.g. a fenced ```console block). Pure and side-effect-
-   * free for the same replay reason. See {@link ToolResultView}.
+   * Pure completed-state presenter.
+   * @param args - typed validated arguments.
+   * @param result - final model-facing tool result.
+   * @returns Tool-owned render intent, or `undefined` for the generic card.
    */
   presentResult?(args: InferArgs<S>, result: ToolResult): ToolResultView | undefined
 }
 
 /**
- * Define a first-party tool whose execution and presentation arguments are
- * inferred from its per-property schema. Raw JSON-Schema definitions remain
- * valid inputs to {@link ToolRegistry.register}; this helper is authoring sugar.
- * @param options - the tool's name, description, typed parameter schema,
- *   execute body, and optional presenters.
- * @returns a registry-ready definition with strict execution validation and
- *   soft presenter and classifier validation for replay compatibility.
+ * Define a first-party tool with inferred arguments and strict execution
+ * validation. Replay-only presenters validate softly and fall back to generic
+ * rendering for obsolete logged arguments.
+ * @param options - typed definition and optional finalizer and presenters.
+ * @returns A registry-ready definition.
  */
-export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>): ToolDefinition {
-  // Object-literal execute methods don't use `this`; the reference is safe.
+export function defineTool<const S extends ParameterSchemaSpec, const O extends ValueSchemaSpec>(
+  options: DefineToolOptions<S, O>,
+): ToolDefinition {
+  // Object-literal methods do not use `this`; retaining references is safe.
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const userExecute = options.execute
   // eslint-disable-next-line @typescript-eslint/unbound-method
+  const userFinalizeContent = options.finalizeContent
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const userRender = options.output.render
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const userPresentationMeta = options.output.presentationMeta
+  // eslint-disable-next-line @typescript-eslint/unbound-method
   const userPresentCall = options.presentCall
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const userPresentResult = options.presentResult
@@ -334,20 +563,33 @@ export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>):
   if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
     throw new Error(`defineTool(${options.name}): timeoutMs must be a positive finite number`)
   }
+  const parameters = parameterSchemaSpecToJsonSchema(options.parameters)
+  const outputSchema = valueSchemaSpecToJsonSchema(options.output.schema)
+  const validate = (args: unknown): string[] => validateJsonSchemaValue(parameters, args, '')
   const tool: ToolDefinition = {
     name: options.name,
     description: options.description,
-    parameters: schemaSpecToJsonSchema(options.parameters) as unknown as Record<string, unknown>,
-    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-    async execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn> {
-      // Validate the model-generated args before the typed body runs. On
-      // mismatch we throw ToolArgsError; the registry turns it into an
-      // isError result so the model can self-correct. After this guard, the
-      // cast to InferArgs<S> reflects the validated shape.
-      const violations = validateArgs(options.parameters, args)
-      if (violations.length > 0) throw new ToolArgsError(violations)
-      return userExecute(args as InferArgs<S>, exec)
+    parameters: parameters as unknown as Record<string, unknown>,
+    output: {
+      schema: outputSchema,
+      render(args: unknown, value: JsonValue): ContentBlock[] {
+        return userRender(args as InferArgs<S>, value as unknown as InferValue<NoInfer<O>>)
+      },
+      ...userPresentationMeta !== undefined ? {
+        presentationMeta(args: unknown, value: JsonValue): JsonValue {
+          return userPresentationMeta(args as InferArgs<S>, value as unknown as InferValue<NoInfer<O>>)
+        },
+      } : {},
     },
+    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    async execute(args: unknown, exec: ToolRunContext): Promise<JsonValue> {
+      const violations = validate(args)
+      if (violations.length > 0) throw new ToolArgsError(violations)
+      return userExecute(args as InferArgs<S>, exec) as Promise<JsonValue>
+    },
+  }
+  if (userFinalizeContent) {
+    tool.finalizeContent = (exec, result) => userFinalizeContent(exec, result)
   }
   // Presentation is display-only and may run on REPLAY of arbitrary logged args
   // (possibly from an older schema), so it must never throw: validate softly and
@@ -355,20 +597,19 @@ export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>):
   // than the hard `ToolArgsError` the execute path raises.
   if (userPresentCall) {
     tool.presentCall = (args: unknown): ToolCallView | undefined => {
-      if (validateArgs(options.parameters, args).length > 0) return undefined
+      if (validate(args).length > 0) return undefined
       return userPresentCall(args as InferArgs<S>)
     }
   }
   if (userPresentResult) {
     tool.presentResult = (args: unknown, result: ToolResult): ToolResultView | undefined => {
-      if (validateArgs(options.parameters, args).length > 0) return undefined
+      if (validate(args).length > 0) return undefined
       return userPresentResult(args as InferArgs<S>, result)
     }
   }
-  // Invalid arguments fail closed without invoking the typed classifier.
   if (userIsConcurrencySafe) {
     tool.isConcurrencySafe = (args: unknown): boolean => {
-      if (validateArgs(options.parameters, args).length > 0) return false
+      if (validate(args).length > 0) return false
       return userIsConcurrencySafe(args as InferArgs<S>)
     }
   }
diff --git a/packages/core/tools/src/testing.ts b/packages/core/tools/src/testing.ts
new file mode 100644
index 0000000000..ad9fa52d85
--- /dev/null
+++ b/packages/core/tools/src/testing.ts
@@ -0,0 +1,42 @@
+/** Canonical tool-definition fixtures for repository tests. @module dsh-tools/testing */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { defineTool } from './schema.ts'
+import type { DefineToolOptions, ParameterSchemaSpec } from './schema.ts'
+import type { ToolDefinition, ToolRunContext } from './index.ts'
+
+const CONTENT_VALUE_SCHEMA = { type: 'array', items: { type: 'json' } } as const
+
+/** Options for a fixture whose canonical value is its rendered content array. */
+export type ContentToolFixtureOptions<S extends ParameterSchemaSpec> = Omit<
+  DefineToolOptions<S, typeof CONTENT_VALUE_SCHEMA>,
+  'output' | 'execute'
+> & {
+  /** Produce the fixture's content blocks as its canonical test value. */
+  execute(args: import('./schema.ts').InferArgs<S>, exec: ToolRunContext): Promise<ContentBlock[]>
+}
+
+/**
+ * Define a test fixture that deliberately uses its content blocks as the
+ * canonical JSON value. Product tools must declare domain-owned DTOs instead.
+ * @param options - ordinary fixture fields plus a content-producing body.
+ * @returns a registry-ready tool with an explicit JSON-array output contract.
+ * @internal
+ */
+export function defineContentToolFixture<const S extends ParameterSchemaSpec>(
+  options: ContentToolFixtureOptions<S>,
+): ToolDefinition {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const execute = options.execute
+  return defineTool({
+    ...options,
+    output: {
+      schema: CONTENT_VALUE_SCHEMA,
+      render: (_args, value) => value as unknown as ContentBlock[],
+    },
+    async execute(args, exec) {
+      return await execute(args, exec) as unknown as JsonValue[]
+    },
+  })
+}
diff --git a/packages/core/tools/src/ts-types.ts b/packages/core/tools/src/ts-types.ts
index e5f67d0891..36d8f1dcc8 100644
--- a/packages/core/tools/src/ts-types.ts
+++ b/packages/core/tools/src/ts-types.ts
@@ -7,6 +7,13 @@
  */
 
 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+import { assertSupportedJsonSchema } from './json-schema.ts'
+import type { JsonSchemaNode, JsonSchemaScalar } from './json-schema.ts'
+/** Internal Code Mode projection: the model-facing schema plus the canonical output schema. */
+export interface ToolSdkSchema extends ToolSchema {
+  /** Validated canonical value returned by the tool binding. */
+  output: JsonSchemaNode
+}
 
 /** Property names that are valid bare TS identifiers; anything else is quoted. */
 const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
@@ -30,48 +37,212 @@ function docLines(description: unknown, indent: number): string[] {
   return [`${pad(indent)}/** ${collapsed.replaceAll('*/', String.raw`*\/`)} */`]
 }
 
+/** Render one scalar already validated by the unified schema boundary. */
+function renderScalar(value: JsonSchemaScalar): string {
+  return JSON.stringify(value)
+}
+
+/** Render a validated scalar `const`/`enum`, falling back to the broad type. */
+function renderConstrainedScalar(node: Record<string, unknown>, type: string): string {
+  const broad = type === 'integer' ? 'number' : type
+  if (Object.hasOwn(node, 'const')) return renderScalar(node.const as JsonSchemaScalar)
+  if (Object.hasOwn(node, 'enum')) {
+    return (node.enum as JsonSchemaScalar[]).map(renderScalar).join(' | ')
+  }
+  return broad
+}
+
+/** A composable type document that can be flattened without recursive string concatenation. */
+interface TypeDocument {
+  readonly parts: readonly (string | TypeDocument)[]
+  readonly containsUnionOrIntersection: boolean
+}
+
+/** Build one document from captured parts while retaining the legacy array-parenthesization test. */
+function typeDocumentFrom(parts: readonly (string | TypeDocument)[]): TypeDocument {
+  return {
+    parts,
+    containsUnionOrIntersection: parts.some(part => typeof part === 'string'
+      ? part.includes('|') || part.includes('&')
+      : part.containsUnionOrIntersection),
+  }
+}
+
+/** Build a small document without an intermediate array at each call site. */
+function typeDocument(...parts: (string | TypeDocument)[]): TypeDocument {
+  return typeDocumentFrom(parts)
+}
+
+/** Flatten a nested document with an explicit work stack. */
+function flattenTypeDocument(document: TypeDocument): string {
+  const chunks: string[] = []
+  const tasks: (string | TypeDocument)[] = [document]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (typeof task === 'string') {
+      chunks.push(task)
+      continue
+    }
+    for (let index = task.parts.length - 1; index >= 0; index--) {
+      const part = task.parts[index]
+      /* v8 ignore next -- the loop is bounded by the captured part count. */
+      if (part !== undefined) tasks.push(part)
+    }
+  }
+  return chunks.join('')
+}
+
+/** One explicit call frame for stack-safe schema-to-TypeScript rendering. */
+interface SchemaRenderFrame {
+  readonly node: JsonSchemaNode
+  readonly indent: number
+  phase: 'start' | 'children'
+  kind?: 'oneOf' | 'array' | 'object'
+  children: { node: JsonSchemaNode; indent: number }[]
+  childIndex: number
+  childDocuments: TypeDocument[]
+  entries: [string, JsonSchemaNode][]
+}
+
+/** Initialize one schema-render frame with empty aggregation state. */
+function schemaRenderFrame(node: JsonSchemaNode, indent: number): SchemaRenderFrame {
+  return { node, indent, phase: 'start', children: [], childIndex: 0, childDocuments: [], entries: [] }
+}
+
+/** Render an already asserted schema to a composable document. */
+function renderSupportedSchema(schema: JsonSchemaNode, indent: number): TypeDocument {
+  const frames: SchemaRenderFrame[] = [schemaRenderFrame(schema, indent)]
+  let rootDocument: TypeDocument | undefined
+  const finish = (document: TypeDocument): void => {
+    frames.pop()
+    const parent = frames.at(-1)
+    if (parent === undefined) rootDocument = document
+    else parent.childDocuments.push(document)
+  }
+
+  while (frames.length > 0) {
+    const frame = frames.at(-1)
+    /* v8 ignore next -- the loop condition guarantees a current frame. */
+    if (frame === undefined) break
+    if (frame.phase === 'children') {
+      if (frame.childIndex < frame.children.length) {
+        const child = frame.children[frame.childIndex]
+        /* v8 ignore next -- childIndex is bounded by children.length. */
+        if (child === undefined) throw new Error('missing schema render child')
+        frame.childIndex++
+        frames.push(schemaRenderFrame(child.node, child.indent))
+        continue
+      }
+      if (frame.kind === 'oneOf') {
+        const parts: (string | TypeDocument)[] = []
+        for (let index = 0; index < frame.childDocuments.length; index++) {
+          if (index > 0) parts.push(' | ')
+          const child = frame.childDocuments[index]
+          /* v8 ignore next -- child documents correspond one-to-one with children. */
+          if (child !== undefined) parts.push(child)
+        }
+        finish(typeDocumentFrom(parts))
+        continue
+      }
+      if (frame.kind === 'array') {
+        const child = frame.childDocuments[0]
+        /* v8 ignore next -- array frames always schedule exactly one child. */
+        if (child === undefined) throw new Error('missing array item type')
+        finish(child.containsUnionOrIntersection
+          ? typeDocument('(', child, ')[]')
+          : typeDocument(child, '[]'))
+        continue
+      }
+
+      const required = new Set(frame.node.required)
+      const parts: (string | TypeDocument)[] = ['{']
+      for (let index = 0; index < frame.entries.length; index++) {
+        const entry = frame.entries[index]
+        const child = frame.childDocuments[index]
+        /* v8 ignore next -- object entries and child documents have the same length. */
+        if (entry === undefined || child === undefined) throw new Error('missing object property type')
+        const [name, prop] = entry
+        for (const line of docLines(prop.description, frame.indent + 1)) parts.push('\n', line)
+        parts.push('\n', `${pad(frame.indent + 1)}${renderKey(name)}${required.has(name) ? '' : '?'}: `, child, ';')
+      }
+      parts.push('\n', `${pad(frame.indent)}}`)
+      const declared = typeDocumentFrom(parts)
+      finish(frame.node.additionalProperties === false
+        ? declared
+        : typeDocument(declared, ' & Record<string, JsonValue>'))
+      continue
+    }
+
+    const node = frame.node
+    if (node.oneOf !== undefined) {
+      frame.kind = 'oneOf'
+      frame.children = Array.from(node.oneOf, child => ({ node: child, indent: frame.indent }))
+      frame.childIndex = 0
+      frame.childDocuments = []
+      frame.phase = 'children'
+      continue
+    }
+    if (node.type === undefined) {
+      finish(typeDocument('JsonValue'))
+      continue
+    }
+    switch (node.type) {
+      case 'string':
+      case 'number':
+      case 'integer':
+      case 'boolean':
+      case 'null':
+        finish(typeDocument(renderConstrainedScalar(node as Record<string, unknown>, node.type)))
+        break
+      case 'array':
+        if (node.items === undefined) {
+          finish(typeDocument('JsonValue[]'))
+        } else {
+          frame.kind = 'array'
+          frame.children = [{ node: node.items, indent: frame.indent }]
+          frame.childIndex = 0
+          frame.childDocuments = []
+          frame.phase = 'children'
+        }
+        break
+      case 'object': {
+        const open = node.additionalProperties !== false
+        const entries = Object.entries(node.properties ?? {})
+        if (entries.length === 0) {
+          finish(typeDocument(open ? 'Record<string, JsonValue>' : 'Record<string, never>'))
+        } else {
+          frame.kind = 'object'
+          frame.entries = entries
+          frame.children = entries.map(([, child]) => ({ node: child, indent: frame.indent + 1 }))
+          frame.childIndex = 0
+          frame.childDocuments = []
+          frame.phase = 'children'
+        }
+        break
+      }
+      /* v8 ignore next -- assertSupportedJsonSchema narrowed this closed type union. */
+      default:
+        finish(typeDocument('unknown'))
+    }
+  }
+
+  /* v8 ignore next -- every root frame produces one document. */
+  return rootDocument ?? typeDocument('unknown')
+}
+
 /**
- * Map one JSON-Schema node to a TypeScript type literal. Handles exactly the
- * subset the `defineTool` DSL emits — `object` (`properties` + `required`),
- * `string` (with `enum` → a literal union), `number`, `boolean`, `array`
- * (`items`) — and returns `unknown` for anything else, without throwing.
+ * Map one enforced JSON-Schema node to a TypeScript type literal. Supports
+ * every unified schema construct and returns `unknown` for malformed or
+ * unsupported inputs without throwing.
  * @param schema - the JSON-Schema node (any shape; hostile inputs degrade).
  * @param indent - the indentation level for nested object members.
  * @returns the TS type text (multi-line for objects with properties).
  */
 export function jsonSchemaToTs(schema: unknown, indent = 0): string {
-  if (typeof schema !== 'object' || schema === null) return 'unknown'
-  const node = schema as Record<string, unknown>
-  switch (node.type) {
-    case 'string': {
-      if (Array.isArray(node.enum) && node.enum.length > 0 && node.enum.every(value => typeof value === 'string')) {
-        return node.enum.map(value => JSON.stringify(value)).join(' | ')
-      }
-      return 'string'
-    }
-    case 'number': return 'number'
-    case 'boolean': return 'boolean'
-    case 'array': {
-      const item = jsonSchemaToTs(node.items, indent)
-      // Parenthesize a union item type so `('a' | 'b')[]` parses as intended.
-      return item.includes('|') ? `(${item})[]` : `${item}[]`
-    }
-    case 'object': {
-      const properties = node.properties
-      if (typeof properties !== 'object' || properties === null) return 'Record<string, unknown>'
-      const entries = Object.entries(properties as Record<string, unknown>)
-      if (entries.length === 0) return 'Record<string, unknown>'
-      const required = new Set(Array.isArray(node.required) ? node.required.filter(name => typeof name === 'string') : [])
-      const lines: string[] = ['{']
-      for (const [name, prop] of entries) {
-        const description = typeof prop === 'object' && prop !== null ? (prop as Record<string, unknown>).description : undefined
-        lines.push(...docLines(description, indent + 1))
-        lines.push(`${pad(indent + 1)}${renderKey(name)}${required.has(name) ? '' : '?'}: ${jsonSchemaToTs(prop, indent + 1)};`)
-      }
-      lines.push(`${pad(indent)}}`)
-      return lines.join('\n')
-    }
-    default: return 'unknown'
+  try {
+    assertSupportedJsonSchema(schema)
+    return flattenTypeDocument(renderSupportedSchema(schema, indent))
+  } catch {
+    return 'unknown'
   }
 }
 
@@ -80,8 +251,8 @@ const SDK_INSTRUCTIONS = `## Writing code for run_code
 
 Pass \`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:
 
-- Call tools as \`await tools.name(args)\` — quoted access for exotic names: \`tools["my-tool"](args)\`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.
-- A FAILED tool call rejects with an \`Error\` carrying the tool's error text — \`try/catch\` it to handle and continue.
+- 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.
+- 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.
 - Calls execute sequentially, even under \`Promise.all\`.
 - 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.
 
@@ -96,15 +267,24 @@ The available tools:`
  *   `run_code` itself).
  * @returns the complete section text.
  */
-export function renderToolsSdk(schemas: ToolSchema[]): string {
+export function renderToolsSdk(schemas: ToolSdkSchema[]): string {
   const sorted = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
-  const members: string[] = []
+  const argsMembers: string[] = []
+  const outputMembers: string[] = []
   for (const schema of sorted) {
-    members.push(...docLines(schema.description, 1))
-    members.push(`${pad(1)}${renderKey(schema.name)}(args: ${jsonSchemaToTs(schema.parameters, 1)}): Promise<string>;`)
+    argsMembers.push(...docLines(schema.description, 1))
+    argsMembers.push(`${pad(1)}${renderKey(schema.name)}: ${jsonSchemaToTs(schema.parameters, 1)};`)
+    outputMembers.push(`${pad(1)}${renderKey(schema.name)}: ${jsonSchemaToTs(schema.output, 1)};`)
   }
-  const declaration = members.length > 0
-    ? `declare const tools: {\n${members.join('\n')}\n}`
-    : 'declare const tools: {}'
-  return `${SDK_INSTRUCTIONS}\n\n\`\`\`ts\n${declaration}\n\`\`\``
+  const argsMap = `interface ToolArgsMap {${argsMembers.length > 0 ? `\n${argsMembers.join('\n')}\n` : ''}}`
+  const outputMap = `interface ToolOutputMap {${outputMembers.length > 0 ? `\n${outputMembers.join('\n')}\n` : ''}}`
+  const declaration = [
+    argsMap,
+    outputMap,
+    'type ToolName = keyof ToolOutputMap',
+    ['declare class ToolCallError extends Error {', '  readonly name: "ToolCallError";', '  readonly toolName: ToolName;', '}'].join('\n'),
+    ['declare const tools: {', '  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;', '}'].join('\n'),
+  ].join('\n\n')
+  const jsonValue = 'type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }'
+  return `${SDK_INSTRUCTIONS}\n\n\`\`\`ts\n${jsonValue}\n\n${declaration}\n\`\`\``
 }
diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts
index b8f47cca81..0681ffc571 100644
--- a/packages/core/tools/tests/code-mode.spec.ts
+++ b/packages/core/tools/tests/code-mode.spec.ts
@@ -6,11 +6,11 @@ import type { Scope } from '@deepseek-ai/dsh-scope'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
 import type { CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
-import ToolRegistry, { CodeRunFailedError, RUN_CODE_NAME, TOOL_ABORTED_BEFORE_DISPATCH, defineTool } from '@deepseek-ai/dsh-tools'
-import type { Config, PostToolDecision, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { CodeRunFailedError, RUN_CODE_NAME, TOOL_ABORTED_BEFORE_DISPATCH, defineContentToolFixture, defineTool } from '@deepseek-ai/dsh-tools'
+import type { Config, JsonSchemaNode, PostToolDecision, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEventMap } from '@deepseek-ai/dsh-session'
+import type { JsonValue, SessionEventMap } from '@deepseek-ai/dsh-session'
 
 const testToolSignal = new AbortController().signal
 
@@ -74,9 +74,13 @@ function registerEcho(ctx: Context, name = 'echo'): unknown[] {
     name,
     description: `Echo tool ${name}.`,
     parameters: { value: { type: 'string', required: true } },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     execute(args) {
       calls.push(args)
-      return Promise.resolve([{ type: 'text' as const, text: `${name}:${args.value}` }])
+      return Promise.resolve(`${name}:${args.value}`)
     },
   }))
   return calls
@@ -122,8 +126,32 @@ describe('mode-aware wire contribution', () => {
     expect(assembly.tools.map(tool => tool.name)).toEqual([RUN_CODE_NAME])
     const sdk = assembly.sections.find(section => section.name === 'tools:sdk')
     expect(sdk?.text).toContain('declare const tools: {')
-    expect(sdk?.text).toContain('echo(args:')
-    expect(sdk?.text).not.toContain('run_code(args:')
+    expect(sdk?.text).toContain('echo: {')
+    expect(sdk?.text).not.toContain('run_code:')
+  })
+
+  it('projects deeply nested output schemas into the Code Mode SDK without structured-clone recursion', async () => {
+    const { ctx, systemPrompt } = await setup({ mode: 'code' })
+    let output: JsonSchemaNode = { type: 'string' }
+    for (let depth = 0; depth < 5_000; depth++) {
+      output = { oneOf: [output, { type: 'null' }] }
+    }
+    ctx.tools.register({
+      name: 'deep_output',
+      description: 'Return a deeply nested output union.',
+      parameters: { type: 'object', properties: {} },
+      output: {
+        schema: output,
+        render: (_args, value) => [{ type: 'text', text: typeof value === 'string' ? value : 'null' }],
+      },
+      execute() { return Promise.resolve('ok') },
+    })
+
+    const assembly = await systemPrompt.assemble()
+    const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text
+
+    expect(sdk).toContain('deep_output: Record<string, JsonValue>;')
+    expect(sdk).toContain('deep_output: string | null')
   })
 
   it.each(['code', 'both'] as const)('treats expert assembly output as authoritative in mode %s', async (mode) => {
@@ -175,8 +203,8 @@ describe('mode-aware wire contribution', () => {
       ? [RUN_CODE_NAME]
       : ['echo', RUN_CODE_NAME])
     const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text
-    expect(sdk).toContain('echo(args:')
-    expect(sdk).not.toContain('hidden(args:')
+    expect(sdk).toContain('echo: {')
+    expect(sdk).not.toContain('hidden:')
 
     runtime.behavior = request => Promise.resolve({
       logs: [],
@@ -205,8 +233,8 @@ describe('mode-aware wire contribution', () => {
       ? [RUN_CODE_NAME]
       : ['kept', RUN_CODE_NAME])
     const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text
-    expect(sdk).not.toContain('denied(args:')
-    expect(sdk).toContain('kept(args:')
+    expect(sdk).not.toContain('denied:')
+    expect(sdk).toContain('kept: {')
 
     runtime.behavior = request => Promise.resolve({
       logs: [],
@@ -220,7 +248,7 @@ describe('mode-aware wire contribution', () => {
   it.each(['code', 'both'] as const)('reserves run_code against scoped shadows and explicit restrictions in mode %s', async (mode) => {
     const { ctx, systemPrompt } = await setup({ mode })
     const { scope, agent } = await mintAgentScope(ctx)
-    const impostor = defineTool({
+    const impostor = defineContentToolFixture({
       name: RUN_CODE_NAME,
       description: 'Scoped impostor.',
       parameters: {},
@@ -232,7 +260,7 @@ describe('mode-aware wire contribution', () => {
     expect(() => scope.ctx.tools.restrict({ allow: [RUN_CODE_NAME] })).toThrow(/cannot name reserved Code Mode presentation transport/)
     expect(() => scope.ctx.tools.restrict({ deny: [RUN_CODE_NAME] })).toThrow(/cannot name reserved Code Mode presentation transport/)
     scope.ctx.systemPrompt.section({ name: 'scoped-note', order: 149, text: 'safe note' })
-    scope.ctx.tools.register(defineTool({
+    scope.ctx.tools.register(defineContentToolFixture({
       name: 'scoped_safe',
       description: 'Safe scoped tool.',
       parameters: {},
@@ -244,7 +272,7 @@ describe('mode-aware wire contribution', () => {
     expect(transports).toHaveLength(1)
     expect(transports[0]?.description).toContain('Execute a TypeScript program')
     expect(assembly.sections.find(section => section.name === 'scoped-note')?.text).toBe('safe note')
-    expect(assembly.sections.find(section => section.name === 'tools:sdk')?.text).toContain('scoped_safe(args:')
+    expect(assembly.sections.find(section => section.name === 'tools:sdk')?.text).toContain('scoped_safe:')
     expect(ctx.tools.get(RUN_CODE_NAME, agent)).toBe(ctx.tools.get(RUN_CODE_NAME))
     const result = await runCode(ctx, 'return 1', { agent })
     expect(result.content).toEqual([{ type: 'text', text: '(run_code completed with no output)' }])
@@ -268,6 +296,10 @@ describe('mode-aware wire contribution', () => {
     const { ctx, runtime } = await setup({ mode: 'both' })
     registerEcho(ctx)
     runtime.behavior = (request) => {
+      expect(request.bindings[0]!.errorClass).toEqual({
+        name: 'ToolCallError',
+        memberNameProperty: 'toolName',
+      })
       const functions = request.bindings[0]!.functions
       return Promise.resolve({
         logs: [],
@@ -331,10 +363,13 @@ describe('the run_code dispatch bridge', () => {
       const tools = request.bindings[0]!.functions
       const first = await tools.echo!({ value: 'one' })
       const second = await tools.echo!({ value: 'two' })
-      return { logs: [`saw ${String(first)}`], value: second }
+      if (typeof first !== 'string' || typeof second !== 'string') throw new Error('echo returned a non-string')
+      return { logs: [`saw ${first}`], value: second }
     }
     const result = await runCode(ctx, 'const …: string = …', { agent })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected run_code success')
+    expect(result.value).toEqual({ logs: ['saw echo:one'], result: 'echo:two' })
     expect(result.content).toEqual([{ type: 'text', text: 'saw echo:one\necho:two' }])
     expect(calls).toEqual([{ value: 'one' }, { value: 'two' }])
     const dispatches = events.filter(event => event.type === 'tool/code-dispatch')
@@ -342,7 +377,7 @@ describe('the run_code dispatch bridge', () => {
       { parentCallId: 'call-1', subCallId: 'call-1:code:1', name: 'echo', arguments: { value: 'one' }, isError: false, resultSummary: 'echo:one' },
       { parentCallId: 'call-1', subCallId: 'call-1:code:2', name: 'echo', arguments: { value: 'two' }, isError: false, resultSummary: 'echo:two' },
     ])
-    expect(result.meta).toEqual({ logs: ['saw echo:one'] })
+    expect(result.meta).toBeUndefined()
   })
 
   it('exposes only an opaque parent token to nested result observers', async () => {
@@ -380,6 +415,10 @@ describe('the run_code dispatch bridge', () => {
       name: 'probe',
       description: 'Records execution overlap.',
       parameters: { id: { type: 'string', required: true } },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
       async execute(args) {
         active++
         expect(active, 'probe executions overlapped').toBe(1)
@@ -387,12 +426,13 @@ describe('the run_code dispatch bridge', () => {
         await new Promise(resolve => setTimeout(resolve, 20))
         intervals.push(['exit', args.id])
         active--
-        return [{ type: 'text' as const, text: args.id }]
+        return args.id
       },
     }))
     runtime.behavior = async (request) => {
       const tools = request.bindings[0]!.functions
       const values = await Promise.all([tools.probe!({ id: 'a' }), tools.probe!({ id: 'b' }), tools.probe!({ id: 'c' })])
+      if (!values.every(value => typeof value === 'string')) throw new Error('probe returned a non-string')
       return { logs: [], value: values.join(',') }
     }
     const result = await runCode(ctx, 'program')
@@ -407,7 +447,7 @@ describe('the run_code dispatch bridge', () => {
 
   it('rejects the program-side call when the tool errors, with the tool error text', async () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'fail',
       description: 'Always fails.',
       parameters: {},
@@ -422,7 +462,7 @@ describe('the run_code dispatch bridge', () => {
       }
     }
     const result = await runCode(ctx, 'program')
-    expect(result.content[0]).toEqual({ type: 'text', text: 'caught: Error: deliberate failure' })
+    expect(result.content[0]).toEqual({ type: 'text', text: 'caught: deliberate failure' })
   })
 
   it('a tools/pre-execute deny reaches the program as a binding rejection', async () => {
@@ -445,7 +485,7 @@ describe('the run_code dispatch bridge', () => {
     expect((result.content[0] as { text: string }).text).toContain('not on my watch')
   })
 
-  it('rejects a binding argument that does not survive JSON normalization, dispatching nothing', async () => {
+  it('rejects a binding argument that is not lossless JSON, dispatching nothing', async () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
     const calls = registerEcho(ctx)
     const { agent, events } = fakeAgent()
@@ -458,25 +498,24 @@ describe('the run_code dispatch bridge', () => {
       }
     }
     const result = await runCode(ctx, 'program', { agent })
-    expect((result.content[0] as { text: string }).text).toContain('JSON-serializable')
+    expect((result.content[0] as { text: string }).text).toContain('lossless JSON')
     expect(calls).toEqual([])
     expect(events.filter(event => event.type === 'tool/code-dispatch')).toEqual([])
   })
 
-  it('dispatches the JSON-normalized value: what the tool sees is what the event logs', async () => {
+  it('dispatches and logs independent snapshots of the same lossless JSON value', async () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
     const calls = registerEcho(ctx)
     const { agent, events } = fakeAgent()
     runtime.behavior = async (request) => {
-      // A Date survives structured clone but is not JSON; the bridge
-      // normalizes it to its JSON form (an ISO string) BEFORE dispatch.
-      await request.bindings[0]!.functions.echo!({ value: 'x', when: new Date(0) }).catch(() => undefined)
+      const args = Object.assign(Object.create(null) as Record<string, unknown>, { value: 'x', nested: ['same'] })
+      await request.bindings[0]!.functions.echo!(args)
       return { logs: [] }
     }
     await runCode(ctx, 'program', { agent })
-    expect(calls).toEqual([{ value: 'x', when: '1970-01-01T00:00:00.000Z' }])
+    expect(calls).toEqual([{ value: 'x', nested: ['same'] }])
     const dispatch = events.find(event => event.type === 'tool/code-dispatch')?.data as SessionEventMap['tool/code-dispatch']
-    expect(dispatch.arguments).toEqual({ value: 'x', when: '1970-01-01T00:00:00.000Z' })
+    expect(dispatch.arguments).toEqual({ value: 'x', nested: ['same'] })
   })
 
   it('defers sub-call additionalContexts onto the outer run_code result', async () => {
@@ -551,7 +590,7 @@ describe('the run_code dispatch bridge', () => {
     })
     const result = await runCode(ctx, 'program')
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'CodeRunFailedError', code: 'CODE_RUN_FAILED' })
+    expect(result.error).toMatchObject({ info: { name: 'CodeRunFailedError', code: 'CODE_RUN_FAILED' } })
     const text = (result.content[0] as { text: string }).text
     expect(text).toContain('code run failed (timeout)')
     expect(text).toContain('compute budget exhausted')
@@ -568,7 +607,7 @@ describe('the run_code dispatch bridge', () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
     const seen: string[] = []
     let sawAbort = false
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'slow',
       description: 'Slow tool observing its signal.',
       parameters: { id: { type: 'string', required: true } },
@@ -604,7 +643,7 @@ describe('the run_code dispatch bridge', () => {
     let sawAbort = false
     let started!: () => void
     const inFlight = new Promise<void>((resolve) => { started = resolve })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'slow',
       description: 'Slow tool observing its signal.',
       parameters: { id: { type: 'string', required: true } },
@@ -654,7 +693,7 @@ describe('the run_code dispatch bridge', () => {
     expect((result.content[0] as { text: string }).text).toContain('requires a code runtime')
   })
 
-  it('presents the PROGRAM as the execute-card title on both call and result (the one slot execute cards always show)', async () => {
+  it('presents the program as the execute-card title', async () => {
     const { ctx } = await setup({ mode: 'code' })
     const tool = ctx.tools.get(RUN_CODE_NAME)!
     // The program IS the title, mirroring how command tools title their cards
@@ -667,24 +706,59 @@ describe('the run_code dispatch bridge', () => {
       kind: 'execute',
       rawInput: 'return 1',
     })
-    const view = tool.presentResult?.({ code: 'return 1' }, {
-      content: [{ type: 'text', text: 'model-facing' }],
-      isError: false,
-      meta: { logs: ['printed'] },
+  })
+
+  it.each([
+    ['logs only', { logs: ['printed'] }, 'printed'],
+    ['result only', { logs: [], value: 'returned' }, 'returned'],
+    ['logs plus result', { logs: ['printed'], value: 'returned' }, 'printed\nreturned'],
+    ['no output', { logs: [] }, '(run_code completed with no output)'],
+  ] as [string, CodeRunResult, string][])('keeps %s in durable content without a result presenter', async (_name, output, text) => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    runtime.behavior = () => Promise.resolve(output)
+
+    const result = await runCode(ctx, 'return 1')
+    const tool = ctx.tools.get(RUN_CODE_NAME)!
+
+    expect(result.content).toEqual([{ type: 'text', text }])
+    // Surfaces keep the pending program title and render this durable content
+    // through their generic fallback. Omitting a result view also prevents the
+    // host frame from carrying the same raw content a second time.
+    expect('presentResult' in tool).toBe(false)
+  })
+
+  it('keeps a post-policy spill preview in durable content without a result presenter', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const preview = 'HEAD\n\n(Omitted 100 bytes. Full formatted result stored at: /tmp/run-code.txt.)\n\nTAIL'
+    runtime.behavior = () => Promise.resolve({ logs: ['printed'], value: 'returned' })
+    ctx.on('tools/post-execute', (exec, _result, next): Promise<PostToolDecision> => {
+      if (exec.name !== RUN_CODE_NAME) return next()
+      return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: preview }] })
     })
-    // The result omits the title — an update replaces only provided fields,
-    // so the pending card's program title persists through completion.
-    expect(view).toEqual({
-      card: 'generic',
-      content: [{ type: 'text', text: 'printed' }],
+
+    const result = await runCode(ctx, 'return 1')
+    const tool = ctx.tools.get(RUN_CODE_NAME)!
+
+    expect(result.content).toEqual([{ type: 'text', text: preview }])
+    expect('presentResult' in tool).toBe(false)
+  })
+
+  it('keeps canonical failure content durable without a result presenter', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    runtime.behavior = () => Promise.resolve({
+      logs: ['captured before failure'],
+      error: { kind: 'output-limit', message: 'outer output exceeded 8 bytes' },
     })
-    // No captured output → no content either; everything pending persists.
-    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [] } }))
-      .toEqual({ card: 'generic' })
-    // Replay with an unrecognizable meta falls back to the generic rendering.
-    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [{ text: 'legacy' }], dispatches: 1 } })).toBeUndefined()
-    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { other: true } })).toBeUndefined()
-    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false })).toBeUndefined()
+
+    const result = await runCode(ctx, 'return 1')
+    const tool = ctx.tools.get(RUN_CODE_NAME)!
+
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{
+      type: 'text',
+      text: 'Error: code run failed (output-limit): outer output exceeded 8 bytes\nCaptured output:\ncaptured before failure',
+    }])
+    expect('presentResult' in tool).toBe(false)
   })
 
   it('renders non-text sub-result blocks as placeholders and truncates long event summaries', async () => {
@@ -695,11 +769,15 @@ describe('the run_code dispatch bridge', () => {
       name: 'mixed',
       description: 'Returns mixed content.',
       parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: () => [
+          { type: 'text', text: long },
+          { type: 'reasoning', text: 'hidden' },
+        ],
+      },
       execute() {
-        return Promise.resolve([
-          { type: 'text' as const, text: long },
-          { type: 'reasoning' as const, text: 'hidden' },
-        ])
+        return Promise.resolve('mixed-value')
       },
     }))
     runtime.behavior = async (request) => {
@@ -708,7 +786,7 @@ describe('the run_code dispatch bridge', () => {
     }
     const result = await runCode(ctx, 'program', { agent })
     expect(result.isError).toBe(false)
-    expect((result.content[0] as { text: string }).text).toBe(`${long}\n[reasoning content]`)
+    expect((result.content[0] as { text: string }).text).toBe('mixed-value')
     const dispatch = events.find(event => event.type === 'tool/code-dispatch')?.data as SessionEventMap['tool/code-dispatch']
     expect(dispatch.resultSummary.length).toBe(201)
     expect(dispatch.resultSummary.endsWith('…')).toBe(true)
@@ -720,9 +798,13 @@ describe('the run_code dispatch bridge', () => {
       name: 'workspace_path',
       description: 'Return a path beneath the session workspace.',
       parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
       execute(_args, exec) {
         const cwd = exec.agent?.session.header.cwd ?? ''
-        return Promise.resolve([{ type: 'text' as const, text: `<path>${cwd}/nested/task.txt</path>\n${'x'.repeat(240)}` }])
+        return Promise.resolve(`<path>${cwd}/nested/task.txt</path>\n${'x'.repeat(240)}`)
       },
     }))
     runtime.behavior = async request => ({
@@ -760,7 +842,7 @@ describe('the run_code dispatch bridge', () => {
     expect((root.events[0]!.data as SessionEventMap['tool/code-dispatch']).resultSummary).toBe('echo:/workspace/value')
   })
 
-  it('rejects undefined, JSON-throwing, and JSON-unrepresentable binding arguments BEFORE dispatch', async () => {
+  it('rejects undefined, getter-throwing, exotic, and unrepresentable binding arguments before dispatch', async () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
     const calls = registerEcho(ctx)
     const { agent, events } = fakeAgent()
@@ -773,8 +855,9 @@ describe('the run_code dispatch bridge', () => {
           // Root undefined must reject up front: the event log rejects it as
           // data, and nothing may execute unlogged.
           await catchMessage(echo(undefined)),
-          // A toJSON that throws a NON-Error propagates out of JSON.stringify.
-          await catchMessage(echo({ toJSON() { throw 'raw-throw' } })),
+          await catchMessage(echo(Object.defineProperty({}, 'bad', { enumerable: true, get() { throw 'raw-throw' } }))),
+          await catchMessage(echo(Object.defineProperty({}, 'bad', { enumerable: true, get() { throw new Error('error-throw') } }))),
+          await catchMessage(echo(new Date(0))),
           // A bare function is a value JSON cannot represent at all.
           await catchMessage(echo(() => 1)),
         ].join(' | '),
@@ -783,18 +866,70 @@ describe('the run_code dispatch bridge', () => {
     const result = await runCode(ctx, 'program', { agent })
     const text = (result.content[0] as { text: string }).text
     expect(text).toContain('call the tool with an arguments object')
-    expect(text).toContain('JSON-serializable: raw-throw')
-    expect(text).toContain('a value JSON cannot represent')
-    // None of the three dispatched, none logged.
+    expect(text).toContain('lossless JSON: raw-throw')
+    expect(text).toContain('lossless JSON: error-throw')
+    expect(text.match(/tool arguments must be lossless JSON/g)).toHaveLength(5)
+    // None dispatched or logged.
     expect(calls).toEqual([])
     expect(events.filter(event => event.type === 'tool/code-dispatch')).toEqual([])
   })
 
+  it('dispatches and durably logs binding arguments deeper than the structured-clone call stack', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const depth = 5_000
+    let observedDepth = 0
+    let observedLeaf: JsonValue | undefined
+    ctx.tools.register(defineTool({
+      name: 'deep_args',
+      description: 'Measure a deeply nested JSON argument.',
+      parameters: { nested: { type: 'json', required: true } },
+      output: {
+        schema: { type: 'integer' },
+        render: (_args, value) => [{ type: 'text', text: String(value) }],
+      },
+      execute(args) {
+        let cursor = args.nested
+        while (Array.isArray(cursor)) {
+          if (cursor.length !== 1) throw new Error('expected one item per nesting layer')
+          observedDepth++
+          cursor = cursor[0]!
+        }
+        observedLeaf = cursor
+        return Promise.resolve(observedDepth)
+      },
+    }))
+    const session = new Session(SessionId('deep-code-arguments'))
+    const agent = { session } as Agent
+    runtime.behavior = async (request) => {
+      let nested: JsonValue = 'leaf'
+      for (let index = 0; index < depth; index++) nested = [nested]
+      const value = await request.bindings[0]!.functions.deep_args!({ nested })
+      return { logs: [], value }
+    }
+
+    const result = await runCode(ctx, 'return tools.deep_args(...)', { agent })
+
+    expect(result.isError).toBe(false)
+    expect(result.isError ? undefined : result.value).toEqual({ logs: [], result: depth })
+    expect({ observedDepth, observedLeaf }).toEqual({ observedDepth: depth, observedLeaf: 'leaf' })
+    const dispatch = session.events.find(event => event.type === 'tool/code-dispatch')
+    if (dispatch === undefined) throw new Error('expected a durable tool/code-dispatch event')
+    const logged = dispatch.data.arguments as { nested: JsonValue }
+    let loggedDepth = 0
+    let loggedCursor = logged.nested
+    while (Array.isArray(loggedCursor)) {
+      if (loggedCursor.length !== 1) throw new Error('expected one logged item per nesting layer')
+      loggedDepth++
+      loggedCursor = loggedCursor[0]!
+    }
+    expect({ loggedDepth, loggedCursor }).toEqual({ loggedDepth: depth, loggedCursor: 'leaf' })
+  })
+
   it('gives the tool and durable log the same immutable argument value', async () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
     const { agent, events } = fakeAgent()
     let mutationSucceeded: boolean | undefined
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'mutator',
       description: 'Attempts to mutate its args object.',
       parameters: { list: { type: 'array', required: true } },
@@ -820,7 +955,11 @@ describe('the run_code dispatch bridge', () => {
       name: '__proto__',
       description: 'A prototype-colliding tool name.',
       parameters: {},
-      execute() { return Promise.resolve([{ type: 'text' as const, text: 'proto-tool-ok' }]) },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
+      execute() { return Promise.resolve('proto-tool-ok') },
     }))
     runtime.behavior = async (request) => {
       const functions = request.bindings[0]!.functions
@@ -833,11 +972,48 @@ describe('the run_code dispatch bridge', () => {
     expect(result.content[0]).toEqual({ type: 'text', text: 'proto-tool-ok' })
   })
 
-  it('renders a non-string completion value inspect-style', async () => {
+  it('renders every non-string JSON root as pretty JSON while preserving strings raw', async () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
-    runtime.behavior = () => Promise.resolve({ logs: [], value: { n: 42 } })
-    const result = await runCode(ctx, 'program')
-    expect((result.content[0] as { text: string }).text).toBe('{ n: 42 }')
+    runtime.behavior = () => Promise.resolve({ logs: [], value: { n: 42, ok: true } })
+    expect((await runCode(ctx, 'object')).content[0]).toEqual({ type: 'text', text: '{\n  "n": 42,\n  "ok": true\n}' })
+    runtime.behavior = () => Promise.resolve({ logs: [], value: {} })
+    expect((await runCode(ctx, 'empty object')).content[0]).toEqual({ type: 'text', text: '{}' })
+    const nested = { outer: [{ inner: true }] }
+    runtime.behavior = () => Promise.resolve({ logs: [], value: nested })
+    expect((await runCode(ctx, 'nested')).content[0]).toEqual({ type: 'text', text: JSON.stringify(nested, null, 2) })
+    runtime.behavior = () => Promise.resolve({ logs: [], value: ['x', 2] })
+    expect((await runCode(ctx, 'array')).content[0]).toEqual({ type: 'text', text: '[\n  "x",\n  2\n]' })
+    runtime.behavior = () => Promise.resolve({ logs: [], value: [] })
+    expect((await runCode(ctx, 'empty array')).content[0]).toEqual({ type: 'text', text: '[]' })
+    runtime.behavior = () => Promise.resolve({ logs: [], value: null })
+    expect((await runCode(ctx, 'null')).content[0]).toEqual({ type: 'text', text: 'null' })
+    runtime.behavior = () => Promise.resolve({ logs: [], value: 'raw' })
+    expect((await runCode(ctx, 'string')).content[0]).toEqual({ type: 'text', text: 'raw' })
+    runtime.behavior = () => Promise.resolve({ logs: [] })
+    const absent = await runCode(ctx, 'undefined')
+    expect(absent.content[0]).toEqual({ type: 'text', text: '(run_code completed with no output)' })
+    expect(absent.isError ? undefined : absent.value).toEqual({ logs: [] })
+  })
+
+  it('renders deeply nested JSON without recursive traversal or quadratic indentation', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    let value: JsonValue = {
+      emptyArray: [],
+      emptyObject: {},
+      pair: ['leaf', 2],
+      record: { first: true, second: null },
+    }
+    for (let depth = 0; depth < 5_000; depth++) value = [value]
+    runtime.behavior = () => Promise.resolve({ logs: [], value })
+
+    const result = await runCode(ctx, 'deep result')
+
+    expect(result.isError).toBe(false)
+    const text = (result.content[0] as { type: 'text'; text: string }).text
+    expect(text.startsWith('[\n  [\n    [')).toBe(true)
+    expect(text).toContain('"leaf"')
+    expect(text.endsWith(']')).toBe(true)
+    expect(text.length).toBeLessThan(11_000)
   })
 
   it('short-circuits a pre-aborted outer signal before the code runtime', async () => {
@@ -855,7 +1031,10 @@ describe('the run_code dispatch bridge', () => {
     expect(result).toEqual({
       content: [{ type: 'text', text: 'Error: tool call aborted before dispatch' }],
       isError: true,
-      error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      error: {
+        message: 'tool call aborted before dispatch',
+        info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      },
     })
     expect(runtime.lastRequest).toBeUndefined()
     expect(calls).toEqual([])
@@ -873,7 +1052,10 @@ describe('the run_code dispatch bridge', () => {
     }
     const result = await runCode(ctx, 'program', { signal: controller.signal })
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'AbortError', code: 'ABORTED' })
+    expect(result.error).toEqual({
+      message: 'tool call aborted',
+      info: { name: 'AbortError', code: 'ABORTED' },
+    })
     expect((result.content[0] as { text: string }).text).toBe('Error: tool call aborted')
     expect(calls).toEqual([])
   })
diff --git a/packages/core/tools/tests/execution-mode.spec.ts b/packages/core/tools/tests/execution-mode.spec.ts
index 054eed65ed..54c4687c60 100644
--- a/packages/core/tools/tests/execution-mode.spec.ts
+++ b/packages/core/tools/tests/execution-mode.spec.ts
@@ -5,7 +5,7 @@ import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, {
-  defineTool,
+  defineContentToolFixture,
   type ToolDefinition,
   type ToolExecutionInput,
   type ToolExecutionMode,
@@ -27,7 +27,7 @@ function exec(name: string, args: unknown): ToolExecutionInput {
 describe('ToolRegistry.executionMode', () => {
   it('returns parallel only for an explicit true classifier', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'safe',
       description: 'parallel-safe',
       parameters: {},
@@ -39,7 +39,7 @@ describe('ToolRegistry.executionMode', () => {
 
   it('defaults to exclusive for a tool with no isConcurrencySafe declaration', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'plain',
       description: 'no declaration',
       parameters: {},
@@ -55,7 +55,7 @@ describe('ToolRegistry.executionMode', () => {
 
   it('returns exclusive when the classifier returns false for these args', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'rw',
       description: 'read or write',
       parameters: { mode: { type: 'string', required: true } },
@@ -66,9 +66,9 @@ describe('ToolRegistry.executionMode', () => {
     expect(ctx.tools.executionMode(exec('rw', { mode: 'write' }))).toEqual({ kind: 'exclusive' })
   })
 
-  it('classifies invalid defineTool arguments as exclusive without throwing', async () => {
+  it('classifies invalid defineContentToolFixture arguments as exclusive without throwing', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'needs-mode',
       description: 'requires mode',
       parameters: { mode: { type: 'string', required: true } },
@@ -84,8 +84,9 @@ describe('ToolRegistry.executionMode', () => {
       name: 'thrower',
       description: 'classifier throws',
       parameters: { type: 'object', properties: {} },
+      output: { schema: { type: 'null' }, render: () => [] },
       isConcurrencySafe() { throw new Error('boom') },
-      async execute() { return [] },
+      async execute() { return null },
     }
     ctx.tools.register(raw)
     expect(ctx.tools.executionMode(exec('thrower', {}))).toEqual({ kind: 'exclusive' })
@@ -97,8 +98,9 @@ describe('ToolRegistry.executionMode', () => {
       name: 'truthy',
       description: 'classifier returns a truthy string',
       parameters: { type: 'object', properties: {} },
+      output: { schema: { type: 'null' }, render: () => [] },
       isConcurrencySafe() { return 'yes' },
-      async execute() { return [] },
+      async execute() { return null },
     } as unknown as ToolDefinition
     ctx.tools.register(raw)
     expect(ctx.tools.executionMode(exec('truthy', {}))).toEqual({ kind: 'exclusive' })
@@ -111,8 +113,9 @@ describe('ToolRegistry.executionMode', () => {
       name: 'raw-safe',
       description: 'raw',
       parameters: { type: 'object', properties: {} },
+      output: { schema: { type: 'null' }, render: () => [] },
       isConcurrencySafe(args) { seen = args; return true },
-      async execute() { return [] },
+      async execute() { return null },
     })
     expect(ctx.tools.executionMode(exec('raw-safe', { anything: 1 }))).toEqual({ kind: 'parallel' })
     expect(seen).toEqual({ anything: 1 })
@@ -120,7 +123,7 @@ describe('ToolRegistry.executionMode', () => {
 
   it('isConcurrencySafe never reaches the model-facing schemas() projection', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'safe',
       description: 'parallel-safe',
       parameters: { x: { type: 'string', required: true } },
diff --git a/packages/core/tools/tests/execution-signal-types.spec.ts b/packages/core/tools/tests/execution-signal-types.spec.ts
index e0e030543f..dd878d648e 100644
--- a/packages/core/tools/tests/execution-signal-types.spec.ts
+++ b/packages/core/tools/tests/execution-signal-types.spec.ts
@@ -80,11 +80,15 @@ const inferredTool = defineTool({
   name: 'signal-inference',
   description: 'Pins contextual signal inference.',
   parameters: {},
+  output: {
+    schema: { type: 'null' },
+    render: () => [],
+  },
   async execute(_args, exec) {
     expectTypeOf(exec.signal).toEqualTypeOf<AbortSignal>()
     // @ts-expect-error -- defineTool contextually exposes a readonly signal.
     exec.signal = new AbortController().signal
-    return []
+    return null
   },
 })
 void inferredTool
diff --git a/packages/core/tools/tests/invariant.spec.ts b/packages/core/tools/tests/invariant.spec.ts
index ef795cce73..3752dc7321 100644
--- a/packages/core/tools/tests/invariant.spec.ts
+++ b/packages/core/tools/tests/invariant.spec.ts
@@ -27,6 +27,7 @@ const execution = (overrides: Partial<ToolExecution> = {}): ToolExecution => ({
 const outcome = (): ToolExecutionResult => Object.freeze({
   content: Object.freeze([{ type: 'text' as const, text: 'ok' }]) as never,
   isError: false,
+  value: null,
 })
 
 function emitResult(ctx: Context, exec: ToolExecution, result: ToolExecutionResult): void {
@@ -78,7 +79,7 @@ describe('tool-pipeline invariants', () => {
     expect(() => { emitResult(ctx, execution(), outcome()) }).toThrow(/execution must be frozen/)
 
     const exec = Object.freeze(execution())
-    expect(() => { emitResult(ctx, exec, { content: [], isError: false }) })
+    expect(() => { emitResult(ctx, exec, { content: [], isError: false, value: null }) })
       .toThrow(/outcome and content must be frozen/)
 
     const anonymous = Object.freeze(execution({ name: '' }))
diff --git a/packages/core/tools/tests/json-schema.spec.ts b/packages/core/tools/tests/json-schema.spec.ts
index 6fa895288e..fc29965c3b 100644
--- a/packages/core/tools/tests/json-schema.spec.ts
+++ b/packages/core/tools/tests/json-schema.spec.ts
@@ -1,304 +1,455 @@
+import { runInNewContext } from 'node:vm'
 import { describe, expect, it } from 'vitest'
 import {
-  assertSupportedOutputSchema,
-  OutputSchemaError,
-  validateStructuredValue,
-  type StructuredOutputSchema,
-} from '../src/json-schema.ts'
+  assertObjectJsonSchema,
+  assertSupportedJsonSchema,
+  JsonSchemaError,
+  validateJsonSchemaValue,
+  type JsonSchemaNode,
+  type ObjectJsonSchema,
+} from '../src/index.ts'
 
-/** Assert-and-narrow helper: the asserted schema, typed. */
-function asserted(schema: unknown): StructuredOutputSchema {
-  assertSupportedOutputSchema(schema)
+function asserted(schema: unknown): JsonSchemaNode {
+  assertSupportedJsonSchema(schema)
   return schema
 }
 
-/** The violations OutputSchemaError carries for a bad schema (throws if it passes). */
-function violationsOf(schema: unknown): string[] {
-  try {
-    assertSupportedOutputSchema(schema)
-  } catch (error: unknown) {
-    if (error instanceof OutputSchemaError) return error.violations
-    throw error
-  }
-  throw new Error('expected the schema to be rejected')
+function assertedObject(schema: unknown): ObjectJsonSchema {
+  assertObjectJsonSchema(schema)
+  return schema
 }
 
-describe('assertSupportedOutputSchema', () => {
-  it('accepts a representative subset schema (all supported keywords)', () => {
-    const schema = asserted({
-      type: 'object',
-      description: 'a finding',
-      title: 'Finding',
-      properties: {
-        file: { type: 'string', description: 'path' },
-        line: { type: 'integer' },
-        severity: { type: 'string', enum: ['low', 'high'] },
-        kind: { type: 'string', const: 'bug' },
-        score: { type: 'number' },
-        confirmed: { type: 'boolean' },
-        parent: { type: 'null' },
-        tags: { type: 'array', items: { type: 'string' } },
-        nested: {
-          type: 'object',
-          properties: { x: { type: 'number', default: 3, examples: [1, 2] } },
-          additionalProperties: false,
+function violationsOf(schema: unknown, objectRoot = false): string[] {
+  try {
+    if (objectRoot) assertObjectJsonSchema(schema)
+    else assertSupportedJsonSchema(schema)
+  } catch (error: unknown) {
+    if (error instanceof JsonSchemaError) return error.violations
+    throw error
+  }
+  throw new Error('expected schema rejection')
+}
+
+function recordWithForgedIntrinsicPrototype(
+  own: Record<string, unknown>,
+  inherited: Record<string, unknown> = {},
+  revoked = false,
+): Record<string, unknown> {
+  const prototype = Object.assign(Object.create(null) as Record<string, unknown>, inherited)
+  const ForgedObject = function ForgedObject(): void {}
+  Object.defineProperty(ForgedObject, 'name', { value: 'Object' })
+  ForgedObject.prototype = prototype
+  const constructor = revoked ? Proxy.revocable(ForgedObject, {}) : undefined
+  if (constructor !== undefined) constructor.revoke()
+  Object.defineProperty(prototype, 'constructor', { value: constructor?.proxy ?? ForgedObject })
+  return Object.assign(Object.create(prototype) as Record<string, unknown>, own)
+}
+
+describe('the enforced raw JSON Schema subset', () => {
+  it('accepts every JSON root and every supported node', () => {
+    for (const schema of [
+      { type: 'string' },
+      { type: 'number' },
+      { type: 'integer' },
+      { type: 'boolean' },
+      { type: 'null' },
+      { type: 'array', items: { type: 'string' } },
+      {
+        type: 'object',
+        properties: {
+          nested: { type: 'object', properties: {}, additionalProperties: false },
+          free: {},
         },
-        anything: { type: 'array' },
+        required: ['nested'],
+        additionalProperties: true,
       },
-      required: ['file', 'line'],
-      additionalProperties: true,
-    })
-    expect(schema.type).toBe('object')
+      { oneOf: [{ type: 'string' }, { type: 'number' }] },
+      { description: 'any JSON', title: 'JSON', default: null, examples: [1, 'x'] },
+    ]) {
+      expect(() => { assertSupportedJsonSchema(schema) }, JSON.stringify(schema)).not.toThrow()
+    }
   })
 
-  it('rejects a non-object root (scalar/array-rooted schemas)', () => {
-    expect(violationsOf({ type: 'string' })).toEqual(['schema.type must be "object" (structured output is object-rooted)'])
-    expect(violationsOf({ type: 'array', items: { type: 'string' } }))
-      .toContain('schema.type must be "object" (structured output is object-rooted)')
+  it('retains an object-root guard only at consumers that need it', () => {
+    expect(assertedObject({ type: 'object' }).type).toBe('object')
+    for (const schema of [{}, { type: 'string' }, { type: 'array' }, { oneOf: [{ type: 'string' }, { type: 'null' }] }]) {
+      expect(violationsOf(schema, true)).toEqual(['schema.type must be "object" (structured output is object-rooted)'])
+    }
   })
 
-  it('rejects non-object schema nodes and missing/unknown type', () => {
-    expect(violationsOf('nope')).toEqual(['schema must be a schema object'])
+  it('rejects non-schema nodes, unknown types, and type arrays', () => {
     expect(violationsOf(null)).toEqual(['schema must be a schema object'])
     expect(violationsOf([])).toEqual(['schema must be a schema object'])
-    expect(violationsOf({})).toEqual(['schema.type must be one of object/array/string/number/integer/boolean/null'])
+    expect(violationsOf('no')).toEqual(['schema must be a schema object'])
     expect(violationsOf({ type: 'tuple' })[0]).toMatch(/type must be one of/)
-    expect(violationsOf({ type: 'object', properties: { a: 'str' } })).toEqual(['schema.properties.a must be a schema object'])
-  })
-
-  it('rejects type ARRAYS with a dedicated message', () => {
     expect(violationsOf({ type: ['string', 'null'] }))
       .toEqual(['schema.type must be a single type string (type arrays are not supported)'])
   })
 
-  it('rejects unsupported constraint keywords loudly (never accepted-then-ignored)', () => {
-    for (const keyword of ['oneOf', 'anyOf', 'allOf', 'not', 'pattern', 'minimum', 'maxLength', '$ref']) {
-      const bad = violationsOf({ type: 'object', [keyword]: [] })
-      expect(bad.some(v => v.includes(`schema.${keyword} is not a supported keyword`))).toBe(true)
-    }
+  it('enforces oneOf vocabulary and its minimum branch count', () => {
+    expect(violationsOf({ oneOf: [] })).toEqual(['schema.oneOf must be an array of at least two schemas'])
+    expect(violationsOf({ oneOf: [{}] })).toEqual(['schema.oneOf must be an array of at least two schemas'])
+    expect(violationsOf({ oneOf: 'x' })).toEqual(['schema.oneOf must be an array of at least two schemas'])
+    expect(violationsOf({ type: 'string', oneOf: [{}, {}] }))
+      .toEqual(['schema cannot declare both type and oneOf'])
+    expect(violationsOf({ oneOf: [{ type: 'string' }, { type: 'number' }], items: {} }))
+      .toEqual(['schema.items is not supported beside oneOf'])
+    expect(violationsOf({ oneOf: [{ type: 'string' }, { type: 'weird' }] })[0])
+      .toContain('schema.oneOf[1].type')
+    const sparse = new Array<unknown>(2)
+    sparse[0] = { type: 'string' }
+    expect(violationsOf({ oneOf: sparse }))
+      .toEqual(['schema.oneOf must be an array of at least two schemas'])
+    const compensatedSparse = new Array<unknown>(2)
+    compensatedSparse[0] = { type: 'string' }
+    Object.defineProperty(compensatedSparse, 'extra', { value: true })
+    expect(violationsOf({ oneOf: compensatedSparse }))
+      .toEqual(['schema.oneOf must be an array of at least two schemas'])
+    class ExoticBranches extends Array<unknown> {}
+    expect(violationsOf({ oneOf: new ExoticBranches({ type: 'string' }, { type: 'null' }) }))
+      .toEqual(['schema.oneOf must be an array of at least two schemas'])
+    const explosiveArray = new Proxy([{ type: 'string' }, { type: 'null' }], {
+      getPrototypeOf() { throw new Error('prototype trap') },
+    })
+    expect(violationsOf({ oneOf: explosiveArray }))
+      .toEqual(['schema.oneOf must be an array of at least two schemas'])
   })
 
-  it('reports EVERY violation, not just the first', () => {
-    const bad = violationsOf({
+  it('rejects unknown and misplaced keywords without accepted-then-ignored behavior', () => {
+    for (const keyword of ['anyOf', 'allOf', 'not', 'pattern', 'minimum', 'maxLength', '$ref']) {
+      expect(violationsOf({ type: 'object', [keyword]: [] })[0]).toContain(`schema.${keyword} is not a supported keyword`)
+    }
+    expect(violationsOf({ type: 'object', items: {} }))
+      .toEqual(['schema.items is not supported on type "object"'])
+    expect(violationsOf({ type: 'array', properties: {} }))
+      .toEqual(['schema.properties is not supported on type "array"'])
+    expect(violationsOf({ type: 'object', enum: ['x'] }))
+      .toEqual(['schema.enum is not supported on type "object"'])
+    expect(violationsOf({ type: 'array', const: null }))
+      .toEqual(['schema.const is not supported on type "array"'])
+    expect(violationsOf({ properties: {}, required: [], additionalProperties: true, items: {}, enum: [], const: null }))
+      .toEqual([
+        'schema.properties requires type or oneOf',
+        'schema.required requires type or oneOf',
+        'schema.additionalProperties requires type or oneOf',
+        'schema.items requires type or oneOf',
+        'schema.enum requires type or oneOf',
+        'schema.const requires type or oneOf',
+      ])
+  })
+
+  it('reports every independent schema violation', () => {
+    expect(violationsOf({
       type: 'object',
       pattern: 'x',
       properties: { a: { type: 'weird' }, b: { type: 'string', minimum: 1 } },
-    })
-    expect(bad.length).toBe(3)
+    })).toHaveLength(3)
   })
 
-  it('rejects keywords on the wrong type (items on object, properties on string, enum on object)', () => {
-    expect(violationsOf({ type: 'object', items: { type: 'string' } }))
-      .toEqual(['schema.items is not supported on type "object"'])
-    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', properties: {} } } }))
-      .toEqual(['schema.properties.a.properties is not supported on type "string"'])
-    expect(violationsOf({ type: 'object', enum: [1] }))
-      .toEqual(['schema.enum is not supported on type "object"'])
-    expect(violationsOf({ type: 'object', properties: { a: { type: 'array', const: 1 } } }))
-      .toEqual(['schema.properties.a.const is not supported on type "array"'])
-  })
-
-  it('validates required: must be string[] naming declared properties', () => {
-    expect(violationsOf({ type: 'object', required: 'file' }))
+  it('validates object properties, required names, and openness', () => {
+    expect(violationsOf({ type: 'object', properties: [] }))
+      .toEqual(['schema.properties must be an object of schemas'])
+    expect(violationsOf({ type: 'object', properties: { a: 'x' } }))
+      .toEqual(['schema.properties.a must be a schema object'])
+    expect(violationsOf({ type: 'object', required: 'a' }))
       .toEqual(['schema.required must be an array of strings'])
     expect(violationsOf({ type: 'object', required: [1] }))
       .toEqual(['schema.required must be an array of strings'])
-    expect(violationsOf({ type: 'object', properties: { a: { type: 'string' } }, required: ['b'] }))
-      .toEqual(['schema.required names "b" which is not in properties'])
-    expect(violationsOf({ type: 'object', required: ['a'] }))
-      .toEqual(['schema.required names "a" which is not in properties'])
-  })
-
-  it('validates additionalProperties must be boolean and enum/const must be scalars', () => {
-    expect(violationsOf({ type: 'object', additionalProperties: {} }))
+    expect(violationsOf({ type: 'object', properties: {}, required: ['missing'] }))
+      .toEqual(['schema.required names "missing" which is not in properties'])
+    expect(violationsOf({ type: 'object', additionalProperties: 'yes' }))
       .toEqual(['schema.additionalProperties must be a boolean'])
-    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: [] } } }))
-      .toEqual(['schema.properties.a.enum must be a non-empty array of scalars'])
-    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: [{}] } } }))
-      .toEqual(['schema.properties.a.enum must be a non-empty array of scalars'])
-    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: 'x' } } }))
-      .toEqual(['schema.properties.a.enum must be a non-empty array of scalars'])
-    expect(violationsOf({ type: 'object', properties: { a: { type: 'number', enum: [Number.NaN] } } }))
-      .toEqual(['schema.properties.a.enum must be a non-empty array of scalars'])
-    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', const: {} } } }))
-      .toEqual(['schema.properties.a.const must be a scalar'])
+    expect(violationsOf({ type: 'object', properties: undefined }))
+      .toEqual(['schema.properties must be an object of schemas'])
+    expect(violationsOf({ type: 'object', properties: undefined, required: ['missing'] }))
+      .toEqual([
+        'schema.properties must be an object of schemas',
+        'schema.required names "missing" which is not in properties',
+      ])
+    const sparseRequired = new Array<string>(1)
+    expect(violationsOf({ type: 'object', required: sparseRequired }))
+      .toEqual(['schema.required must be an array of strings'])
   })
 
-  it('rejects non-string description/title and non-JSON annotation payloads', () => {
-    expect(violationsOf({ type: 'object', description: 7 }))
-      .toEqual(['schema.description must be a string'])
-    expect(violationsOf({ type: 'object', title: 7 }))
-      .toEqual(['schema.title must be a string'])
-    expect(violationsOf({ type: 'object', default: () => 1 }))
-      .toEqual(['schema.default annotation must be JSON data'])
-    expect(violationsOf({ type: 'object', examples: [undefined] }))
-      .toEqual(['schema.examples annotation must be JSON data'])
-    expect(violationsOf({ type: 'object', examples: [Number.POSITIVE_INFINITY] }))
-      .toEqual(['schema.examples annotation must be JSON data'])
-    // A cyclic annotation payload is caught by the JSON-data walk.
-    const cyclicAnnotation: Record<string, unknown> = {}
-    cyclicAnnotation.self = cyclicAnnotation
-    expect(violationsOf({ type: 'object', default: cyclicAnnotation }))
-      .toEqual(['schema.default annotation must be JSON data'])
-    // Object/array annotations that ARE JSON data pass.
-    asserted({ type: 'object', default: { a: [1, 'x', null, true] } })
+  it('requires type-correct scalar enum and const values', () => {
+    for (const schema of [
+      { type: 'string', enum: ['a'], const: 'a' },
+      { type: 'number', enum: [1.5], const: 1.5 },
+      { type: 'integer', enum: [1], const: 1 },
+      { type: 'boolean', enum: [true], const: true },
+      { type: 'null', enum: [null], const: null },
+    ]) {
+      expect(() => { assertSupportedJsonSchema(schema) }, JSON.stringify(schema)).not.toThrow()
+    }
+
+    expect(violationsOf({ type: 'string', enum: [] }))
+      .toEqual(['schema.enum must be a non-empty array of string values'])
+    expect(violationsOf({ type: 'number', enum: ['1'] }))
+      .toEqual(['schema.enum must be a non-empty array of number values'])
+    expect(violationsOf({ type: 'integer', enum: [1.5] }))
+      .toEqual(['schema.enum must be a non-empty array of integer values'])
+    expect(violationsOf({ type: 'number', enum: [Number.NaN] }))
+      .toEqual(['schema.enum must be a non-empty array of number values'])
+    expect(violationsOf({ type: 'number', const: -0 }))
+      .toEqual(['schema.const must be a number value'])
+    expect(violationsOf({ type: 'boolean', const: 1 }))
+      .toEqual(['schema.const must be a boolean value'])
+    expect(violationsOf({ type: 'string', enum: undefined }))
+      .toEqual(['schema.enum must be a non-empty array of string values'])
+    expect(violationsOf({ type: 'string', enum: ['a'], const: 'b' }))
+      .toEqual(['schema.const must be one of schema.enum when both are declared'])
+    const sparseEnum = new Array<string>(1)
+    expect(violationsOf({ type: 'string', enum: sparseEnum }))
+      .toEqual(['schema.enum must be a non-empty array of string values'])
   })
 
-  it('rejects a circular schema instead of recursing forever', () => {
-    const node: Record<string, unknown> = { type: 'object' }
-    node.properties = { self: node }
-    expect(violationsOf(node)).toEqual(['schema.properties.self is circular'])
+  it('validates annotation types and lossless JSON payloads', () => {
+    expect(violationsOf({ description: 1 })).toEqual(['schema.description must be a string'])
+    expect(violationsOf({ title: 1 })).toEqual(['schema.title must be a string'])
+    for (const [key, value] of [
+      ['default', undefined],
+      ['examples', [undefined]],
+      ['default', Number.POSITIVE_INFINITY],
+      ['examples', new Date(0)],
+    ] as const) {
+      expect(violationsOf({ [key]: value })).toEqual([`schema.${key} annotation must be lossless JSON data`])
+    }
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+    expect(violationsOf({ default: cyclic }))
+      .toEqual(['schema.default annotation must be lossless JSON data'])
+
+    const explosive = new Proxy({}, {
+      ownKeys() { throw new Error('annotation trap') },
+    })
+    expect(violationsOf({ examples: explosive }))
+      .toEqual(['schema.examples annotation must be lossless JSON data'])
+    expect(violationsOf({ default: Object.defineProperty({}, 'hidden', { value: true }) }))
+      .toEqual(['schema.default annotation must be lossless JSON data'])
+    expect(violationsOf({ default: { [Symbol('hidden')]: true } }))
+      .toEqual(['schema.default annotation must be lossless JSON data'])
   })
 
-  it('accepts the same subschema object reused in two SIBLING positions (a DAG, not a cycle)', () => {
+  it('accepts lossless annotation containers from another JavaScript realm', () => {
+    const schema = runInNewContext(`({
+      type: 'object',
+      properties: { value: { type: 'string', enum: ['x'] } },
+      required: ['value'],
+      default: { x: 1 },
+      examples: [[{ ok: true }]],
+    })`) as unknown
+
+    expect(() => { assertSupportedJsonSchema(schema) }).not.toThrow()
+  })
+
+  it('rejects cyclic/exotic schema structure but permits sibling reuse', () => {
+    const cyclic: Record<string, unknown> = { type: 'object' }
+    cyclic.properties = { self: cyclic }
+    expect(violationsOf(cyclic)).toEqual(['schema.properties.self is circular'])
     const leaf = { type: 'string' }
-    asserted({ type: 'object', properties: { a: leaf, b: leaf } })
+    expect(() => { assertSupportedJsonSchema({ type: 'object', properties: { a: leaf, b: leaf } }) }).not.toThrow()
+    expect(violationsOf({ type: 'object', properties: new Map() }))
+      .toEqual(['schema.properties must be an object of schemas'])
+    expect(violationsOf({ type: 'object', properties: { at: new Date(0) } }))
+      .toEqual(['schema.properties.at must be a schema object'])
+
+    const forgedSchema = recordWithForgedIntrinsicPrototype(
+      { type: 'object' },
+      { oneOf: [{ type: 'string' }, { type: 'null' }] },
+    )
+    expect(violationsOf(forgedSchema)).toEqual(['schema must be a schema object'])
+    expect(violationsOf(forgedSchema, true)).toEqual(['schema must be a schema object'])
+    expect(violationsOf(recordWithForgedIntrinsicPrototype({ type: 'string' }, {}, true)))
+      .toEqual(['schema must be a schema object'])
+    const prototypeWithoutConstructor = Object.create(null) as object
+    expect(violationsOf(Object.create(prototypeWithoutConstructor) as unknown))
+      .toEqual(['schema must be a schema object'])
+    expect(violationsOf(Object.defineProperty({ type: 'string' }, 'hidden', { value: true })))
+      .toEqual(['schema must be a schema object'])
+    expect(violationsOf({ type: 'string', [Symbol('hidden')]: true }))
+      .toEqual(['schema must be a schema object'])
+    expect(violationsOf(new Proxy({}, {
+      getPrototypeOf() { throw new Error('prototype trap') },
+    }))).toEqual(['schema must be a schema object'])
+    expect(violationsOf(new Proxy({}, {
+      ownKeys() { throw new Error('keys trap') },
+    }))).toEqual(['schema must be a schema object'])
   })
 
-  it('required cannot be satisfied by INHERITED names — `toString` is not a declared property', () => {
-    // `'toString' in {}` is true via Object.prototype; the declared-property
-    // contract must be an own-property check.
+  it('asserts deeply nested raw unions without using the JavaScript call stack', () => {
+    const depth = 5_000
+    let schema: JsonSchemaNode = { type: 'string' }
+    for (let index = 0; index < depth; index++) schema = { oneOf: [schema, { type: 'null' }] }
+
+    expect(() => { assertSupportedJsonSchema(schema) }).not.toThrow()
+  })
+
+  it('uses own-property semantics for required declarations', () => {
     expect(violationsOf({ type: 'object', properties: {}, required: ['toString'] }))
       .toEqual(['schema.required names "toString" which is not in properties'])
   })
-
-  it('rejects exotic host objects where the subset expects plain JSON structure', () => {
-    // A Map as `properties` has no own enumerable entries: structurally it
-    // would read as "no properties" and serialize to {} — lossy, not loud.
-    expect(violationsOf({ type: 'object', properties: new Map() }))
-      .toEqual(['schema.properties must be an object of schemas'])
-    // A Date node is not a schema object even though Object.values(date) is [].
-    expect(violationsOf({ type: 'object', properties: { at: new Date(0) } }))
-      .toEqual(['schema.properties.at must be a schema object'])
-  })
-
-  it('rejects exotic annotation payloads that would serialize lossily', () => {
-    expect(violationsOf({ type: 'object', default: new Date(0) }))
-      .toEqual(['schema.default annotation must be JSON data'])
-    expect(violationsOf({ type: 'object', examples: [new Map()] }))
-      .toEqual(['schema.examples annotation must be JSON data'])
-  })
 })
 
-describe('validateStructuredValue', () => {
-  const schema = asserted({
-    type: 'object',
-    properties: {
-      file: { type: 'string' },
-      line: { type: 'integer' },
-      score: { type: 'number' },
-      confirmed: { type: 'boolean' },
-      parent: { type: 'null' },
-      severity: { type: 'string', enum: ['low', 'high'] },
-      kind: { type: 'string', const: 'bug' },
-      tags: { type: 'array', items: { type: 'string' } },
-      free: { type: 'array' },
-      nested: { type: 'object', properties: { x: { type: 'number' } }, required: ['x'], additionalProperties: false },
-    },
-    required: ['file'],
+describe('validateJsonSchemaValue', () => {
+  it('validates scalar, array, object, and null roots', () => {
+    expect(validateJsonSchemaValue(asserted({ type: 'string' }), 'x')).toEqual([])
+    expect(validateJsonSchemaValue(asserted({ type: 'number' }), 1.5)).toEqual([])
+    expect(validateJsonSchemaValue(asserted({ type: 'integer' }), 2)).toEqual([])
+    expect(validateJsonSchemaValue(asserted({ type: 'boolean' }), true)).toEqual([])
+    expect(validateJsonSchemaValue(asserted({ type: 'null' }), null)).toEqual([])
+    expect(validateJsonSchemaValue(asserted({ type: 'array', items: { type: 'string' } }), ['x'])).toEqual([])
+    expect(validateJsonSchemaValue(asserted({ type: 'object' }), { x: 1 })).toEqual([])
   })
 
-  it('accepts a fully valid value (empty violations)', () => {
-    expect(validateStructuredValue(schema, {
-      file: 'a.ts', line: 3, score: 0.5, confirmed: true, parent: null,
-      severity: 'high', kind: 'bug', tags: ['x'], free: [1, { any: true }], nested: { x: 1 },
-    })).toEqual([])
+  it('rejects wrong scalar types and lossy numbers', () => {
+    expect(validateJsonSchemaValue(asserted({ type: 'string' }), 1)).toEqual(['"value" must be a string'])
+    expect(validateJsonSchemaValue(asserted({ type: 'number' }), '1')).toEqual(['"value" must be a number'])
+    expect(validateJsonSchemaValue(asserted({ type: 'number' }), Number.NaN)).toEqual(['"value" must be a finite JSON number'])
+    expect(validateJsonSchemaValue(asserted({ type: 'number' }), -0)).toEqual(['"value" must be a finite JSON number'])
+    expect(validateJsonSchemaValue(asserted({ type: 'integer' }), 1.5)).toEqual(['"value" must be an integer'])
+    expect(validateJsonSchemaValue(asserted({ type: 'boolean' }), 'true')).toEqual(['"value" must be a boolean'])
+    expect(validateJsonSchemaValue(asserted({ type: 'null' }), 0)).toEqual(['"value" must be null'])
   })
 
-  it('reports missing required and wrong root type', () => {
-    expect(validateStructuredValue(schema, {})).toEqual(['missing required property "value.file"'])
-    expect(validateStructuredValue(schema, 'nope')).toEqual(['"value" must be an object'])
-    expect(validateStructuredValue(schema, [])).toEqual(['"value" must be an object'])
+  it('enforces scalar enum and const together', () => {
+    const schema = asserted({ type: 'string', enum: ['a', 'b'], const: 'a' })
+    expect(validateJsonSchemaValue(schema, 'a')).toEqual([])
+    expect(validateJsonSchemaValue(schema, 'c')).toEqual(['"value" must be one of ["a","b"]'])
+    expect(validateJsonSchemaValue(schema, 'b')).toEqual(['"value" must be "a"'])
   })
 
-  it('type-checks every scalar branch with path-qualified messages', () => {
-    expect(validateStructuredValue(schema, { file: 1 })).toEqual(['"value.file" must be a string'])
-    expect(validateStructuredValue(schema, { file: 'a', line: 1.5 })).toEqual(['"value.line" must be an integer'])
-    expect(validateStructuredValue(schema, { file: 'a', line: 'x' })).toEqual(['"value.line" must be an integer'])
-    expect(validateStructuredValue(schema, { file: 'a', score: 'x' })).toEqual(['"value.score" must be a finite number'])
-    expect(validateStructuredValue(schema, { file: 'a', score: Number.NaN })).toEqual(['"value.score" must be a finite number'])
-    expect(validateStructuredValue(schema, { file: 'a', confirmed: 'yes' })).toEqual(['"value.confirmed" must be a boolean'])
-    expect(validateStructuredValue(schema, { file: 'a', parent: 0 })).toEqual(['"value.parent" must be null'])
+  it('validates object requiredness, nested values, and raw open defaults', () => {
+    const open = asserted({
+      type: 'object',
+      properties: {
+        file: { type: 'string' },
+        nested: {
+          type: 'object',
+          properties: { line: { type: 'integer' } },
+          required: ['line'],
+          additionalProperties: false,
+        },
+      },
+      required: ['file'],
+    })
+    expect(validateJsonSchemaValue(open, { file: 'a', extra: [1], nested: { line: 2 } })).toEqual([])
+    expect(validateJsonSchemaValue(open, { nested: { line: 1 } }))
+      .toEqual(['missing required property "value.file"'])
+    expect(validateJsonSchemaValue(open, { file: 1, nested: {} })).toEqual([
+      '"value.file" must be a string',
+      'missing required property "value.nested.line"',
+    ])
+    expect(validateJsonSchemaValue(open, { file: 'a', nested: { line: 1, extra: true } }))
+      .toEqual(['"value.nested.extra" is not a declared property (additionalProperties: false)'])
+    expect(validateJsonSchemaValue(open, 'x')).toEqual(['"value" must be an object'])
   })
 
-  it('enforces enum membership and const equality', () => {
-    expect(validateStructuredValue(schema, { file: 'a', severity: 'mid' }))
-      .toEqual(['"value.severity" must be one of ["low","high"]'])
-    expect(validateStructuredValue(schema, { file: 'a', kind: 'feature' }))
-      .toEqual(['"value.kind" must be "bug"'])
+  it('treats present undefined as missing when required, then rejects other lossy objects', () => {
+    const required = asserted({ type: 'object', properties: { x: {} }, required: ['x'] })
+    expect(validateJsonSchemaValue(required, { x: undefined }))
+      .toEqual(['missing required property "value.x"'])
+    expect(validateJsonSchemaValue(asserted({ type: 'object' }), { x: undefined }))
+      .toEqual(['"value" must be a lossless JSON object'])
+    expect(validateJsonSchemaValue(asserted({ type: 'object' }), new Date(0)))
+      .toEqual(['"value" must be an object'])
   })
 
-  it('checks arrays per index; an items-less array accepts anything', () => {
-    expect(validateStructuredValue(schema, { file: 'a', tags: 'x' })).toEqual(['"value.tags" must be an array'])
-    expect(validateStructuredValue(schema, { file: 'a', tags: ['ok', 2] })).toEqual(['"value.tags[1]" must be a string'])
-    expect(validateStructuredValue(schema, { file: 'a', free: [{ deep: [1] }, null] })).toEqual([])
+  it('returns a violation instead of throwing for a container with a hostile getter', () => {
+    const value = Object.defineProperty({}, 'answer', {
+      enumerable: true,
+      get() { throw new Error('getter exploded') },
+    })
+    const schema = asserted({
+      type: 'object',
+      properties: { answer: { type: 'integer' } },
+      required: ['answer'],
+    })
+
+    expect(validateJsonSchemaValue(schema, value))
+      .toEqual(['"value" must be a lossless JSON value'])
   })
 
-  it('recurses into nested objects: required + additionalProperties: false', () => {
-    expect(validateStructuredValue(schema, { file: 'a', nested: {} }))
-      .toEqual(['missing required property "value.nested.x"'])
-    expect(validateStructuredValue(schema, { file: 'a', nested: { x: 1, y: 2 } }))
-      .toEqual(['"value.nested.y" is not a declared property (additionalProperties: false)'])
-    expect(validateStructuredValue(schema, { file: 'a', nested: 3 }))
-      .toEqual(['"value.nested" must be an object'])
+  it('validates dense arrays per index and rejects lossy arrays', () => {
+    const schema = asserted({ type: 'array', items: { type: 'integer' } })
+    expect(validateJsonSchemaValue(schema, [1, 2])).toEqual([])
+    expect(validateJsonSchemaValue(schema, runInNewContext('[1, 2]'))).toEqual([])
+    expect(validateJsonSchemaValue(schema, [1, 1.5])).toEqual(['"value[1]" must be an integer'])
+    expect(validateJsonSchemaValue(schema, 'x')).toEqual(['"value" must be an array'])
+    const sparse: number[] = []
+    sparse.length = 2
+    sparse[0] = 1
+    expect(validateJsonSchemaValue(schema, sparse)).toEqual(['"value" must be a dense lossless JSON array'])
   })
 
-  it('a required key present-but-undefined counts as missing', () => {
-    expect(validateStructuredValue(schema, { file: undefined })).toEqual(['missing required property "value.file"'])
+  it('validates exact-one oneOf semantics, including overlap', () => {
+    const disjoint = asserted({ oneOf: [{ type: 'string' }, { type: 'number' }] })
+    expect(validateJsonSchemaValue(disjoint, 'x')).toEqual([])
+    expect(validateJsonSchemaValue(disjoint, null))
+      .toEqual(['"value" must match exactly one oneOf branch (matched 0)'])
+    const overlap = asserted({ oneOf: [{ type: 'number' }, { type: 'integer' }] })
+    expect(validateJsonSchemaValue(overlap, 1))
+      .toEqual(['"value" must match exactly one oneOf branch (matched 2)'])
+    expect(validateJsonSchemaValue(overlap, 1.5)).toEqual([])
   })
 
-  it('inherited properties satisfy nothing: required, additionalProperties, and recursion are own-property only', () => {
-    // required: ['toString'] must NOT be satisfied by Object.prototype.toString.
-    expect(validateStructuredValue(
+  it('validates deeply nested exact-one unions without using the JavaScript call stack', () => {
+    const depth = 5_000
+    let schema: JsonSchemaNode = { type: 'string' }
+    for (let index = 0; index < depth; index++) schema = { oneOf: [schema, { type: 'null' }] }
+    assertSupportedJsonSchema(schema)
+
+    expect(validateJsonSchemaValue(schema, 'leaf')).toEqual([])
+    expect(validateJsonSchemaValue(schema, 42))
+      .toEqual(['"value" must match exactly one oneOf branch (matched 0)'])
+  })
+
+  it('an unconstrained schema accepts only lossless JSON values', () => {
+    const anyJson = asserted({})
+    for (const value of [null, true, 1, 'x', [1], { x: null }]) {
+      expect(validateJsonSchemaValue(anyJson, value), JSON.stringify(value)).toEqual([])
+    }
+    for (const value of [undefined, () => 1, Number.POSITIVE_INFINITY, -0, new Map()]) {
+      expect(validateJsonSchemaValue(anyJson, value)).toEqual(['"value" must be a lossless JSON value'])
+    }
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+    expect(validateJsonSchemaValue(anyJson, cyclic)).toEqual(['"value" must be a lossless JSON value'])
+    const explosive = new Proxy({}, {
+      ownKeys() { throw new Error('value trap') },
+    })
+    expect(validateJsonSchemaValue(anyJson, explosive)).toEqual(['"value" must be a lossless JSON value'])
+  })
+
+  it('uses own properties for requiredness, recursion, and closed-object checks', () => {
+    expect(validateJsonSchemaValue(
       asserted({ type: 'object', properties: { toString: { type: 'string' } }, required: ['toString'] }),
       {},
     )).toEqual(['missing required property "value.toString"'])
-    // additionalProperties: false must flag an OWN `toString` key even though
-    // `'toString' in properties` is true via the prototype.
-    expect(validateStructuredValue(
-      asserted({ type: 'object', additionalProperties: false }),
-      { toString: 1 },
-    )).toEqual(['"value.toString" is not a declared property (additionalProperties: false)'])
-    // A declared property the value does NOT carry must not be validated
-    // against the value's INHERITED member (constructor is a function on
-    // every plain object's prototype, not a carried property).
-    expect(validateStructuredValue(
+    expect(validateJsonSchemaValue(asserted({ type: 'object', additionalProperties: false }), { toString: 1 }))
+      .toEqual(['"value.toString" is not a declared property (additionalProperties: false)'])
+    expect(validateJsonSchemaValue(
       asserted({ type: 'object', properties: { constructor: { type: 'string' } } }),
       {},
     )).toEqual([])
+
+    const inheritedUnion = Object.assign(
+      Object.create({ oneOf: [{ type: 'string' }, { type: 'null' }] }) as JsonSchemaNode,
+      { type: 'object' as const },
+    )
+    expect(validateJsonSchemaValue(inheritedUnion, {})).toEqual([])
+    expect(validateJsonSchemaValue(inheritedUnion, 'x')).toEqual(['"value" must be an object'])
+    expect(validateJsonSchemaValue(
+      { type: 'object', properties: undefined } as unknown as JsonSchemaNode,
+      {},
+    )).toEqual([])
+    expect(validateJsonSchemaValue(
+      { type: 'object', required: undefined } as unknown as JsonSchemaNode,
+      {},
+    )).toEqual([])
   })
 
-  it('a non-plain object value is not an object in the JSON sense', () => {
-    expect(validateStructuredValue(asserted({ type: 'object' }), new Date(0)))
-      .toEqual(['"value" must be an object'])
-  })
-
-  it('collects multiple violations across branches in one pass', () => {
-    expect(validateStructuredValue(schema, { line: 'x', severity: 'mid' })).toEqual([
-      'missing required property "value.file"',
-      '"value.line" must be an integer',
-      '"value.severity" must be one of ["low","high"]',
-    ])
-  })
-
-  it('null-typed const/enum work through the scalar path', () => {
-    const nullish = asserted({ type: 'object', properties: { a: { type: 'null', const: null } } })
-    expect(validateStructuredValue(nullish, { a: null })).toEqual([])
-  })
-
-  it('rejects a non-object properties value in the schema walk', () => {
-    expect(violationsOf({ type: 'object', properties: [] }))
-      .toEqual(['schema.properties must be an object of schemas'])
-  })
-
-  it('an object schema without properties/required only type-checks its value', () => {
-    const bare = asserted({ type: 'object' })
-    expect(validateStructuredValue(bare, { any: ['thing'] })).toEqual([])
-    expect(validateStructuredValue(bare, 7)).toEqual(['"value" must be an object'])
-  })
-
-  it('validateStructuredValue throws on a type the assert would never let through (assertNever backstop)', () => {
-    const forged = { type: 'tuple' } as unknown as StructuredOutputSchema
-    expect(() => validateStructuredValue(forged, 1)).toThrow(/tuple/)
+  it('keeps assertNever as a forged-schema backstop', () => {
+    const forged = { type: 'tuple' } as unknown as JsonSchemaNode
+    expect(() => validateJsonSchemaValue(forged, 1)).toThrow(/tuple/)
   })
 })
diff --git a/packages/core/tools/tests/properties.spec.ts b/packages/core/tools/tests/properties.spec.ts
index 51b49fccd4..e04e9f5c5b 100644
--- a/packages/core/tools/tests/properties.spec.ts
+++ b/packages/core/tools/tests/properties.spec.ts
@@ -1,61 +1,92 @@
 /**
  * Property-based tests for the tool-schema DSL (the property-testing Agent Note), including
- * the the property-testing ↔ runtime-validation composition composition: generated args that satisfy a SchemaSpec must
+ * the property-testing ↔ runtime-validation composition: generated args that satisfy a ParameterSchemaSpec must
  * pass validateArgs, and targeted corruptions must be rejected. This closes the
  * validator/InferArgs drift risk noted in the arg-validation Agent Note.
  */
 
 import { describe, expect, it } from 'vitest'
 import fc from 'fast-check'
-import { schemaSpecToJsonSchema, validateArgs } from '@deepseek-ai/dsh-tools'
-import type { SchemaProp, SchemaSpec } from '@deepseek-ai/dsh-tools'
+import { isJsonValue } from '@deepseek-ai/dsh-session'
+import { parameterSchemaSpecToJsonSchema, validateArgs } from '@deepseek-ai/dsh-tools'
+import type { ParameterPropertySpec, ParameterSchemaSpec, ValueSchemaSpec } from '@deepseek-ai/dsh-tools'
+
+/** Remove parameter-only requiredness before nesting a schema as an array item. */
+function asValueSchema(prop: ParameterPropertySpec): ValueSchemaSpec {
+  const { required: _required, ...schema } = prop
+  return schema
+}
 
 // A leaf prop arbitrary (no nesting) with optional required/enum.
-function leafPropArb(): fc.Arbitrary<SchemaProp> {
+function leafPropArb(): fc.Arbitrary<ParameterPropertySpec> {
   return fc.oneof(
-    fc.record({ required: fc.boolean() }).map(({ required }): SchemaProp => ({ type: 'string', ...required ? { required: true } : {} })),
-    fc.record({ required: fc.boolean() }).map(({ required }): SchemaProp => ({ type: 'number', ...required ? { required: true } : {} })),
-    fc.record({ required: fc.boolean() }).map(({ required }): SchemaProp => ({ type: 'boolean', ...required ? { required: true } : {} })),
+    fc.record({ required: fc.boolean() }).map(({ required }): ParameterPropertySpec => ({ type: 'string', ...required ? { required: true } : {} })),
+    fc.record({ required: fc.boolean() }).map(({ required }): ParameterPropertySpec => ({ type: 'number', ...required ? { required: true } : {} })),
+    fc.record({ required: fc.boolean() }).map(({ required }): ParameterPropertySpec => ({ type: 'integer', ...required ? { required: true } : {} })),
+    fc.record({ required: fc.boolean() }).map(({ required }): ParameterPropertySpec => ({ type: 'boolean', ...required ? { required: true } : {} })),
+    fc.record({ required: fc.boolean() }).map(({ required }): ParameterPropertySpec => ({ type: 'null', ...required ? { required: true } : {} })),
+    fc.record({ required: fc.boolean() }).map(({ required }): ParameterPropertySpec => ({ type: 'json', ...required ? { required: true } : {} })),
     fc.record({ values: fc.uniqueArray(fc.string({ minLength: 1 }), { minLength: 1, maxLength: 3 }), required: fc.boolean() })
-      .map(({ values, required }): SchemaProp => ({ type: 'string', enum: values, ...required ? { required: true } : {} })),
+      .map(({ values, required }): ParameterPropertySpec => ({ type: 'string', enum: values, ...required ? { required: true } : {} })),
+    fc.record({ value: fc.string(), required: fc.boolean() })
+      .map(({ value, required }): ParameterPropertySpec => ({ type: 'string', const: value, ...required ? { required: true } : {} })),
+    fc.record({ required: fc.boolean() })
+      .map(({ required }): ParameterPropertySpec => ({
+        oneOf: [{ type: 'string' }, { type: 'null' }],
+        ...required ? { required: true } : {},
+      })),
   )
 }
 
 /** A prop arbitrary up to `depth` levels of nesting (objects and arrays). */
-function propArb(depth: number): fc.Arbitrary<SchemaProp> {
+function propArb(depth: number): fc.Arbitrary<ParameterPropertySpec> {
   if (depth <= 0) return leafPropArb()
   return fc.oneof(
     { weight: 3, arbitrary: leafPropArb() },
     {
       weight: 1,
-      arbitrary: fc.record({ properties: specArb(depth - 1), required: fc.boolean() })
-        .map(({ properties, required }): SchemaProp => ({ type: 'object', properties, ...required ? { required: true } : {} })),
+      arbitrary: fc.record({ properties: specArb(depth - 1), required: fc.boolean(), additionalProperties: fc.boolean() })
+        .map(({ properties, required, additionalProperties }): ParameterPropertySpec => ({
+          type: 'object',
+          additionalProperties,
+          properties,
+          ...required ? { required: true } : {},
+        })),
     },
     {
       weight: 1,
       arbitrary: fc.record({ items: propArb(depth - 1), required: fc.boolean() })
-        .map(({ items, required }): SchemaProp => ({ type: 'array', items, ...required ? { required: true } : {} })),
+        .map(({ items, required }): ParameterPropertySpec => ({
+          type: 'array',
+          items: asValueSchema(items),
+          ...required ? { required: true } : {},
+        })),
     },
   )
 }
 
-function specArb(depth: number): fc.Arbitrary<SchemaSpec> {
+function specArb(depth: number): fc.Arbitrary<ParameterSchemaSpec> {
   return fc.dictionary(fc.string({ minLength: 1, maxLength: 6 }), propArb(depth), { maxKeys: 4 })
 }
 
 /** Generate a value that satisfies a prop (used to build valid args). */
-function valueForProp(prop: SchemaProp): fc.Arbitrary<unknown> {
+function valueForProp(prop: ParameterPropertySpec): fc.Arbitrary<unknown> {
+  if ('oneOf' in prop) return fc.oneof(...prop.oneOf.map(valueForProp))
+  if ('const' in prop) return fc.constant(prop.const)
   switch (prop.type) {
     case 'string': return prop.enum ? fc.constantFrom(...prop.enum) : fc.string()
-    case 'number': return fc.double({ noNaN: true, noDefaultInfinity: true })
+    case 'number': return fc.double({ noNaN: true, noDefaultInfinity: true }).filter(value => !Object.is(value, -0))
+    case 'integer': return fc.integer()
     case 'boolean': return fc.boolean()
+    case 'null': return fc.constant(null)
     case 'object': return prop.properties ? validArgsForSpec(prop.properties) : fc.constant({})
     case 'array': return prop.items ? fc.array(valueForProp(prop.items), { maxLength: 3 }) : fc.constant([])
+    case 'json': return fc.jsonValue().filter(value => isJsonValue(value))
   }
 }
 
 /** Generate args satisfying every required key of a spec (optionals included randomly). */
-function validArgsForSpec(spec: SchemaSpec): fc.Arbitrary<Record<string, unknown>> {
+function validArgsForSpec(spec: ParameterSchemaSpec): fc.Arbitrary<Record<string, unknown>> {
   const entries = Object.entries(spec)
   return fc.tuple(...entries.map(([key, prop]) =>
     fc.tuple(
@@ -76,29 +107,29 @@ function validArgsForSpec(spec: SchemaSpec): fc.Arbitrary<Record<string, unknown
 }
 
 /** Collect the `required: true` keys at the top level of a spec. */
-function requiredKeys(spec: SchemaSpec): string[] {
+function requiredKeys(spec: ParameterSchemaSpec): string[] {
   return Object.entries(spec).filter(([, p]) => p.required === true).map(([k]) => k)
 }
 
 describe('schema DSL properties', () => {
   it('JSON Schema `required` equals the required:true keys at every level', () => {
     fc.assert(fc.property(specArb(2), (spec) => {
-      const checkLevel = (s: SchemaSpec, json: { required?: string[]; properties: Record<string, unknown> }) => {
+      const checkLevel = (s: ParameterSchemaSpec, json: { required?: string[]; properties: Record<string, unknown> }) => {
         expect(new Set(json.required ?? [])).toEqual(new Set(requiredKeys(s)))
         for (const [key, prop] of Object.entries(s)) {
           const propJson = json.properties[key] as Record<string, unknown>
-          if (prop.type === 'object' && prop.properties) {
+          if ('type' in prop && prop.type === 'object' && prop.properties) {
             checkLevel(prop.properties, propJson as { required?: string[]; properties: Record<string, unknown> })
           }
         }
       }
-      checkLevel(spec, schemaSpecToJsonSchema(spec))
+      checkLevel(spec, parameterSchemaSpecToJsonSchema(spec))
     }))
   })
 
   it('conversion is total (never throws) for any spec', () => {
     fc.assert(fc.property(specArb(3), (spec) => {
-      expect(() => schemaSpecToJsonSchema(spec)).not.toThrow()
+      expect(() => parameterSchemaSpecToJsonSchema(spec)).not.toThrow()
     }))
   })
 
diff --git a/packages/core/tools/tests/schema.spec.ts b/packages/core/tools/tests/schema.spec.ts
new file mode 100644
index 0000000000..ae095b5361
--- /dev/null
+++ b/packages/core/tools/tests/schema.spec.ts
@@ -0,0 +1,205 @@
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import {
+  JsonSchemaError,
+  parameterSchemaSpecToJsonSchema,
+  valueSchemaSpecToJsonSchema,
+  type InferArgs,
+  type InferValue,
+  type JsonValue,
+  type ParameterSchemaSpec,
+  type ValueSchemaSpec,
+} from '../src/index.ts'
+
+describe('the unified author schema DSL', () => {
+  it('compiles every value root and the author-only json node', () => {
+    expect(valueSchemaSpecToJsonSchema({ type: 'string', enum: ['a', 'b'], const: 'a' }))
+      .toEqual({ type: 'string', enum: ['a', 'b'], const: 'a' })
+    expect(valueSchemaSpecToJsonSchema({ type: 'number' })).toEqual({ type: 'number' })
+    expect(valueSchemaSpecToJsonSchema({ type: 'integer' })).toEqual({ type: 'integer' })
+    expect(valueSchemaSpecToJsonSchema({ type: 'boolean' })).toEqual({ type: 'boolean' })
+    expect(valueSchemaSpecToJsonSchema({ type: 'null' })).toEqual({ type: 'null' })
+    expect(valueSchemaSpecToJsonSchema({ type: 'array', items: { type: 'json' } }))
+      .toEqual({ type: 'array', items: {} })
+    expect(valueSchemaSpecToJsonSchema({ type: 'object', additionalProperties: false, properties: {} }))
+      .toEqual({ type: 'object', additionalProperties: false, properties: {} })
+    expect(valueSchemaSpecToJsonSchema({
+      type: 'json',
+      description: 'anything',
+      title: 'Any JSON',
+      default: null,
+      examples: [{ nested: true }],
+    })).toEqual({ description: 'anything', title: 'Any JSON', default: null, examples: [{ nested: true }] })
+    expect(valueSchemaSpecToJsonSchema({ oneOf: [{ type: 'string' }, { type: 'null' }] }))
+      .toEqual({ oneOf: [{ type: 'string' }, { type: 'null' }] })
+  })
+
+  it('keeps the implicit parameter root open while preserving explicit object openness', () => {
+    expect(parameterSchemaSpecToJsonSchema({
+      closed: {
+        type: 'object',
+        additionalProperties: false,
+        required: true,
+        properties: { id: { type: 'integer', required: true } },
+      },
+      open: { type: 'object', additionalProperties: true },
+    })).toEqual({
+      type: 'object',
+      properties: {
+        closed: {
+          type: 'object',
+          additionalProperties: false,
+          properties: { id: { type: 'integer' } },
+          required: ['id'],
+        },
+        open: { type: 'object', additionalProperties: true },
+      },
+      required: ['closed'],
+    })
+  })
+
+  it('rejects runtime-forged author forms rather than compiling them lossily', () => {
+    for (const schema of [
+      { type: 'object' },
+      { oneOf: [{ type: 'string' }] },
+      { type: 'number', enum: ['1'] },
+      { type: 'string', enum: ['a'], const: 'b' },
+      { type: 'integer', const: 1.5 },
+      { type: 'json', default: undefined },
+      { type: 'array', items: { type: 'string', required: true } },
+      { type: 'array', items: 42 },
+      { type: 'string', extra: true },
+      { type: 'string', oneOf: [{ type: 'string' }, { type: 'null' }] },
+      { oneOf: 'not-an-array' },
+      { type: 'string', enum: 'a' },
+      {},
+      null,
+    ]) {
+      expect(() => valueSchemaSpecToJsonSchema(schema as ValueSchemaSpec), JSON.stringify(schema)).toThrow(JsonSchemaError)
+    }
+    expect(() => parameterSchemaSpecToJsonSchema({
+      value: { type: 'string', required: false },
+    } as unknown as ParameterSchemaSpec)).toThrow(JsonSchemaError)
+    expect(() => parameterSchemaSpecToJsonSchema(null as unknown as ParameterSchemaSpec)).toThrow(JsonSchemaError)
+    expect(() => parameterSchemaSpecToJsonSchema({ bad: 42 } as unknown as ParameterSchemaSpec)).toThrow(JsonSchemaError)
+
+    const symbolKey = Symbol('hidden')
+    expect(() => parameterSchemaSpecToJsonSchema({
+      value: { type: 'string' },
+      [symbolKey]: { type: 'number' },
+    } as unknown as ParameterSchemaSpec)).toThrow(JsonSchemaError)
+    const hiddenKey = Object.defineProperty({ value: { type: 'string' } }, 'hidden', {
+      value: { type: 'number' },
+    })
+    expect(() => parameterSchemaSpecToJsonSchema(hiddenKey as ParameterSchemaSpec)).toThrow(JsonSchemaError)
+    const sparseOneOf = new Array<ValueSchemaSpec>(2)
+    sparseOneOf[0] = { type: 'string' }
+    expect(() => valueSchemaSpecToJsonSchema({ oneOf: sparseOneOf } as unknown as ValueSchemaSpec)).toThrow(JsonSchemaError)
+    const decoratedEnum = Object.assign(['a'], { hidden: true })
+    expect(() => valueSchemaSpecToJsonSchema({
+      type: 'string',
+      enum: decoratedEnum,
+    })).toThrow(JsonSchemaError)
+  })
+
+  it('rejects cyclic author schemas', () => {
+    const schema: Record<string, unknown> = { type: 'array' }
+    schema.items = schema
+    expect(() => valueSchemaSpecToJsonSchema(schema as unknown as ValueSchemaSpec)).toThrow(/circular/)
+
+    const properties: Record<string, unknown> = {}
+    properties.self = { type: 'object', additionalProperties: true, properties }
+    expect(() => parameterSchemaSpecToJsonSchema(properties as ParameterSchemaSpec)).toThrow(/circular/)
+  })
+
+  it('compiles deeply nested author unions without using the JavaScript call stack', () => {
+    const depth = 5_000
+    let spec: unknown = { type: 'string' }
+    for (let index = 0; index < depth; index++) spec = { oneOf: [spec, { type: 'null' }] }
+
+    const compiled = valueSchemaSpecToJsonSchema(spec as ValueSchemaSpec)
+
+    let cursor = compiled
+    let layers = 0
+    while (cursor.oneOf !== undefined) {
+      cursor = cursor.oneOf[0]!
+      layers++
+    }
+    expect(layers).toBe(depth)
+    expect(cursor).toEqual({ type: 'string' })
+  })
+
+  it('preserves a property literally named __proto__ as schema data', () => {
+    const properties = Object.create(null) as ParameterSchemaSpec
+    properties.__proto__ = { type: 'string', required: true }
+
+    const schema = parameterSchemaSpecToJsonSchema(properties)
+
+    expect(Object.hasOwn(schema.properties, '__proto__')).toBe(true)
+    expect(schema.properties.__proto__).toEqual({ type: 'string' })
+    expect(schema.required).toEqual(['__proto__'])
+  })
+
+  it('infers scalar literals, arrays, objects, json, and exact-one unions', () => {
+    expectTypeOf<InferValue<{ type: 'string'; enum: readonly ['a', 'b'] }>>().toEqualTypeOf<'a' | 'b'>()
+    expectTypeOf<InferValue<{ type: 'number'; const: 1 }>>().toEqualTypeOf<1>()
+    expectTypeOf<InferValue<{ type: 'integer' }>>().toEqualTypeOf<number>()
+    expectTypeOf<InferValue<{ type: 'boolean'; enum: readonly [true] }>>().toEqualTypeOf<true>()
+    expectTypeOf<InferValue<{ type: 'null' }>>().toEqualTypeOf<null>()
+    expectTypeOf<InferValue<{ type: 'array'; items: { type: 'string' } }>>().toEqualTypeOf<string[]>()
+    expectTypeOf<InferValue<{ type: 'array' }>>().toEqualTypeOf<JsonValue[]>()
+    expectTypeOf<InferValue<{ type: 'json' }>>().toEqualTypeOf<JsonValue>()
+    expectTypeOf<InferValue<{ oneOf: readonly [{ type: 'string' }, { type: 'null' }] }>>()
+      .toEqualTypeOf<string | null>()
+    expectTypeOf<InferValue<{
+      type: 'object'
+      additionalProperties: false
+      properties: { id: { type: 'integer'; required: true }; label: { type: 'string' } }
+    }>>().toEqualTypeOf<{ id: number; label?: string }>()
+    expectTypeOf<InferValue<{
+      type: 'object'
+      additionalProperties: true
+      properties: { id: { type: 'integer'; required: true } }
+    }>>().toEqualTypeOf<{ id: number } & Record<string, JsonValue>>()
+  })
+
+  it('bounds inference for deeply nested author schemas', () => {
+    type Repeat<Count extends number, Result extends unknown[] = []> =
+      Result['length'] extends Count ? Result : Repeat<Count, [unknown, ...Result]>
+    type DeepArraySchema<Levels extends unknown[]> =
+      Levels extends [unknown, ...infer Rest]
+        ? { type: 'array'; items: DeepArraySchema<Rest> }
+        : { type: 'string' }
+    type PeelArrays<Value, Levels extends unknown[]> =
+      Levels extends [unknown, ...infer Rest]
+        ? Value extends (infer Item)[] ? PeelArrays<Item, Rest> : never
+        : Value
+
+    type DeepValue = InferValue<DeepArraySchema<Repeat<50>>>
+    expectTypeOf<PeelArrays<DeepValue, Repeat<16>>>().toEqualTypeOf<JsonValue>()
+  })
+
+  it('infers required and optional parameter keys', () => {
+    expectTypeOf<InferArgs<{
+      path: { type: 'string'; required: true }
+      offset: { type: 'integer' }
+      data: { type: 'json' }
+    }>>().toEqualTypeOf<{ path: string; offset?: number; data?: JsonValue }>()
+  })
+
+  it('makes invalid author forms compile-time errors', () => {
+    const symbolKey = Symbol('parameter')
+    const invalidObjects = {
+      // @ts-expect-error explicit object schemas require an openness decision
+      object: { type: 'object' } satisfies ValueSchemaSpec,
+      // @ts-expect-error oneOf requires at least two branches
+      oneOf: { oneOf: [{ type: 'string' }] } satisfies ValueSchemaSpec,
+      // @ts-expect-error scalar enum values must match the node type
+      enum: { type: 'number', enum: ['1'] } satisfies ValueSchemaSpec,
+      // @ts-expect-error parameter requiredness is true-or-absent
+      required: { value: { type: 'string', required: false } } satisfies ParameterSchemaSpec,
+      // @ts-expect-error parameter maps accept string keys only
+      symbol: { [symbolKey]: { type: 'string' } } satisfies ParameterSchemaSpec,
+    }
+    expect(Object.keys(invalidObjects)).toHaveLength(5)
+  })
+})
diff --git a/packages/core/tools/tests/scoped.spec.ts b/packages/core/tools/tests/scoped.spec.ts
index a18adf8593..922173653f 100644
--- a/packages/core/tools/tests/scoped.spec.ts
+++ b/packages/core/tools/tests/scoped.spec.ts
@@ -9,7 +9,6 @@ import type { PreToolDecision, ToolDefinition, ToolExecution, ToolExecutionInput
 import type { Agent } from '@deepseek-ai/dsh-agent'
 
 import { CallId } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 
 const testToolSignal = new AbortController().signal
@@ -39,7 +38,11 @@ function tool(name: string, reply = `ran:${name}`): ToolDefinition {
     name,
     description: `tool ${name}`,
     parameters: { type: 'object', properties: {} },
-    execute: (): Promise<ContentBlock[]> => Promise.resolve([{ type: 'text', text: reply }]),
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value as string }],
+    },
+    execute: (): Promise<string> => Promise.resolve(reply),
   }
 }
 
@@ -224,7 +227,7 @@ describe('scoped execution dispatch', () => {
       ...tool('t'),
       execute: () => {
         bodyCalls += 1
-        return Promise.resolve([{ type: 'text', text: 'ran:t' }])
+        return Promise.resolve('ran:t')
       },
     })
     const guard = (execution: Readonly<ToolExecution>): string => {
@@ -256,7 +259,7 @@ describe('scoped execution dispatch', () => {
       ...tool('t'),
       execute: () => {
         bodyCalls += 1
-        return Promise.resolve([])
+        return Promise.resolve('ran:t')
       },
     })
     ctx.tools.guard(() => undefined)
@@ -322,14 +325,14 @@ describe('scoped execution dispatch', () => {
       execute: (args) => {
         safeCalls += 1
         safeArguments = args
-        return Promise.resolve([{ type: 'text', text: 'safe' }])
+        return Promise.resolve('safe')
       },
     })
     ctx.tools.register({
       ...tool('danger'),
       execute: () => {
         dangerCalls += 1
-        return Promise.resolve([{ type: 'text', text: 'danger' }])
+        return Promise.resolve('danger')
       },
     })
     scope.ctx.tools.guard(exec => exec.name === 'danger' ? 'danger denied' : undefined)
@@ -382,7 +385,7 @@ describe('scoped execution dispatch', () => {
       ...tool('t'),
       execute: () => {
         bodyCalls += 1
-        return Promise.resolve([])
+        return Promise.resolve('ran:t')
       },
     })
     ctx.on('tools/pre-execute', (_exec, next) => {
@@ -444,7 +447,7 @@ describe('scoped execution dispatch', () => {
       ...tool('t'),
       execute: (_args, exec) => {
         observed.push(exec.parent)
-        return Promise.resolve([{ type: 'text', text: 'ran:t' }])
+        return Promise.resolve('ran:t')
       },
     })
     ctx.on('tools/pre-execute', (exec, next) => {
@@ -561,7 +564,7 @@ describe('scoped execution dispatch', () => {
       ...tool('t'),
       execute: () => {
         bodyCalls += 1
-        return Promise.resolve([])
+        return Promise.resolve('ran:t')
       },
     })
     ctx.on('tools/pre-execute', (_exec, next) => {
@@ -604,6 +607,7 @@ describe('scoped execution dispatch', () => {
     expect(result).toEqual({
       content: [{ type: 'text', text: 'ran:t' }],
       isError: false,
+      value: 'ran:t',
     })
   })
 
@@ -622,6 +626,7 @@ describe('scoped execution dispatch', () => {
       return {
         content: [{ type: 'text', text: 'outer failure' }],
         isError: true,
+        error: { message: 'outer failure' },
       }
     }, { prepend: true })
     scope.ctx.on('tools/result', (_exec, result) => {
diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts
index 3eb1152a92..92f2c49cce 100644
--- a/packages/core/tools/tests/tools.spec.ts
+++ b/packages/core/tools/tests/tools.spec.ts
@@ -1,14 +1,14 @@
 import { describe, expect, expectTypeOf, it } from 'vitest'
 import { Context } from 'cordis'
-import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
+import { CallId, HarnessError, type ContentBlock } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import ApprovalService, { type ApprovalOutcome, type ApprovalRequest } from '@deepseek-ai/dsh-user-approval'
 import ToolRegistry, {
-  defineTool, schemaSpecToJsonSchema, validateArgs, ToolArgsError, ToolNotFoundError,
+  defineContentToolFixture, defineTool, JsonSchemaError, parameterSchemaSpecToJsonSchema, validateArgs, ToolArgsError, ToolNotFoundError,
   TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH,
-  type InferArgs, type SchemaSpec, type PreToolDecision, type PostToolDecision,
-  type ToolDispatchExecution, type ToolExecutionResult,
+  type InferArgs, type JsonValue, type ParameterSchemaSpec, type PreToolDecision, type PostToolDecision,
+  type JsonSchemaNode, type ToolDefinition, type ToolDispatchExecution, type ToolExecutionResult, type ToolExecutionToken,
 } from '@deepseek-ai/dsh-tools'
 
 const testToolSignal = new AbortController().signal
@@ -24,8 +24,12 @@ const echoTool = defineTool({
   name: 'echo',
   description: 'echo arguments back',
   parameters: { text: { type: 'string' } },
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   async execute(args) {
-    return [{ type: 'text' as const, text: args.text ?? '' }]
+    return args.text ?? ''
   },
 })
 
@@ -47,22 +51,22 @@ describe('ToolRegistry', () => {
     expect(assembly.tools.map(t => t.name)).toEqual(['echo'])
   })
 
-  it('schemas() drops the UI presentation callbacks — they must never reach the model', async () => {
+  it('schemas() drops host callbacks — they must never reach the model', async () => {
     const ctx = await setup()
-    // A tool that declares presentCall/presentResult (functions). schemas() feeds
-    // the system-prompt assembly → the model request, so those callbacks (and
-    // `execute`) must be stripped: a function in the JSON tool schema would
-    // corrupt the request. schemas() is an explicit allowlist, so it can't leak.
-    ctx.tools.register(defineTool({
+    // Tool definitions contain output, finalization, execution, and presentation
+    // callbacks. schemas() is an explicit allowlist so none can reach the model.
+    ctx.tools.register(defineContentToolFixture({
       name: 'present',
       description: 'has presenters',
       parameters: { x: { type: 'string', required: true } },
       async execute() { return [] },
+      finalizeContent: (_exec, result) => result.content,
       presentCall: args => ({ card: 'generic', title: args.x }),
       presentResult: (args, result) => ({ card: 'generic', title: args.x, content: result.content }),
     }))
     const schema = ctx.tools.schemas()[0] as unknown as Record<string, unknown>
     expect(Object.keys(schema).sort()).toEqual(['description', 'name', 'parameters'])
+    expect(schema.finalizeContent).toBeUndefined()
     expect(schema.presentCall).toBeUndefined()
     expect(schema.presentResult).toBeUndefined()
     expect(schema.execute).toBeUndefined()
@@ -70,7 +74,7 @@ describe('ToolRegistry', () => {
 
   it('schemas() excludes timeoutMs — the budget must never reach the model', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'budgeted', description: 'has a budget', parameters: {}, timeoutMs: 5_000,
       async execute() { return [{ type: 'text' as const, text: 'ok' }] },
     }))
@@ -82,17 +86,24 @@ describe('ToolRegistry', () => {
   it('executes a tool and returns its content', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)
+    let observed: ToolExecutionResult | undefined
+    ctx.on('tools/result', (_exec, result) => { observed = result })
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } })
-    expect(result).toEqual({ content: [{ type: 'text', text: 'hi' }], isError: false })
+    expect(result).toEqual({ content: [{ type: 'text', text: 'hi' }], isError: false, value: 'hi' })
+    expect(observed).toEqual(result)
   })
 
-  it('threads a tool-attached meta (object return form) onto the result', async () => {
+  it('projects presentation metadata from the canonical value', async () => {
     const ctx = await setup()
     ctx.tools.register({
       ...echoTool,
       name: 'meta-tool',
+      output: {
+        ...echoTool.output,
+        presentationMeta: () => ({ diffs: [{ path: 'a', oldText: null, newText: 'x' }] }),
+      },
       async execute() {
-        return { content: [{ type: 'text', text: 'ok' }], meta: { diffs: [{ path: 'a', oldText: null, newText: 'x' }] } }
+        return 'ok'
       },
     })
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'meta-tool', arguments: {} })
@@ -100,20 +111,21 @@ describe('ToolRegistry', () => {
       content: [{ type: 'text', text: 'ok' }],
       isError: false,
       meta: { diffs: [{ path: 'a', oldText: null, newText: 'x' }] },
+      value: 'ok',
     })
   })
 
-  it('omits meta when the object return form supplies none', async () => {
+  it('omits meta when no presentation projector is declared', async () => {
     const ctx = await setup()
     ctx.tools.register({
       ...echoTool,
       name: 'no-meta-tool',
       async execute() {
-        return { content: [{ type: 'text', text: 'ok' }] }
+        return 'ok'
       },
     })
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'no-meta-tool', arguments: {} })
-    expect(result).toEqual({ content: [{ type: 'text', text: 'ok' }], isError: false })
+    expect(result).toEqual({ content: [{ type: 'text', text: 'ok' }], isError: false, value: 'ok' })
     expect('meta' in result).toBe(false)
   })
 
@@ -124,8 +136,12 @@ describe('ToolRegistry', () => {
     ctx.tools.register({
       ...echoTool,
       name: 'bad-meta',
+      output: {
+        ...echoTool.output,
+        presentationMeta: () => (() => undefined) as unknown as JsonValue,
+      },
       async execute() {
-        return { content: [], meta: () => undefined }
+        return 'ok'
       },
     })
 
@@ -135,9 +151,408 @@ describe('ToolRegistry', () => {
     })
     expect(result.isError).toBe(true)
     expect(result.content[0]?.type === 'text' && result.content[0].text).toContain('Error:')
+    expect(result.error).toMatchObject({ info: { name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' } })
     expect(observedError).toBe(true)
   })
 
+  it('finalizes errors discovered while snapshotting non-content result fields', async () => {
+    const ctx = await setup()
+    let finalizeCalls = 0
+    ctx.tools.register({
+      ...echoTool,
+      name: 'throwing-meta',
+      output: {
+        ...echoTool.output,
+        presentationMeta() {
+          const meta = {}
+          Object.defineProperty(meta, 'value', {
+            enumerable: true,
+            get() { throw new Error('snapshot failed: '.repeat(100)) },
+          })
+          return meta
+        },
+      },
+      finalizeContent(_exec, result) {
+        finalizeCalls += 1
+        const block = result.content[0]
+        if (block?.type !== 'text') return undefined
+        return [{ type: 'text', text: block.text.slice(0, 32) }]
+      },
+      async execute() {
+        return 'body'
+      },
+    })
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('throwing-meta'), name: 'throwing-meta', arguments: {},
+    })
+
+    expect(result.isError).toBe(true)
+    const block = result.content[0]
+    expect(block?.type).toBe('text')
+    expect(block?.type === 'text' ? block.text : '').toMatch(/^Error: tool "throwing-meta"/)
+    expect(block?.type === 'text' ? block.text : '').toHaveLength(32)
+    expect(finalizeCalls).toBe(1)
+  })
+
+  it('normalizes a throwing final content callback without invoking it again', async () => {
+    const ctx = await setup()
+    let finalizeCalls = 0
+    ctx.tools.register({
+      ...echoTool,
+      name: 'throwing-finalizer',
+      finalizeContent() {
+        finalizeCalls += 1
+        throw new Error('finalizer violated its total contract')
+      },
+    })
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('throwing-finalizer'), name: 'throwing-finalizer', arguments: {},
+    })
+
+    expect(result).toEqual({
+      content: [{ type: 'text', text: 'Error: finalizer violated its total contract' }],
+      isError: true,
+      error: { message: 'finalizer violated its total contract' },
+    })
+    expect(finalizeCalls).toBe(1)
+  })
+
+  it('requires every raw registration to declare its canonical output', async () => {
+    const ctx = await setup()
+    const missingOutput = {
+      name: 'legacy-content-tool',
+      description: 'missing output',
+      parameters: {},
+      execute: async () => [{ type: 'text', text: 'legacy' }],
+    } as unknown as ToolDefinition
+
+    expect(() => ctx.tools.register(missingOutput))
+      .toThrow('must declare output { schema, render, presentationMeta? }')
+  })
+
+  it('rejects lossy and schema-mismatched body values before post-execute', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'lossy-output',
+      description: 'lossy',
+      parameters: {},
+      output: { schema: { type: 'json' }, render: () => [] },
+      execute: async () => (() => undefined) as unknown as JsonValue,
+    }))
+    ctx.tools.register(defineTool({
+      name: 'wrong-output',
+      description: 'wrong schema',
+      parameters: {},
+      output: { schema: { type: 'string' }, render: () => [] },
+      execute: async () => 42 as unknown as string,
+    }))
+
+    const lossy = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('lossy'), name: 'lossy-output', arguments: {} })
+    const mismatch = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('mismatch'), name: 'wrong-output', arguments: {} })
+    expect(lossy.error).toMatchObject({ info: { name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' } })
+    expect(lossy.content[0]?.type === 'text' ? lossy.content[0].text : '').toContain('not lossless JSON')
+    expect(mismatch.error).toMatchObject({ info: { name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' } })
+    expect(mismatch.content[0]?.type === 'text' ? mismatch.content[0].text : '').toContain('"value" must be a string')
+  })
+
+  it('classifies a throwing body snapshot as invalid tool output', async () => {
+    const ctx = await setup()
+    const hostile = Object.defineProperty({}, 'value', {
+      enumerable: true,
+      get: () => { throw new Error('body snapshot getter exploded') },
+    })
+    ctx.tools.register(defineTool({
+      name: 'hostile-body',
+      description: 'hostile body',
+      parameters: {},
+      output: { schema: { type: 'json' }, render: () => [] },
+      execute: async () => hostile as JsonValue,
+    }))
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('hostile-body'), name: 'hostile-body', arguments: {},
+    })
+    expect(result.error?.message).toContain('value snapshot failed: body snapshot getter exploded')
+    expect(result.error?.info).toEqual({ name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' })
+  })
+
+  it.each(['render', 'presentationMeta'] as const)('contains a throwing output.%s projector as one failed call', async (projector) => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: `throwing-${projector}`,
+      description: projector,
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: () => {
+          if (projector === 'render') throw new Error('renderer exploded')
+          return [{ type: 'text', text: 'ok' }]
+        },
+        presentationMeta: () => {
+          if (projector === 'presentationMeta') throw new Error('metadata exploded')
+          return null
+        },
+      },
+      execute: async () => 'ok',
+    }))
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId(projector), name: `throwing-${projector}`, arguments: {} })
+    expect(result.isError).toBe(true)
+    expect(result.error?.message)
+      .toContain(projector === 'render' ? 'renderer exploded' : 'metadata exploded')
+    expect(result.error?.info).toEqual({ name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' })
+    expect('value' in result).toBe(false)
+  })
+
+  it.each(['render', 'presentationMeta'] as const)('contains a throwing output.%s snapshot as one failed call', async (projector) => {
+    const ctx = await setup()
+    const hostile = Object.defineProperty({}, 'value', {
+      enumerable: true,
+      get: () => { throw new Error('snapshot getter exploded') },
+    })
+    ctx.tools.register(defineTool({
+      name: `hostile-${projector}`,
+      description: projector,
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: () => projector === 'render'
+          ? hostile as unknown as ContentBlock[]
+          : [{ type: 'text', text: 'ok' }],
+        presentationMeta: () => projector === 'presentationMeta'
+          ? hostile as unknown as JsonValue
+          : null,
+      },
+      execute: async () => 'ok',
+    }))
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId(`hostile-${projector}`), name: `hostile-${projector}`, arguments: {},
+    })
+    expect(result.error?.message).toContain('snapshot getter exploded')
+    expect(result.error?.info).toEqual({ name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' })
+  })
+
+  it('keeps value/meta through content replacement and recomputes both projections after value replacement', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'projected',
+      description: 'projected',
+      parameters: {},
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: { text: { type: 'string', required: true } },
+        },
+        render: (_args, value) => [{ type: 'text', text: `render:${value.text}` }],
+        presentationMeta: (_args, value) => ({ projected: value.text }),
+      },
+      execute: async () => ({ text: 'body' }),
+    }))
+    let replacement: 'content' | 'value' = 'content'
+    ctx.on('tools/post-execute', async () => {
+      if (replacement === 'content') {
+        return { kind: 'accept', content: [{ type: 'text', text: 'policy content' }] }
+      }
+      return {
+        kind: 'accept',
+        value: { text: 'policy value' },
+        additionalContexts: [{ content: [{ type: 'text', text: 'value context' }], source: { kind: 'plugin', plugin: 'test' } }],
+      }
+    })
+
+    const content = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('content'), name: 'projected', arguments: {} })
+    replacement = 'value'
+    const value = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('value'), name: 'projected', arguments: {} })
+
+    expect(content).toEqual({
+      isError: false,
+      value: { text: 'body' },
+      content: [{ type: 'text', text: 'policy content' }],
+      meta: { projected: 'body' },
+    })
+    expect(value).toEqual({
+      isError: false,
+      value: { text: 'policy value' },
+      content: [{ type: 'text', text: 'render:policy value' }],
+      meta: { projected: 'policy value' },
+      additionalContexts: [{ content: [{ type: 'text', text: 'value context' }], source: { kind: 'plugin', plugin: 'test' } }],
+    })
+  })
+
+  it('fails a post-execute decision that replaces both projections or supplies an invalid value', async () => {
+    const both = await setup()
+    both.tools.register(echoTool)
+    both.on('tools/post-execute', async () => ({
+      kind: 'accept',
+      value: 'replacement',
+      content: [{ type: 'text', text: 'also replacement' }],
+    } as unknown as PostToolDecision))
+    const bothResult = await both.tools.execute({ signal: testToolSignal, callId: CallId('both'), name: 'echo', arguments: {} })
+    expect(bothResult).toMatchObject({
+      isError: true,
+      error: { message: 'tools/post-execute accept decision cannot replace both value and content' },
+    })
+
+    const invalid = await setup()
+    invalid.tools.register(echoTool)
+    invalid.on('tools/post-execute', async () => ({ kind: 'accept', value: 1 }))
+    const invalidResult = await invalid.tools.execute({ signal: testToolSignal, callId: CallId('invalid'), name: 'echo', arguments: {} })
+    expect(invalidResult.error).toMatchObject({ info: { code: 'INVALID_TOOL_OUTPUT' } })
+    expect('value' in invalidResult).toBe(false)
+  })
+
+  it('turns a post-execute block into a valueless failure', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'block',
+      feedback: [{ type: 'text', text: 'blocked by policy' }],
+    }))
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('block'), name: 'echo', arguments: { text: 'secret' } })
+    expect(result).toEqual({
+      isError: true,
+      error: { message: 'blocked by policy' },
+      content: [{ type: 'text', text: 'blocked by policy' }],
+    })
+    expect('value' in result).toBe(false)
+  })
+
+  it('replaces a canonical value without manufacturing additional context', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+    ctx.on('tools/post-execute', async () => ({ kind: 'accept', value: 'replacement' }))
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('replace-value'), name: 'echo', arguments: {} })
+    expect(result).toEqual({
+      isError: false,
+      value: 'replacement',
+      content: [{ type: 'text', text: 'replacement' }],
+    })
+  })
+
+  it.each([
+    [[], 'tool result blocked by post-execute policy'],
+    [[{ type: 'reasoning', text: 'private rationale' }], '[reasoning content]'],
+  ] as const)('derives a stable failure message from non-text or empty block feedback', async (feedback, message) => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+    ctx.on('tools/post-execute', async () => ({ kind: 'block', feedback: [...feedback] }))
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('block-message'), name: 'echo', arguments: {} })
+    expect(result.error?.message).toBe(message)
+  })
+
+  it('contains a non-JSON post-execute failure projection as a safe final error', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'block',
+      feedback: [{ type: 'text', text: 'blocked', invalid: () => undefined } as never],
+    }))
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('invalid-block'), name: 'echo', arguments: {} })
+    expect(result).toMatchObject({
+      isError: true,
+      error: { message: 'tool result must be losslessly JSON-serializable' },
+    })
+  })
+
+  it('rejects value replacement on a failed dispatch', async () => {
+    const ctx = await setup()
+    ctx.tools.register({
+      ...echoTool,
+      name: 'throw-before-replace',
+      async execute() { throw new Error('body failed') },
+    })
+    ctx.on('tools/post-execute', async () => ({ kind: 'accept', value: 'replacement' }))
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('failed-replace'), name: 'throw-before-replace', arguments: {},
+    })
+    expect(result.error?.message).toBe('tools/post-execute cannot replace the value of a failed result')
+  })
+
+  it('fails value replacement when the owning tool disappears before post-policy resolves', async () => {
+    const ctx = await setup()
+    const dispose = ctx.tools.register(echoTool)
+    ctx.on('tools/post-execute', async () => {
+      dispose()
+      return { kind: 'accept', value: 'replacement' }
+    })
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('post-disposed'), name: 'echo', arguments: {} })
+    expect(result.error).toEqual({
+      message: 'unknown tool "echo"',
+      info: { name: 'ToolNotFoundError', code: 'UNKNOWN_TOOL' },
+    })
+  })
+
+  it('normalizes wrapper-authored failure metadata and contexts', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+    ctx.on('tools/execute', async () => ({
+      isError: true,
+      error: { message: 'wrapped failure' },
+      content: [{ type: 'text', text: 'wrapper content' }],
+      meta: { wrapped: true },
+      additionalContexts: [{ content: [{ type: 'text', text: 'wrapper context' }], source: { kind: 'plugin', plugin: 'test' } }],
+    }))
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('wrapper-failure'), name: 'echo', arguments: {} })
+    expect(result).toEqual({
+      isError: true,
+      error: { message: 'wrapped failure' },
+      content: [{ type: 'text', text: 'wrapper content' }],
+      meta: { wrapped: true },
+      additionalContexts: [{ content: [{ type: 'text', text: 'wrapper context' }], source: { kind: 'plugin', plugin: 'test' } }],
+    })
+  })
+
+  it('fails wrapper-authored success normalization when the owning tool disappears', async () => {
+    const ctx = await setup()
+    const dispose = ctx.tools.register(echoTool)
+    ctx.on('tools/execute', async () => {
+      dispose()
+      return { isError: false, value: 'replacement', content: [] }
+    })
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('wrapper-disposed'), name: 'echo', arguments: {} })
+    expect(result.error).toEqual({
+      message: 'unknown tool "echo"',
+      info: { name: 'ToolNotFoundError', code: 'UNKNOWN_TOOL' },
+    })
+  })
+
+  it('suppresses presentation metadata only for nested composite dispatches', async () => {
+    const ctx = await setup()
+    ctx.tools.register({
+      ...echoTool,
+      name: 'meta-suppression',
+      output: { ...echoTool.output, presentationMeta: () => ({ card: true }) },
+    })
+    const direct = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('direct'), name: 'meta-suppression', arguments: {} })
+    const nested = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('nested'),
+      name: 'meta-suppression',
+      arguments: {},
+      parent: Symbol('outer') as ToolExecutionToken,
+    })
+    expect(direct.meta).toEqual({ card: true })
+    expect(nested.meta).toBeUndefined()
+    expect(nested.isError ? undefined : nested.value).toBe('')
+  })
+
   it('returns isError results for unknown tools and throwing tools', async () => {
     const ctx = await setup()
     ctx.tools.register({
@@ -152,7 +567,10 @@ describe('ToolRegistry', () => {
     expect(unknown.isError).toBe(true)
     expect(unknown.content[0]).toMatchObject({ text: 'Error: unknown tool "nope"' })
     // An unknown tool is a routable failure class, same as a tool-thrown one.
-    expect(unknown.error).toEqual({ name: 'ToolNotFoundError', code: 'UNKNOWN_TOOL' })
+    expect(unknown.error).toEqual({
+      message: 'unknown tool "nope"',
+      info: { name: 'ToolNotFoundError', code: 'UNKNOWN_TOOL' },
+    })
 
     const thrown = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c2'), name: 'boom', arguments: {} })
     expect(thrown.isError).toBe(true)
@@ -194,15 +612,22 @@ describe('ToolRegistry', () => {
   it('lets a tools/pre-execute listener deny a call (permission pattern)', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)
+    let postSawFrozen = false
 
     ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
       if (exec.name === 'echo') return { kind: 'deny', reason: 'denied by policy' }
       return next()
     })
+    ctx.on('tools/post-execute', async (_exec, result, next) => {
+      postSawFrozen = Object.isFrozen(result)
+      expect(Reflect.set(result, 'content', [])).toBe(false)
+      return next()
+    })
 
     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: denied by policy' })
+    expect(postSawFrozen).toBe(true)
   })
 
   it('an ask decision degrades to deny when no approval seam is mounted', async () => {
@@ -319,7 +744,7 @@ describe('ToolRegistry', () => {
 
       await expect(pending).resolves.toMatchObject({
         isError: true,
-        error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+        error: { info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
       })
       expect(dispatched).toBe(0)
     })
@@ -388,6 +813,36 @@ describe('ToolRegistry', () => {
     expect(result.content[0]).toMatchObject({ text: 'output rejected: try again' })
   })
 
+  it('runs the snapshotted final content transform after outer pipeline normalization', async () => {
+    const ctx = await setup()
+    const dispose = ctx.tools.register(defineContentToolFixture({
+      name: 'bounded',
+      description: 'bounded result',
+      parameters: {},
+      async execute() { return [{ type: 'text', text: 'body' }] },
+      finalizeContent(exec, result) {
+        expect(exec.name).toBe('bounded')
+        expect(result.isError).toBe(true)
+        return [{ type: 'text', text: 'bounded failure' }]
+      },
+    }))
+    ctx.on('tools/pre-execute', async () => {
+      dispose()
+      throw new HarnessError('policy failed', 'POLICY_FAILED')
+    })
+
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('bounded'), name: 'bounded', arguments: {} })
+
+    expect(result).toEqual({
+      content: [{ type: 'text', text: 'bounded failure' }],
+      isError: true,
+      error: {
+        message: 'policy failed',
+        info: { name: 'HarnessError', code: 'POLICY_FAILED' },
+      },
+    })
+  })
+
   it('a block decision can ALSO attach additionalContexts', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)
@@ -418,7 +873,7 @@ describe('ToolRegistry', () => {
 
   it('preserves tool-deferred, execute-wrapper, and post-execute contexts in order', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'composite',
       description: 'composite',
       parameters: {},
@@ -462,7 +917,7 @@ describe('ToolRegistry', () => {
 
   it('keeps deferred contexts when a composite tool throws, but drops them when the outer call is blocked', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'failing-composite',
       description: 'failing composite',
       parameters: {},
@@ -513,7 +968,7 @@ describe('ToolRegistry', () => {
   it('runs tools/execute after an allowed pre-execute, around dispatch, and before post-execute', async () => {
     const ctx = await setup()
     const order: string[] = []
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'traced',
       description: 'echo',
       parameters: { text: { type: 'string' } },
@@ -533,7 +988,7 @@ describe('ToolRegistry', () => {
     ctx.on('tools/post-execute', async (_exec, _result, next) => { order.push('post'); return next() })
 
     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 })
+    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.
     expect(order).toEqual(['pre', 'execute:before', 'dispatch', 'execute:after', 'post'])
   })
@@ -565,7 +1020,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toMatchObject({
       content: [{ type: 'text', text: 'Error: tool call aborted before dispatch' }],
       isError: true,
-      error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      error: { info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
     })
     expect(dispatched).toBe(0)
   })
@@ -597,6 +1052,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toEqual({
       content: [{ type: 'text', text: 'Error: policy denied the call' }],
       isError: true,
+      error: { message: 'policy denied the call' },
     })
     expect(dispatched).toBe(0)
   })
@@ -628,6 +1084,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toEqual({
       content: [{ type: 'text', text: 'Error: gate interrupted' }],
       isError: true,
+      error: { message: 'gate interrupted' },
     })
     expect(dispatched).toBe(0)
   })
@@ -665,7 +1122,7 @@ describe('ToolRegistry', () => {
 
     await expect(pending).resolves.toMatchObject({
       isError: true,
-      error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      error: { info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
     })
     expect(dispatched).toBe(0)
   })
@@ -694,7 +1151,10 @@ describe('ToolRegistry', () => {
       callId: CallId('cancelled-wrapper'), name: 'must-not-run', arguments: {}, signal: controller.signal,
     })
 
-    expect(result.error).toEqual({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(result.error).toEqual({
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    })
     expect(dispatched).toBe(0)
   })
 
@@ -712,6 +1172,7 @@ describe('ToolRegistry', () => {
       entered.resolve(undefined)
       await release.promise
       return {
+        value: 'wrapper success',
         content: [{ type: 'text', text: 'wrapper success' }],
         isError: false,
         additionalContexts: [{
@@ -735,7 +1196,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toMatchObject({
       content: [{ type: 'text', text: 'Error: tool call aborted before dispatch' }],
       isError: true,
-      error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      error: { info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
       additionalContexts: [{ source: { kind: 'plugin', plugin: 'wrapper' } }],
     })
     expect(dispatched).toBe(0)
@@ -751,7 +1212,7 @@ describe('ToolRegistry', () => {
           content: [{ type: 'text', text: 'completed child work' }],
           source: { kind: 'plugin', plugin: 'child' },
         })
-        return [{ type: 'text', text: 'body complete' }]
+        return 'body complete'
       },
     })
     const entered = Promise.withResolvers<undefined>()
@@ -773,7 +1234,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toMatchObject({
       content: [{ type: 'text', text: 'Error: tool call aborted' }],
       isError: true,
-      error: { name: 'AbortError', code: TOOL_ABORTED },
+      error: { info: { name: 'AbortError', code: TOOL_ABORTED } },
       additionalContexts: [{ source: { kind: 'plugin', plugin: 'child' } }],
     })
   })
@@ -788,7 +1249,7 @@ describe('ToolRegistry', () => {
           content: [{ type: 'text', text: 'completed child work' }],
           source: { kind: 'plugin', plugin: 'child' },
         })
-        return [{ type: 'text', text: 'body complete' }]
+        return 'body complete'
       },
     })
     const entered = Promise.withResolvers<undefined>()
@@ -816,7 +1277,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toMatchObject({
       content: [{ type: 'text', text: 'Error: tool call aborted' }],
       isError: true,
-      error: { name: 'AbortError', code: 'ABORTED' },
+      error: { info: { name: 'AbortError', code: TOOL_ABORTED } },
       additionalContexts: [
         { source: { kind: 'plugin', plugin: 'child' } },
         { source: { kind: 'plugin', plugin: 'post' } },
@@ -851,7 +1312,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toMatchObject({
       content: [{ type: 'text', text: 'Error: wrapper failed' }],
       isError: true,
-      error: { name: 'HarnessError', code: 'WRAPPER_FAILURE' },
+      error: { info: { name: 'HarnessError', code: 'WRAPPER_FAILURE' } },
     })
     expect(dispatched).toBe(0)
   })
@@ -864,7 +1325,7 @@ describe('ToolRegistry', () => {
       name: 'tool-failure',
       execute(_args, exec) {
         entered.resolve(undefined)
-        return new Promise<never[]>((_resolve, reject) => {
+        return new Promise<never>((_resolve, reject) => {
           exec.signal.addEventListener('abort', () => {
             reject(new HarnessError('tool failed', 'TOOL_FAILURE'))
           }, { once: true })
@@ -882,7 +1343,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toMatchObject({
       content: [{ type: 'text', text: 'Error: tool failed' }],
       isError: true,
-      error: { name: 'HarnessError', code: 'TOOL_FAILURE' },
+      error: { info: { name: 'HarnessError', code: 'TOOL_FAILURE' } },
     })
   })
 
@@ -908,7 +1369,7 @@ describe('ToolRegistry', () => {
     await expect(pending).resolves.toMatchObject({
       content: [{ type: 'text', text: 'Error: post-policy failed' }],
       isError: true,
-      error: { name: 'HarnessError', code: 'POST_FAILURE' },
+      error: { info: { name: 'HarnessError', code: 'POST_FAILURE' } },
     })
   })
 
@@ -923,9 +1384,9 @@ describe('ToolRegistry', () => {
       execute(_args, exec) {
         bodySignal = exec.signal
         entered.resolve(undefined)
-        if (exec.signal.aborted) return Promise.resolve([])
-        return new Promise((resolve) => {
-          exec.signal.addEventListener('abort', () => { resolve([]) }, { once: true })
+        if (exec.signal.aborted) return Promise.resolve('stopped')
+        return new Promise<string>((resolve) => {
+          exec.signal.addEventListener('abort', () => { resolve('stopped') }, { once: true })
         })
       },
     })
@@ -950,7 +1411,7 @@ describe('ToolRegistry', () => {
 
     await expect(pending).resolves.toMatchObject({
       isError: true,
-      error: { name: 'AbortError', code: 'ABORTED' },
+      error: { info: { name: 'AbortError', code: TOOL_ABORTED } },
     })
     expect(bodySignal?.aborted).toBe(true)
     expect(replacement.signal.aborted).toBe(false)
@@ -984,7 +1445,7 @@ describe('ToolRegistry', () => {
   it('waits for an uncooperative started body before returning ABORTED', async () => {
     const ctx = await setup()
     const entered = Promise.withResolvers<undefined>()
-    const release = Promise.withResolvers<never[]>()
+    const release = Promise.withResolvers<string>()
     ctx.tools.register({
       ...echoTool,
       name: 'uncooperative',
@@ -1009,10 +1470,10 @@ describe('ToolRegistry', () => {
       Promise.resolve('pending' as const),
     ])
     expect(state).toBe('pending')
-    release.resolve([])
+    release.resolve('settled')
     await expect(pending).resolves.toMatchObject({
       isError: true,
-      error: { name: 'AbortError', code: 'ABORTED' },
+      error: { info: { name: 'AbortError', code: TOOL_ABORTED } },
       additionalContexts: [{ source: { kind: 'plugin', plugin: 'nested' } }],
     })
   })
@@ -1057,7 +1518,10 @@ describe('ToolRegistry', () => {
     expect(result).toEqual({
       content: [{ type: 'text', text: 'Error: tool call aborted before dispatch' }],
       isError: true,
-      error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      error: {
+        message: 'tool call aborted before dispatch',
+        info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      },
     })
     expect(observedResult).toBe(result)
     expect(Object.isFrozen(observedExecution)).toBe(true)
@@ -1084,6 +1548,7 @@ describe('ToolRegistry', () => {
     expect(result).toEqual({
       content: [{ type: 'text', text: 'Error: tool execution arguments must be losslessly JSON-serializable' }],
       isError: true,
+      error: { message: 'tool execution arguments must be losslessly JSON-serializable' },
     })
     expect(observed).toBe(1)
   })
@@ -1123,11 +1588,36 @@ describe('ToolRegistry', () => {
     })
 
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'boom', arguments: {} })
-    expect(seen).toEqual({ isError: true, error: { name: 'HarnessError', code: 'BOOM' } })
+    expect(seen).toEqual({
+      isError: true,
+      error: { message: 'kaboom', info: { name: 'HarnessError', code: 'BOOM' } },
+    })
     expect(result.isError).toBe(true)
     expect(result.content[0]).toMatchObject({ text: 'Error: kaboom' })
   })
 
+  it('freezes core dispatch outcomes before around and post listeners can observe them', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+    const mutationAttempts: boolean[] = []
+    ctx.on('tools/execute', async (_exec, next) => {
+      const result = await next()
+      mutationAttempts.push(Reflect.set(result, 'value', 'around mutation'))
+      return result
+    })
+    ctx.on('tools/post-execute', async (_exec, result, next) => {
+      mutationAttempts.push(Reflect.set(result, 'value', 'post mutation'))
+      return next()
+    })
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('frozen-canonical'), name: 'echo', arguments: { text: 'original' },
+    })
+    expect(mutationAttempts).toEqual([false, false])
+    expect(result.isError ? undefined : result.value).toBe('original')
+  })
+
   it('a thrown tool normalized inside tools/execute still reaches post-execute', async () => {
     const ctx = await setup()
     ctx.tools.register({
@@ -1157,7 +1647,7 @@ describe('ToolRegistry', () => {
       name: 'signal-probe',
       async execute(_args, exec) {
         seenSignal = exec.signal
-        return [{ type: 'text' as const, text: 'ok' }]
+        return 'ok'
       },
     })
 
@@ -1183,23 +1673,73 @@ describe('ToolRegistry', () => {
     ctx.tools.register({
       ...echoTool,
       name: 'never-runs',
-      async execute() { dispatched = true; return [] },
+      async execute() { dispatched = true; return 'unreachable' },
     })
 
     ctx.on('tools/execute', async (_exec: ToolDispatchExecution, _next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult> =>
-      ({ content: [{ type: 'text', text: 'short-circuited' }], isError: false }))
+      ({ content: [{ type: 'text', text: 'ignored authored content' }], isError: false, value: 'short-circuited' }))
 
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'never-runs', arguments: {} })
     expect(dispatched).toBe(false) // returning without next() skips core dispatch
     expect(result.content[0]).toMatchObject({ text: 'short-circuited' })
   })
 
+  it('revalidates a cached canonical result returned from a different dispatch', async () => {
+    const ctx = await setup()
+    ctx.tools.register({ ...echoTool, name: 'string-output', async execute() { return 'cached' } })
+    let objectBodyRan = false
+    ctx.tools.register(defineTool({
+      name: 'object-output',
+      description: 'Return one closed object.',
+      parameters: {},
+      output: {
+        schema: {
+          type: 'object',
+          properties: { ok: { type: 'boolean', required: true } },
+          additionalProperties: false,
+        },
+        render: (_args, value) => [{ type: 'text', text: String(value.ok) }],
+      },
+      execute() {
+        objectBodyRan = true
+        return Promise.resolve({ ok: true })
+      },
+    }))
+    let cached: ToolExecutionResult | undefined
+    ctx.on('tools/execute', async (exec, next) => {
+      if (exec.name === 'string-output') {
+        cached = await next()
+        return cached
+      }
+      if (exec.name === 'object-output') {
+        if (cached === undefined) throw new Error('expected the first dispatch result')
+        return cached
+      }
+      return next()
+    })
+
+    const first = await ctx.tools.execute({
+      signal: testToolSignal, callId: CallId('cached-first'), name: 'string-output', arguments: {},
+    })
+    const second = await ctx.tools.execute({
+      signal: testToolSignal, callId: CallId('cached-second'), name: 'object-output', arguments: {},
+    })
+
+    expect(first.isError ? undefined : first.value).toBe('cached')
+    expect(objectBodyRan).toBe(false)
+    expect(second).toMatchObject({
+      isError: true,
+      error: { info: { name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' } },
+    })
+  })
+
   it('preserves additionalContexts supplied by an around-dispatch result', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)
     ctx.on('tools/execute', async () => ({
       content: [{ type: 'text', text: 'short-circuited with context' }],
       isError: false,
+      value: 'short-circuited with context',
       additionalContexts: [{
         content: [{ type: 'text', text: 'from around dispatch' }],
         source: { kind: 'plugin', plugin: 'test' },
@@ -1224,6 +1764,7 @@ describe('ToolRegistry', () => {
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } })
     expect(result).toEqual({
       content: [{ type: 'text', text: 'Error: wrapper broke' }],
+      error: { message: 'wrapper broke' },
       isError: true,
     })
   })
@@ -1239,6 +1780,7 @@ describe('ToolRegistry', () => {
 
     expect(result).toEqual({
       content: [{ type: 'text', text: 'Error: permission hook broke' }],
+      error: { message: 'permission hook broke' },
       isError: true,
     })
   })
@@ -1254,6 +1796,7 @@ describe('ToolRegistry', () => {
 
     expect(result).toEqual({
       content: [{ type: 'text', text: 'Error: post hook broke' }],
+      error: { message: 'post hook broke' },
       isError: true,
     })
   })
@@ -1269,7 +1812,7 @@ describe('ToolRegistry', () => {
 
     expect(result).toMatchObject({
       isError: true,
-      error: { name: 'HarnessError', code: 'DENIED' },
+      error: { message: 'denied', info: { name: 'HarnessError', code: 'DENIED' } },
     })
   })
 
@@ -1289,6 +1832,41 @@ describe('ToolRegistry', () => {
     }])
   })
 
+  it('schemas() snapshots deeply nested parameters without using structured-clone recursion', async () => {
+    const ctx = await setup()
+    const depth = 5_000
+    let nested: JsonSchemaNode = { type: 'string' }
+    for (let index = 0; index < depth; index++) nested = { oneOf: [nested, { type: 'null' }] }
+    ctx.tools.register({
+      ...echoTool,
+      name: 'deep-schema',
+      parameters: { type: 'object', properties: { nested } },
+    })
+
+    const projected = ctx.tools.schemas()[0]!.parameters as JsonSchemaNode
+
+    let cursor = projected.properties!.nested!
+    let layers = 0
+    while (cursor.oneOf !== undefined) {
+      cursor = cursor.oneOf[0]!
+      layers++
+    }
+    expect(layers).toBe(depth)
+    expect(cursor).toEqual({ type: 'string' })
+  })
+
+  it('rejects schema projection when a raw registration is not lossless JSON', async () => {
+    const ctx = await setup()
+    ctx.tools.register({
+      ...echoTool,
+      name: 'lossy-schema',
+      parameters: { type: 'object', default: Number.NaN },
+    })
+
+    expect(() => ctx.tools.schemas())
+      .toThrow('tool "lossy-schema" parameters must be lossless JSON before schema projection')
+  })
+
   it('rejects a non-positive or non-finite registration timeout', async () => {
     const ctx = await setup()
     expect(() => ctx.tools.register({ ...echoTool, name: 'zero-timeout', timeoutMs: 0 }))
@@ -1368,13 +1946,13 @@ describe('ToolRegistry', () => {
 })
 
 describe('defineTool / schema DSL', () => {
-  it('converts SchemaSpec to standard JSON Schema with required array', () => {
+  it('converts ParameterSchemaSpec to standard JSON Schema with required array', () => {
     const spec = {
       path: { type: 'string', required: true, description: 'Absolute path' },
       offset: { type: 'number' },
       limit: { type: 'number', description: 'Max lines' },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     expect(jsonSchema).toEqual({
       type: 'object',
       properties: {
@@ -1387,7 +1965,7 @@ describe('defineTool / schema DSL', () => {
   })
 
   it('handles empty spec (no properties, no required)', () => {
-    expect(schemaSpecToJsonSchema({})).toEqual({
+    expect(parameterSchemaSpecToJsonSchema({})).toEqual({
       type: 'object',
       properties: {},
     })
@@ -1397,19 +1975,21 @@ describe('defineTool / schema DSL', () => {
     const spec = {
       config: {
         type: 'object',
+        additionalProperties: true,
         required: true,
         properties: {
           host: { type: 'string', required: true },
           port: { type: 'number' },
         },
       },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     expect(jsonSchema).toEqual({
       type: 'object',
       properties: {
         config: {
           type: 'object',
+          additionalProperties: true,
           properties: {
             host: { type: 'string' },
             port: { type: 'number' },
@@ -1430,10 +2010,14 @@ describe('defineTool / schema DSL', () => {
         text: { type: 'string', required: true },
         uppercase: { type: 'boolean' },
       },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
       async execute(args) {
         // args is typed: { text: string; uppercase?: boolean }
         const result = args.uppercase ? args.text.toUpperCase() : args.text
-        return [{ type: 'text', text: result }]
+        return result
       },
     })
 
@@ -1458,6 +2042,7 @@ describe('defineTool / schema DSL', () => {
       arguments: { text: 'hello', uppercase: true },
     })
     expect(result.isError).toBe(false)
+    expect(result.isError ? undefined : result.value).toBe('HELLO')
     expect(result.content).toEqual([{ type: 'text', text: 'HELLO' }])
   })
 
@@ -1468,12 +2053,13 @@ describe('defineTool / schema DSL', () => {
       name: 'type-check',
       description: '',
       parameters: { a: { type: 'string' as const, required: true as const }, b: { type: 'number' as const } },
+      output: { schema: { type: 'string' }, render: () => [] },
       async execute(args) {
         // Verify types at runtime via typeof
         expect(typeof args.a).toBe('string')
         // args.b should be undefined when not provided
         void args
-        return [{ type: 'text', text: args.a }]
+        return args.a
       },
     })
     void tool
@@ -1488,8 +2074,12 @@ describe('defineTool / schema DSL', () => {
         req: { type: 'string', required: true },
         opt: { type: 'number', description: 'Optional number' },
       },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
       async execute(args) {
-        return [{ type: 'text', text: `${args.req}:${args.opt ?? 'none'}` }]
+        return `${args.req}:${args.opt ?? 'none'}`
       },
     }))
 
@@ -1526,9 +2116,13 @@ describe('defineTool / schema DSL', () => {
         properties: { path: { type: 'string' } },
         required: ['path'],
       },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value as string }],
+      },
       async execute(args: unknown) {
         const p = args as { path: string }
-        return [{ type: 'text', text: p.path }]
+        return p.path
       },
     })
 
@@ -1554,8 +2148,8 @@ describe('schema DSL edge cases', () => {
   it('emits enum values in JSON Schema property', () => {
     const spec = {
       color: { type: 'string', enum: ['red', 'green', 'blue'], description: 'Color choice' },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     expect(jsonSchema.properties['color']).toMatchObject({
       type: 'string',
       enum: ['red', 'green', 'blue'],
@@ -1566,8 +2160,8 @@ describe('schema DSL edge cases', () => {
   it('emits default value in JSON Schema property', () => {
     const spec = {
       limit: { type: 'number', default: 25 },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     expect(jsonSchema.properties['limit']).toMatchObject({
       type: 'number',
       default: 25,
@@ -1577,8 +2171,8 @@ describe('schema DSL edge cases', () => {
   it('handles array items without nested properties (plain type array)', () => {
     const spec = {
       tags: { type: 'array', items: { type: 'string' } },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     expect(jsonSchema.properties['tags']).toEqual({
       type: 'array',
       items: { type: 'string' },
@@ -1588,8 +2182,8 @@ describe('schema DSL edge cases', () => {
   it('handles enum and default together in one property', () => {
     const spec = {
       level: { type: 'string', enum: ['low', 'high'], default: 'low' },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     expect(jsonSchema.properties['level']).toMatchObject({
       type: 'string',
       enum: ['low', 'high'],
@@ -1600,8 +2194,8 @@ describe('schema DSL edge cases', () => {
   it('omits description, enum, default keys when not specified', () => {
     const spec = {
       bare: { type: 'string' },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     const prop = jsonSchema.properties['bare'] as Record<string, unknown>
     expect(prop).toEqual({ type: 'string' })
     expect('description' in prop).toBe(false)
@@ -1612,8 +2206,8 @@ describe('schema DSL edge cases', () => {
   it('handles array with no items (items omitted)', () => {
     const spec = {
       raw: { type: 'array' },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     expect(jsonSchema.properties['raw']).toEqual({
       type: 'array',
     })
@@ -1623,13 +2217,14 @@ describe('schema DSL edge cases', () => {
     const spec = {
       config: {
         type: 'object',
+        additionalProperties: true,
         properties: {
           host: { type: 'string' },
           port: { type: 'number' },
         },
       },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
+    } satisfies ParameterSchemaSpec
+    const jsonSchema = parameterSchemaSpecToJsonSchema(spec)
     expect(jsonSchema.properties['config']).toMatchObject({
       type: 'object',
       properties: {
@@ -1660,6 +2255,7 @@ describe('schema DSL optional and nested contracts', () => {
         type: 'array'
         items: {
           type: 'object'
+          additionalProperties: true
           properties: {
             host: { type: 'string'; required: true }
             port: { type: 'number' }
@@ -1669,7 +2265,7 @@ describe('schema DSL optional and nested contracts', () => {
     }>
     expectTypeOf<Args>().toEqualTypeOf<{
       names: string[]
-      servers?: { host: string; port?: number }[]
+      servers?: ({ host: string; port?: number } & Record<string, JsonValue>)[]
     }>()
   })
 
@@ -1679,20 +2275,22 @@ describe('schema DSL optional and nested contracts', () => {
         type: 'array',
         items: {
           type: 'object',
+          additionalProperties: true,
           properties: {
             host: { type: 'string', required: true },
             port: { type: 'number' },
           },
         },
       },
-    } satisfies SchemaSpec
-    expect(schemaSpecToJsonSchema(spec)).toEqual({
+    } satisfies ParameterSchemaSpec
+    expect(parameterSchemaSpecToJsonSchema(spec)).toEqual({
       type: 'object',
       properties: {
         servers: {
           type: 'array',
           items: {
             type: 'object',
+            additionalProperties: true,
             properties: {
               host: { type: 'string' },
               port: { type: 'number' },
@@ -1774,7 +2372,7 @@ describe('validateArgs (the runtime-validation Agent Note, part 1)', () => {
     const spec = {
       path: { type: 'string', required: true },
       limit: { type: 'number' },
-    } satisfies SchemaSpec
+    } satisfies ParameterSchemaSpec
     expect(validateArgs(spec, { path: '/tmp' })).toEqual([])
     expect(validateArgs(spec, { path: '/tmp', limit: 5 })).toEqual([])
     // never throws regardless of shape
@@ -1784,18 +2382,18 @@ describe('validateArgs (the runtime-validation Agent Note, part 1)', () => {
   })
 
   it('flags a missing required key and a required key present as undefined', () => {
-    const spec = { path: { type: 'string', required: true } } satisfies SchemaSpec
+    const spec = { path: { type: 'string', required: true } } satisfies ParameterSchemaSpec
     expect(validateArgs(spec, {})).toEqual(['missing required property "path"'])
     expect(validateArgs(spec, { path: undefined })).toEqual(['missing required property "path"'])
   })
 
   it('allows extra keys (no additionalProperties:false) and omitted optionals', () => {
-    const spec = { path: { type: 'string', required: true } } satisfies SchemaSpec
+    const spec = { path: { type: 'string', required: true } } satisfies ParameterSchemaSpec
     expect(validateArgs(spec, { path: '/tmp', extra: 1 })).toEqual([])
   })
 
   it('does not apply defaults (validation only)', () => {
-    const spec = { limit: { type: 'number', default: 25 } } satisfies SchemaSpec
+    const spec = { limit: { type: 'number', default: 25 } } satisfies ParameterSchemaSpec
     // absent optional is valid, and validation does not synthesize the default
     expect(validateArgs(spec, {})).toEqual([])
   })
@@ -1805,39 +2403,41 @@ describe('validateArgs (the runtime-validation Agent Note, part 1)', () => {
       s: { type: 'string' },
       n: { type: 'number' },
       b: { type: 'boolean' },
-    } satisfies SchemaSpec
+    } satisfies ParameterSchemaSpec
     expect(validateArgs(spec, { s: 1 })).toEqual(['"s" must be a string'])
     expect(validateArgs(spec, { n: 'x' })).toEqual(['"n" must be a number'])
     expect(validateArgs(spec, { b: 'x' })).toEqual(['"b" must be a boolean'])
   })
 
   it('checks enum membership', () => {
-    const spec = { color: { type: 'string', enum: ['red', 'green'] } } satisfies SchemaSpec
+    const spec = { color: { type: 'string', enum: ['red', 'green'] } } satisfies ParameterSchemaSpec
     expect(validateArgs(spec, { color: 'red' })).toEqual([])
     expect(validateArgs(spec, { color: 'blue' })).toEqual(['"color" must be one of ["red","green"]'])
   })
 
-  it('checks enum uniformly with the converter (enum on a non-string prop)', () => {
-    // The converter emits `enum` regardless of type; the validator must agree.
-    // `enum` is string[], so a number value can never be a member.
-    const spec = { n: { type: 'number', enum: ['1', '2'] } } as unknown as SchemaSpec
-    expect(validateArgs(spec, { n: 1 })).toEqual(['"n" must be one of ["1","2"]'])
+  it('enforces type-correct scalar enum declarations', () => {
+    const spec = { n: { type: 'number', enum: [1, 2] } } satisfies ParameterSchemaSpec
+    expect(validateArgs(spec, { n: 1 })).toEqual([])
+    expect(validateArgs(spec, { n: 3 })).toEqual(['"n" must be one of [1,2]'])
+    const invalid = { n: { type: 'number', enum: ['1', '2'] } } as unknown as ParameterSchemaSpec
+    expect(() => validateArgs(invalid, { n: 1 })).toThrow(JsonSchemaError)
   })
 
-  it('rejects an unknown SchemaType at runtime (assertNever guard)', () => {
-    const spec = { x: { type: 'weird' } } as unknown as SchemaSpec
-    expect(() => validateArgs(spec, { x: 1 })).toThrow(/unreachable variant.*validateArgs/)
+  it('rejects an unknown schema type at the author boundary', () => {
+    const spec = { x: { type: 'weird' } } as unknown as ParameterSchemaSpec
+    expect(() => validateArgs(spec, { x: 1 })).toThrow(JsonSchemaError)
   })
 
   it('recurses into nested objects (and an object without properties only type-checks)', () => {
     const spec = {
       config: {
         type: 'object',
+        additionalProperties: true,
         required: true,
         properties: { host: { type: 'string', required: true }, port: { type: 'number' } },
       },
-      bag: { type: 'object' },
-    } satisfies SchemaSpec
+      bag: { type: 'object', additionalProperties: true },
+    } satisfies ParameterSchemaSpec
     expect(validateArgs(spec, { config: { host: 'h' }, bag: { anything: true } })).toEqual([])
     expect(validateArgs(spec, { config: { port: 9 }, bag: 5 })).toEqual([
       'missing required property "config.host"',
@@ -1849,7 +2449,7 @@ describe('validateArgs (the runtime-validation Agent Note, part 1)', () => {
     const spec = {
       tags: { type: 'array', items: { type: 'string' } },
       raw: { type: 'array' },
-    } satisfies SchemaSpec
+    } satisfies ParameterSchemaSpec
     expect(validateArgs(spec, { tags: ['a', 'b'], raw: [1, {}, 'x'] })).toEqual([])
     expect(validateArgs(spec, { tags: ['a', 2] })).toEqual(['"tags[1]" must be a string'])
     // a non-array value for an array-typed prop
@@ -1860,9 +2460,9 @@ describe('validateArgs (the runtime-validation Agent Note, part 1)', () => {
     const spec = {
       servers: {
         type: 'array',
-        items: { type: 'object', properties: { host: { type: 'string', required: true } } },
+        items: { type: 'object', additionalProperties: true, properties: { host: { type: 'string', required: true } } },
       },
-    } satisfies SchemaSpec
+    } satisfies ParameterSchemaSpec
     expect(validateArgs(spec, { servers: [{ host: 'a' }, {}] })).toEqual([
       'missing required property "servers[1].host"',
     ])
@@ -1872,7 +2472,7 @@ describe('validateArgs (the runtime-validation Agent Note, part 1)', () => {
 describe('defineTool validation (the runtime-validation Agent Note, part 1)', () => {
   it('returns an isError result with the violations when the model sends bad args', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'reader',
       description: 'reads a path',
       parameters: { path: { type: 'string', required: true } },
@@ -1890,7 +2490,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
 
   it('runs execute normally when args are valid', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'reader',
       description: 'reads a path',
       parameters: { path: { type: 'string', required: true } },
@@ -1899,7 +2499,11 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
       },
     }))
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'reader', arguments: { path: '/x' } })
-    expect(result).toEqual({ content: [{ type: 'text', text: 'read /x' }], isError: false })
+    expect(result).toEqual({
+      content: [{ type: 'text', text: 'read /x' }],
+      isError: false,
+      value: [{ type: 'text', text: 'read /x' }],
+    })
   })
 
   it('ToolArgsError carries a stable code and the violation list', () => {
@@ -1913,7 +2517,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
 
   it('a schema-invalid call surfaces the structured error on the result', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'reader',
       description: 'reads a path',
       parameters: { path: { type: 'string', required: true } },
@@ -1923,7 +2527,10 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
     }))
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'reader', arguments: {} })
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'ToolArgsError', code: 'INVALID_ARGS' })
+    expect(result.error).toEqual({
+      message: 'invalid arguments: missing required property "path"',
+      info: { name: 'ToolArgsError', code: 'INVALID_ARGS' },
+    })
   })
 
   it('a tool throwing a HarnessError surfaces its name and code', async () => {
@@ -1938,11 +2545,11 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
     })
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'coded', arguments: {} })
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'HarnessError', code: 'ENOSPC' })
+    expect(result.error).toEqual({ message: 'disk full', info: { name: 'HarnessError', code: 'ENOSPC' } })
     expect(result.content[0]).toMatchObject({ text: 'Error: disk full' })
   })
 
-  it('a non-HarnessError throw has no structured error (only the text)', async () => {
+  it('a non-HarnessError throw retains only its message', async () => {
     const ctx = await setup()
     ctx.tools.register({
       ...echoTool,
@@ -1953,7 +2560,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
     })
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'plain', arguments: {} })
     expect(result.isError).toBe(true)
-    expect(result.error).toBeUndefined()
+    expect(result.error).toEqual({ message: 'just a message' })
     expect(result.content[0]).toMatchObject({ text: 'Error: just a message' })
   })
 
@@ -1964,8 +2571,12 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
       name: 'raw',
       description: 'raw tool',
       parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value as string }],
+      },
       async execute(args: unknown) {
-        return [{ type: 'text', text: typeof args }]
+        return typeof args
       },
     })
     // Missing the "required" path — but raw tools validate their own input, so
@@ -1975,7 +2586,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
   })
 
   it('attaches a positive-finite timeoutMs to the definition', () => {
-    const tool = defineTool({
+    const tool = defineContentToolFixture({
       name: 'x', description: 'd', parameters: {}, timeoutMs: 30_000,
       async execute() { return [{ type: 'text' as const, text: 'ok' }] },
     })
@@ -1983,7 +2594,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
   })
 
   it('omits timeoutMs when not declared', () => {
-    const tool = defineTool({
+    const tool = defineContentToolFixture({
       name: 'x', description: 'd', parameters: {},
       async execute() { return [{ type: 'text' as const, text: 'ok' }] },
     })
@@ -1991,7 +2602,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
   })
 
   it('throws when timeoutMs is zero or negative', () => {
-    const make = (ms: number) => defineTool({
+    const make = (ms: number) => defineContentToolFixture({
       name: 'x', description: 'd', parameters: {}, timeoutMs: ms,
       async execute() { return [{ type: 'text' as const, text: 'ok' }] },
     })
@@ -2000,7 +2611,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
   })
 
   it('throws when timeoutMs is non-finite', () => {
-    expect(() => defineTool({
+    expect(() => defineContentToolFixture({
       name: 'x', description: 'd', parameters: {}, timeoutMs: Infinity,
       async execute() { return [{ type: 'text' as const, text: 'ok' }] },
     })).toThrow('positive finite number')
@@ -2008,8 +2619,27 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
 })
 
 describe('defineTool presentation (presentCall / presentResult)', () => {
+  it('preserves inline enum and const literals in inferred arguments', () => {
+    defineTool({
+      name: 'literal-args',
+      description: 'literal arguments',
+      parameters: {
+        mode: { type: 'string', enum: ['read', 'write'], required: true },
+        attempt: { type: 'integer', const: 1 },
+      },
+      output: {
+        schema: { type: 'null' },
+        render: () => [],
+      },
+      async execute(args) {
+        expectTypeOf(args).toEqualTypeOf<{ mode: 'read' | 'write'; attempt?: 1 }>()
+        return null
+      },
+    })
+  })
+
   it('threads presentCall/presentResult onto the ToolDefinition with typed args', () => {
-    const tool = defineTool({
+    const tool = defineContentToolFixture({
       name: 'demo',
       description: 'demo',
       parameters: { path: { type: 'string', required: true }, n: { type: 'number' } },
@@ -2029,7 +2659,7 @@ describe('defineTool presentation (presentCall / presentResult)', () => {
   })
 
   it('a tool without presentCall/presentResult leaves them undefined (UI falls back generically)', () => {
-    const tool = defineTool({
+    const tool = defineContentToolFixture({
       name: 'plain',
       description: 'plain',
       parameters: { x: { type: 'string', required: true } },
@@ -2040,7 +2670,7 @@ describe('defineTool presentation (presentCall / presentResult)', () => {
   })
 
   it('presentCall/presentResult validate softly: malformed args return undefined, never throw (display runs on replay)', () => {
-    const tool = defineTool({
+    const tool = defineContentToolFixture({
       name: 'demo',
       description: 'demo',
       parameters: { path: { type: 'string', required: true } },
diff --git a/packages/core/tools/tests/ts-types.spec.ts b/packages/core/tools/tests/ts-types.spec.ts
index df30a58238..df820fc153 100644
--- a/packages/core/tools/tests/ts-types.spec.ts
+++ b/packages/core/tools/tests/ts-types.spec.ts
@@ -1,20 +1,37 @@
 import { describe, expect, it } from 'vitest'
 import { jsonSchemaToTs, renderToolsSdk } from '@deepseek-ai/dsh-tools/src/ts-types.ts'
-import { schemaSpecToJsonSchema } from '@deepseek-ai/dsh-tools'
-import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { ToolSdkSchema } from '@deepseek-ai/dsh-tools/src/ts-types.ts'
+import { parameterSchemaSpecToJsonSchema } from '@deepseek-ai/dsh-tools'
 
 describe('jsonSchemaToTs', () => {
-  it('maps the defineTool DSL subset', () => {
+  it('maps every unified schema construct', () => {
     const cases: [unknown, string][] = [
       [{ type: 'string' }, 'string'],
       [{ type: 'number' }, 'number'],
+      [{ type: 'integer' }, 'number'],
       [{ type: 'boolean' }, 'boolean'],
+      [{ type: 'null' }, 'null'],
       [{ type: 'string', enum: ['a', 'b'] }, '"a" | "b"'],
+      [{ type: 'number', enum: [1, 2] }, '1 | 2'],
+      [{ type: 'integer', const: 2 }, '2'],
+      [{ type: 'boolean', const: true }, 'true'],
+      [{ type: 'null', const: null }, 'null'],
+      [{ type: 'string', enum: ['a', 'b'], const: 'a' }, '"a"'],
+      [{ oneOf: [{ type: 'string' }, { type: 'null' }] }, 'string | null'],
       [{ type: 'array', items: { type: 'number' } }, 'number[]'],
       [{ type: 'array', items: { type: 'string', enum: ['x', 'y'] } }, '("x" | "y")[]'],
-      [{ type: 'array' }, 'unknown[]'],
-      [{ type: 'object' }, 'Record<string, unknown>'],
-      [{ type: 'object', properties: {} }, 'Record<string, unknown>'],
+      [{ type: 'array' }, 'JsonValue[]'],
+      [{ type: 'object' }, 'Record<string, JsonValue>'],
+      [{ type: 'object', additionalProperties: false }, 'Record<string, never>'],
+      [{ type: 'object', properties: {} }, 'Record<string, JsonValue>'],
+      [{ type: 'object', properties: {}, additionalProperties: false }, 'Record<string, never>'],
+      [{
+        type: 'object',
+        additionalProperties: false,
+        properties: { id: { type: 'integer' }, label: { type: 'string' } },
+        required: ['id'],
+      }, ['{', '  id: number;', '  label?: string;', '}'].join('\n')],
+      [{}, 'JsonValue'],
     ]
     for (const [schema, expected] of cases) {
       expect(jsonSchemaToTs(schema), JSON.stringify(schema)).toBe(expected)
@@ -22,11 +39,12 @@ describe('jsonSchemaToTs', () => {
   })
 
   it('renders objects with required/optional keys, nested shapes, and per-property docs', () => {
-    const schema = schemaSpecToJsonSchema({
+    const schema = parameterSchemaSpecToJsonSchema({
       path: { type: 'string', required: true, description: 'Absolute file path' },
       limit: { type: 'number' },
       opts: {
         type: 'object',
+        additionalProperties: true,
         properties: { deep: { type: 'boolean', required: true } },
       },
     })
@@ -37,8 +55,8 @@ describe('jsonSchemaToTs', () => {
       '  limit?: number;',
       '  opts?: {',
       '    deep: boolean;',
-      '  };',
-      '}',
+      '  } & Record<string, JsonValue>;',
+      '} & Record<string, JsonValue>',
     ].join('\n'))
   })
 
@@ -48,9 +66,6 @@ describe('jsonSchemaToTs', () => {
       null,
       42,
       'string-schema',
-      {},
-      { type: 'integer' },
-      { type: 'null' },
       { oneOf: [{ type: 'string' }] },
       { $ref: '#/defs/x' },
       { type: 'object', properties: 7 },
@@ -61,18 +76,13 @@ describe('jsonSchemaToTs', () => {
     for (const schema of cases) {
       expect(() => jsonSchemaToTs(schema), JSON.stringify(schema)).not.toThrow()
     }
-    expect(jsonSchemaToTs({ type: 'integer' })).toBe('unknown')
     expect(jsonSchemaToTs({ oneOf: [] })).toBe('unknown')
-    expect(jsonSchemaToTs({ type: 'object', properties: 7 })).toBe('Record<string, unknown>')
-    expect(jsonSchemaToTs({ type: 'object', properties: { bad: { $ref: 'x' } }, required: ['bad'] })).toContain('bad: unknown;')
-    // A non-string-only enum degrades to plain string; an empty one too.
-    expect(jsonSchemaToTs({ type: 'string', enum: [1, 2] })).toBe('string')
-    expect(jsonSchemaToTs({ type: 'string', enum: [] })).toBe('string')
-    // A hostile required list only accepts string members.
-    expect(jsonSchemaToTs({ type: 'object', properties: { a: { type: 'string' } }, required: [7] })).toContain('a?: string;')
-    // A property VALUE that is not an object degrades to unknown (and can
-    // carry no description).
-    expect(jsonSchemaToTs({ type: 'object', properties: { weird: 42 } })).toContain('weird?: unknown;')
+    expect(jsonSchemaToTs({ type: 'object', properties: 7 })).toBe('unknown')
+    expect(jsonSchemaToTs({ type: 'object', properties: { bad: { $ref: 'x' } }, required: ['bad'] })).toBe('unknown')
+    expect(jsonSchemaToTs({ type: 'string', enum: [1, 2] })).toBe('unknown')
+    expect(jsonSchemaToTs({ type: 'string', enum: [] })).toBe('unknown')
+    expect(jsonSchemaToTs({ type: 'object', properties: { a: { type: 'string' } }, required: [7] })).toBe('unknown')
+    expect(jsonSchemaToTs({ type: 'object', properties: { weird: 42 } })).toBe('unknown')
   })
 
   it('escapes a comment-closer inside a description so the generated JSDoc cannot end early', () => {
@@ -83,33 +93,59 @@ describe('jsonSchemaToTs', () => {
     expect(rendered).not.toContain('tool-*/ over')
     expect(rendered).toContain(String.raw`tool-*\/ over`)
   })
+
+  it('renders deeply nested unions without using the JavaScript call stack', () => {
+    const depth = 5_000
+    let schema: unknown = { type: 'string' }
+    for (let index = 0; index < depth; index++) schema = { oneOf: [schema, { type: 'null' }] }
+
+    const rendered = jsonSchemaToTs(schema)
+
+    expect(rendered.startsWith('string | null')).toBe(true)
+    expect(rendered.length).toBe('string'.length + depth * ' | null'.length)
+  })
 })
 
 describe('renderToolsSdk', () => {
-  const bash: ToolSchema = {
+  const bash: ToolSdkSchema = {
     name: 'bash',
     description: 'Run a shell command.',
-    parameters: schemaSpecToJsonSchema({ command: { type: 'string', required: true } }) as unknown as Record<string, unknown>,
+    parameters: parameterSchemaSpecToJsonSchema({ command: { type: 'string', required: true } }) as unknown as Record<string, unknown>,
+    output: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { exitCode: { type: 'integer' } },
+      required: ['exitCode'],
+    },
   }
-  const exotic: ToolSchema = {
+  const exotic: ToolSdkSchema = {
     name: 'my-mcp.tool',
     description: 'Exotic name.',
-    parameters: schemaSpecToJsonSchema({}) as unknown as Record<string, unknown>,
+    parameters: parameterSchemaSpecToJsonSchema({}) as unknown as Record<string, unknown>,
+    output: { type: 'array', items: { type: 'string' } },
   }
 
   it('declares every tool in lexicographic order with quoted keys for exotic names', () => {
     const text = renderToolsSdk([exotic, bash])
+    expect(text).toContain('interface ToolArgsMap {')
+    expect(text).toContain('interface ToolOutputMap {')
+    expect(text).toContain('type ToolName = keyof ToolOutputMap')
+    expect(text).toContain('declare class ToolCallError extends Error')
+    expect(text).toContain('readonly toolName: ToolName;')
     expect(text).toContain('declare const tools: {')
-    expect(text.indexOf('bash(args:')).toBeGreaterThan(0)
-    expect(text).toContain('"my-mcp.tool"(args:')
-    expect(text.indexOf('bash(args:')).toBeLessThan(text.indexOf('"my-mcp.tool"(args:'))
-    expect(text).toContain('): Promise<string>;')
+    expect(text).toContain('type JsonValue = null | boolean | number | string')
+    expect(text.indexOf('bash: {')).toBeGreaterThan(0)
+    expect(text).toContain('"my-mcp.tool":')
+    expect(text.indexOf('bash:')).toBeLessThan(text.indexOf('"my-mcp.tool":'))
+    expect(text).toContain('exitCode: number;')
+    expect(text).toContain('"my-mcp.tool": string[];')
+    expect(text).toContain('[K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;')
     expect(text).toContain('/** Run a shell command. */')
     // The fixed instruction lines the model relies on.
     expect(text).toContain('erasable syntax only')
-    expect(text).toContain('rejects with an `Error`')
+    expect(text).toContain('rejects with `ToolCallError`')
     expect(text).toContain('sequentially, even under `Promise.all`')
-    expect(text).toContain('JSON-serializable')
+    expect(text).toContain('lossless JSON')
   })
 
   it('is deterministic: same tool set, byte-identical text regardless of input order', () => {
@@ -119,6 +155,8 @@ describe('renderToolsSdk', () => {
   })
 
   it('renders an empty declaration for an empty tool set', () => {
-    expect(renderToolsSdk([])).toContain('declare const tools: {}')
+    const text = renderToolsSdk([])
+    expect(text).toContain('interface ToolArgsMap {}')
+    expect(text).toContain('interface ToolOutputMap {}')
   })
 })
diff --git a/packages/examples/acp-demo/README.md b/packages/examples/acp-demo/README.md
index db13d069f5..93d89d6557 100644
--- a/packages/examples/acp-demo/README.md
+++ b/packages/examples/acp-demo/README.md
@@ -15,7 +15,7 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it
 | `@deepseek-ai/dsh-command-goal` | the discoverable direct `/goal` producer; the app enables the spine's persisted-goal stack with it |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by clients that can complete ACP elicitation requests |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) |
-| `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | exact current-surface reads and bounded `dsh-session:` snapshots |
+| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | combined exact/FTS session queries and bounded `dsh-session:` snapshots |
 | `@deepseek-ai/dsh-session-checkpoint-policy` | semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
 | `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers when a leaf explicitly exposes a user-question tool |
 | ~~`@deepseek-ai/dsh-tool-ask-user`~~ | **omitted by default** — ACP elicitation support is still client-dependent, so leaves must opt in deliberately |
@@ -43,7 +43,7 @@ The app owns this cluster through one ordered Cordis effect. Teardown drains the
 | `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
 | `goals` | owner defaults | persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
 | `llmRetry` | owner defaults | bounded transient model-request retry policy routed through `dsh-agent-spine-demo` |
-| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
+| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory and the parent of the derived `session-query.db` index |
 | `packChunks` | `false` | write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`) |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
 | `sessionReferences` | service defaults | cross-session candidate and snapshot limits routed to `dsh-session-reference` |
@@ -58,7 +58,7 @@ The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the
 - honors `DSH_SNAPSHOT=replay` by booting the sibling `cordis.snapshot.yml` (the keyless replay tree, `llm-replay` in place of `llm-deepseek`);
 - in a snapshot run, disposes the context on stdin EOF so the session log is fully flushed before exit.
 
-Run it under `node --expose-internals`, or Loader's optional `node-addon-require-builtin` fallback is required, so the cordis Loader can resolve the config's bare plugin specifiers through its internal module loader. (`demo:acp` runs under tsx, whose tsconfig `paths` map resolves them instead.)
+The repository installs Loader's optional `node-addon-require-builtin` peer, so the built bin resolves bare plugin specifiers through the internal module loader under plain Node. (`demo:acp` runs under tsx, whose tsconfig `paths` map resolves them instead.)
 
 All diagnostics go to **stderr** — stdout is the protocol.
 
diff --git a/packages/examples/acp-demo/package.json b/packages/examples/acp-demo/package.json
index 6f3dd21ebd..36de692404 100644
--- a/packages/examples/acp-demo/package.json
+++ b/packages/examples/acp-demo/package.json
@@ -46,6 +46,7 @@
     "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
     "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
     "@deepseek-ai/dsh-session-reference": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-user-interaction": "^0.0.1",
@@ -66,6 +67,7 @@
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
diff --git a/packages/examples/acp-demo/src/index.ts b/packages/examples/acp-demo/src/index.ts
index de36614365..1a05a14e3e 100644
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -12,6 +12,7 @@
  */
 
 import type { Context } from 'cordis'
+import { join } from 'node:path'
 import z from 'schemastery'
 import * as acp from '@deepseek-ai/dsh-acp'
 import CommandService from '@deepseek-ai/dsh-commands'
@@ -25,7 +26,7 @@ import SessionPersistenceJsonl, {
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQueryService from '@deepseek-ai/dsh-session-query'
+import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
 
 export const name = 'acp-demo'
@@ -57,7 +58,7 @@ export interface Config {
   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`. */
+  /** 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 `false`. */
   packChunks?: boolean
@@ -110,14 +111,16 @@ export const Config: z<Config> = z.object({
 /**
  * Compose the spine with the ACP front door. The agent-spine-demo bundle pre-creates
  * NO agents (its `agents` list defaults to `[]`) and carries the deployment
- * `persona`; the JSONL backend persists under `persistenceRoot`; the ACP
- * bridge owns stdout for JSON-RPC and creates one agent per `session/new`
- * from the provider/model pair. The composite effect unloads in reverse order,
- * keeping checkpoint and persistence listeners attached until ACP agents have
- * flushed their closing events. No logger, no `hmr` — stdout stays pure.
+ * `persona`; the JSONL backend and derived query index persist under
+ * `persistenceRoot`; the ACP bridge owns stdout for JSON-RPC and creates one
+ * agent per `session/new` from the provider/model pair. The composite effect
+ * unloads in reverse order, keeping checkpoint and persistence listeners
+ * attached until ACP agents have flushed their closing events. No logger, no
+ * `hmr` — stdout stays pure.
  */
 export function apply(ctx: Context, config: Config): void {
   const goals = config.goals ?? {}
+  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
   ctx.effect(function* () {
     yield ctx.plugin(CommandService).dispose
     if (goals !== false) yield ctx.plugin(commandGoal).dispose
@@ -127,13 +130,13 @@ export function apply(ctx: Context, config: Config): void {
     // persistence passthroughs rather than sharing a facade with stdio-demo.
     /* jscpd:ignore-start */
     yield ctx.plugin(SessionPersistenceJsonl, {
-      root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
+      root: persistenceRoot,
       ...config.packChunks !== undefined ? { packChunks: config.packChunks } : {},
       ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
     }).dispose
     /* jscpd:ignore-end */
     yield ctx.plugin(sessionCheckpointPolicy).dispose
-    yield ctx.plugin(SessionQueryService).dispose
+    yield ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') }).dispose
     yield ctx.plugin(SessionReferenceService, config.sessionReferences ?? {}).dispose
     yield ctx.plugin(acp, { provider: config.provider, model: config.model }).dispose
   }, 'acp-demo.composition')
diff --git a/packages/examples/acp-demo/tests/acp-agent.spec.ts b/packages/examples/acp-demo/tests/acp-agent.spec.ts
index 876bf54f75..18cd0b5221 100644
--- a/packages/examples/acp-demo/tests/acp-agent.spec.ts
+++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts
@@ -219,7 +219,8 @@ describe('dsh-acp-demo composition', () => {
         name,
         description: name,
         parameters: {},
-        execute: async () => [],
+        output: { schema: { type: 'null' }, render: () => [] },
+        execute: async () => null,
       })
     }
     const assembly = await ctx.get('systemPrompt')!.assemble()
diff --git a/packages/examples/acp-demo/tests/built-bin.e2e.ts b/packages/examples/acp-demo/tests/built-bin.e2e.ts
index 29791b497f..eb49988dc8 100644
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -23,8 +23,7 @@ import { ACP_SESSION_REFERENCE_META_KEY } from '@deepseek-ai/dsh-acp'
 /**
  * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer and
  * complete a mock-backed turn. This catches built-only settle races, stdout protocol leaks, and
- * published persistence behavior that the tsx source-path smoke cannot. It skips before build;
- * `--expose-internals` enables Cordis bare-plugin loading.
+ * published persistence behavior that the tsx source-path smoke cannot. It skips before build.
  */
 
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
@@ -37,7 +36,8 @@ const dshPackages = [
   'bash/bash-local', 'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
   'session-persistence/session-persistence',
   'session-persistence/session-checkpoint-policy', 'session-persistence/session-persistence-jsonl',
-  'session-query/session-query', 'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
+  'session-query/session-query', 'session-query/session-query-sqlite',
+  'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
   'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
@@ -133,7 +133,7 @@ afterEach(async () => {
 describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, no tsx)', () => {
   it('boots the published bin, completes a turn, and writes default Zstandard persistence', async () => {
     consumer = await makeConsumer()
-    child = spawn(process.execPath, ['--expose-internals', acpBin, '--config', './cordis.yml'], {
+    child = spawn(process.execPath, [acpBin, '--config', './cordis.yml'], {
       cwd: consumer,
       env: {
         ...process.env,
@@ -226,7 +226,7 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, n
 /** Spawn the built acp bin against `configArg` and resolve with its exit code + stderr. */
 function runBinExpectingExit(configArg: string, cwd: string = tmpdir()): Promise<{ code: number; stderr: string }> {
   return new Promise((resolve, reject) => {
-    const proc = spawn(process.execPath, ['--expose-internals', acpBin, '--config', configArg], {
+    const proc = spawn(process.execPath, [acpBin, '--config', configArg], {
       cwd,
       env: {
         ...process.env,
diff --git a/packages/examples/acp-demo/tsconfig.json b/packages/examples/acp-demo/tsconfig.json
index cdc104e987..0115fc938b 100644
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -26,6 +26,9 @@
     {
       "path": "../../session-query/session-query"
     },
+    {
+      "path": "../../session-query/session-query-sqlite"
+    },
     {
       "path": "../../context/session-reference"
     },
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 47687029a5..e00bf2016d 100644
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -235,7 +235,7 @@ describe('dsh-agent-spine-demo bundle', () => {
       agentOptions: { provider: 'mock', model: 'mock' },
     })
 
-    handle.agent.send([{ type: 'text', text: 'recover' }])
+    handle.agent.followup([{ type: 'text', text: 'recover' }])
     await waitForIdle(ctx, handle.agent)
 
     expect(adapter.requests).toBe(2)
@@ -335,7 +335,7 @@ describe('dsh-agent-spine-demo bundle', () => {
       })
       const agent = handle.agent
 
-      agent.send([{ type: 'text', text: 'hi' }])
+      agent.followup([{ type: 'text', text: 'hi' }])
       await waitForIdle(ctx, agent)
 
       const sentText = adapter.requests[0]?.messages.map(messageText).join('\n')
@@ -364,7 +364,7 @@ describe('dsh-agent-spine-demo bundle', () => {
         agentOptions: { provider: 'mock', model: 'mock' },
       })
 
-      handle.agent.send([{ type: 'text', text: 'hi' }])
+      handle.agent.followup([{ type: 'text', text: 'hi' }])
       await waitForIdle(ctx, handle.agent)
 
       expect(adapter.requests[0]?.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }])
@@ -454,7 +454,7 @@ describe('dsh-agent-spine-demo bundle', () => {
         agentOptions: { provider: 'mock', model: 'mock' },
       })
 
-      handle.agent.send([{ type: 'text', text: 'hi' }])
+      handle.agent.followup([{ type: 'text', text: 'hi' }])
       await waitForIdle(ctx, handle.agent)
 
       expect(messageText(adapter.requests[0]?.messages[0])).toContain('workspace rule before skills')
@@ -562,7 +562,8 @@ describe('dsh-agent-spine-demo bundle', () => {
         name,
         description: name,
         parameters: {},
-        execute: async () => [],
+        output: { schema: { type: 'null' }, render: () => [] },
+        execute: async () => null,
       })
     }
     const assembly = await ctx.get('systemPrompt')!.assemble()
diff --git a/packages/examples/cli-demo/README.md b/packages/examples/cli-demo/README.md
index ee806614eb..8a931cc147 100644
--- a/packages/examples/cli-demo/README.md
+++ b/packages/examples/cli-demo/README.md
@@ -38,7 +38,7 @@ The root headless-agent example supplies its leaf:
 pnpm run demo:headless "inspect the failing test and fix it"
 ```
 
-Loader configs with bare package specifiers require `node --expose-internals` or the Loader's optional native fallback. The root command supplies the Node flag.
+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
 
diff --git a/packages/examples/cli-demo/src/cli.ts b/packages/examples/cli-demo/src/cli.ts
index 66ce345520..e6672f91ad 100644
--- a/packages/examples/cli-demo/src/cli.ts
+++ b/packages/examples/cli-demo/src/cli.ts
@@ -290,7 +290,7 @@ export async function runOneShot(ctx: Context, options: OneShotOptions): Promise
   try {
     /* v8 ignore next -- skips send only when cancellation wins the listener-registration race above */
     if (!settled) { // eslint-disable-line @typescript-eslint/no-unnecessary-condition
-      agent.send([{ type: 'text', text: options.task }])
+      agent.followup([{ type: 'text', text: options.task }])
     }
     await turnEnded
   } finally {
diff --git a/packages/examples/cli-demo/tests/built-bin.e2e.ts b/packages/examples/cli-demo/tests/built-bin.e2e.ts
index e002be43e0..5c3a6ad62e 100644
--- a/packages/examples/cli-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts
@@ -116,7 +116,7 @@ interface BinResult {
 
 function runBuiltBin(cwd: string, args: readonly string[], interrupt?: NodeJS.Signals): Promise<BinResult> {
   return new Promise((resolveResult, reject) => {
-    const child = spawn(process.execPath, ['--expose-internals', cliBin, ...args], {
+    const child = spawn(process.execPath, [cliBin, ...args], {
       cwd,
       env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
       stdio: ['ignore', 'pipe', 'pipe'],
diff --git a/packages/examples/cli-demo/tests/cli-demo.spec.ts b/packages/examples/cli-demo/tests/cli-demo.spec.ts
index adf3999445..9bd8088dbe 100644
--- a/packages/examples/cli-demo/tests/cli-demo.spec.ts
+++ b/packages/examples/cli-demo/tests/cli-demo.spec.ts
@@ -104,7 +104,13 @@ describe('dsh-cli-demo app composition', () => {
     })
     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: {}, execute: async () => [] })
+      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([
diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts
index e477924f3f..c57dda5b00 100644
--- a/packages/examples/cli-demo/tests/cli.spec.ts
+++ b/packages/examples/cli-demo/tests/cli.spec.ts
@@ -115,7 +115,11 @@ async function harness(script: readonly ScriptEntry[]): Promise<Harness> {
     name: 'echo',
     description: 'Echo text.',
     parameters: { text: { type: 'string', required: true } },
-    execute: async args => [{ type: 'text', text: `ECHO: ${(args as { text: string }).text}` }],
+    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')
@@ -365,7 +369,7 @@ describe('runOneShot and executeCli', () => {
     const { ctx, agent } = await harness([textResponse('streamed')])
     const other = ctx.sessions.create(SessionId('unrelated'))
     let injected = false
-    ctx.on('agent/queued', (subject) => {
+    ctx.on('agent/inbox/enqueue', (subject) => {
       if (subject !== agent || injected) return
       injected = true
       agent.inject([{ type: 'text', text: 'startup injection' }], { source: { kind: 'plugin', plugin: 'test' } })
@@ -379,7 +383,7 @@ describe('runOneShot and executeCli', () => {
     expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 2, trigger: { kind: 'message' } } })
     expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 2 } })
     expect(lines.slice(0, -1).every(line => line['sessionId'] === agent.session.id)).toBe(true)
-    expect(events.some(event => event.type === 'context/message')).toBe(false)
+    expect(events.some(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toBe(false)
   })
 
   it('emits partial data and a diagnostic for non-completed turns', async () => {
@@ -467,7 +471,7 @@ describe('runOneShot and executeCli', () => {
     startup.ctx.on('session/event', (session, event) => {
       if (session === startup.agent.session && event.type === 'assistant/chunk') started()
     })
-    startup.agent.send([{ type: 'text', text: 'first' }])
+    startup.agent.followup([{ type: 'text', text: 'first' }])
     await running
     const startupAbort = new AbortController()
     const waiting = runOneShot(startup.ctx, { task: 'second', signal: startupAbort.signal })
@@ -477,7 +481,7 @@ describe('runOneShot and executeCli', () => {
 
     const queued = await harness([textResponse('unused')])
     const queuedAbort = new AbortController()
-    queued.ctx.on('agent/queued', (agent) => {
+    queued.ctx.on('agent/inbox/enqueue', (agent) => {
       if (agent === queued.agent) queuedAbort.abort('cancel queued')
     })
     await expect(runOneShot(queued.ctx, { task: 'task', signal: queuedAbort.signal })).rejects.toThrow('cancel queued')
diff --git a/packages/examples/tui-demo/README.md b/packages/examples/tui-demo/README.md
index 146e6503bf..10ff7872c5 100644
--- a/packages/examples/tui-demo/README.md
+++ b/packages/examples/tui-demo/README.md
@@ -13,7 +13,7 @@ Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and
 | `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-session-checkpoint-policy` | Semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
-| `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | Exact current-surface reads and bounded `@session` snapshots consumed by the TUI |
+| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | Combined exact/FTS session queries and bounded `@session` snapshots consumed by the TUI |
 | `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service |
 | `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays |
 | `@deepseek-ai/dsh-tool-ask-user` | Model-facing `ask_user_question` tool |
@@ -37,18 +37,19 @@ Swappable LLM, bash, filesystem, and other capability providers remain in the le
 | `toolTasks` | owner defaults | Background-task control-tool config, or `false` |
 | `goals` | owner defaults | Persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
 | `workspaceContext` | required | Workspace-instruction config, or `false` |
-| `persistenceRoot` | `./.sessions` | JSONL persistence root |
+| `persistenceRoot` | `./.sessions` | JSONL persistence root and parent of the derived `session-query.db` index |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
 | `sessionReferences` | service defaults | Cross-session candidate and snapshot limits routed to `dsh-session-reference` |
 | `welcome` | `ready.` | TUI subtitle |
+| `resumeCommand` | — | Exit and no-host fallback command template; the selector itself uses session query and host handoff |
 | `ui` | owner defaults | TUI presentation settings such as reasoning, color, and card height |
 | `resumeSessionId` | — | Exact persisted session to resume |
 
-Fresh runs mint a `main-session-<uuid>` session id and pass it to both the TUI and configured agent. Resumed runs bind both components to `resumeSessionId`. The TUI mounts before the spine so it can render a matching config-start failure instead of leaving a blank terminal.
+Fresh runs mint a `main-session-<uuid>` session id and pass it to both the TUI and configured agent. Resumed runs bind both components to `resumeSessionId`. The TUI mounts before the spine so it can render a matching config-start failure instead of leaving a blank terminal. The app composes persistence and session query for `/resume`; an embedding host may additionally provide `tuiResumeHost` for in-place process handoff.
 
 ## The bin
 
-`dsh-tui-demo [path-to-cordis.yml]` defaults to `./cordis.yml`, loads the optional cwd `.env`, boots the Cordis Loader, and waits for the full plugin tree. Bare package specifiers require `node --expose-internals` or the Loader's optional native fallback; the repository scripts use `--expose-internals`.
+`dsh-tui-demo [path-to-cordis.yml]` defaults to `./cordis.yml`, loads the optional cwd `.env`, boots the Cordis Loader, and waits for the full plugin tree. The repository installs Loader's optional native helper, so bare package specifiers resolve under plain Node.
 
 ## Example leaf
 
diff --git a/packages/examples/tui-demo/package.json b/packages/examples/tui-demo/package.json
index ad2e92be5d..1ddf5060b1 100644
--- a/packages/examples/tui-demo/package.json
+++ b/packages/examples/tui-demo/package.json
@@ -48,6 +48,7 @@
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
     "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
     "@deepseek-ai/dsh-session-reference": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
     "@deepseek-ai/dsh-tui": "^0.0.1",
@@ -72,6 +73,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
     "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
diff --git a/packages/examples/tui-demo/src/index.ts b/packages/examples/tui-demo/src/index.ts
index 69b6a3a291..29f985c8e7 100644
--- a/packages/examples/tui-demo/src/index.ts
+++ b/packages/examples/tui-demo/src/index.ts
@@ -10,6 +10,7 @@
 
 import type { Context } from 'cordis'
 import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
 import z from 'schemastery'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
@@ -23,7 +24,7 @@ import SessionPersistenceJsonl, {
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQueryService from '@deepseek-ai/dsh-session-query'
+import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
 import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as uiTui from '@deepseek-ai/dsh-tui'
@@ -52,7 +53,7 @@ export interface Config {
   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`. */
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
   persistenceRoot?: string
   /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
   persistenceCompression?: JsonlCompression
@@ -119,14 +120,15 @@ export function composeTuiApp(ctx: Context, config: Config): void {
   const resumeSessionId = config.resumeSessionId === '' ? undefined : config.resumeSessionId
   const sessionId = SessionId(resumeSessionId ?? `main-session-${randomUUID()}`)
   const goals = config.goals ?? {}
+  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
   ctx.plugin(CommandService)
   if (goals !== false) ctx.plugin(commandGoal)
   ctx.plugin(SessionPersistenceJsonl, {
-    root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
+    root: persistenceRoot,
     ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
   })
   ctx.plugin(sessionCheckpointPolicy)
-  ctx.plugin(SessionQueryService)
+  ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') })
   ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
   ctx.plugin(UserInteractionService)
   ctx.plugin(uiTui, {
diff --git a/packages/examples/tui-demo/tests/built-bin.e2e.ts b/packages/examples/tui-demo/tests/built-bin.e2e.ts
index 904c75784a..6a793bf104 100644
--- a/packages/examples/tui-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/tui-demo/tests/built-bin.e2e.ts
@@ -54,9 +54,9 @@ async function makeConsumer(): Promise<string> {
 /** Run the built bin in `cwd` with PIPED stdio; resolve with output + exit code. */
 function runBuiltBin(cwd: string): Promise<{ stdout: string; code: number; stderr: string }> {
   return new Promise((resolve, reject) => {
-    // NO tsx — this is the published `node lib/bin.js` path (`--expose-internals`
-    // matches the demo command; the guard fires before the Loader needs it).
-    const child = spawn(process.execPath, ['--expose-internals', tuiBin, './cordis.yml'], {
+    // NO tsx — this is the published `node lib/bin.js` path; the guard fires
+    // before the Loader resolves the config tree.
+    const child = spawn(process.execPath, [tuiBin, './cordis.yml'], {
       cwd,
       env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
       stdio: ['pipe', 'pipe', 'pipe'],
diff --git a/packages/examples/tui-demo/tests/tui-agent.spec.ts b/packages/examples/tui-demo/tests/tui-agent.spec.ts
index 8c05abfbab..cdab42289b 100644
--- a/packages/examples/tui-demo/tests/tui-agent.spec.ts
+++ b/packages/examples/tui-demo/tests/tui-agent.spec.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import { join } from 'node:path'
 import type { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
@@ -51,7 +52,7 @@ describe('dsh-tui-demo app', () => {
       'command-goal',
       'SessionPersistenceJsonl',
       'session-checkpoint-policy',
-      'SessionQueryService',
+      'SessionQuerySqlite',
       'SessionReferenceService',
       'UserInteractionService',
       'ui-tui',
@@ -60,6 +61,7 @@ describe('dsh-tui-demo app', () => {
     ])
     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({
       maxReferences: 2,
       candidateLimit: 7,
diff --git a/packages/examples/tui-demo/tsconfig.json b/packages/examples/tui-demo/tsconfig.json
index cb219721a5..d87f0f1c9e 100644
--- a/packages/examples/tui-demo/tsconfig.json
+++ b/packages/examples/tui-demo/tsconfig.json
@@ -29,6 +29,9 @@
     {
       "path": "../../session-query/session-query"
     },
+    {
+      "path": "../../session-query/session-query-sqlite"
+    },
     {
       "path": "../../context/session-reference"
     },
diff --git a/packages/fs/tool-fs-search/README.md b/packages/fs/tool-fs-search/README.md
index 7b254fd59e..5d0655bcc9 100644
--- a/packages/fs/tool-fs-search/README.md
+++ b/packages/fs/tool-fs-search/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-tool-fs-search
 
-The **model-facing filesystem discovery tools** — `glob`, `grep` — backed by the **bash executor seam**, not by `ctx.fs` provider methods. At load, the package probes `command -v rg` through `ctx.bash`; if the executor cannot find ripgrep on its `PATH`, it logs a warning and registers no tools or prompt sections. Each call assembles a fixed ripgrep command (every model-controlled value through one package-private shell-quoting helper), runs it via `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` as an ordinary foreground tool call, parses the raw `rg` output, and returns a bounded, workdir-relative result. The package injects `tools`, `systemPrompt`, and `bash` — deliberately **not** `fs`; `ctx.spillStore` is read opportunistically with `ctx.get()` because formatted-result spill is optional.
+The **model-facing filesystem discovery tools**—`glob`, `grep`—are backed by the **bash executor seam**, not by `ctx.fs` provider methods. At load, the package probes `command -v rg` through `ctx.bash`; if the executor cannot find ripgrep on its `PATH`, it logs a warning and registers no tools or prompt sections. Each call assembles a fixed ripgrep command (every model-controlled value through one package-private shell-quoting helper), runs it via `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` as an ordinary foreground tool call, parses the raw `rg` output, and returns a workdir-relative canonical value. The package injects `tools`, `systemPrompt`, and `bash`—deliberately **not** `fs`; `ctx.spillStore` is read opportunistically with `ctx.get()` because formatted-result spill is optional.
 
 ```ts ignore-check
 // Default deployment: a bash executor whose PATH includes rg, then the discovery tools.
@@ -39,7 +39,7 @@ Routine budgets stay out of the model-facing schema (no `head_limit`/`offset`/`c
 
 ## Two budgets, two artifacts
 
-Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam and parses only complete retained stdout; if the executor still returns `stdout.truncated`, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query. The model-facing recovery artifact is different: when a search yields more logical results than the inline cap, the tool saves the COMPLETE formatted result through `ctx.spillStore.saveText()` (suggested names `glob-results.txt` / `grep-results.txt`, owner = the calling session, source = the tool execution identity) and appends a footer naming the returned locator and retrieval hint. This is the first tool-owned spill call in the codebase — deliberate, because retention here is item-level: the generic `@deepseek-ai/dsh-spill-policy` only sees the final text on `tools/post-execute`, by which point a capped search has already omitted later paths/matches. A missing spill backend, a call with no session owner, or a `saveText()` failure keeps the inline page and reports that the complete result could not be saved — never an `isError`.
+Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam and parses only complete retained stdout; if the executor still returns `stdout.truncated`, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query. A successful `glob` keeps every acquired path in `{ paths }`; `grep` keeps every acquired `{ path, lineNumber, line }` in `{ matches }`. Inline item and per-line preview caps apply only in the Native renderer. For a direct surface call with more logical results than the inline cap, post-policy best-effort saves the complete formatted preview through `ctx.spillStore.saveText()` and replaces only presentation with a head page plus locator. Nested Code dispatches skip that spill because their full canonical value does not enter model context. Missing/failed spill keeps the inline page and reports that the complete result could not be saved—never an `isError`.
 
 ## Errors
 
diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts
index a3e803fb50..6d42acee66 100644
--- a/packages/fs/tool-fs-search/src/glob.ts
+++ b/packages/fs/tool-fs-search/src/glob.ts
@@ -12,7 +12,6 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { ItemRetainer } from '@deepseek-ai/dsh-retention'
 import type { RetainedItems } from '@deepseek-ai/dsh-retention'
 import type { SpillRef } from '@deepseek-ai/dsh-spill'
@@ -20,6 +19,7 @@ import type {} from '@deepseek-ai/dsh-bash'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
 import { singleQuote } from './shell-quote.ts'
+import { acceptedSurfaceValue } from './surface.ts'
 
 /**
  * Default cap on paths retained inline by one `glob` call (the `globMaxResults`
@@ -117,6 +117,14 @@ export function formatGlobOutput(retained: RetainedItems<string>, spillRef: Spil
   return `${body}\n\n(Showing ${retained.kept} of ${retained.seen} paths. ${recovery})`
 }
 
+/** Retain and format one canonical path list for the Native surface. */
+function renderGlobPaths(paths: string[], maxResults: number, spillRef?: SpillRef): string {
+  if (paths.length === 0) return 'No files found'
+  const retainer = new ItemRetainer<string>({ kind: 'head', maxItems: maxResults })
+  for (const path of paths) retainer.push(path)
+  return formatGlobOutput(retainer.finish(), spillRef)
+}
+
 /**
  * Pending-call presentation: a search card titled by the pattern (and root).
  *
@@ -142,7 +150,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
     text: 'Use the glob tool — not shell find or ls — to discover files by path pattern. Results are sorted by modification time and include hidden and ignored files.',
   })
 
-  ctx.tools.register(defineTool({
+  const tool = defineTool({
     name: 'glob',
     description: 'Find files whose paths match a glob pattern. Returns matching paths sorted by modification time, '
       + 'including hidden and ignored files (VCS metadata directories are excluded). '
@@ -152,28 +160,44 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
       path: { type: 'string', description: 'Directory to search in. Defaults to the session workspace; a relative path resolves against it.' },
     },
     timeoutMs: caps.timeoutMs,
-    async execute(args, exec): Promise<ContentBlock[]> {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          paths: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderGlobPaths(value.paths, caps.maxResults) }],
+    },
+    async execute(args, exec) {
       const input = parseGlobArgs(args)
       const run = await runRipgrep(ctx, exec, 'glob', buildGlobCommand(input), caps.rawOutputMaxBytes)
-      if (run.noMatches) return [{ type: 'text', text: 'No files found' }]
+      if (run.noMatches) return { paths: [] }
 
-      const retainer = new ItemRetainer<string>({ kind: 'head', maxItems: caps.maxResults })
       const all: string[] = []
       for (const line of run.stdout.split('\n')) {
         if (line.length === 0) continue
         const displayPath = toWorkdirRelative(line, run.workdir)
         all.push(displayPath)
-        retainer.push(displayPath)
       }
-      const retained = retainer.finish()
-
-      // The complete sorted list is the recovery artifact; save it only when
-      // the inline page omitted paths (an uncapped result needs no spill file).
-      const spillRef = retained.truncated
-        ? await trySaveFormattedResult(ctx, exec, 'glob-results.txt', all.join('\n'))
-        : undefined
-      return [{ type: 'text', text: formatGlobOutput(retained, spillRef) }]
+      return { paths: all }
     },
     presentCall: presentGlobCall,
-  }))
+  })
+  ctx.tools.register(tool)
+
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    const decision = await next()
+    const value = acceptedSurfaceValue(ctx, tool, exec, result, decision) as { paths: string[] } | undefined
+    if (value === undefined) return decision
+    const paths = value.paths
+    if (paths.length <= caps.maxResults) return decision
+    const spillRef = await trySaveFormattedResult(ctx, exec, 'glob-results.txt', paths.join('\n'))
+    return {
+      kind: 'accept',
+      content: [{ type: 'text', text: renderGlobPaths(paths, caps.maxResults, spillRef) }],
+      ...decision.additionalContexts !== undefined ? { additionalContexts: decision.additionalContexts } : {},
+    }
+  })
 }
diff --git a/packages/fs/tool-fs-search/src/grep.ts b/packages/fs/tool-fs-search/src/grep.ts
index 3935513b73..aa82749f3f 100644
--- a/packages/fs/tool-fs-search/src/grep.ts
+++ b/packages/fs/tool-fs-search/src/grep.ts
@@ -13,7 +13,6 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { ItemRetainer, TextRetainer } from '@deepseek-ai/dsh-retention'
 import type { RetainedItems } from '@deepseek-ai/dsh-retention'
 import type { SpillRef } from '@deepseek-ai/dsh-spill'
@@ -21,6 +20,7 @@ import type {} from '@deepseek-ai/dsh-bash'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { SearchError, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
 import { singleQuote } from './shell-quote.ts'
+import { acceptedSurfaceValue } from './surface.ts'
 
 /**
  * Default cap on flat matches retained inline by one `grep` call (the
@@ -241,6 +241,20 @@ export function formatGrepOutput(retained: RetainedItems<GrepMatch>, spillRef: S
   return `${header}\n\n${body}\n\n(${recovery})`
 }
 
+/** Apply the Native per-line preview budget without changing the canonical matches. */
+function previewGrepMatches(matches: GrepMatch[], maxLineBytes: number): GrepMatch[] {
+  return matches.map(match => ({ ...match, line: previewLine(match.line, maxLineBytes) }))
+}
+
+/** Retain and format one canonical match list for the Native surface. */
+function renderGrepMatches(matches: GrepMatch[], maxMatches: number, maxLineBytes: number, spillRef?: SpillRef): string {
+  if (matches.length === 0) return 'No matches found'
+  const previewed = previewGrepMatches(matches, maxLineBytes)
+  const retainer = new ItemRetainer<GrepMatch>({ kind: 'head', maxItems: maxMatches })
+  for (const match of previewed) retainer.push(match)
+  return formatGrepOutput(retainer.finish(), spillRef)
+}
+
 /**
  * Pending-call presentation: a search card titled by the pattern (and target /
  * include filter).
@@ -268,7 +282,7 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
     text: 'Use the grep tool — not shell grep or rg — to search file contents. Use read on a matched file when you need surrounding context.',
   })
 
-  ctx.tools.register(defineTool({
+  const tool = defineTool({
     name: 'grep',
     description: 'Search file contents with a ripgrep regular expression. Returns matching lines with line numbers, grouped by file. '
       + `Returns the first ${caps.maxMatches} matches inline; a capped result reports where the complete match list was saved. `
@@ -279,37 +293,70 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
       include: { type: 'string', description: 'One glob filter for which files to search (e.g. "*.ts", "*.{js,jsx}"). Not a list; negation is not supported.' },
     },
     timeoutMs: caps.timeoutMs,
-    async execute(args, exec): Promise<ContentBlock[]> {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          matches: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                path: { type: 'string', required: true },
+                lineNumber: { type: 'integer', required: true },
+                line: { type: 'string', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: renderGrepMatches(value.matches, caps.maxMatches, caps.maxLineBytes),
+      }],
+    },
+    async execute(args, exec) {
       const input = parseGrepArgs(args)
       const run = await runRipgrep(ctx, exec, 'grep', buildGrepCommand(input), caps.rawOutputMaxBytes)
-      if (run.noMatches) return [{ type: 'text', text: 'No matches found' }]
+      if (run.noMatches) return { matches: [] }
 
-      const retainer = new ItemRetainer<GrepMatch>({ kind: 'head', maxItems: caps.maxMatches })
       const all: GrepMatch[] = []
       for (const raw of parseGrepMatches(run.stdout)) {
         const match: GrepMatch = {
           path: toWorkdirRelative(raw.path, run.workdir),
           lineNumber: raw.lineNumber,
-          line: previewLine(raw.line, caps.maxLineBytes),
+          line: raw.line,
         }
         all.push(match)
-        retainer.push(match)
       }
-      const retained = retainer.finish()
-
-      // The spill file stores the FULL formatted match list (same grouped,
-      // per-line-previewed shape the model saw), so read offset/limit pages the
-      // same logical result; save only when the inline page omitted matches.
-      const spillRef = retained.truncated
-        ? await trySaveFormattedResult(
-          ctx,
-          exec,
-          'grep-results.txt',
-          `Found ${all.length} ${matchNoun(all.length)}\n\n${formatGrepMatches(all)}`,
-        )
-        : undefined
-      return [{ type: 'text', text: formatGrepOutput(retained, spillRef) }]
+      return { matches: all }
     },
     presentCall: presentGrepCall,
-  }))
+  })
+  ctx.tools.register(tool)
+
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    const decision = await next()
+    const value = acceptedSurfaceValue(ctx, tool, exec, result, decision) as { matches: GrepMatch[] } | undefined
+    if (value === undefined) return decision
+    const matches = value.matches
+    if (matches.length <= caps.maxMatches) return decision
+    const spillRef = await trySaveFormattedResult(
+      ctx,
+      exec,
+      'grep-results.txt',
+      `Found ${matches.length} ${matchNoun(matches.length)}\n\n${formatGrepMatches(previewGrepMatches(matches, caps.maxLineBytes))}`,
+    )
+    return {
+      kind: 'accept',
+      content: [{
+        type: 'text',
+        text: renderGrepMatches(matches, caps.maxMatches, caps.maxLineBytes, spillRef),
+      }],
+      ...decision.additionalContexts !== undefined ? { additionalContexts: decision.additionalContexts } : {},
+    }
+  })
 }
diff --git a/packages/fs/tool-fs-search/src/surface.ts b/packages/fs/tool-fs-search/src/surface.ts
new file mode 100644
index 0000000000..78bdd6cc42
--- /dev/null
+++ b/packages/fs/tool-fs-search/src/surface.ts
@@ -0,0 +1,27 @@
+/** Shared surface-only post-policy selection for search result spill. @module dsh-tool-fs-search/surface */
+
+import type { Context } from 'cordis'
+import type { JsonValue, PostToolDecision, ToolDefinition, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+
+/**
+ * Return the accepted canonical value only when this tool still owns a direct
+ * successful surface call and no downstream policy replaced either projection.
+ * @param ctx - the tool plugin context used to resolve the live scoped owner.
+ * @param tool - the exact registered definition whose value may be projected.
+ * @param exec - the completed execution identity.
+ * @param result - the canonical result before post-policy decisions are applied.
+ * @param decision - the composed downstream post-policy decision.
+ * @returns the canonical value to project, or `undefined` when spill must defer.
+ */
+export function acceptedSurfaceValue(
+  ctx: Context,
+  tool: ToolDefinition,
+  exec: ToolExecution,
+  result: ToolExecutionResult,
+  decision: PostToolDecision,
+): JsonValue | undefined {
+  if (decision.kind !== 'accept' || decision.content !== undefined || Object.hasOwn(decision, 'value')
+    || exec.parent !== undefined || exec.name !== tool.name || result.isError
+    || ctx.tools.get(exec.name, exec.agent) !== tool) return undefined
+  return result.value
+}
diff --git a/packages/fs/tool-fs-search/tests/integration.spec.ts b/packages/fs/tool-fs-search/tests/integration.spec.ts
index 7c2ab16705..c497d7e428 100644
--- a/packages/fs/tool-fs-search/tests/integration.spec.ts
+++ b/packages/fs/tool-fs-search/tests/integration.spec.ts
@@ -99,7 +99,7 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
     it('classifies an invalid glob as SEARCH_INVALID_PATTERN', async () => {
       const result = await call('glob', { pattern: '[' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_INVALID_PATTERN' })
+      expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_INVALID_PATTERN' } })
     })
   })
 
@@ -142,13 +142,13 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
     it('classifies a real rg regex error as SEARCH_INVALID_PATTERN', async () => {
       const result = await call('grep', { pattern: '(unclosed' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'SEARCH_INVALID_PATTERN' })
+      expect(result.error).toMatchObject({ info: { code: 'SEARCH_INVALID_PATTERN' } })
     })
 
     it('classifies a missing target as SEARCH_FAILED', async () => {
       const result = await call('grep', { pattern: 'x', path: 'no-such-dir' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+      expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
     })
   })
 
@@ -179,14 +179,14 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
         signal: controller.signal,
       })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+      expect(result.error).toMatchObject({ info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } })
     })
 
     it('an unusable session cwd (spawn failure) is SEARCH_FAILED', async () => {
       const gone = join(dir, 'deleted-session-dir')
       const result = await call('glob', { pattern: '*' }, { session: { header: { id: 'session-int', cwd: gone } } })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_FAILED' })
+      expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } })
       expect(text(result)).toContain('could not start')
     })
   })
diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts
index 9e4aa6483e..1951d97a8d 100644
--- a/packages/fs/tool-fs-search/tests/tools.spec.ts
+++ b/packages/fs/tool-fs-search/tests/tools.spec.ts
@@ -15,7 +15,7 @@ import { Context } from 'cordis'
 import { join } from 'node:path'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { TOOL_ABORTED_BEFORE_DISPATCH, type ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
 import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
 import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
@@ -148,7 +148,12 @@ async function expectSetupRejects(options: SetupOptions, message: RegExp): Promi
 const agent = (cwd?: string) => ({ session: { header: { id: 'session-1', ...cwd !== undefined ? { cwd } : {} } } })
 
 let callCounter = 0
-function call(ctx: Context, name: string, args: unknown, options: { agent?: object; signal?: AbortSignal } = {}) {
+function call(
+  ctx: Context,
+  name: string,
+  args: unknown,
+  options: { agent?: object; signal?: AbortSignal; parent?: ToolExecutionToken } = {},
+) {
   return ctx.tools.execute({
     signal: testToolSignal,
     callId: CallId(`call-${++callCounter}`),
@@ -156,6 +161,7 @@ function call(ctx: Context, name: string, args: unknown, options: { agent?: obje
     arguments: args,
     ...options.agent ? { agent: options.agent as never } : {},
     ...options.signal ? { signal: options.signal } : {},
+    ...options.parent ? { parent: options.parent } : {},
   })
 }
 
@@ -320,7 +326,7 @@ describe('workdir derivation and signal forwarding', () => {
     bash.handler = () => runResult('', { timedOut: true, timeoutMs: 1234, exitCode: null, signal: 'SIGTERM' })
     const result = await call(ctx, 'glob', { pattern: '*' })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ code: 'SEARCH_ABORTED' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_ABORTED' } })
     expect(text(result)).toContain('timed out after 1234ms')
   })
 
@@ -331,7 +337,7 @@ describe('workdir derivation and signal forwarding', () => {
     bash.handler = () => { throw new Error('aborted before spawn') }
     const result = await call(ctx, 'grep', { pattern: 'x' }, { signal: controller.signal })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(result.error).toMatchObject({ info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } })
     expect(bash.specs).toHaveLength(0)
   })
 
@@ -346,7 +352,7 @@ describe('workdir derivation and signal forwarding', () => {
     const result = await call(ctx, 'grep', { pattern: 'x' }, { signal: controller.signal })
 
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_ABORTED' })
+    expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_ABORTED' } })
     expect(text(result)).toContain('aborted before completion')
   })
 
@@ -357,7 +363,7 @@ describe('workdir derivation and signal forwarding', () => {
     const result = await call(ctx, 'glob', { pattern: '*' })
 
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_ABORTED' })
+    expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_ABORTED' } })
     expect(text(result)).toContain('aborted before completion')
   })
 
@@ -367,7 +373,7 @@ describe('workdir derivation and signal forwarding', () => {
     bash.handler = () => { throw new Error('spawn bash ENOENT') }
     const result = await call(ctx, 'glob', { pattern: '*' })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_FAILED' })
+    expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } })
     expect(text(result)).toContain('could not start')
   })
 })
@@ -388,7 +394,7 @@ describe('exit semantics and failure classification', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: regex parse error:\n    (\nerror: unclosed group', truncated: false } })
     const result = await call(ctx, 'grep', { pattern: '(' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_INVALID_PATTERN' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_INVALID_PATTERN' } })
     expect(text(result)).toContain('regex parse error')
   })
 
@@ -396,14 +402,14 @@ describe('exit semantics and failure classification', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: error parsing glob \'[\': unclosed character class', truncated: false } })
     const result = await call(ctx, 'glob', { pattern: '[' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_INVALID_PATTERN' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_INVALID_PATTERN' } })
   })
 
   it('a missing rg binary classifies as SEARCH_FAILED naming ripgrep', async () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('', { exitCode: 127, stderr: { text: 'bash: line 1: rg: command not found', truncated: false } })
     const result = await call(ctx, 'glob', { pattern: '*' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
     expect(text(result)).toContain('requires ripgrep (rg)')
     // The same classification holds from either evidence alone: the 127 exit
     // with silent stderr, or a shell's command-not-found text on another exit.
@@ -417,7 +423,7 @@ describe('exit semantics and failure classification', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: missing.dir: IO error: no such file or directory', truncated: false } })
     const result = await call(ctx, 'grep', { pattern: 'x', path: 'missing.dir' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
     expect(text(result)).toContain('IO error')
   })
 
@@ -425,7 +431,7 @@ describe('exit semantics and failure classification', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('', { exitCode: 3 })
     const result = await call(ctx, 'glob', { pattern: '*' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
     expect(text(result)).toContain('exit 3')
   })
 
@@ -443,7 +449,7 @@ describe('exit semantics and failure classification', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('', { exitCode: null, signal: 'SIGKILL' })
     const result = await call(ctx, 'grep', { pattern: 'x' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
     expect(text(result)).toContain('SIGKILL')
   })
 
@@ -451,7 +457,7 @@ describe('exit semantics and failure classification', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('', { exitCode: null, signal: null })
     const result = await call(ctx, 'glob', { pattern: '*' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
   })
 })
 
@@ -469,7 +475,7 @@ describe('raw output acquisition', () => {
     const { ctx, bash } = await setup({ config: { rawOutputMaxBytes: 16 } })
     bash.handler = () => runResult('', { stdout: { text: 'x', truncated: true, spillPath: '/does/not/get-read' } })
     const result = await call(ctx, 'glob', { pattern: '*' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_RAW_OUTPUT_OVERFLOW' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_RAW_OUTPUT_OVERFLOW' } })
     expect(text(result)).toContain('narrow pattern, path, or include')
   })
 
@@ -480,7 +486,7 @@ describe('raw output acquisition', () => {
     const { ctx, bash } = await setup({ config: { rawOutputMaxBytes: 16 } })
     bash.handler = () => runResult(`${'x'.repeat(64)}\n`)
     const result = await call(ctx, 'grep', { pattern: 'x' })
-    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_RAW_OUTPUT_OVERFLOW' })
+    expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_RAW_OUTPUT_OVERFLOW' } })
     expect(text(result)).toContain('narrow pattern, path, or include')
   })
 
@@ -488,7 +494,7 @@ describe('raw output acquisition', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('', { stdout: { text: 'partial', truncated: true } })
     const result = await call(ctx, 'grep', { pattern: 'x' })
-    expect(result.error).toMatchObject({ code: 'SEARCH_RAW_OUTPUT_OVERFLOW' })
+    expect(result.error).toMatchObject({ info: { code: 'SEARCH_RAW_OUTPUT_OVERFLOW' } })
   })
 })
 
@@ -497,6 +503,8 @@ describe('glob results', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('/sessions/s1/src/a.ts\n/elsewhere/b.ts\nrel/c.ts\n')
     const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') })
+    if (result.isError) throw new Error('expected glob success')
+    expect(result.value).toEqual({ paths: [join('src', 'a.ts'), '/elsewhere/b.ts', 'rel/c.ts'] })
     expect(text(result)).toBe(`${join('src', 'a.ts')}\n/elsewhere/b.ts\nrel/c.ts`)
   })
 
@@ -516,9 +524,15 @@ describe('glob results', () => {
 
   it('caps at globMaxResults and saves the FULL sorted list through spillStore', async () => {
     const { ctx, bash, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'accept',
+      additionalContexts: [{ content: [{ type: 'text', text: 'glob context' }], source: { kind: 'plugin', plugin: 'test' } }],
+    }))
     bash.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
     const result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected glob success')
+    expect(result.value).toEqual({ paths: ['a.ts', 'b.ts', 'c.ts', 'd.ts'] })
     expect(text(result)).toBe('a.ts\nb.ts\n\n(Showing 2 of 4 paths. Full sorted result stored at: /spill/glob-results.txt. Use the fake retrieval hint.)')
     expect(spill?.saves).toHaveLength(1)
     expect(spill?.saves[0]).toMatchObject({
@@ -528,6 +542,7 @@ describe('glob results', () => {
       content: 'a.ts\nb.ts\nc.ts\nd.ts',
     })
     expect(spill?.saves[0]?.source.callId).toBeDefined()
+    expect(result.additionalContexts?.[0]?.content).toEqual([{ type: 'text', text: 'glob context' }])
   })
 
   it('does not create a spill file when the result fits inline', async () => {
@@ -538,6 +553,36 @@ describe('glob results', () => {
     expect(spill?.saves).toHaveLength(0)
   })
 
+  it('preserves a downstream canonical value replacement instead of spilling the old value', async () => {
+    const { ctx, bash, spill } = await setup({ config: { globMaxResults: 1 }, spill: true })
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'accept' as const,
+      value: { paths: ['replacement-a.ts', 'replacement-b.ts'] },
+    }))
+    bash.handler = () => runResult('old-a.ts\nold-b.ts\n')
+
+    const result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') })
+
+    if (result.isError) throw new Error('expected glob replacement success')
+    expect(result.value).toEqual({ paths: ['replacement-a.ts', 'replacement-b.ts'] })
+    expect(text(result)).toContain('replacement-a.ts')
+    expect(text(result)).not.toContain('old-a.ts')
+    expect(spill?.saves).toHaveLength(0)
+  })
+
+  it('keeps the full nested Code value without creating a surface spill', async () => {
+    const { ctx, bash, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
+    bash.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
+    const result = await call(ctx, 'glob', { pattern: '*.ts' }, {
+      agent: agent('/w'),
+      parent: Symbol('run_code') as ToolExecutionToken,
+    })
+    if (result.isError) throw new Error('expected glob success')
+    expect(result.value).toEqual({ paths: ['a.ts', 'b.ts', 'c.ts', 'd.ts'] })
+    expect(text(result)).toBe('a.ts\nb.ts\n\n(Showing 2 of 4 paths. The complete result could not be saved; narrow pattern or path to see more.)')
+    expect(spill?.saves).toHaveLength(0)
+  })
+
   it.each([
     ['no spill backend loaded', { fail: false, spill: false, ownerless: false }],
     ['saveText fails', { fail: true, spill: true, ownerless: false }],
@@ -566,6 +611,14 @@ describe('grep results', () => {
     ].join('\n'))
     const result = await call(ctx, 'grep', { pattern: 'const' })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected grep success')
+    expect(result.value).toEqual({
+      matches: [
+        { path: 'a.ts', lineNumber: 3, line: 'const x = 1' },
+        { path: 'a.ts', lineNumber: 9, line: 'const y = 2' },
+        { path: 'b.ts', lineNumber: 1, line: 'const z = 3' },
+      ],
+    })
     expect(text(result)).toBe('Found 3 matches\n\na.ts\nLine 3: const x = 1\nLine 9: const y = 2\n\nb.ts\nLine 1: const z = 3')
   })
 
@@ -588,6 +641,8 @@ describe('grep results', () => {
     // Use a multibyte straddle instead: 'aé' repeated — cut at 7 bytes: a(1)é(2)a(1)é(2)=6 +a(1)=7 → next é straddles: trimmed.
     bash.handler = () => runResult(`${matchLine('a.txt', 1, 'aéaéaéaé')}\n`)
     const result = await call(ctx, 'grep', { pattern: 'a' })
+    if (result.isError) throw new Error('expected grep success')
+    expect(result.value).toEqual({ matches: [{ path: 'a.txt', lineNumber: 1, line: 'aéaéaéaé' }] })
     expect(text(result)).toContain('Line 1: aéaéa (line truncated)')
   })
 
@@ -605,6 +660,10 @@ describe('grep results', () => {
 
   it('caps at grepMaxMatches and spills the full formatted match list', async () => {
     const { ctx, bash, spill } = await setup({ config: { grepMaxMatches: 2 }, spill: true })
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'accept',
+      additionalContexts: [{ content: [{ type: 'text', text: 'grep context' }], source: { kind: 'plugin', plugin: 'test' } }],
+    }))
     bash.handler = () => runResult([
       matchLine('a.ts', 1, 'one'),
       matchLine('a.ts', 2, 'two'),
@@ -612,12 +671,66 @@ describe('grep results', () => {
       '',
     ].join('\n'))
     const result = await call(ctx, 'grep', { pattern: 'e' }, { agent: agent('/w') })
+    if (result.isError) throw new Error('expected grep success')
+    expect(result.value).toEqual({
+      matches: [
+        { path: 'a.ts', lineNumber: 1, line: 'one' },
+        { path: 'a.ts', lineNumber: 2, line: 'two' },
+        { path: 'b.ts', lineNumber: 3, line: 'three' },
+      ],
+    })
     expect(text(result)).toBe('Found 2 of 3 matches\n\na.ts\nLine 1: one\nLine 2: two\n\n(Full grep result stored at: /spill/grep-results.txt. Use the fake retrieval hint.)')
     expect(spill?.saves[0]).toMatchObject({
       source: { toolName: 'grep', label: 'result' },
       suggestedName: 'grep-results.txt',
       content: 'Found 3 matches\n\na.ts\nLine 1: one\nLine 2: two\n\nb.ts\nLine 3: three',
     })
+    expect(result.additionalContexts?.[0]?.content).toEqual([{ type: 'text', text: 'grep context' }])
+  })
+
+  it('preserves a downstream canonical value replacement instead of spilling the old matches', async () => {
+    const { ctx, bash, spill } = await setup({ config: { grepMaxMatches: 1 }, spill: true })
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'accept' as const,
+      value: {
+        matches: [
+          { path: 'replacement.ts', lineNumber: 7, line: 'first' },
+          { path: 'replacement.ts', lineNumber: 8, line: 'second' },
+        ],
+      },
+    }))
+    bash.handler = () => runResult(`${matchLine('old.ts', 1, 'old')}\n`)
+
+    const result = await call(ctx, 'grep', { pattern: 'old' }, { agent: agent('/w') })
+
+    if (result.isError) throw new Error('expected grep replacement success')
+    expect(result.value).toEqual({
+      matches: [
+        { path: 'replacement.ts', lineNumber: 7, line: 'first' },
+        { path: 'replacement.ts', lineNumber: 8, line: 'second' },
+      ],
+    })
+    expect(text(result)).toContain('replacement.ts')
+    expect(text(result)).not.toContain('old.ts')
+    expect(spill?.saves).toHaveLength(0)
+  })
+
+  it('keeps every nested Code match in the value without creating a surface spill', async () => {
+    const { ctx, bash, spill } = await setup({ config: { grepMaxMatches: 1 }, spill: true })
+    bash.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n${matchLine('b.ts', 2, 'two')}\n`)
+    const result = await call(ctx, 'grep', { pattern: 'o' }, {
+      agent: agent('/w'),
+      parent: Symbol('run_code') as ToolExecutionToken,
+    })
+    if (result.isError) throw new Error('expected grep success')
+    expect(result.value).toEqual({
+      matches: [
+        { path: 'a.ts', lineNumber: 1, line: 'one' },
+        { path: 'b.ts', lineNumber: 2, line: 'two' },
+      ],
+    })
+    expect(text(result)).toBe('Found 1 of 2 matches\n\na.ts\nLine 1: one\n\n(The complete result could not be saved; narrow pattern, path, or include to see more.)')
+    expect(spill?.saves).toHaveLength(0)
   })
 
   it('reports the unsaved remainder when capped with no spill backend', async () => {
@@ -660,7 +773,7 @@ describe('rg --json transport failures (SEARCH_FAILED)', () => {
     bash.handler = () => runResult(`${line}\n`)
     const result = await call(ctx, 'grep', { pattern: 'x' })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_FAILED' })
+    expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } })
   })
 })
 
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index 6dd22d384f..a99316c181 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -32,6 +32,8 @@ All keys are optional; the defaults are the shipped read caps.
 
 Field names are snake_case to match Claude Code and existing harness tool schemas.
 
+Canonical successes are `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. Native renderers preserve the line-numbered read and mutation acknowledgements below. Write/edit derive replayable diff-card metadata from these values; the values themselves are execution-local and are not added to `tool/result`.
+
 ## The tool is the executor; policy is an event gate
 
 The tools do **not** inject a policy service or inspect any cache. Each tool resolves the path via `ctx.fs.resolve(path, { cwd, signal })` — passing the calling agent's session cwd (`exec.agent.session.header.cwd`) so a relative path resolves against the session's workspace, matching `dsh-tool-bash`, and forwarding tool cancellation through resolution (see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)) — then:
diff --git a/packages/fs/tool-fs/src/edit.ts b/packages/fs/tool-fs/src/edit.ts
index d3bb9a2803..951c0b7b57 100644
--- a/packages/fs/tool-fs/src/edit.ts
+++ b/packages/fs/tool-fs/src/edit.ts
@@ -8,10 +8,9 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { DiffCallView, DiffResultView, ToolResult } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
-import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
+import { computeHunkDiffs, diffsFromMeta } from './diff.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
 import type { FsSandboxSurface } from './sandbox.ts'
 
@@ -90,7 +89,26 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
       replace_all: { type: 'boolean', description: 'Replace all matches. Defaults to false; when false, old_string must appear exactly once.' },
       ...sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {},
     },
-    async execute(args: EditToolArgs, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          path: { type: 'string', required: true },
+          before: { type: 'string', required: true },
+          after: { type: 'string', required: true },
+        },
+      },
+      render: (args, value) => [{
+        type: 'text',
+        text: formatEditOutput(value.path, args.replace_all ?? false),
+      }],
+      presentationMeta: (args, value) => ({
+        diffs: computeHunkDiffs(args.file_path, value.before, value.after)
+          .map(({ path, oldText, newText }) => ({ path, oldText, newText })),
+      }),
+    },
+    async execute(args: EditToolArgs, exec) {
       const input = parseEditArgs(args)
       // Resolve the per-call sandbox policy (approved mode > session override
       // > backend default, plus the session cwd root) BEFORE anything executes.
@@ -115,11 +133,10 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
       }
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      // An edit necessarily changes content, so result metadata carries at least one applied hunk.
-      const diffs = computeHunkDiffs(input.filePath, outcome.before, outcome.after)
       return {
-        content: [{ type: 'text', text: formatEditOutput(target.displayPath, input.replaceAll) }],
-        meta: { diffs },
+        path: target.displayPath,
+        before: outcome.before,
+        after: outcome.after,
       }
     },
     // Pure display: a diff card of the literal replacement (old_string → new_string), derived
diff --git a/packages/fs/tool-fs/src/read-render.ts b/packages/fs/tool-fs/src/read-render.ts
index 943ff98f61..7e581bb22c 100644
--- a/packages/fs/tool-fs/src/read-render.ts
+++ b/packages/fs/tool-fs/src/read-render.ts
@@ -37,9 +37,9 @@ export interface FileTextLine {
 export interface WindowResult {
   /** Returned lines, already numbered. */
   lines: FileTextLine[]
-  /** Total line count in the file, unless `truncatedByBytes` stopped scanning early. */
+  /** Exact total line count in the file. */
   totalLines: number
-  /** Whether selected output hit the byte cap before EOF or the requested limit. */
+  /** Whether selected output hit the byte cap. */
   truncatedByBytes: boolean
 }
 
@@ -49,9 +49,9 @@ export interface FileReadOutcome {
   offset: number
   /** Returned lines, already numbered. */
   lines: FileTextLine[]
-  /** Total line count in the file, unless `truncatedByBytes` stopped scanning early. */
+  /** Exact total line count in the file. */
   totalLines: number
-  /** Whether selected output hit the byte cap before EOF or the requested limit. */
+  /** Whether selected output hit the byte cap. */
   truncatedByBytes?: true
 }
 
@@ -60,11 +60,10 @@ interface WindowAccumulator {
   totalLines: number
   outputBytes: number
   truncatedByBytes: boolean
-  done: boolean
 }
 
 function newAccumulator(): WindowAccumulator {
-  return { lines: [], totalLines: 0, outputBytes: 0, truncatedByBytes: false, done: false }
+  return { lines: [], totalLines: 0, outputBytes: 0, truncatedByBytes: false }
 }
 
 function truncateLine(line: string, maxLineLength: number): string {
@@ -77,13 +76,12 @@ function lineByteSize(line: string, currentLineCount: number): number {
 
 function consumeLine(acc: WindowAccumulator, rawLine: string, request: ReadWindow): void {
   acc.totalLines += 1
-  if (acc.totalLines < request.offset || acc.lines.length >= request.limit) return
+  if (acc.truncatedByBytes || acc.totalLines < request.offset || acc.lines.length >= request.limit) return
 
   const text = truncateLine(rawLine, request.maxLineLength)
   const bytes = lineByteSize(text, acc.lines.length)
   if (acc.outputBytes + bytes > request.maxBytes) {
     acc.truncatedByBytes = true
-    acc.done = true
     return
   }
   acc.outputBytes += bytes
@@ -102,8 +100,9 @@ function finish(acc: WindowAccumulator, request: ReadWindow, displayPath: string
 }
 
 /**
- * Build one window from streamed or whole-file chunks, enforcing line and byte caps and throwing
- * `FS_NOT_FOUND` when the requested offset is past EOF.
+ * Build one window from streamed or whole-file chunks, enforcing line and byte caps while still
+ * scanning to an exact total line count, and throwing `FS_NOT_FOUND` when the requested offset is
+ * past EOF.
  * @param chunks - decoded text chunks in file order; chunk boundaries carry no meaning.
  * @param request - the resolved window; the caller has already applied its defaults and caps.
  * @param displayPath - the caller-facing path used in the offset-out-of-range error.
@@ -137,7 +136,6 @@ export async function buildWindow(
       appendToLineBuffer(chunk.slice(startPos, newlinePos))
       flushLine()
       startPos = newlinePos + 1
-      if (acc.done) return finish(acc, request, displayPath)
     }
     appendToLineBuffer(chunk.slice(startPos))
   }
diff --git a/packages/fs/tool-fs/src/read.ts b/packages/fs/tool-fs/src/read.ts
index cb1409987d..4e299d9a79 100644
--- a/packages/fs/tool-fs/src/read.ts
+++ b/packages/fs/tool-fs/src/read.ts
@@ -7,12 +7,10 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { FsError } from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { buildWindow, formatReadOutput } from './read-render.ts'
-import type { FileReadOutcome } from './read-render.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
 
 /** Default and maximum number of lines returned by one `read` call (the `readLimit` config). */
@@ -84,9 +82,46 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       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 ${caps.limit}.` },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          path: { type: 'string', required: true },
+          offset: { type: 'integer', required: true },
+          lines: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                number: { type: 'integer', required: true },
+                text: { type: 'string', required: true },
+              },
+            },
+          },
+          totalLines: { type: 'integer', required: true },
+        },
+      },
+      render: (args, value) => {
+        const input = parseReadArgs(args, caps.limit)
+        const endLine = value.lines.at(-1)?.number ?? Math.max(0, value.offset - 1)
+        const truncatedByBytes = value.lines.length < input.limit && endLine < value.totalLines
+        return [{
+          type: 'text',
+          text: formatReadOutput(value.path, {
+            offset: value.offset,
+            lines: value.lines,
+            totalLines: value.totalLines,
+            ...truncatedByBytes ? { truncatedByBytes: true } : {},
+          }),
+        }]
+      },
+    },
     // Observation races fail closed because guarded mutations re-check the version in-lock.
     isConcurrencySafe: () => true,
-    async execute(args, exec): Promise<ContentBlock[]> {
+    async execute(args, exec) {
       const input = parseReadArgs(args, caps.limit)
       const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath))
 
@@ -107,17 +142,17 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
         target.displayPath,
       )
 
-      const outcome: FileReadOutcome = {
+      const outcome = {
+        path: target.displayPath,
         offset: input.offset,
         lines: window.lines,
         totalLines: window.totalLines,
-        ...window.truncatedByBytes ? { truncatedByBytes: true } : {},
       }
       // Record the observed version (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)
-      return [{ type: 'text', text: formatReadOutput(target.displayPath, outcome) }]
+      return outcome
     },
     // Pure display: a generic card titled by the file with the read window appended (`Read
     // foo.txt (5 - 8)`), `read` kind (icon), and a follow-along location whose line is the
diff --git a/packages/fs/tool-fs/src/write.ts b/packages/fs/tool-fs/src/write.ts
index 1e92b66612..ba96dbe40c 100644
--- a/packages/fs/tool-fs/src/write.ts
+++ b/packages/fs/tool-fs/src/write.ts
@@ -8,11 +8,10 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { DiffCallView, DiffResultView, ToolResult } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 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, type FsDiffMeta } from './diff.ts'
+import { computeHunkDiffs, diffsFromMeta } from './diff.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
 import type { FsSandboxSurface } from './sandbox.ts'
 
@@ -33,7 +32,7 @@ export function parseWriteArgs(args: { file_path: string; content: string }): {
  * @param outcome - the write outcome; its `operation` selects the Created/Updated wording.
  * @returns the model-facing confirmation envelope (no file content is echoed back).
  */
-export function formatWriteOutput(displayPath: string, outcome: FsWriteOutcome): string {
+export function formatWriteOutput(displayPath: string, outcome: Pick<FsWriteOutcome, 'operation'>): string {
   const verb = outcome.operation === 'create' ? 'Created' : 'Updated'
   return `<path>${displayPath}</path>
 <type>file</type>
@@ -74,7 +73,32 @@ export function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void {
       content: { type: 'string', required: true, description: 'Full UTF-8 text content to write.' },
       ...sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {},
     },
-    async execute(args: WriteToolArgs, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          path: { type: 'string', required: true },
+          operation: { type: 'string', required: true, enum: ['create', 'update'] },
+          before: {
+            required: true,
+            oneOf: [
+              { type: 'string' },
+              { type: 'null' },
+            ],
+          },
+          after: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: formatWriteOutput(value.path, value) }],
+      presentationMeta: (args, value) => ({
+        diffs: value.before === null
+          ? []
+          : computeHunkDiffs(args.file_path, value.before, value.after)
+            .map(({ path, oldText, newText }) => ({ path, oldText, newText })),
+      }),
+    },
+    async execute(args: WriteToolArgs, exec) {
       const input = parseWriteArgs(args)
       // Resolve the per-call sandbox policy (approved mode > session override
       // > backend default, plus the session cwd root) BEFORE anything executes;
@@ -94,12 +118,11 @@ export function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void {
       }
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      // Overwrites carry applied hunks. Creates have no prior text, so result presentation uses
-      // the args-derived whole-file diff instead.
-      const diffs = outcome.before !== null ? computeHunkDiffs(input.filePath, outcome.before, outcome.after) : []
       return {
-        content: [{ type: 'text', text: formatWriteOutput(target.displayPath, outcome) }],
-        ...diffs.length > 0 ? { meta: { diffs } } : {},
+        path: target.displayPath,
+        operation: outcome.operation,
+        before: outcome.before,
+        after: outcome.after,
       }
     },
     // Pure display: a diff card (an editor renders write as a new-file / full- replace diff).
diff --git a/packages/fs/tool-fs/tests/fs-tools.e2e.ts b/packages/fs/tool-fs/tests/fs-tools.e2e.ts
index 472b32f47a..b768813b22 100644
--- a/packages/fs/tool-fs/tests/fs-tools.e2e.ts
+++ b/packages/fs/tool-fs/tests/fs-tools.e2e.ts
@@ -36,7 +36,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('fs tools with-key smoke', () =>
     // (config.cwd = workdir) is the workspace.
     const agent = ctx.agentLoop.create(SessionId('fs-e2e'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    agent.send([{ type: 'text', text:
+    agent.followup([{ type: 'text', text:
       'Create a file named note.txt containing exactly the line: status: draft. '
       + 'Then read it back, then edit it to replace the literal word draft with final. '
       + 'Tell me when done.' }])
@@ -68,7 +68,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('fs tools with-key smoke', () =>
         meta: { cwd: sessionDir },
         agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
       })
-      handle.agent.send([{ type: 'text', text:
+      handle.agent.followup([{ type: 'text', text:
         'Use the write tool to create a file named where.txt containing exactly the line: here. Tell me when done.' }])
       await waitForIdle(ctx, handle.agent)
 
diff --git a/packages/fs/tool-fs/tests/integration.spec.ts b/packages/fs/tool-fs/tests/integration.spec.ts
index a0dbc11294..e911b9addc 100644
--- a/packages/fs/tool-fs/tests/integration.spec.ts
+++ b/packages/fs/tool-fs/tests/integration.spec.ts
@@ -70,7 +70,7 @@ describe('default deployment (with dsh-fs-policy)', () => {
       await writeFile(join(dir, 'a.txt'), 'original')
       const result = await call('write', { file_path: 'a.txt', content: 'clobber' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
+      expect(result.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } })
       expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('original')
     })
 
@@ -88,7 +88,7 @@ describe('default deployment (with dsh-fs-policy)', () => {
       await writeFile(join(dir, 'a.txt'), 'changed-externally') // out-of-band change
       const result = await call('write', { file_path: 'a.txt', content: 'replaced' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'FS_STALE_VERSION' })
+      expect(result.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
     })
   })
 
@@ -105,7 +105,7 @@ describe('default deployment (with dsh-fs-policy)', () => {
       await writeFile(join(dir, 'bin'), Buffer.from([0x00, 0x01, 0x02]))
       const result = await call('read', { file_path: 'bin' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'FS_NOT_TEXT' })
+      expect(result.error).toMatchObject({ info: { code: 'FS_NOT_TEXT' } })
     })
 
     it('paginates a multi-line file with offset/limit', async () => {
@@ -130,7 +130,7 @@ describe('default deployment (with dsh-fs-policy)', () => {
       await writeFile(join(dir, 'a.txt'), 'hello world')
       const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
+      expect(result.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } })
       expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello world')
     })
 
@@ -154,7 +154,7 @@ describe('default deployment (with dsh-fs-policy)', () => {
       await writeFile(join(dir, 'a.txt'), 'goodbye') // out-of-band change removes 'world'
       const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'FS_STALE_VERSION' })
+      expect(result.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
     })
 
     it('rejects an ambiguous match without replace_all', async () => {
@@ -162,7 +162,7 @@ describe('default deployment (with dsh-fs-policy)', () => {
       await call('read', { file_path: 'a.txt' })
       const result = await call('edit', { file_path: 'a.txt', old_string: 'a', new_string: 'b' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'FS_AMBIGUOUS_EDIT' })
+      expect(result.error).toMatchObject({ info: { code: 'FS_AMBIGUOUS_EDIT' } })
       expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('a a a')
     })
 
@@ -190,7 +190,7 @@ describe('default deployment (with dsh-fs-policy)', () => {
       // The model-facing edit still rejects: the read did not emit fs/observed.
       const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
       expect(result.isError).toBe(true)
-      expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
+      expect(result.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } })
     })
   })
 
@@ -263,14 +263,14 @@ describe('bare provider (no dsh-fs-policy)', () => {
   it('edit of a MISSING target reports FS_STALE_VERSION even on the unguarded path', async () => {
     const result = await call('edit', { file_path: 'missing.txt', old_string: 'a', new_string: 'b' })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ code: 'FS_STALE_VERSION' })
+    expect(result.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
   })
 
   it('edit still enforces literal-match codes (FS_EDIT_NOT_FOUND), unrelated to freshness', async () => {
     await writeFile(join(dir, 'a.txt'), 'hello world')
     const result = await call('edit', { file_path: 'a.txt', old_string: 'absent', new_string: 'x' })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ code: 'FS_EDIT_NOT_FOUND' })
+    expect(result.error).toMatchObject({ info: { code: 'FS_EDIT_NOT_FOUND' } })
   })
 
   it('neither write nor edit stats in the tool on the bare path', async () => {
@@ -354,11 +354,11 @@ describe('signal, concurrency, and the fs/observed contract', () => {
     await writeFile(join(dir, 'a.txt'), 'hello')
     const read = await callSig(AbortSignal.abort(), 'read', { file_path: 'a.txt' })
     expect(read.isError).toBe(true)
-    expect(read.error).toMatchObject({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(read.error).toMatchObject({ info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } })
 
     const write = await callSig(AbortSignal.abort(), 'write', { file_path: 'new.txt', content: 'x' })
     expect(write.isError).toBe(true)
-    expect(write.error).toMatchObject({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(write.error).toMatchObject({ info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } })
     await expect(readFile(join(dir, 'new.txt'), 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
 
     // Read first (un-aborted, SAME session owner) so the edit clears the
@@ -366,7 +366,7 @@ describe('signal, concurrency, and the fs/observed contract', () => {
     expect((await callOwned('read', { file_path: 'a.txt' })).isError).toBe(false)
     const edit = await callSig(AbortSignal.abort(), 'edit', { file_path: 'a.txt', old_string: 'hello', new_string: 'bye' })
     expect(edit.isError).toBe(true)
-    expect(edit.error).toMatchObject({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(edit.error).toMatchObject({ info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } })
     expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello') // unchanged
   })
 
@@ -381,7 +381,7 @@ describe('signal, concurrency, and the fs/observed contract', () => {
     ])
     const errors = [one, two].filter(r => r.isError)
     expect(errors).toHaveLength(1)
-    expect(errors[0]?.error).toMatchObject({ code: 'FS_STALE_VERSION' })
+    expect(errors[0]?.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
     // The world is consistent: exactly one edit landed.
     const onDisk = await readFile(join(dir, 'a.txt'), 'utf8')
     expect(onDisk === 'ONE value here' || onDisk === 'base TWO here').toBe(true)
@@ -410,7 +410,7 @@ describe('signal, concurrency, and the fs/observed contract', () => {
       new_string: 'edited',
     })
     expect(edit.isError).toBe(true)
-    expect(edit.error).toMatchObject({ code: 'FS_STALE_VERSION' })
+    expect(edit.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
     expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('newer current content\n')
   })
 
diff --git a/packages/fs/tool-fs/tests/read-render.spec.ts b/packages/fs/tool-fs/tests/read-render.spec.ts
index ab4d2a618b..c2afaf002e 100644
--- a/packages/fs/tool-fs/tests/read-render.spec.ts
+++ b/packages/fs/tool-fs/tests/read-render.spec.ts
@@ -86,6 +86,7 @@ describe('buildWindow', () => {
     it('caps output at a custom maxBytes', async () => {
       const result = await buildWindow(whole('aaaa\nbbbb\ncccc'), { offset: 1, limit: 10, maxLineLength: 2000, maxBytes: 9 }, 'f')
       expect(result.lines.map(l => l.text)).toEqual(['aaaa', 'bbbb'])
+      expect(result.totalLines).toBe(3)
       expect(result.truncatedByBytes).toBe(true)
     })
   })
@@ -105,6 +106,7 @@ describe('buildWindow', () => {
     it('caps output bytes mid-stream', async () => {
       const big = Array.from({ length: 2000 }, () => 'y'.repeat(100)).join('\n')
       const result = await buildWindow(chunked(big, 512), READ_ALL, 'f')
+      expect(result.totalLines).toBe(2000)
       expect(result.truncatedByBytes).toBe(true)
     })
 
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index df55bb99f4..00fe570215 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -7,7 +7,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join, sep } from 'node:path'
+import { join, resolve, sep } from 'node:path'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -195,6 +195,13 @@ describe('read tool', () => {
     fs.files.set('key:a.txt', 'hello\nworld')
     const result = await call(ctx, 'read', { file_path: 'a.txt' })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected read success')
+    expect(result.value).toEqual({
+      path: '/abs/a.txt',
+      offset: 1,
+      lines: [{ number: 1, text: 'hello' }, { number: 2, text: 'world' }],
+      totalLines: 2,
+    })
     expect(text(result)).toBe(`<path>/abs/a.txt</path>
 <type>file</type>
 <content>
@@ -205,6 +212,15 @@ describe('read tool', () => {
 </content>`)
   })
 
+  it('returns an explicit empty canonical line window for an empty file', async () => {
+    const { ctx, fs } = await setup()
+    fs.files.set('key:empty.txt', '')
+    const result = await call(ctx, 'read', { file_path: 'empty.txt' })
+    if (result.isError) throw new Error('expected empty read success')
+    expect(result.value).toEqual({ path: '/abs/empty.txt', offset: 1, lines: [], totalLines: 0 })
+    expect(text(result)).toContain('(End of file - total 0 lines)')
+  })
+
   it('rejects a non-positive offset via arg validation', async () => {
     const { ctx } = await setup()
     const result = await call(ctx, 'read', { file_path: 'a.txt', offset: 0 })
@@ -260,7 +276,7 @@ describe('read tool', () => {
     const { ctx } = await setup()
     const result = await call(ctx, 'read', { file_path: 'missing.txt' })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ code: 'FS_NOT_FOUND' })
+    expect(result.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
   })
 
   it('rejects a non-regular target', async () => {
@@ -269,7 +285,7 @@ describe('read tool', () => {
     fs.stat = async () => ({ version: FsVersion('v1'), type: 'directory' })
     const result = await call(ctx, 'read', { file_path: 'd' })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
+    expect(result.error).toMatchObject({ info: { code: 'FS_NOT_REGULAR_FILE' } })
   })
 
   it('streams a large file (size at/above the cap) instead of reading whole', async () => {
@@ -335,6 +351,8 @@ describe('write tool', () => {
     const { ctx, fs } = await setup()
     const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'hi' }, { session: { header: {} } })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected write success')
+    expect(result.value).toEqual({ path: '/abs/a.txt', operation: 'create', before: null, after: 'hi' })
     expect(text(result)).toContain('Created file')
     expect(fs.writeIntents).toEqual([{ kind: 'createIfAbsent' }])
   })
@@ -351,7 +369,7 @@ describe('write tool', () => {
     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({ name: 'FsError', code: 'FS_STALE_VERSION' })
+    expect(result.error).toMatchObject({ info: { name: 'FsError', code: 'FS_STALE_VERSION' } })
   })
 })
 
@@ -362,6 +380,8 @@ describe('edit tool', () => {
     fs.files.set('key:a.txt', 'a')
     await call(ctx, 'read', { file_path: 'a.txt' }, { session })
     const result = await call(ctx, 'edit', { file_path: 'a.txt', old_string: 'a', new_string: 'b' }, { session })
+    if (result.isError) throw new Error('expected edit success')
+    expect(result.value).toEqual({ path: '/abs/a.txt', before: 'a', after: 'b' })
     expect(text(result)).toBe('The file /abs/a.txt has been updated successfully.')
   })
 
@@ -400,7 +420,7 @@ describe('edit tool', () => {
     fs.files.set('key:a.txt', 'hello')
     const result = await call(ctx, 'edit', { file_path: 'a.txt', old_string: 'a', new_string: 'b' }, { session: { header: {} } })
     expect(result.isError).toBe(true)
-    expect(result.error).toMatchObject({ code: 'FS_NOT_OBSERVED' })
+    expect(result.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } })
   })
 })
 
@@ -498,27 +518,27 @@ describe('result-time contextual diff (meta + presentResult)', () => {
     expect(view).toEqual({ card: 'diff', title: 'Write a.txt', diffs: [{ path: 'a.txt', oldText: 'a\nb\nc\nOLD\nd\ne\nf', newText: 'a\nb\nc\nNEW\nd\ne\nf' }] })
   })
 
-  it('write CREATE: no before-version → no meta, but presentResult still renders a whole-file diff card', async () => {
-    // A create has no prior content (no `meta`), yet the completed card must be a `diff` — an
+  it('write CREATE: an empty applied-diff projection still falls back to the whole-file diff card', async () => {
+    // A create has no prior content, yet the completed card must be a `diff` — an
     // ACP tool_call_update.content REPLACES the call's content, so a non-diff result would
     // clobber the pending new-file diff.
     const { ctx } = await setup()
     const session = { header: {} }
     const result = await call(ctx, 'write', { file_path: 'new.txt', content: 'fresh\n' }, { session })
     expect(result.isError).toBe(false)
-    expect(result.meta).toBeUndefined()
+    expect(result.meta).toEqual({ diffs: [] })
     const view = ctx.tools.get('write')?.presentResult?.({ file_path: 'new.txt', content: 'fresh\n' }, result)
     expect(view).toEqual({ card: 'diff', title: 'Write new.txt', diffs: [{ path: 'new.txt', oldText: null, newText: 'fresh\n' }] })
   })
 
-  it('write OVERWRITE with identical content: a before exists but yields no hunk → no meta, presentResult falls back to a whole-file diff', async () => {
+  it('write OVERWRITE with identical content: an empty applied-diff projection falls back to a whole-file diff', async () => {
     const { ctx, fs } = await setup()
     const session = { header: {} }
     fs.files.set('key:a.txt', 'same\n')
     await call(ctx, 'read', { file_path: 'a.txt' }, { session })
     const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'same\n' }, { session })
     expect(result.isError).toBe(false)
-    expect(result.meta).toBeUndefined()
+    expect(result.meta).toEqual({ diffs: [] })
     const view = ctx.tools.get('write')?.presentResult?.({ file_path: 'a.txt', content: 'same\n' }, result)
     expect(view).toEqual({ card: 'diff', title: 'Write a.txt', diffs: [{ path: 'a.txt', oldText: null, newText: 'same\n' }] })
   })
@@ -583,6 +603,9 @@ describe('read caps are plugin config', () => {
     const { ctx, fs } = await setupWith({ readMaxBytes: 9 })
     fs.files.set('key:a.txt', 'aaaa\nbbbb\ncccc')
     const result = await call(ctx, 'read', { file_path: 'a.txt' })
+    expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected read success')
+    expect(result.value).toMatchObject({ totalLines: 3 })
     expect(text(result)).toContain('Output capped.')
     expect(text(result)).not.toContain('cccc')
   })
@@ -706,13 +729,13 @@ describe('sandbox escalation surface (write/edit)', () => {
   it('a plain write stamps the default mode with the calling session root', async () => {
     const { ctx, fs } = await setupConfining()
     await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent())
-    expect(fs.stamped).toEqual([{ mode: 'workspace-write', workspaceRoot: '/session-project' }])
+    expect(fs.stamped).toEqual([{ mode: 'workspace-write', workspaceRoot: resolve('/session-project') }])
   })
 
   it('a standing session override folds onto the stamp', async () => {
     const { ctx, fs } = await setupConfining()
     await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent([{ type: 'sandbox/mode', data: { mode: 'read-only' } }]))
-    expect(fs.stamped).toEqual([{ mode: 'read-only', workspaceRoot: '/session-project' }])
+    expect(fs.stamped).toEqual([{ mode: 'read-only', workspaceRoot: resolve('/session-project') }])
   })
 
   it('a denied write maps to the shared marker plus the escalation hint (isError)', async () => {
@@ -745,7 +768,7 @@ describe('sandbox escalation surface (write/edit)', () => {
       agent: escalationAgent() as never,
       signal: new AbortController().signal,
     })
-    expect(fs.stamped).toEqual([{ mode: 'danger-full-access', workspaceRoot: '/session-project' }])
+    expect(fs.stamped).toEqual([{ mode: 'danger-full-access', workspaceRoot: resolve('/session-project') }])
   })
 
   it('a rejected escalation fails closed with its own text and never mutates', async () => {
diff --git a/packages/goal/command-goal/tests/command-goal.spec.ts b/packages/goal/command-goal/tests/command-goal.spec.ts
index 35994ecb71..a958659eba 100644
--- a/packages/goal/command-goal/tests/command-goal.spec.ts
+++ b/packages/goal/command-goal/tests/command-goal.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentStatus, InjectOptions } from '@deepseek-ai/dsh-agent'
 import CommandService from '@deepseek-ai/dsh-commands'
 import GoalService from '@deepseek-ai/dsh-goal'
@@ -27,10 +27,10 @@ function nextTurn(session: Session): number {
 
 /** Append one idle injection using the public Agent contract's balanced shape. */
 function appendInjection(session: Session, content: ContentBlock[], options?: InjectOptions): void {
-  const source: MessageSource = options?.source ?? { kind: 'user' }
+  const source: MessageSource = options?.source ?? { kind: 'plugin', plugin: '' }
   const turn = nextTurn(session)
   session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-  session.append('context/message', {
+  session.append('user/message', {
     content,
     source,
     ...options?.meta === undefined ? {} : { meta: options.meta },
@@ -48,9 +48,11 @@ function stubAgent(id: string): { agent: Agent; session: Session } {
     session,
     ctx: new Context(),
     get status() { return status },
-    send() {},
-    steer() {},
-    inject(content, options) { appendInjection(session, content, options) },
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
+    inject(content, options) { appendInjection(session, content, options); return AgentMessageId('stub') },
+    send: () => AgentMessageId('stub'),
     cancel() { status = 'idle' },
     whenIdle() { return Promise.resolve() },
   }
@@ -125,7 +127,7 @@ describe('/goal human command', () => {
     expect(created.text).toContain('Rounds: 0/256')
     expect(created.text).toContain('Activation: armed')
     expect(test.ctx.goals.get(test.agent)?.objective).toBe('finish the release')
-    expect(test.session.events.map(event => event.type)).toEqual(['turn/start', 'context/message', 'turn/end'])
+    expect(test.session.events.map(event => event.type)).toEqual(['turn/start', 'user/message', 'turn/end'])
 
     const count = test.session.events.length
     await expect(run(test, ' replacement')).resolves.toEqual({
diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts
index bcb3fc2a75..67cbd89d05 100644
--- a/packages/goal/goal-session/src/index.ts
+++ b/packages/goal/goal-session/src/index.ts
@@ -219,7 +219,7 @@ export function apply(ctx: Context): void {
     }
     state.attempt = reservation
     try {
-      agent.send(content, {
+      agent.followup(content, {
         source: { kind: 'goal', goalId: goal.id, revision: goal.revision, round },
       })
     } catch (error: unknown) {
@@ -306,10 +306,10 @@ export function apply(ctx: Context): void {
         requestDrive(state)
       }
     })
-    ctx.on('agent/queued', (agent, content, info) => {
+    ctx.on('agent/inbox/enqueue', (agent, info) => {
       const state = stateFor(agent)
       const attempt = state.attempt
-      if (attempt !== undefined && sameQueued(content, info.source, attempt)) return
+      if (attempt !== undefined && sameQueued(info.content, info.source, attempt)) return
       state.competingQueued = true
       if (attempt?.phase === 'queued') attempt.stale = true
     })
diff --git a/packages/goal/goal-session/src/prompt.ts b/packages/goal/goal-session/src/prompt.ts
index 9a2f69fcd8..d98f0bb83a 100644
--- a/packages/goal/goal-session/src/prompt.ts
+++ b/packages/goal/goal-session/src/prompt.ts
@@ -7,7 +7,7 @@ import type { GoalView } from '@deepseek-ai/dsh-goal'
  * Render the complete goal-round instruction retained in session history.
  * @param goal - exact active goal revision being admitted.
  * @param round - next positive round number.
- * @returns a fresh one-block prompt for `Agent.send()`.
+ * @returns a fresh one-block prompt for `Agent.followup()`.
  */
 export function renderGoalRoundPrompt(goal: GoalView, round: number): ContentBlock[] {
   return [{
diff --git a/packages/goal/goal-session/tests/goal-session.spec.ts b/packages/goal/goal-session/tests/goal-session.spec.ts
index f204893578..dc3d6723a7 100644
--- a/packages/goal/goal-session/tests/goal-session.spec.ts
+++ b/packages/goal/goal-session/tests/goal-session.spec.ts
@@ -207,7 +207,9 @@ describe('same-session goal driving', () => {
     expect(test.adapter.requests).toHaveLength(2)
     const rounds: number[] = []
     for (const event of test.agent.session.events) {
-      if (event.type === 'user/message' && event.data.source.kind === 'goal') {
+      // Round zero is a durable goal state change; positive rounds are the
+      // admitted continuation prompts this test counts.
+      if (event.type === 'user/message' && event.data.source.kind === 'goal' && event.data.source.round > 0) {
         rounds.push(event.data.source.round)
       }
     }
@@ -274,7 +276,7 @@ describe('same-session goal driving', () => {
       ? Promise.resolve({ kind: 'block', reason: 'stop this round' })
       : next())
     test.ctx.on('goal/changed', (agent, change) => {
-      if (change.operation === 'block') agent.send([{ type: 'text', text: 'inspect the blocker' }])
+      if (change.operation === 'block') agent.followup([{ type: 'text', text: 'inspect the blocker' }])
     })
     test.ctx.goals.create(test.agent, { objective: 'stop and inspect' })
 
@@ -287,7 +289,7 @@ describe('same-session goal driving', () => {
 
   it('pauses and drops a reserved round when cancellation lands before admission', async () => {
     const test = await harness([])
-    const cancel = test.ctx.on('agent/queued', (agent, _content, info) => {
+    const cancel = test.ctx.on('agent/inbox/enqueue', (agent, info) => {
       if (agent === test.agent && info.source.kind === 'goal') {
         cancel()
         agent.cancel({ kind: 'user' })
@@ -299,8 +301,10 @@ describe('same-session goal driving', () => {
 
     expect(goal).toMatchObject({ roundsStarted: 0, activation: 'disarmed' })
     expect(test.adapter.requests).toHaveLength(0)
+    // No admitted continuation round (positive round); goal state changes
+    // (round zero) are expected in the log.
     expect(test.agent.session.events.some(event => event.type === 'user/message'
-      && event.data.source.kind === 'goal')).toBe(false)
+      && event.data.source.kind === 'goal' && event.data.source.round > 0)).toBe(false)
   })
 
   it('pauses an admitted round when cancellation aborts an active step', async () => {
@@ -319,7 +323,7 @@ describe('same-session goal driving', () => {
   it('lets already-queued human work finish before reserving the next round', async () => {
     const test = await harness([textResponse('human answer'), textResponse('goal answer')])
     test.ctx.goals.create(test.agent, { objective: 'continue after the human', maxGoalRounds: 1 })
-    test.agent.send([{ type: 'text', text: 'human goes first' }])
+    test.agent.followup([{ type: 'text', text: 'human goes first' }])
 
     await waitForGoal(test.ctx, test.agent, goal => goal?.phase === 'blocked')
 
@@ -334,7 +338,7 @@ describe('same-session goal driving', () => {
     const warnings: string[] = []
     test.ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof test.ctx.logger.warn
     let inserted = false
-    test.ctx.on('agent/queued', (agent, _content, info) => {
+    test.ctx.on('agent/inbox/enqueue', (agent, info) => {
       if (agent !== test.agent || info.source.kind !== 'goal' || inserted) return
       inserted = true
       const lastStart = agent.session.events.findLast(event => event.type === 'turn/start')
@@ -357,10 +361,10 @@ describe('same-session goal driving', () => {
   it('makes a reserved round stale when a listener queues human work behind it', async () => {
     const test = await harness([textResponse('human batch'), textResponse('later goal')])
     let inserted = false
-    test.ctx.on('agent/queued', (agent, _content, info) => {
+    test.ctx.on('agent/inbox/enqueue', (agent, info) => {
       if (agent !== test.agent || info.source.kind !== 'goal' || inserted) return
       inserted = true
-      agent.send([{ type: 'text', text: 'human joined the pending batch' }])
+      agent.followup([{ type: 'text', text: 'human joined the pending batch' }])
     })
     test.ctx.goals.create(test.agent, { objective: 'yield to nested human input', maxGoalRounds: 1 })
 
@@ -375,7 +379,7 @@ describe('same-session goal driving', () => {
   it('blocks a queued reservation made stale by a goal edit and continues the new revision', async () => {
     const test = await harness([textResponse('new revision')])
     let edited = false
-    test.ctx.on('agent/queued', (agent, _content, info) => {
+    test.ctx.on('agent/inbox/enqueue', (agent, info) => {
       if (agent !== test.agent || info.source.kind !== 'goal' || edited) return
       edited = true
       const current = test.ctx.goals.get(agent)
@@ -391,7 +395,7 @@ describe('same-session goal driving', () => {
     expect(blocked?.type === 'prompt/blocked' ? blocked.data.reason : undefined)
       .toBe('stale goal-round reservation')
     const admitted = test.agent.session.events.find(event => event.type === 'user/message'
-      && event.data.source.kind === 'goal')
+      && event.data.source.kind === 'goal' && event.data.source.round > 0)
     expect(admitted?.type === 'user/message' && admitted.data.source.kind === 'goal'
       ? admitted.data.source.revision
       : undefined).toBe(2)
@@ -475,10 +479,16 @@ describe('same-session goal driving', () => {
     expect(injectedTurn).toBeGreaterThan(goalTurn)
   })
 
-  it('blocks the goal when a custom agent rejects the otherwise valid send', async () => {
+  it('blocks the goal when a custom agent rejects the otherwise valid follow-up', async () => {
     const test = await harness([])
-    vi.spyOn(test.agent, 'send').mockImplementationOnce(() => {
-      throw new Error('queue rejected')
+    // Reject only the goal-sourced round follow-up, not the state-change injection
+    // that precedes it.
+    const realFollowup = test.agent.followup.bind(test.agent)
+    vi.spyOn(test.agent, 'followup').mockImplementation((content, options) => {
+      if (options?.source?.kind === 'goal') {
+        throw new Error('queue rejected')
+      }
+      return realFollowup(content, options)
     })
     test.ctx.goals.create(test.agent, { objective: 'handle queue failure' })
 
@@ -492,11 +502,15 @@ describe('same-session goal driving', () => {
     expect(test.adapter.requests).toHaveLength(0)
   })
 
-  it('preserves a custom agent side effect when send disarms before throwing', async () => {
+  it('preserves a custom agent side effect when followup disarms before throwing', async () => {
     const test = await harness([])
-    vi.spyOn(test.agent, 'send').mockImplementationOnce(() => {
-      test.ctx.goals.disarm(test.agent)
-      throw new Error('queue rejected after disarm')
+    const realFollowup = test.agent.followup.bind(test.agent)
+    vi.spyOn(test.agent, 'followup').mockImplementation((content, options) => {
+      if (options?.source?.kind === 'goal') {
+        test.ctx.goals.disarm(test.agent)
+        throw new Error('queue rejected after disarm')
+      }
+      return realFollowup(content, options)
     })
     test.ctx.goals.create(test.agent, { objective: 'preserve the newer activation state' })
 
@@ -554,7 +568,7 @@ describe('same-session goal driving', () => {
   it('fails a pre-admission read closed even when the first disarm attempt throws', async () => {
     const test = await harness([textResponse('retry after containment')])
     let armed = true
-    test.ctx.on('agent/queued', (agent, _content, info) => {
+    test.ctx.on('agent/inbox/enqueue', (agent, info) => {
       if (agent !== test.agent || info.source.kind !== 'goal' || !armed) return
       armed = false
       vi.spyOn(test.ctx.goals, 'get').mockImplementationOnce(() => {
@@ -595,7 +609,7 @@ describe('same-session goal driving', () => {
 
   it('blocks forged goal attribution without touching an absent reservation', async () => {
     const test = await harness([])
-    test.agent.send([{ type: 'text', text: 'forged automatic work' }], {
+    test.agent.followup([{ type: 'text', text: 'forged automatic work' }], {
       source: { kind: 'goal', goalId: GoalId('forged-goal'), revision: 1, round: 1 },
     })
     await test.agent.whenIdle()
@@ -607,7 +621,7 @@ describe('same-session goal driving', () => {
 
   it('does not invent goal state when ordinary queued work is cancelled', async () => {
     const test = await harness([])
-    test.agent.send([{ type: 'text', text: 'cancel ordinary work' }])
+    test.agent.followup([{ type: 'text', text: 'cancel ordinary work' }])
     test.agent.cancel({ kind: 'user' })
     await test.agent.whenIdle()
 
@@ -617,7 +631,7 @@ describe('same-session goal driving', () => {
 
   it('disarms without durably pausing when cancellation belongs to unrelated human work', async () => {
     const test = await harness(['hang'])
-    test.agent.send([{ type: 'text', text: 'inspect something first' }])
+    test.agent.followup([{ type: 'text', text: 'inspect something first' }])
     await waitForRequests(test.adapter, 1)
     const created = test.ctx.goals.create(test.agent, { objective: 'continue after inspection' })
 
@@ -635,7 +649,7 @@ describe('same-session goal driving', () => {
 
   it('falls back to disarming when a cancelled reservation cannot be paused', async () => {
     const test = await harness([])
-    const cancel = test.ctx.on('agent/queued', (agent, _content, info) => {
+    const cancel = test.ctx.on('agent/inbox/enqueue', (agent, info) => {
       if (agent !== test.agent || info.source.kind !== 'goal') return
       cancel()
       vi.spyOn(test.ctx.goals, 'pause').mockImplementationOnce(() => {
@@ -689,7 +703,7 @@ describe('same-session goal driving', () => {
   it('cancels an accepted queued round and awaits its driver task during teardown', async () => {
     const test = await harness([])
     let unloading: Promise<void> | undefined
-    test.ctx.on('agent/queued', (agent, _content, info) => {
+    test.ctx.on('agent/inbox/enqueue', (agent, info) => {
       if (agent === test.agent && info.source.kind === 'goal' && unloading === undefined) {
         unloading = Promise.resolve(test.driver.dispose())
       }
diff --git a/packages/goal/goal-session/tests/invariant.spec.ts b/packages/goal/goal-session/tests/invariant.spec.ts
index 19200747e8..0427a41333 100644
--- a/packages/goal/goal-session/tests/invariant.spec.ts
+++ b/packages/goal/goal-session/tests/invariant.spec.ts
@@ -40,7 +40,7 @@ function view(roundsStarted: number): GoalView {
 
 function appendChange(session: Session): void {
   session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
-  session.append('context/message', {
+  session.append('user/message', {
     content: renderGoalChange(change),
     source: changeSource,
     meta: change as never,
@@ -126,7 +126,7 @@ describe('goal-session prompt invariants', () => {
   it('attributes an invalid durable prefix during late loading', async () => {
     const { ctx, session } = await mount(true)
     session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
-    session.append('context/message', {
+    session.append('user/message', {
       content: [{ type: 'text', text: 'counterfeit goal state' }],
       source: changeSource,
       meta: change as never,
diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md
index e50044d135..1df6d08f5c 100644
--- a/packages/goal/goal/README.md
+++ b/packages/goal/goal/README.md
@@ -19,7 +19,7 @@ Event-sourced same-session goal state. The service retains one current completio
 
 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.
 
-Every non-clear mutation appends a complete versioned snapshot through `agent.inject()`; clear appends a revisioned tombstone. The `context/message` content projected verbatim to the model, its `{ kind: 'goal' }` source, and its metadata must agree exactly. Replay rejects malformed shapes, source/content drift, discontinuous revisions, illegal lifecycle transitions, non-monotonic per-goal timestamps, and non-sequential goal rounds. Mutation timestamps clamp against the preceding goal update when wall time moves backward.
+Every non-clear mutation appends a complete versioned snapshot through `agent.inject()`; clear appends a revisioned tombstone. The round-zero `user/message` content projected verbatim to the model, its `{ kind: 'goal' }` source, and its metadata must agree exactly. Replay rejects malformed shapes, source/content drift, discontinuous revisions, illegal lifecycle transitions, non-monotonic per-goal timestamps, and non-sequential goal rounds. Mutation timestamps clamp against the preceding goal update when wall time moves backward.
 
 Injection may append immediately or wait in an active tool-batch FIFO. The service overlays accepted pending changes in memory and reconciles each exact payload when it enters the log, so consecutive model-tool mutations see their own latest revisions without treating an unlogged cache as durable state. Reentrant append observers see each accepted mutation exactly once, and incremental replay retains its cursor at the first corrupt event. `goal/changed` fires after the append or enqueue succeeds; listener failures are contained.
 
diff --git a/packages/goal/goal/src/fold.ts b/packages/goal/goal/src/fold.ts
index fe88ebcdba..2ff756249f 100644
--- a/packages/goal/goal/src/fold.ts
+++ b/packages/goal/goal/src/fold.ts
@@ -17,7 +17,7 @@ import type {
   GoalSnapshotChangeMeta,
 } from './types.ts'
 
-type ContextMessageEvent = Extract<SessionEvent, { type: 'context/message' }>
+type UserMessageEvent = Extract<SessionEvent, { type: 'user/message' }>
 
 const SNAPSHOT_OPERATIONS: ReadonlySet<Exclude<GoalOperation, 'clear'>> = new Set([
   'create',
@@ -310,17 +310,18 @@ export function applyGoalChange(state: GoalFoldState, change: GoalChangeMeta): v
 }
 
 /**
- * Decode and verify one model-visible goal context event without folding it.
- * @param event - context event whose metadata and rendered content must agree.
- * @returns validated change or `undefined` for an unrelated context event.
+ * Decode and verify one model-visible goal state change without folding it. A
+ * goal state change is a round-zero goal-sourced `user/message` carrying
+ * `goal/change` metadata; any other user message returns `undefined`. Goal
+ * metadata on a non-goal source, or a mismatched attribution or rendered body,
+ * fails replay loudly.
+ * @param event - user message whose metadata and rendered content must agree.
+ * @returns validated change, or `undefined` when the message is not a goal state change.
  */
-export function decodeGoalEvent(event: ContextMessageEvent): GoalChangeMeta | undefined {
+export function decodeGoalEvent(event: UserMessageEvent): GoalChangeMeta | undefined {
   const change = decodeGoalChange(event.data.meta)
+  if (change === undefined) return undefined
   const source = goalSource(event.data.source)
-  if (change === undefined) {
-    if (source !== undefined) throw new Error(`goal source at session event ${event.seq} lacks goal change metadata`)
-    return undefined
-  }
   const ref = goalChangeRef(change)
   if (source === undefined || source.goalId !== ref.id || source.revision !== ref.revision || source.round !== 0) {
     throw new Error(`goal change at session event ${event.seq} has mismatched source attribution`)
@@ -338,23 +339,27 @@ export function decodeGoalEvent(event: ContextMessageEvent): GoalChangeMeta | un
  * @returns decoded change for pending-overlay reconciliation.
  */
 export function applyGoalEvent(state: GoalFoldState, event: SessionEvent): GoalChangeMeta | undefined {
-  if (event.type === 'context/message') {
-    const change = decodeGoalEvent(event)
-    if (change === undefined) return undefined
-    applyGoalChange(state, change)
-    return change
-  }
   if (event.type === 'user/message') {
-    const source = goalSource(event.data.source)
-    if (source !== undefined) {
-      const current = state.goal
-      if (current === undefined || current.phase !== 'active' || source.goalId !== current.id
-        || source.revision !== current.revision || source.round !== state.roundsStarted + 1
-        || source.round > current.maxGoalRounds) {
-        throw new Error(`goal round at session event ${event.seq} is not the next admitted round of the active goal`)
-      }
-      state.roundsStarted = source.round
+    // A goal state change carries `goal/change` metadata (round zero).
+    const change = decodeGoalEvent(event)
+    if (change !== undefined) {
+      applyGoalChange(state, change)
+      return change
     }
+    const source = goalSource(event.data.source)
+    if (source === undefined) return undefined
+    // A goal-sourced message without change metadata must be a positive-round
+    // admitted continuation prompt; round zero owes durable change metadata.
+    if (source.round === 0) {
+      throw new Error(`goal source at session event ${event.seq} lacks goal change metadata`)
+    }
+    const current = state.goal
+    if (current === undefined || current.phase !== 'active' || source.goalId !== current.id
+      || source.revision !== current.revision || source.round !== state.roundsStarted + 1
+      || source.round > current.maxGoalRounds) {
+      throw new Error(`goal round at session event ${event.seq} is not the next admitted round of the active goal`)
+    }
+    state.roundsStarted = source.round
   }
   return undefined
 }
diff --git a/packages/goal/goal/src/index.ts b/packages/goal/goal/src/index.ts
index 7391c69e93..e4700452fa 100644
--- a/packages/goal/goal/src/index.ts
+++ b/packages/goal/goal/src/index.ts
@@ -370,7 +370,9 @@ export class GoalService extends Service {
   /** Incrementally observe durable events without losing deferred mutations. */
   private sync(session: Session, cache: GoalCache): void {
     for (const event of session.events.slice(cache.observedSeq)) {
-      if (event.type === 'context/message') {
+      // A goal state change is a round-zero goal-sourced user message; a
+      // positive round is a continuation prompt handled by applyGoalEvent.
+      if (event.type === 'user/message' && event.data.source.kind === 'goal' && event.data.source.round === 0) {
         const change = decodeGoalEvent(event)
         if (change !== undefined) {
           const pending = cache.pending[0]
diff --git a/packages/goal/goal/src/runtime.ts b/packages/goal/goal/src/runtime.ts
index 49184faa8c..5a97cceae0 100644
--- a/packages/goal/goal/src/runtime.ts
+++ b/packages/goal/goal/src/runtime.ts
@@ -3,7 +3,7 @@
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { GoalErrorCode, GoalId as GoalIdType } from './types.ts'
 
-/** Version of the goal change metadata embedded in `context/message`. */
+/** Version of the goal change metadata embedded in a round-zero `user/message`. */
 export const GOAL_CHANGE_VERSION = 1
 
 /**
diff --git a/packages/goal/goal/src/types.ts b/packages/goal/goal/src/types.ts
index 2c6798718d..7da3c525d7 100644
--- a/packages/goal/goal/src/types.ts
+++ b/packages/goal/goal/src/types.ts
@@ -89,7 +89,7 @@ export interface GoalClearChangeMeta {
   readonly clearedAt: number
 }
 
-/** Durable metadata union carried by a goal-owned `context/message`. */
+/** Durable metadata union carried by a goal-owned round-zero `user/message`. */
 export type GoalChangeMeta = GoalSnapshotChangeMeta | GoalClearChangeMeta
 
 /** Message attribution for durable goal state and continuation rounds. */
diff --git a/packages/goal/goal/tests/goal.e2e.ts b/packages/goal/goal/tests/goal.e2e.ts
index 0c582645bc..756073083a 100644
--- a/packages/goal/goal/tests/goal.e2e.ts
+++ b/packages/goal/goal/tests/goal.e2e.ts
@@ -50,11 +50,11 @@ describe('goal domain through a real cordis.yml and headless process', () => {
     expect(result['result']).toContain('CLI tool round trip complete')
     expect(events.filter(event => event.type === 'turn/end')).toHaveLength(1)
 
-    const contexts = events.filter(event => event.type === 'context/message'
+    const contexts = events.filter(event => event.type === 'user/message'
       && event.data.source.kind === 'goal')
     expect(contexts).toHaveLength(1)
     const context = contexts[0]
-    if (context?.type !== 'context/message') throw new Error('expected goal context event')
+    if (context?.type !== 'user/message') throw new Error('expected goal context event')
     const change = decodeGoalChange(context.data.meta)
     if (change === undefined) throw new Error('expected durable goal change')
     expect(change).toMatchObject({
@@ -69,7 +69,9 @@ describe('goal domain through a real cordis.yml and headless process', () => {
     })
     expect(context.data.content).toEqual(renderGoalChange(change))
     expect(JSON.stringify(context)).not.toContain('activation')
+    // No admitted continuation round ran (the snapshot mounts without starting
+    // a round); the round-zero state change from create is expected above.
     expect(events.filter(event => event.type === 'user/message'
-      && event.data.source.kind === 'goal')).toHaveLength(0)
+      && event.data.source.kind === 'goal' && event.data.source.round > 0)).toHaveLength(0)
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })
diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts
index ad2011fc62..264261d94b 100644
--- a/packages/goal/goal/tests/goal.spec.ts
+++ b/packages/goal/goal/tests/goal.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentStatus, InjectOptions } from '@deepseek-ai/dsh-agent'
 import { HarnessError, type ContentBlock, type MessageSource } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -34,7 +34,7 @@ function nextTurn(session: Session): number {
 
 /** Mirror the public Agent.inject idle/open-turn contract for domain tests. */
 function appendInjection(session: Session, content: ContentBlock[], options?: InjectOptions): void {
-  const source: MessageSource = options?.source ?? { kind: 'user' }
+  const source: MessageSource = options?.source ?? { kind: 'plugin', plugin: '' }
   const context = {
     content,
     source,
@@ -43,12 +43,12 @@ function appendInjection(session: Session, content: ContentBlock[], options?: In
   const last = session.events.at(-1)
   const open = last !== undefined && last.type !== 'turn/end'
   if (open) {
-    session.append('context/message', context, { surfaceOp: 'append' })
+    session.append('user/message', context, { surfaceOp: 'append' })
     return
   }
   const turn = nextTurn(session)
   session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-  session.append('context/message', context, { surfaceOp: 'append' })
+  session.append('user/message', context, { surfaceOp: 'append' })
   session.append('turn/end', { turn, reason: { kind: 'completed' } })
 }
 
@@ -64,12 +64,15 @@ function stubAgentForSession(session: Session): StubAgent {
     session,
     ctx: new Context(),
     get status() { return status },
-    send() {},
-    steer() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
     inject(content, options) {
       if (shouldDefer) deferred.push({ content, options })
       else appendInjection(session, content, options)
+      return AgentMessageId('stub')
     },
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle() { return Promise.resolve() },
   }
@@ -131,10 +134,10 @@ describe('GoalService creation and replay', () => {
     })
     expect(goal.id).toMatch(/^goal-/)
     expect(seen).toEqual(['create'])
-    expect(session.events.map(event => event.type)).toEqual(['turn/start', 'context/message', 'turn/end'])
+    expect(session.events.map(event => event.type)).toEqual(['turn/start', 'user/message', 'turn/end'])
     const context = session.events[1]
-    expect(context?.type).toBe('context/message')
-    if (context?.type !== 'context/message') throw new Error('expected goal context')
+    expect(context?.type).toBe('user/message')
+    if (context?.type !== 'user/message') throw new Error('expected goal context')
     expect(context.data.source).toEqual({ kind: 'goal', goalId: goal.id, revision: 1, round: 0 })
     const change = decodeGoalChange(context.data.meta)
     if (change === undefined) throw new Error('expected decoded goal change')
@@ -266,7 +269,9 @@ describe('GoalService creation and replay', () => {
 
   it('requires the exact live registry instance for reads and mutations', async () => {
     const { ctx, agent } = await harness()
-    const impostor = { ...agent, session: new Session(agent.id) }
+    // A same-id agent backed by a different session object — the live-instance
+    // check must reject it even though the ids match.
+    const impostor = stubAgentForSession(new Session(agent.id)).agent
     expect(() => ctx.goals.get(impostor)).toThrow(expect.objectContaining({ code: 'GOAL_AGENT_NOT_LIVE' }))
     expect(() => ctx.goals.create(impostor, { objective: 'no' })).toThrow(expect.objectContaining({
       code: 'GOAL_AGENT_NOT_LIVE',
@@ -407,8 +412,8 @@ describe('GoalService mutations', () => {
     vi.setSystemTime(80)
     ctx.goals.clear(agent, goal)
     const clear = session.events
-      .filter(event => event.type === 'context/message')
-      .map(event => decodeGoalChange(event.data.meta))
+      .filter(event => event.type === 'user/message' && event.data.source.kind === 'goal')
+      .map(event => event.type === 'user/message' ? decodeGoalChange(event.data.meta) : undefined)
       .at(-1)
     expect(clear).toMatchObject({ operation: 'clear', clearedAt: 100 })
     expect(() => foldGoal(session.events)).not.toThrow()
@@ -454,7 +459,7 @@ describe('GoalService mutations', () => {
     ctx.agents.register(stub.agent)
     let observed: ReturnType<GoalService['get']>
     ctx.on('session/event', (session, event) => {
-      if (session === stub.session && event.type === 'context/message') observed = ctx.goals.get(stub.agent)
+      if (session === stub.session && event.type === 'user/message' && event.data.source.kind === 'goal') observed = ctx.goals.get(stub.agent)
     })
 
     const created = ctx.goals.create(stub.agent, { objective: 'publish once' })
@@ -473,7 +478,7 @@ describe('GoalService mutations', () => {
     let reject = true
     stub.agent.inject = (content, options) => {
       if (reject) throw new Error('injection rejected')
-      append(content, options)
+      return append(content, options)
     }
     ctx.agents.register(stub.agent)
 
@@ -517,7 +522,7 @@ describe('GoalService mutations', () => {
     const source = { kind: 'goal', goalId: change.goal.id, revision: 1, round: 0 } as const
     const turn = nextTurn(session)
     session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-    session.append('context/message', {
+    session.append('user/message', {
       content: renderGoalChange(change), source, meta: change as never,
     }, { surfaceOp: 'append' })
     session.append('turn/end', { turn, reason: { kind: 'completed' } })
@@ -594,7 +599,7 @@ describe('goal replay validation', () => {
     }
     const turn = nextTurn(session)
     session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-    session.append('context/message', {
+    session.append('user/message', {
       content: overrides.content ?? renderGoalChange(change),
       source,
       meta: change as never,
@@ -791,7 +796,7 @@ describe('goal replay validation', () => {
     const source = { kind: 'goal', goalId: GoalId('goal-missing-meta'), revision: 1, round: 0 } as const
     const turn = nextTurn(session)
     session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-    session.append('context/message', {
+    session.append('user/message', {
       content: [{ type: 'text', text: 'missing' }], source,
     }, { surfaceOp: 'append' })
     session.append('turn/end', { turn, reason: { kind: 'completed' } })
@@ -853,7 +858,7 @@ describe('goal replay validation', () => {
     const source = { kind: 'goal', goalId: change.goal.id, revision: 2, round: 0 } as const
     const turn = nextTurn(session)
     session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-    session.append('context/message', {
+    session.append('user/message', {
       content: renderGoalChange(clear), source, meta: clear as never,
     }, { surfaceOp: 'append' })
     session.append('turn/end', { turn, reason: { kind: 'completed' } })
diff --git a/packages/goal/goal/tests/invariant.spec.ts b/packages/goal/goal/tests/invariant.spec.ts
index 85f0b839d1..996743ceca 100644
--- a/packages/goal/goal/tests/invariant.spec.ts
+++ b/packages/goal/goal/tests/invariant.spec.ts
@@ -45,7 +45,7 @@ describe('goal stream invariants', () => {
     const ctx = await setup()
     const session = ctx.sessions.create(SessionId('goal-invariant-valid'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
-    session.append('context/message', {
+    session.append('user/message', {
       content: renderGoalChange(change),
       source: changeSource,
       meta: change as never,
@@ -71,7 +71,7 @@ describe('goal stream invariants', () => {
     const session = ctx.sessions.create(SessionId('goal-invariant-invalid'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
     expect(() => {
-      session.append('context/message', {
+      session.append('user/message', {
         content: [{ type: 'text', text: 'counterfeit' }],
         source: changeSource,
         meta: change as never,
@@ -82,7 +82,7 @@ describe('goal stream invariants', () => {
     }))
     expect(session.seq).toBe(1)
     expect(() => {
-      session.append('context/message', {
+      session.append('user/message', {
         content: renderGoalChange(change),
         source: changeSource,
         meta: change as never,
@@ -95,7 +95,7 @@ describe('goal stream invariants', () => {
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('goal-invariant-late-load'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
-    session.append('context/message', {
+    session.append('user/message', {
       content: renderGoalChange(change),
       source: changeSource,
       meta: change as never,
diff --git a/packages/goal/tool-goal/README.md b/packages/goal/tool-goal/README.md
index 6b900e2a05..346ac07dcc 100644
--- a/packages/goal/tool-goal/README.md
+++ b/packages/goal/tool-goal/README.md
@@ -6,9 +6,11 @@ The model-facing control surface for [`ctx.goals`](../goal/README.md): `get_goal
 
 - `get_goal()` returns the current goal or `null`, including the compare-and-set id/revision, durable phase, admitted/capped goal rounds, any blocker reason, and current process-local activation.
 - `create_goal(objective, max_goal_rounds?)` creates one goal from a direct top-level human turn. The model may infer long-running goal intent without an exact command phrase; non-human turns and subagents are rejected at execution.
-- `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`. Replacements belong only to `edit`; `blocked_reason` is required only for `blocked` and is persisted with the stable code `model-reported`.
+- `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`. Replacements belong only to `edit`; `blocked_reason` is required only for `blocked` and is persisted with the stable code `model-reported`. Strict-schema empty-string and zero fillers count as omitted, while meaningful values remain limited to their action.
 
-All calls are exclusive, so a model-ordered batch observes earlier mutations and their new revisions. ACP and other clients receive pure generic cards: read for `get_goal`, other for mutations.
+All calls are exclusive, so a model-ordered batch observes earlier mutations and their new revisions. ACP and other clients receive pure generic cards: read for `get_goal`, other for mutations. Mutation cards select the first meaningful action value and otherwise show the goal id, so accepted fillers never produce blank input.
+
+All three canonical values match the compact JSON already rendered to Native callers: `{ goal: null }` or `{ goal: { id, revision, objective, phase, roundsStarted, maxGoalRounds, blockedReason? }, activation }`. Programmatic consumers therefore receive the same domain structure without parsing the rendered JSON.
 
 An autonomous goal round that successfully reports `complete` or `blocked` contributes the existing terminal `agent/turn-stop` decision for that physical turn. Direct-human mutations never contribute this stop: the assistant may acknowledge the change and concurrent human steering remains available to the loop.
 
@@ -16,7 +18,7 @@ An autonomous goal round that successfully reports `complete` or `blocked` contr
 
 Execution requires the exact live `exec.agent`, its inherited `AgentRegistry` initiator, running status, and an open turn. Create, edit, pause, and resume additionally require an accepted `{ kind: 'user' }` message or steering event in a runtime-root agent's current turn. Durable fork lineage does not demote a resumed root; live subagent ownership does.
 
-`{ kind: 'user' }` is a host attestation. `Agent.send()` and `steer()` assign it when their caller omits a source, so plugins, schedulers, and other non-human producers must pass their own source rather than inheriting human authority.
+`{ kind: 'user' }` is a host attestation. `Agent.followup()` and `steer()` assign it when their caller omits a source, so plugins, schedulers, and other non-human producers must pass their own source rather than inheriting human authority.
 
 Complete and blocked also accept the exact current goal round: a goal-sourced `user/message` whose id, revision, and round equal the folded current goal. A goal-round blocked call is mechanically rejected until `blockedAfterConsecutiveRounds`; the model judges whether the same condition actually persisted and must describe it in `blocked_reason`. Direct human authority may stop a goal immediately.
 
diff --git a/packages/goal/tool-goal/src/authority.ts b/packages/goal/tool-goal/src/authority.ts
index 41fe713dc6..f48c9cd098 100644
--- a/packages/goal/tool-goal/src/authority.ts
+++ b/packages/goal/tool-goal/src/authority.ts
@@ -64,7 +64,7 @@ export function goalToolExecution(ctx: Context, exec: ToolRunContext): GoalToolE
 
 /**
  * Whether host-attested human input appears in the current root-agent turn.
- * An omitted `Agent.send()` / `steer()` source resolves to `user`, so non-human
+ * An omitted `Agent.followup()` / `steer()` source resolves to `user`, so non-human
  * producers must supply their own source rather than inheriting this authority.
  */
 function hasDirectHumanInput(ctx: Context, execution: GoalToolExecution): boolean {
diff --git a/packages/goal/tool-goal/src/index.ts b/packages/goal/tool-goal/src/index.ts
index 075264f93e..09953041fa 100644
--- a/packages/goal/tool-goal/src/index.ts
+++ b/packages/goal/tool-goal/src/index.ts
@@ -54,6 +54,62 @@ const GET_DESCRIPTION =
   + 'continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. '
   + 'Call this before updating a goal.'
 
+/** Canonical goal-tool output, matching the existing compact Native JSON. */
+type GoalToolValue =
+  | { goal: null }
+  | {
+    goal: {
+      id: string
+      revision: number
+      objective: string
+      phase: GoalView['phase']
+      roundsStarted: number
+      maxGoalRounds: number
+      blockedReason?: { code: string; message: string }
+    }
+    activation: GoalView['activation']
+  }
+
+const GOAL_VALUE_SCHEMA = {
+  oneOf: [
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        goal: { type: 'null', required: true },
+      },
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        goal: {
+          type: 'object',
+          additionalProperties: false,
+          required: true,
+          properties: {
+            id: { type: 'string', required: true },
+            revision: { type: 'integer', required: true },
+            objective: { type: 'string', required: true },
+            phase: { type: 'string', required: true, enum: ['active', 'paused', 'blocked', 'complete'] },
+            roundsStarted: { type: 'integer', required: true },
+            maxGoalRounds: { type: 'integer', required: true },
+            blockedReason: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                code: { type: 'string', required: true },
+                message: { type: 'string', required: true },
+              },
+            },
+          },
+        },
+        activation: { type: 'string', required: true, enum: ['armed', 'disarmed'] },
+      },
+    },
+  ],
+} as const
+
 /** Render policy guidance with its deployment-selected blocked threshold. */
 function guidance(blockedAfter: number): string {
   return 'Use goal tools for one long-running completion objective in the current session. '
@@ -76,6 +132,16 @@ function resolveConfig(config: Config): ResolvedConfig {
   return { blockedAfterConsecutiveRounds: blockedAfter }
 }
 
+/** Whether optional text is meaningful rather than a strict-schema empty filler. */
+function hasText(value: string | undefined): value is string {
+  return value !== undefined && value !== ''
+}
+
+/** Whether an optional round cap is meaningful rather than a strict-schema zero filler. */
+function hasRoundCap(value: number | undefined): value is number {
+  return value !== undefined && value !== 0
+}
+
 /** Build the exact compare-and-set ref from model arguments. */
 function goalRef(goalId: string, revision: number): GoalRef {
   if (goalId.length === 0 || goalId !== goalId.trim()
@@ -89,9 +155,9 @@ function goalRef(goalId: string, revision: number): GoalRef {
 }
 
 /** Stable compact model result; activation is an observation, not replay state. */
-function renderGoal(goal: GoalView | undefined): string {
-  if (goal === undefined) return JSON.stringify({ goal: null })
-  return JSON.stringify({
+function goalValue(goal: GoalView | undefined): GoalToolValue {
+  if (goal === undefined) return { goal: null }
+  return {
     goal: {
       id: goal.id,
       revision: goal.revision,
@@ -99,10 +165,18 @@ function renderGoal(goal: GoalView | undefined): string {
       phase: goal.phase,
       roundsStarted: goal.roundsStarted,
       maxGoalRounds: goal.maxGoalRounds,
-      ...goal.blockedReason === undefined ? {} : { blockedReason: goal.blockedReason },
+      ...goal.blockedReason === undefined ? {} : {
+        blockedReason: { code: goal.blockedReason.code, message: goal.blockedReason.message },
+      },
     },
     activation: goal.activation,
-  })
+  }
+}
+
+/** Reusable canonical output declaration for all three goal controls. */
+const GOAL_OUTPUT = {
+  schema: GOAL_VALUE_SCHEMA,
+  render: (_args: unknown, value: GoalToolValue) => [{ type: 'text' as const, text: JSON.stringify(value) }],
 }
 
 /** Generic, args-only pending presentation shared by the goal tools. */
@@ -144,12 +218,10 @@ export function apply(ctx: Context, config: Config): void {
     name: 'get_goal',
     description: GET_DESCRIPTION,
     parameters: {},
+    output: GOAL_OUTPUT,
     execute(_args, exec) {
       const execution = goalToolExecution(ctx, exec)
-      return Promise.resolve([{
-        type: 'text',
-        text: renderGoal(ctx.goals.get(execution.agent)),
-      }])
+      return Promise.resolve(goalValue(ctx.goals.get(execution.agent)))
     },
     presentCall: () => present('Read current goal', 'read'),
   }))
@@ -168,6 +240,7 @@ export function apply(ctx: Context, config: Config): void {
         description: 'Optional positive safe-integer limit on automatic continuation rounds.',
       },
     },
+    output: GOAL_OUTPUT,
     execute(args, exec) {
       const execution = goalToolExecution(ctx, exec)
       requireDirectHuman(ctx, execution)
@@ -176,7 +249,7 @@ export function apply(ctx: Context, config: Config): void {
         ...args.max_goal_rounds === undefined ? {} : { maxGoalRounds: args.max_goal_rounds },
       })
       observeMutation(terminalTurns, execution, false)
-      return Promise.resolve([{ type: 'text', text: renderGoal(goal) }])
+      return Promise.resolve(goalValue(goal))
     },
     presentCall: args => present('Create goal', 'other', args.objective),
   }))
@@ -203,28 +276,26 @@ export function apply(ctx: Context, config: Config): void {
         description: 'Concrete blocking condition; required only with action blocked.',
       },
     },
+    output: GOAL_OUTPUT,
     execute(args, exec) {
       const execution = goalToolExecution(ctx, exec)
       const ref = goalRef(args.goal_id, args.revision)
       const replacements = {
-        ...args.objective === undefined ? {} : { objective: args.objective },
-        ...args.max_goal_rounds === undefined ? {} : { maxGoalRounds: args.max_goal_rounds },
+        ...hasText(args.objective) ? { objective: args.objective } : {},
+        ...hasRoundCap(args.max_goal_rounds) ? { maxGoalRounds: args.max_goal_rounds } : {},
       }
       if (args.action === 'edit') {
         requireDirectHuman(ctx, execution)
-        if (args.blocked_reason !== undefined) {
+        if (hasText(args.blocked_reason)) {
           throw new HarnessError('blocked_reason is valid only with action blocked', 'GOAL_TOOL_INVALID_UPDATE')
         }
         const goal = ctx.goals.edit(execution.agent, ref, replacements)
         observeMutation(terminalTurns, execution, false)
-        return Promise.resolve([{
-          type: 'text',
-          text: renderGoal(goal),
-        }])
+        return Promise.resolve(goalValue(goal))
       }
       if (args.action === 'pause' || args.action === 'resume') {
         requireDirectHuman(ctx, execution)
-        if (args.objective !== undefined || args.max_goal_rounds !== undefined || args.blocked_reason !== undefined) {
+        if (hasText(args.objective) || hasRoundCap(args.max_goal_rounds) || hasText(args.blocked_reason)) {
           throw new HarnessError(
             'objective and max_goal_rounds are valid only with action edit; blocked_reason is valid only with action blocked',
             'GOAL_TOOL_INVALID_UPDATE',
@@ -234,16 +305,16 @@ export function apply(ctx: Context, config: Config): void {
           ? ctx.goals.pause(execution.agent, ref)
           : ctx.goals.resume(execution.agent, ref)
         observeMutation(terminalTurns, execution, false)
-        return Promise.resolve([{ type: 'text', text: renderGoal(goal) }])
+        return Promise.resolve(goalValue(goal))
       }
       const authority = completionAuthority(ctx, execution)
-      if (args.objective !== undefined || args.max_goal_rounds !== undefined) {
+      if (hasText(args.objective) || hasRoundCap(args.max_goal_rounds)) {
         throw new HarnessError(
           'objective and max_goal_rounds are valid only with action edit',
           'GOAL_TOOL_INVALID_UPDATE',
         )
       }
-      if (args.action === 'complete' && args.blocked_reason !== undefined) {
+      if (args.action === 'complete' && hasText(args.blocked_reason)) {
         throw new HarnessError('blocked_reason is valid only with action blocked', 'GOAL_TOOL_INVALID_UPDATE')
       }
       if (args.action === 'blocked'
@@ -265,12 +336,16 @@ export function apply(ctx: Context, config: Config): void {
           message: args.blocked_reason as string,
         })
       observeMutation(terminalTurns, execution, authority.kind === 'goal-round')
-      return Promise.resolve([{ type: 'text', text: renderGoal(goal) }])
+      return Promise.resolve(goalValue(goal))
     },
     presentCall: args => present(
       `${args.action === 'blocked' ? 'Mark' : args.action.charAt(0).toUpperCase() + args.action.slice(1)} goal`,
       'other',
-      args.blocked_reason ?? args.objective ?? args.goal_id,
+      hasText(args.blocked_reason)
+        ? args.blocked_reason
+        : hasText(args.objective)
+          ? args.objective
+          : hasRoundCap(args.max_goal_rounds) ? args.max_goal_rounds : args.goal_id,
     ),
   }))
 }
diff --git a/packages/goal/tool-goal/tests/tool-goal.spec.ts b/packages/goal/tool-goal/tests/tool-goal.spec.ts
index faaf9d1c76..eaab21e202 100644
--- a/packages/goal/tool-goal/tests/tool-goal.spec.ts
+++ b/packages/goal/tool-goal/tests/tool-goal.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentStatus, InjectOptions } from '@deepseek-ai/dsh-agent'
 import GoalService, { GoalId } from '@deepseek-ai/dsh-goal'
 import type { GoalRef } from '@deepseek-ai/dsh-goal'
@@ -31,16 +31,19 @@ function stubAgent(rawId: string, supplied?: Session): StubAgent {
     session,
     get status() { return status },
     ctx: new Context(),
-    send() {},
-    steer() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
     inject(content: ContentBlock[], options?: InjectOptions) {
-      const source = options?.source ?? { kind: 'user' }
-      session.append('context/message', {
+      const source = options?.source ?? { kind: 'plugin', plugin: '' }
+      session.append('user/message', {
         content,
         source,
         ...options?.meta === undefined ? {} : { meta: options.meta },
       }, { surfaceOp: 'append' })
+      return AgentMessageId('stub')
     },
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle() { return Promise.resolve() },
   }
@@ -98,9 +101,12 @@ async function execute(
 /** Parse the compact JSON returned by a successful goal tool. */
 function resultJson(result: ToolExecutionResult): Record<string, unknown> {
   expect(result.isError).toBe(false)
+  if (result.isError) throw new Error('expected goal tool success')
   const block = result.content[0]
   if (block?.type !== 'text') throw new Error('expected text tool result')
-  return JSON.parse(block.text) as Record<string, unknown>
+  const parsed = JSON.parse(block.text) as Record<string, unknown>
+  expect(result.value).toEqual(parsed)
+  return parsed
 }
 
 /** Read the returned goal sub-object. */
@@ -139,8 +145,17 @@ describe('goal tool registration and presentation', () => {
     expect(ctx.tools.get('update_goal')?.presentCall?.({
       goal_id: 'goal-1', revision: 2, action: 'blocked', blocked_reason: 'Waiting for a human choice.',
     })).toEqual({ card: 'generic', title: 'Mark goal', kind: 'other', rawInput: 'Waiting for a human choice.' })
+    expect(ctx.tools.get('update_goal')?.presentCall?.({
+      goal_id: 'goal-1', revision: 2, action: 'edit',
+      objective: 'ship', max_goal_rounds: 0, blocked_reason: '',
+    })).toEqual({ card: 'generic', title: 'Edit goal', kind: 'other', rawInput: 'ship' })
+    expect(ctx.tools.get('update_goal')?.presentCall?.({
+      goal_id: 'goal-1', revision: 2, action: 'edit',
+      objective: '', max_goal_rounds: 8, blocked_reason: '',
+    })).toEqual({ card: 'generic', title: 'Edit goal', kind: 'other', rawInput: 8 })
     expect(ctx.tools.get('update_goal')?.presentCall?.({
       goal_id: 'goal-1', revision: 2, action: 'resume',
+      objective: '', max_goal_rounds: 0, blocked_reason: '',
     })).toEqual({ card: 'generic', title: 'Resume goal', kind: 'other', rawInput: 'goal-1' })
     expect(ctx.tools.get('update_goal')?.presentCall?.({ wrong: true })).toBeUndefined()
   })
@@ -196,7 +211,7 @@ describe('goal tool execution authority', () => {
   it('rejects agentless, driverless, non-human, and live-child creation', async () => {
     const { ctx, root } = await harness()
     const agentless = await execute(ctx, 'get_goal', {})
-    expect(agentless.error?.code).toBe('GOAL_TOOL_AGENT_REQUIRED')
+    expect(agentless.error?.info?.code).toBe('GOAL_TOOL_AGENT_REQUIRED')
 
     openTurn(root, { kind: 'user' })
     const driverless = await ctx.tools.execute({
@@ -206,12 +221,12 @@ describe('goal tool execution authority', () => {
       arguments: {},
       agent: root.agent,
     })
-    expect(driverless.error?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
+    expect(driverless.error?.info?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
     closeTurn(root, 1)
 
     openTurn(root, { kind: 'plugin', plugin: 'test' })
     const nonHuman = await execute(ctx, 'create_goal', { objective: 'forged' }, root.agent)
-    expect(nonHuman.error?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
+    expect(nonHuman.error?.info?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
     closeTurn(root, 2)
 
     const child = stubAgent('goal-tool-child')
@@ -219,19 +234,21 @@ describe('goal tool execution authority', () => {
     ctx.agents.announce(child.agent)
     openTurn(child, { kind: 'user' })
     const childResult = await execute(ctx, 'create_goal', { objective: 'child goal' }, child.agent)
-    expect(childResult.error?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
+    expect(childResult.error?.info?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
   })
 
   it('rejects stale agent objects and agents outside running status through the executor', async () => {
     const { ctx, root } = await harness()
     openTurn(root, { kind: 'user' })
-    const stale = { ...root.agent }
+    // A distinct agent object over root's exact session: same id, not the live
+    // registered instance, so the executor must reject it.
+    const stale = stubAgent('goal-tool-stale', root.agent.session).agent
     const staleResult = await execute(ctx, 'get_goal', {}, stale, stale)
-    expect(staleResult.error?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
+    expect(staleResult.error?.info?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
 
     root.setStatus('idle')
     const idleResult = await execute(ctx, 'get_goal', {}, root.agent)
-    expect(idleResult.error?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
+    expect(idleResult.error?.info?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
   })
 
   it('treats a fork resumed as a runtime root as direct-human authority', async () => {
@@ -261,12 +278,12 @@ describe('goal tool execution authority', () => {
   it('rejects calls before a turn and after its end boundary', async () => {
     const { ctx, root } = await harness()
     const before = await execute(ctx, 'get_goal', {}, root.agent)
-    expect(before.error?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
+    expect(before.error?.info?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
 
     const turn = openTurn(root, { kind: 'user' })
     closeTurn(root, turn)
     const after = await execute(ctx, 'get_goal', {}, root.agent)
-    expect(after.error?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
+    expect(after.error?.info?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
   })
 
   it('rejects terminal reporting without human input or a current goal round', async () => {
@@ -275,11 +292,11 @@ describe('goal tool execution authority', () => {
     const result = await execute(ctx, 'update_goal', {
       goal_id: 'goal-missing', revision: 1, action: 'complete',
     }, root.agent)
-    expect(result.error?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
+    expect(result.error?.info?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
     const malformed = await execute(ctx, 'update_goal', {
       goal_id: 'goal-missing', revision: 1, action: 'pause', objective: 'probe',
     }, root.agent)
-    expect(malformed.error?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
+    expect(malformed.error?.info?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
   })
 
   it('accepts direct human steering in a goal-sourced root turn', async () => {
@@ -307,7 +324,7 @@ describe('goal tool execution authority', () => {
     ctx.agents.register(other.agent)
     openTurn(other, { kind: 'user' })
     const result = await execute(ctx, 'get_goal', {}, other.agent, root.agent)
-    expect(result.error?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
+    expect(result.error?.info?.code).toBe('GOAL_TOOL_DRIVER_REQUIRED')
   })
 })
 
@@ -378,7 +395,7 @@ describe('goal tool state transitions', () => {
     const { ctx, root } = await harness()
     openTurn(root, { kind: 'user' })
     const invalidCreate = await execute(ctx, 'create_goal', { objective: ' ' }, root.agent)
-    expect(invalidCreate.error?.code).toBe('GOAL_INVALID_OBJECTIVE')
+    expect(invalidCreate.error?.info?.code).toBe('GOAL_INVALID_OBJECTIVE')
     const created = ctx.goals.create(root.agent, { objective: 'valid' })
     const replacement = await execute(ctx, 'update_goal', {
       goal_id: created.id,
@@ -386,26 +403,26 @@ describe('goal tool state transitions', () => {
       action: 'pause',
       objective: 'not valid for pause',
     }, root.agent)
-    expect(replacement.error?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
+    expect(replacement.error?.info?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
     const terminalUpdate = await execute(ctx, 'update_goal', {
       goal_id: created.id,
       revision: created.revision,
       action: 'complete',
       max_goal_rounds: 2,
     }, root.agent)
-    expect(terminalUpdate.error?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
+    expect(terminalUpdate.error?.info?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
     const blockedWithoutReason = await execute(ctx, 'update_goal', {
       goal_id: created.id, revision: created.revision, action: 'blocked',
     }, root.agent)
-    expect(blockedWithoutReason.error?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
+    expect(blockedWithoutReason.error?.info?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
     const blockedWithEmptyReason = await execute(ctx, 'update_goal', {
       goal_id: created.id, revision: created.revision, action: 'blocked', blocked_reason: ' ',
     }, root.agent)
-    expect(blockedWithEmptyReason.error?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
+    expect(blockedWithEmptyReason.error?.info?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
     const completeWithReason = await execute(ctx, 'update_goal', {
       goal_id: created.id, revision: created.revision, action: 'complete', blocked_reason: 'Not a blocker.',
     }, root.agent)
-    expect(completeWithReason.error?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
+    expect(completeWithReason.error?.info?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
     const editWithReason = await execute(ctx, 'update_goal', {
       goal_id: created.id,
       revision: created.revision,
@@ -413,11 +430,82 @@ describe('goal tool state transitions', () => {
       objective: 'still valid',
       blocked_reason: 'Not valid for edit.',
     }, root.agent)
-    expect(editWithReason.error?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
+    expect(editWithReason.error?.info?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
     const malformedRef = await execute(ctx, 'update_goal', {
       goal_id: '', revision: 0, action: 'edit', objective: 'x',
     }, root.agent)
-    expect(malformedRef.error?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
+    expect(malformedRef.error?.info?.code).toBe('GOAL_TOOL_INVALID_UPDATE')
+  })
+
+  it('accepts only empty fillers in fields unused by the selected action', async () => {
+    const { ctx, root } = await harness()
+    openTurn(root, { kind: 'user' })
+    let goal = ctx.goals.create(root.agent, { objective: 'valid' })
+
+    const edited = await execute(ctx, 'update_goal', {
+      goal_id: goal.id,
+      revision: goal.revision,
+      action: 'edit',
+      objective: 'edited',
+      max_goal_rounds: 0,
+      blocked_reason: '',
+    }, root.agent)
+    expect(resultGoal(edited)).toMatchObject({ objective: 'edited' })
+    goal = ctx.goals.get(root.agent)!
+
+    const capped = await execute(ctx, 'update_goal', {
+      goal_id: goal.id,
+      revision: goal.revision,
+      action: 'edit',
+      objective: '',
+      max_goal_rounds: 8,
+      blocked_reason: '',
+    }, root.agent)
+    expect(resultGoal(capped)).toMatchObject({ objective: 'edited', maxGoalRounds: 8 })
+    goal = ctx.goals.get(root.agent)!
+
+    const paused = await execute(ctx, 'update_goal', {
+      goal_id: goal.id,
+      revision: goal.revision,
+      action: 'pause',
+      objective: '',
+      max_goal_rounds: 0,
+      blocked_reason: '',
+    }, root.agent)
+    expect(resultGoal(paused)).toMatchObject({ phase: 'paused', objective: 'edited' })
+    goal = ctx.goals.get(root.agent)!
+
+    const resumed = await execute(ctx, 'update_goal', {
+      goal_id: goal.id,
+      revision: goal.revision,
+      action: 'resume',
+      objective: '',
+      max_goal_rounds: 0,
+      blocked_reason: '',
+    }, root.agent)
+    expect(resultGoal(resumed)).toMatchObject({ phase: 'active', objective: 'edited' })
+    goal = ctx.goals.get(root.agent)!
+
+    const blocked = await execute(ctx, 'update_goal', {
+      goal_id: goal.id,
+      revision: goal.revision,
+      action: 'blocked',
+      objective: '',
+      max_goal_rounds: 0,
+      blocked_reason: 'actual blocker',
+    }, root.agent)
+    expect(resultGoal(blocked)).toMatchObject({ phase: 'blocked' })
+    goal = ctx.goals.resume(root.agent, { id: goal.id, revision: goal.revision + 1 })
+
+    const complete = await execute(ctx, 'update_goal', {
+      goal_id: goal.id,
+      revision: goal.revision,
+      action: 'complete',
+      objective: '',
+      max_goal_rounds: 0,
+      blocked_reason: '',
+    }, root.agent)
+    expect(resultGoal(complete)).toMatchObject({ phase: 'complete', objective: 'edited' })
   })
 
   it('allows exact goal rounds to complete but not edit or pause', async () => {
@@ -429,7 +517,7 @@ describe('goal tool state transitions', () => {
     const edit = await execute(ctx, 'update_goal', {
       goal_id: created.id, revision: created.revision, action: 'edit', objective: 'forbidden',
     }, root.agent)
-    expect(edit.error?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
+    expect(edit.error?.info?.code).toBe('GOAL_TOOL_AUTHORITY_REQUIRED')
     const complete = await execute(ctx, 'update_goal', {
       goal_id: created.id, revision: created.revision, action: 'complete',
     }, root.agent)
@@ -451,7 +539,7 @@ describe('goal tool state transitions', () => {
         action: 'blocked',
         blocked_reason: 'The required credential is still unavailable.',
       }, root.agent)
-      expect(result.error?.code).toBe('GOAL_TOOL_BLOCK_THRESHOLD')
+      expect(result.error?.info?.code).toBe('GOAL_TOOL_BLOCK_THRESHOLD')
       closeTurn(root, turn)
     }
     openTurn(root, { kind: 'goal', goalId: ref.id, revision: ref.revision, round: 3 })
diff --git a/packages/guard/README.md b/packages/guard/README.md
index 05c9625cb0..e7066ba434 100644
--- a/packages/guard/README.md
+++ b/packages/guard/README.md
@@ -6,4 +6,4 @@ Behavioral guard plugins that watch the agent loop for unproductive patterns and
 |---|---|---|
 | `repeat-tool-guard/` | Advisory reminders when an agent loops on identical tool calls | (listens on `ctx.tools`' waterfalls) |
 
-Reminders travel as `additionalContexts` on the `tools/post-execute` decision; the agent loop appends them as logged `context/message` events after the step's tool results (see [the tools package](../core/tools)), so everything a guard says to the model is reconstructable from the session log.
+Reminders travel as `additionalContexts` on the `tools/post-execute` decision; the agent loop appends them as logged plugin-sourced `user/message` events after the step's tool results (see [the tools package](../core/tools)), so everything a guard says to the model is reconstructable from the session log.
diff --git a/packages/guard/repeat-tool-guard/README.md b/packages/guard/repeat-tool-guard/README.md
index ef5e4e5846..e7bd79732e 100644
--- a/packages/guard/repeat-tool-guard/README.md
+++ b/packages/guard/repeat-tool-guard/README.md
@@ -30,11 +30,11 @@ The chain key is `(tool name, canonical arguments)` — canonicalization is a de
 
 ## Reminder delivery
 
-Reminders ride the post-execute decision's `additionalContexts` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit. The loop buffers the context and appends it as a `context/message` after the step's tool results, which the session renders as a plain synthetic user message — so the reminder is model-visible, source-attributed, and reconstructable from the session log with no new session event. The guard always delegates via `next()` and prepends its reminder to the downstream decision's context array (both variants — a blocked call still gets the nudge); every entry retains its own source and metadata.
+Reminders ride the post-execute decision's `additionalContexts` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit. The loop buffers the context and appends it as an injected `user/message` after the step's tool results, which the session renders as a plain synthetic user message — so the reminder is model-visible, source-attributed, and reconstructable from the session log with no new session event. The guard always delegates via `next()` and prepends its reminder to the downstream decision's context array (both variants — a blocked call still gets the nudge); every entry retains its own source and metadata.
 
 ## Testing
 
-Unit suites drive a real agent loop against a mock adapter (no network) and cover the chain semantics above to per-file 100%. The snapshot tier owns the transcript surface: a scripted-replay scenario repeats a call five times and pins both reminder tiers (gentle at 3, detailed at 5) as `context/message`s in the ACP transcript.
+Unit suites drive a real agent loop against a mock adapter (no network) and cover the chain semantics above to per-file 100%. The snapshot tier owns the transcript surface: a scripted-replay scenario repeats a call five times and pins both reminder tiers (gentle at 3, detailed at 5) as injected `user/message`s in the ACP transcript.
 
 ## Model Experience
 
diff --git a/packages/guard/repeat-tool-guard/src/index.ts b/packages/guard/repeat-tool-guard/src/index.ts
index 2265c583d5..47eaadbfdb 100644
--- a/packages/guard/repeat-tool-guard/src/index.ts
+++ b/packages/guard/repeat-tool-guard/src/index.ts
@@ -213,8 +213,7 @@ export function apply(ctx: Context, config: Config): void {
       return { kind: 'block', feedback: downstream.feedback, additionalContexts: prependContext(reminder, downstream.additionalContexts) }
     }
     return {
-      kind: 'accept',
-      ...downstream.content !== undefined ? { content: downstream.content } : {},
+      ...downstream,
       additionalContexts: prependContext(reminder, downstream.additionalContexts),
     }
   })
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 b3c90021a5..d0a3214518 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
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -26,8 +26,8 @@ async function harness(config: Config = {}): Promise<Context> {
   await mountAgentLoopTestDependencies(ctx)
   await ctx.plugin(AgentLoop, { agents: [] })
   await ctx.plugin(RepeatToolGuard, config)
-  ctx.tools.register(defineTool({ name: 'probe', description: 'p', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-  ctx.tools.register(defineTool({ name: 'other', description: 'o', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+  ctx.tools.register(defineContentToolFixture({ name: 'probe', description: 'p', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+  ctx.tools.register(defineContentToolFixture({ name: 'other', description: 'o', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
   return ctx
 }
 
@@ -35,10 +35,10 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => { const d = ctx.on('agent/status', (s, st) => { if (s === agent && st === 'idle') { d(); resolve() } }) })
 }
 
-/** Every `context/message` in the agent's log, flattened to joined text + source for terse assertions. */
+/** Every injected-context user message in the agent's log, flattened to joined text + source for terse assertions. */
 function reminders(agent: Agent): { text: string; source: unknown }[] {
   return [...agent.session.events]
-    .filter((e): e is SessionEvent<'context/message'> => e.type === 'context/message')
+    .filter((e): e is SessionEvent<'user/message'> => e.type === 'user/message' && e.data.source.kind !== 'user')
     .map(e => ({
       text: e.data.content.map(block => block.type === 'text' ? block.text : '').join('|'),
       source: e.data.source,
@@ -56,7 +56,7 @@ describe('threshold escalation', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const found = reminders(agent)
@@ -77,7 +77,7 @@ describe('threshold escalation', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const found = reminders(agent)
@@ -99,7 +99,7 @@ describe('chain semantics', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const found = reminders(agent)
@@ -123,7 +123,7 @@ describe('chain semantics', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(reminders(agent)).toHaveLength(1)
@@ -141,7 +141,7 @@ describe('chain semantics', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const found = reminders(agent)
@@ -162,7 +162,7 @@ describe('chain semantics', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const found = reminders(agent)
@@ -178,7 +178,7 @@ describe('chain semantics', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(reminders(agent)).toHaveLength(1) // probe was NOT excluded
@@ -194,7 +194,7 @@ describe('chain semantics', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(reminders(agent)).toHaveLength(1) // all three canonicalize identically
@@ -215,8 +215,8 @@ describe('chain semantics', () => {
     ]))
     const agentA = ctx.agentLoop.create(SessionId('a'), { provider: 'mock-a', model: 'model-a' })
     const agentB = ctx.agentLoop.create(SessionId('b'), { provider: 'mock-b', model: 'model-b' })
-    agentA.send([{ type: 'text', text: 'go' }])
-    agentB.send([{ type: 'text', text: 'go' }])
+    agentA.followup([{ type: 'text', text: 'go' }])
+    agentB.followup([{ type: 'text', text: 'go' }])
     await Promise.all([waitForIdle(ctx, agentA), waitForIdle(ctx, agentB)])
 
     expect(reminders(agentA)).toHaveLength(0) // 2 repeats < 3, despite B's 3 in the same registry
@@ -234,9 +234,9 @@ describe('chain semantics', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
-    agent.send([{ type: 'text', text: 'again' }])
+    agent.followup([{ type: 'text', text: 'again' }])
     await waitForIdle(ctx, agent)
 
     expect(reminders(agent)).toHaveLength(0)
@@ -256,13 +256,13 @@ describe('chain semantics', () => {
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
       first = inner.agentLoop.create(SessionId('reused'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
-    first.send([{ type: 'text', text: 'go' }])
+    first.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, first)
     await fiber.dispose()
     await first.whenIdle()
 
     const second = ctx.agentLoop.create(SessionId('reused'), { provider: 'mock', model: 'mock' })
-    second.send([{ type: 'text', text: 'go' }])
+    second.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, second)
 
     expect(reminders(second)).toHaveLength(0)
@@ -278,7 +278,7 @@ describe('chain semantics', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(reminders(agent)).toHaveLength(1)
@@ -294,7 +294,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ]))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(reminders(agent)).toHaveLength(0)
@@ -316,7 +316,7 @@ describe('fold onto the downstream decision', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const found = reminders(agent)
@@ -334,11 +334,11 @@ describe('fold onto the downstream decision', () => {
     expect(results[1]!.data.content).toEqual([{ type: 'text', text: 'nope' }])
   })
 
-  it('preserves a downstream accept content replacement while folding', async () => {
+  it('preserves a downstream canonical value replacement while folding', async () => {
     const ctx = await harness({ thresholds: [2] })
     ctx.on('tools/post-execute', async () => ({
       kind: 'accept' as const,
-      content: [{ type: 'text' as const, text: 'replaced' }],
+      value: [{ type: 'text' as const, text: 'replaced' }],
     }))
     const adapter = new MockAdapter([
       toolCallResponse('c1', 'probe', { q: 1 }),
@@ -347,7 +347,7 @@ describe('fold onto the downstream decision', () => {
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const found = reminders(agent)
diff --git a/packages/hooks/hook-protocol/README.md b/packages/hooks/hook-protocol/README.md
index 42a642caf0..3a84807285 100644
--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -27,7 +27,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).
 
-Like every event they must sit inside an open turn. The mid-turn points (`PreToolUse`/`PostToolUse`/`UserPromptSubmit`/`Stop`) fire inside the loop's open turn by construction; `SessionStart` gets no `hook/*` record (its injected `context/message` is the durable evidence) — see the hooks Agent Note.
+Like every event they must sit inside an open turn. The mid-turn points (`PreToolUse`/`PostToolUse`/`UserPromptSubmit`/`Stop`) fire inside the loop's open turn by construction; `SessionStart` gets no `hook/*` record (its injected `user/message` is the durable evidence) — see the hooks Agent Note.
 
 ## Model Experience
 
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index 5a5d33427d..3595d9445c 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -253,8 +253,7 @@ export function apply(ctx: Context, config: Config): void {
       return { ...downstream, additionalContexts: prependContext(context, downstream.additionalContexts) }
     }
     return {
-      kind: 'accept',
-      ...downstream.content !== undefined ? { content: downstream.content } : {},
+      ...downstream,
       additionalContexts: prependContext(context, downstream.additionalContexts),
     }
   })
diff --git a/packages/hooks/hooks-claude/tests/bridge.spec.ts b/packages/hooks/hooks-claude/tests/bridge.spec.ts
index 953b4befd0..f5fd5702d5 100644
--- a/packages/hooks/hooks-claude/tests/bridge.spec.ts
+++ b/packages/hooks/hooks-claude/tests/bridge.spec.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { Context, type Fiber } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -97,7 +97,7 @@ describe('hooks-claude bridge — UserPromptSubmit', () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(dir, adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'do something' }])
+    agent.followup([{ type: 'text', text: 'do something' }])
     await waitForIdle(ctx, agent)
 
     // The prompt was blocked: model never called, turn ended rejected.
@@ -120,13 +120,13 @@ describe('hooks-claude bridge — UserPromptSubmit', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(dir, adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     // The injected context reached the model and is recorded with the plugin source.
     expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('remember: be brief')
-    const ctxMsg = events(agent).find(e => e.type === 'context/message')
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'hooks-claude' })
+    const ctxMsg = events(agent).find(e => e.type === 'user/message' && e.data.source.kind !== 'user')
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'hooks-claude' })
   })
 })
 
@@ -143,9 +143,9 @@ describe('hooks-claude bridge — PreToolUse', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'danger', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
     let ran = false
-    ctx.tools.register(defineTool({ name: 'danger', description: 'd', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] } }))
+    ctx.tools.register(defineContentToolFixture({ name: 'danger', description: 'd', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] } }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'use danger' }])
+    agent.followup([{ type: 'text', text: 'use danger' }])
     await waitForIdle(ctx, agent)
 
     expect(ran).toBe(false)
@@ -166,9 +166,9 @@ describe('hooks-claude bridge — PreToolUse', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'safe', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
     let ran = false
-    ctx.tools.register(defineTool({ name: 'safe', description: 's', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ran ok' }] } }))
+    ctx.tools.register(defineContentToolFixture({ name: 'safe', description: 's', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ran ok' }] } }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'use safe' }])
+    agent.followup([{ type: 'text', text: 'use safe' }])
     await waitForIdle(ctx, agent)
 
     expect(ran).toBe(true)
@@ -188,9 +188,9 @@ describe('hooks-claude bridge — PostToolUse', () => {
 
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
-    ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'raw output' }] } }))
+    ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'raw output' }] } }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const result = events(agent).find(e => e.type === 'tool/result')
@@ -209,17 +209,17 @@ describe('hooks-claude bridge — PostToolUse', () => {
 
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
-    ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     const log = events(agent)
     const resultIdx = log.findIndex(e => e.type === 'tool/result')
-    const ctxIdx = log.findIndex(e => e.type === 'context/message')
+    const ctxIdx = log.findIndex(e => e.type === 'user/message' && e.data.source.kind !== 'user')
     expect(ctxIdx).toBeGreaterThan(resultIdx) // context appended AFTER the tool result
     const ctxMsg = log[ctxIdx]
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.content.some(b => b.type === 'text' && b.text.includes('tool was slow'))).toBe(true)
+    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 () => {
@@ -233,9 +233,9 @@ describe('hooks-claude bridge — PostToolUse', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
     let ran = false
-    ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
+    ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     // `ask` degrades to deny today (FIXME permissions): the tool does not run and the result is isError.
@@ -262,9 +262,9 @@ describe('hooks-claude bridge — SessionStart', () => {
     // session-start fires async (detached .then → agent.inject); wait for the
     // injected context/message to actually land before sending, rather than a
     // fixed sleep that flakes under load.
-    await waitFor(() => events(agent).some(e => e.type === 'context/message'
+    await waitFor(() => events(agent).some(e => e.type === 'user/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('project uses tabs'))))
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('project uses tabs')
@@ -357,7 +357,7 @@ describe('hooks-claude bridge — load resilience', () => {
     await ctx.plugin(HooksClaude, { configPath: '/nonexistent/hooks.json' })
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     // The turn ran normally — no hooks, no crash.
     expect(adapter.requests).toHaveLength(1)
@@ -379,7 +379,7 @@ describe('hooks-claude bridge — load resilience', () => {
     await fiber.dispose()
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1) // not blocked → the listener is gone
     expect(events(agent).some(e => e.type === 'hook/invoked')).toBe(false) // no hook ran
diff --git a/packages/hooks/hooks-claude/tests/coverage-cases.ts b/packages/hooks/hooks-claude/tests/coverage-cases.ts
index e303c589be..ab770479ed 100644
--- a/packages/hooks/hooks-claude/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-claude/tests/coverage-cases.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { Context } from 'cordis'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -72,9 +72,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
         const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'capture.sh', `#!/usr/bin/env bash\ncat > "${cap}"\n`) }] }] })
         const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
         const ctx = await harness(path, adapter, { ...sessionRoot !== undefined ? { sessionRoot } : {} })
-        ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+        ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
         const agent = ctx.agentLoop.create(SessionId('transcript'), { provider: 'mock', model: 'mock' })
-        agent.send([{ type: 'text', text: 'go' }])
+        agent.followup([{ type: 'text', text: 'go' }])
         await waitForIdle(ctx, agent)
         return {
           payload: JSON.parse(readFileSync(cap, 'utf8')) as { transcript_path: string },
@@ -102,9 +102,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter, { pluginRoot: d, projectDir: d })
       ctx.logger.warn = warn as never
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true) // substituted command ran
     })
@@ -118,9 +118,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       ctx.logger.warn = warn as never
       let sawArgs: unknown
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: { command: { type: 'string' } }, async execute(args) { sawArgs = args; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: { command: { type: 'string' } }, async execute(args) { sawArgs = args; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // updatedInput is NOT honored — the tool ran with the ORIGINAL args.
       expect((sawArgs as { command?: string }).command).toBe('original')
@@ -136,11 +136,11 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([textResponse('ran')])
       const ctx = await harness(path, adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
-      // The prompt proceeded unchanged; no context/message injected.
+      // The prompt proceeded unchanged; no injected context.
       expect(adapter.requests).toHaveLength(1)
-      expect(events(agent).some(e => e.type === 'context/message')).toBe(false)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user')).toBe(false)
     })
 
     it('a PreToolUse hook fires for a no-agent direct tool call (no session/turn to record into)', async () => {
@@ -149,7 +149,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const ctx = await harness(path, new MockAdapter([]))
       let ran = false
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
       // Call execute() directly with NO agent — the bridge's no-agent/no-turn path.
       const { CallId } = await import('@deepseek-ai/dsh-llm')
       const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'echo', arguments: {} })
@@ -164,9 +164,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.stderrSummary?.endsWith('…')).toBe(true)
@@ -189,9 +189,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter, { stderrSummaryMaxChars: 40 })
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.stderrSummary).toBe('x'.repeat(40) + '…')
@@ -207,7 +207,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(path, adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(2)
       expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('continue please')
@@ -223,7 +223,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(path, adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // A second model request ran → the empty-reason block forced continuation.
       expect(adapter.requests).toHaveLength(2)
@@ -269,9 +269,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'x' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'x' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text.includes('blocked by PreToolUse hook'))).toBe(true)
@@ -283,9 +283,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text.includes('blocked by PostToolUse hook'))).toBe(true)
@@ -314,7 +314,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([textResponse('no')])
       const ctx = await harness(path, adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const turnEnd = events(agent).findLast(e => e.type === 'turn/end')
       expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'rejected' && turnEnd.data.reason.reason).toContain('blocked by UserPromptSubmit hook')
@@ -327,9 +327,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // ask (no reason) → degrades to deny with the registry's generic message.
       expect(ran).toBe(false)
@@ -342,9 +342,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.exitCode).toBe(0)
@@ -369,7 +369,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       HooksClaude.apply(ctx, { configPath: join(d, 'hooks.json') })
       ctx.llm.registerAdapter(['mock'], adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true)
     })
@@ -382,9 +382,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -397,9 +397,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.isError).toBe(true)
@@ -416,9 +416,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.decision).toBe('stop') // recorded
@@ -433,15 +433,15 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.isError).toBe(true)
       expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text.includes('bad'))).toBe(true)
       // additionalContext also injected (the block + context arm).
-      expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('context too')))).toBe(true)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('context too')))).toBe(true)
     })
 
     it('a PreToolUse hook whose hookSpecificOutput names a DIFFERENT event does NOT deny the tool', async () => {
@@ -453,9 +453,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // the mismatched deny was discarded → the tool ran
     })
@@ -473,9 +473,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       // The factory create() path honors meta.cwd (the plain agentLoop.create() does not).
       const { SessionId } = await import('@deepseek-ai/dsh-session')
       const handle = await ctx.agents.create({ sessionId: SessionId('s1'), meta: { cwd: workspace }, agentOptions: { provider: 'mock', model: 'mock' } })
-      handle.agent.send([{ type: 'text', text: 'go' }])
+      handle.agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, handle.agent)
-      expect(events(handle.agent).some(e => e.type === 'context/message'
+      expect(events(handle.agent).some(e => e.type === 'user/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes(`dir=${workspace}`)))).toBe(true)
       await handle.dispose()
     })
@@ -491,12 +491,12 @@ export function defineCoverageCases(group: CoverageGroup): void {
       // A later listener that blocks every prompt (registered AFTER the bridge).
       ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy veto' }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // the downstream block won: the model was never called, no user/message was
       // recorded, and the (sole, fully-blocked) prompt closed the turn `rejected`
       expect(adapter.requests).toHaveLength(0)
-      expect(events(agent).some(e => e.type === 'user/message')).toBe(false)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user')).toBe(false)
       const turnEnd = events(agent).findLast(e => e.type === 'turn/end')
       expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toMatchObject({ kind: 'rejected', reason: 'policy veto' })
     })
@@ -519,7 +519,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
         }],
       }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const req = JSON.stringify(adapter.requests[0]!.messages)
       expect(req).toContain('from-bridge')
@@ -528,30 +528,30 @@ export function defineCoverageCases(group: CoverageGroup): void {
       // the original prompt was replaced by the downstream rewrite
       const userMsg = events(agent).find(e => e.type === 'user/message')
       expect(userMsg?.type === 'user/message' && userMsg.data.content.some(b => b.type === 'text' && b.text === 'rewritten-prompt')).toBe(true)
-      const contexts = events(agent).filter(event => event.type === 'context/message')
-      expect(contexts.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      const contexts = events(agent).filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
+      expect(contexts.map(event => event.type === 'user/message' && event.data.source)).toEqual([
         { kind: 'plugin', plugin: 'hooks-claude' },
         { kind: 'plugin', plugin: 'policy' },
       ])
-      expect(contexts[1]?.type === 'context/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
+      expect(contexts[1]?.type === 'user/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
     })
 
-    it('folds the bridge PostToolUse context onto a downstream ACCEPT that replaces content', async () => {
+    it('folds the bridge PostToolUse context onto a downstream canonical value replacement', async () => {
     // The bridge hook adds context; a later post-execute listener accepts with a
-    // content rewrite. Both the rewrite and the bridge context survive.
+    // canonical replacement. Both the replacement and the bridge context survive.
       const d = dir()
       const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n')
       const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, content: [{ type: 'text' as const, text: 'rewritten-result' }] }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, value: [{ type: 'text' as const, text: 'rewritten-result' }] }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text === 'rewritten-result')).toBe(true)
-      expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
     })
 
     it('keeps bridge and downstream PostToolUse contexts as separate sourced events', async () => {
@@ -560,7 +560,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({
         kind: 'accept' as const,
         additionalContexts: [{
@@ -570,15 +570,15 @@ export function defineCoverageCases(group: CoverageGroup): void {
         }],
       }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
 
-      const contexts = events(agent).filter(event => event.type === 'context/message')
-      expect(contexts.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      const contexts = events(agent).filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
+      expect(contexts.map(event => event.type === 'user/message' && event.data.source)).toEqual([
         { kind: 'plugin', plugin: 'hooks-claude' },
         { kind: 'plugin', plugin: 'policy' },
       ])
-      expect(contexts[1]?.type === 'context/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
+      expect(contexts[1]?.type === 'user/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
     })
 
     it('folds the bridge PostToolUse context onto a downstream listener BLOCK', async () => {
@@ -590,16 +590,16 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'block' as const, feedback: [{ type: 'text' as const, text: 'downstream-block' }] }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.isError).toBe(true)
       expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text.includes('downstream-block'))).toBe(true)
       // the bridge's context still landed (folded onto the block)
-      expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
     })
 
   })
@@ -615,9 +615,9 @@ export function defineCoverageCases(group: CoverageGroup): void {
       // yields a HookOutput with exitCode undefined → the `exitCode` spread false arm.
       const bash = ctx.bash
       bash.run = (() => Promise.reject(new Error('executor down')))
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && 'exitCode' in res.data).toBe(false)
@@ -640,7 +640,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       await waitFor(() => threw)
       expect(threw).toBe(true)
       agent.inject = original
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(1) // loop survived the thrown inject
     })
@@ -663,11 +663,11 @@ export function defineCoverageCases(group: CoverageGroup): void {
       await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, cwd: serverDir })
       await ctx.plugin(HooksClaude, { configPath: join(serverDir, 'hooks.json') })
       ctx.llm.registerAdapter(['mock'], adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
 
       const { SessionId } = await import('@deepseek-ai/dsh-session')
       const handle = await ctx.agents.create({ sessionId: SessionId('s1'), meta: { cwd: sessionDir }, agentOptions: { provider: 'mock', model: 'mock' } })
-      handle.agent.send([{ type: 'text', text: 'go' }])
+      handle.agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, handle.agent)
 
       expect(existsSync(marker)).toBe(true) // the marker landed in the SESSION dir
@@ -717,7 +717,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       const warn = vi.fn(); ctx.logger.warn = warn as never
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('systemMessage'))
       // Not surfaced: the systemMessage text never reaches the model request.
@@ -736,7 +736,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       // Send immediately — do NOT wait for the session-start inject.
-      agent.send([{ type: 'text', text: 'go' }])
+      agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(1) // the turn ran regardless of hook timing
     })
diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts
index 7d05950957..c2ec2613d5 100644
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -231,8 +231,7 @@ export function apply(ctx: Context, config: Config): void {
       return { ...downstream, additionalContexts: prependContext(context, downstream.additionalContexts) }
     }
     return {
-      kind: 'accept',
-      ...downstream.content !== undefined ? { content: downstream.content } : {},
+      ...downstream,
       additionalContexts: prependContext(context, downstream.additionalContexts),
     }
   })
diff --git a/packages/hooks/hooks-codex/tests/bridge.spec.ts b/packages/hooks/hooks-codex/tests/bridge.spec.ts
index 684650104a..923a4bf8b5 100644
--- a/packages/hooks/hooks-codex/tests/bridge.spec.ts
+++ b/packages/hooks/hooks-codex/tests/bridge.spec.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -75,9 +75,9 @@ describe('hooks-codex bridge', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
     const ctx = await harness(dir, adapter)
     let ran = false
-    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'no' }] } }))
+    ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'no' }] } }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'run ls' }])
+    agent.followup([{ type: 'text', text: 'run ls' }])
     await waitForIdle(ctx, agent)
 
     expect(ran).toBe(false)
@@ -98,7 +98,7 @@ describe('hooks-codex bridge', () => {
     const adapter = new MockAdapter([textResponse('first answer'), textResponse('second answer after goal')])
     const ctx = await harness(dir, adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(adapter.requests).toHaveLength(2)
@@ -115,7 +115,7 @@ describe('hooks-codex bridge', () => {
     const adapter = new MockAdapter([textResponse('must not run')])
     const ctx = await harness(dir, adapter)
     const agent = ctx.agentLoop.create(SessionId('cancel-prompt-hook'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'cancel the hook' }])
+    agent.followup([{ type: 'text', text: 'cancel the hook' }])
     await waitFor(() => existsSync(marker))
     const pid = Number(readFileSync(pidFile, 'utf8').trim())
 
@@ -139,7 +139,7 @@ describe('hooks-codex bridge', () => {
     const adapter = new MockAdapter([textResponse('fine')])
     const ctx = await harness(dir, adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1)
   })
@@ -149,7 +149,7 @@ describe('hooks-codex bridge', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(dir, adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1)
   })
@@ -169,7 +169,7 @@ describe('hooks-codex bridge', () => {
     await fiber.dispose()
     ctx.llm.registerAdapter(['mock'], adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1) // not blocked → the listener is gone
     expect(events(agent).some(e => e.type === 'hook/invoked')).toBe(false) // no hook ran
diff --git a/packages/hooks/hooks-codex/tests/coverage-cases.ts b/packages/hooks/hooks-codex/tests/coverage-cases.ts
index d0f0df92f6..ebb2164902 100644
--- a/packages/hooks/hooks-codex/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-codex/tests/coverage-cases.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { Context } from 'cordis'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -63,9 +63,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
         const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'capture.sh', `#!/usr/bin/env bash\ncat > "${cap}"\n`) }] }] })
         const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
         const ctx = await harness(path, adapter, { ...sessionRoot !== undefined ? { sessionRoot } : {} })
-        ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+        ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
         const agent = ctx.agentLoop.create(SessionId('transcript'), { provider: 'mock', model: 'mock' })
-        agent.send([{ type: 'text', text: 'go' }])
+        agent.followup([{ type: 'text', text: 'go' }])
         await waitForIdle(ctx, agent)
         return {
           payload: JSON.parse(readFileSync(cap, 'utf8')) as { transcript_path: string | null },
@@ -84,7 +84,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('no')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(0)
       const te = events(agent).findLast(e => e.type === 'turn/end')
       expect(te?.type === 'turn/end' && te.data.reason.kind).toBe('rejected')
@@ -96,7 +96,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('ctx-x')
     })
 
@@ -109,7 +109,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy veto' }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(0)
       expect(events(agent).some(e => e.type === 'user/message')).toBe(false)
       const te = events(agent).findLast(e => e.type === 'turn/end')
@@ -131,33 +131,33 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
         }],
       }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const req = JSON.stringify(adapter.requests[0]!.messages)
       expect(req).toContain('from-bridge')
       expect(req).toContain('from-downstream')
       expect(req).toContain('rewritten-prompt')
-      const contexts = events(agent).filter(event => event.type === 'context/message')
-      expect(contexts.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      const contexts = events(agent).filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
+      expect(contexts.map(event => event.type === 'user/message' && event.data.source)).toEqual([
         { kind: 'plugin', plugin: 'hooks-codex' },
         { kind: 'plugin', plugin: 'policy' },
       ])
-      expect(contexts[1]?.type === 'context/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
+      expect(contexts[1]?.type === 'user/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
     })
   })
 
   if (selected.has('post-tool')) describe('hooks-codex coverage — post-tool and session context mapping', () => {
-    it('folds the bridge PostToolUse context onto a downstream ACCEPT that replaces content', async () => {
+    it('folds the bridge PostToolUse context onto a downstream canonical value replacement', async () => {
       const d = dir()
       hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, content: [{ type: 'text' as const, text: 'rewritten-result' }] }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, value: [{ type: 'text' as const, text: 'rewritten-result' }] }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text === 'rewritten-result')).toBe(true)
-      expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
     })
 
     it('keeps bridge and downstream PostToolUse contexts as separate sourced events', async () => {
@@ -165,7 +165,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({
         kind: 'accept' as const,
         additionalContexts: [{
@@ -175,14 +175,14 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
         }],
       }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
 
-      const contexts = events(agent).filter(event => event.type === 'context/message')
-      expect(contexts.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      const contexts = events(agent).filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
+      expect(contexts.map(event => event.type === 'user/message' && event.data.source)).toEqual([
         { kind: 'plugin', plugin: 'hooks-codex' },
         { kind: 'plugin', plugin: 'policy' },
       ])
-      expect(contexts[1]?.type === 'context/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
+      expect(contexts[1]?.type === 'user/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
     })
 
     it('folds the bridge PostToolUse context onto a downstream listener BLOCK', async () => {
@@ -190,14 +190,14 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'block' as const, feedback: [{ type: 'text' as const, text: 'downstream-block' }] }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.isError).toBe(true)
       expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text.includes('downstream-block'))).toBe(true)
-      expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
     })
 
     it('SessionStart additionalContext is injected for the first request', async () => {
@@ -206,9 +206,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      await waitFor(() => events(agent).some(e => e.type === 'context/message'
+      await waitFor(() => events(agent).some(e => e.type === 'user/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('start-ctx'))))
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('start-ctx')
     })
 
@@ -217,9 +217,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'p.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.isError).toBe(true)
       expect(r?.type === 'tool/result' && r.data.content.some(b => b.type === 'text' && b.text.includes('blocked by PostToolUse hook'))).toBe(true)
@@ -230,10 +230,10 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"post-ctx"}}\'\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
-      expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('post-ctx')))).toBe(true)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('post-ctx')))).toBe(true)
     })
   })
 
@@ -244,9 +244,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', {}), textResponse('done')]) // no command arg
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // clean-exit hook allows; commandOf returned ''
     })
 
@@ -255,9 +255,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'n.sh', '#!/usr/bin/env bash\nexit 0\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.exitCode).toBe(0)
       expect(res?.type === 'hook/result' && 'stderrSummary' in res.data).toBe(false)
@@ -268,9 +268,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'l.sh', '#!/usr/bin/env bash\nprintf "x%.0s" {1..600} >&2\nexit 2\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.stderrSummary?.endsWith('…')).toBe(true)
       expect(res?.type === 'hook/result' && res.data.stderrSummary?.length).toBe(501) // default 500-char cap + ellipsis
@@ -291,9 +291,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'l.sh', '#!/usr/bin/env bash\nprintf "x%.0s" {1..600} >&2\nexit 2\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter, { stderrSummaryMaxChars: 40 })
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.stderrSummary).toBe('x'.repeat(40) + '…')
     })
@@ -316,7 +316,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       HooksCodex.apply(ctx, { configPath: join(d, 'hooks.json') })
       ctx.llm.registerAdapter(['mock'], adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('async hook'))
     })
@@ -327,9 +327,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
     })
 
@@ -344,8 +344,8 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => existsSync(marker)) // the clean no-output hook has finished
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
-      expect(events(agent).some(e => e.type === 'context/message')).toBe(false)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user')).toBe(false)
     })
 
     it('a throwing SessionStart inject is contained (logged)', async () => {
@@ -368,9 +368,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
     })
 
@@ -381,9 +381,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // matcher didn't match → no hook ran → tool proceeded
       expect(events(agent).some(e => e.type === 'hook/invoked')).toBe(false)
     })
@@ -397,9 +397,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.decision).toBe('stop') // recorded
       expect(ran).toBe(true) // NOT honored: the tool still ran (halt is deferred)
@@ -410,9 +410,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'd.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.content.some(b => b.type === 'text' && b.text.includes('blocked by PreToolUse hook'))).toBe(true)
     })
@@ -422,13 +422,13 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'bc.sh', '#!/usr/bin/env bash\necho \'{"decision":"block","reason":"bad","hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"ctx too"}}\'\n') }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.isError).toBe(true)
       expect(r?.type === 'tool/result' && r.data.content.some(b => b.type === 'text' && b.text.includes('bad'))).toBe(true)
-      expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('ctx too')))).toBe(true)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('ctx too')))).toBe(true)
     })
 
     it('commandOf reads a non-string command arg as an empty command', async () => {
@@ -439,9 +439,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'cap.sh', `#!/usr/bin/env bash\ncat > "${cap}"\nexit 0\n`) }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 7 }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'number' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'number' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const payload = JSON.parse(readFileSync(cap, 'utf8')) as { tool_input: { command: string } }
       expect(payload.tool_input.command).toBe('')
     })
@@ -451,7 +451,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'd.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
       const ctx = await harness(join(d, 'hooks.json'), new MockAdapter([]))
       let ran = false
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
       const { CallId } = await import('@deepseek-ai/dsh-llm')
       const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'Bash', arguments: { command: 'x' } })
       expect(ran).toBe(false) // denied
@@ -462,7 +462,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const d = dir()
       hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"x"}}\'\n') }] }] })
       const ctx = await harness(join(d, 'hooks.json'), new MockAdapter([]))
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const { CallId } = await import('@deepseek-ai/dsh-llm')
       const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'Bash', arguments: { command: 'x' } })
       expect(result.isError).toBeFalsy()
@@ -475,9 +475,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.bash.run = (() => Promise.reject(new Error('executor down')))
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && 'exitCode' in res.data).toBe(false)
     })
@@ -493,7 +493,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(2) // empty-reason block forced continuation
       expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('blocked by Stop hook')
     })
@@ -506,7 +506,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('extra guidance from a plain hook')
     })
 
@@ -521,7 +521,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => existsSync(marker)) // the exit-2 hook has finished
-      expect(events(agent).some(e => e.type === 'context/message'
+      expect(events(agent).some(e => e.type === 'user/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('stale')))).toBe(false)
     })
 
@@ -534,7 +534,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(1) // exit 1 is non-blocking → the turn ran
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('stale')
     })
@@ -545,9 +545,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      await waitFor(() => events(agent).some(e => e.type === 'context/message'
+      await waitFor(() => events(agent).some(e => e.type === 'user/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('session preamble'))))
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('session preamble')
     })
 
@@ -559,7 +559,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('unrelated')
     })
 
@@ -572,9 +572,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'cap.sh', `#!/usr/bin/env bash\ncat > "${cap}"\nexit 0\n`) }] }] })
       const adapter = new MockAdapter([toolCallResponse('c1', 'shell', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      ctx.tools.register(defineTool({ name: 'shell', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'shell', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const payload = JSON.parse(readFileSync(cap, 'utf8')) as { tool_name: string; tool_input: { command: string } }
       expect(payload.tool_name).toBe('shell')
       expect(payload.tool_input.command).toBe('ls')
@@ -588,9 +588,9 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'shell', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
-      ctx.tools.register(defineTool({ name: 'shell', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'shell', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(false) // the matcher fired → the hook denied the tool
       expect(events(agent).some(e => e.type === 'hook/invoked' && e.data.point === 'PreToolUse')).toBe(true)
     })
@@ -602,7 +602,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const warn = vi.fn(); ctx.logger.warn = warn as never
       const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+      agent.followup([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('systemMessage'))
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('heads up')
     })
@@ -622,10 +622,10 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, cwd: serverDir })
       await ctx.plugin(HooksCodex, { configPath: join(serverDir, 'hooks.json'), model: 'm' })
       ctx.llm.registerAdapter(['mock'], adapter)
-      ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.tools.register(defineContentToolFixture({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const { SessionId } = await import('@deepseek-ai/dsh-session')
       const handle = await ctx.agents.create({ sessionId: SessionId('s1'), meta: { cwd: sessionDir }, agentOptions: { provider: 'mock', model: 'mock' } })
-      handle.agent.send([{ type: 'text', text: 'go' }])
+      handle.agent.followup([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, handle.agent)
       expect(existsSync(marker)).toBe(true)
       expect(readFileSync(marker, 'utf8').trim().endsWith(sessionDir.split('/').pop()!)).toBe(true)
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 5ca6b9b8ca..1badfe65e8 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -8,6 +8,8 @@ Wire messages form a four-quadrant discriminated union — who initiates × requ
 
 The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md).
 
+The mux stream projects the latest log-backed title as a validated `session/title` control frame after each attached-session subscription baseline and immediately after the corresponding live raw title event. This projection does not add titles to `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs.
+
 ## 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/src/api/events.schema.ts b/packages/host/apiproxy/src/api/events.schema.ts
index a46cdfe09e..0a63305b8a 100644
--- a/packages/host/apiproxy/src/api/events.schema.ts
+++ b/packages/host/apiproxy/src/api/events.schema.ts
@@ -17,6 +17,7 @@ export const askUserQuestionItemSchema = z.object({
   id: z.string(),
   question: z.string(),
   header: z.string().optional(),
+  detail: z.string().optional(),
   options: z.array(z.object({ label: z.string(), description: z.string().optional() })).optional(),
   multiSelect: z.boolean().optional(),
 }) satisfies z.ZodType<Wire<AskUserQuestionItem>>
@@ -25,9 +26,13 @@ export const askUserQuestionItemSchema = z.object({
 export const muxFrameSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('session/event'), sessionId: sessionIdSchema, event: sessionEventSchema, view: toolEventViewSchema.optional() }),
   z.object({ type: z.literal('session/subscribed'), sessionId: sessionIdSchema, lastSeq: z.number().int() }),
+  z.object({ type: z.literal('session/title'), sessionId: sessionIdSchema, title: z.string().min(1), eventSeq: z.number().int().nonnegative(), updatedAt: z.number() }),
   z.object({ type: z.literal('approval/requested'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, toolName: z.string(), callId: z.string().optional(), reason: z.string().optional() }),
   z.object({ type: z.literal('approval/resolved'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]) }),
-  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema) }),
+  // Non-empty by wire contract: the user-interaction service rejects empty
+  // batches at ask() (EMPTY_QUESTIONS), so an empty frame is host breakage
+  // and must fail loud here, not reach the composer.
+  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema).min(1) }),
   z.object({ type: z.literal('question/resolved'), sessionId: sessionIdSchema, questionRpcId: rpcIdSchema, outcome: z.union([z.literal('answered'), z.literal('cancelled')]) }),
   z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
 ]) as unknown as z.ZodType<MuxFrame>
diff --git a/packages/host/apiproxy/src/api/events.ts b/packages/host/apiproxy/src/api/events.ts
index eac4f0e65c..c03877c31d 100644
--- a/packages/host/apiproxy/src/api/events.ts
+++ b/packages/host/apiproxy/src/api/events.ts
@@ -33,8 +33,9 @@ export type ToolEventView =
 export interface EventsApi {
   /**
    * All-session aggregated mux stream. On open, emits a subscribed control frame for every
-   * attached session and replays each session's still-pending approval/question requested
-   * frames (rpcId reused verbatim — the refresh-recovery baseline).
+   * attached session followed by its optional latest title snapshot, then replays each
+   * session's still-pending approval/question requested frames (rpcId reused verbatim — the
+   * refresh-recovery baseline).
    * since: resume seam, unimplemented in v1 (ignored if passed); reconnection = reopen the
    * stream + refetch history.
    */
@@ -54,6 +55,7 @@ export interface EventsApi {
 export type MuxFrame =
   | { type: 'session/event'; sessionId: SessionId; event: SessionEvent; view?: ToolEventView }
   | { type: 'session/subscribed'; sessionId: SessionId; lastSeq: number }
+  | { type: 'session/title'; sessionId: SessionId; title: string; eventSeq: number; updatedAt: number }
   | { type: 'approval/requested'; sessionId: SessionId; approvalId: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string }
   | { type: 'approval/resolved'; sessionId: SessionId; approvalId: ApprovalRequestId; outcome: ApprovalOutcome }
   | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] }
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index c51c785a7c..c2fbb0d189 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -39,7 +39,7 @@ export type {
 } from './rpc.ts'
 
 // ---- Errors and ids ----
-export { RpcId } from './rpc.ts'
+export { RpcId, transportError } from './rpc.ts'
 export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
 
 // ---- Method registry and derived generics ----
diff --git a/packages/host/apiproxy/src/api/rpc.schema.ts b/packages/host/apiproxy/src/api/rpc.schema.ts
index d993e763b7..20ef251cd6 100644
--- a/packages/host/apiproxy/src/api/rpc.schema.ts
+++ b/packages/host/apiproxy/src/api/rpc.schema.ts
@@ -33,6 +33,7 @@ export const rpcIdSchema = z.string() as unknown as z.ZodType<RpcId>
 /** Error body: discriminated by code, per-branch details aligned to RpcErrorDetailsMap; details is required. */
 export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code', [
   z.object({ code: z.literal('bad-request'), message: z.string(), details: z.object({ issues: z.array(z.custom<ZodIssue>()) }) }),
+  z.object({ code: z.literal('cancelled'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
   z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
diff --git a/packages/host/apiproxy/src/api/rpc.ts b/packages/host/apiproxy/src/api/rpc.ts
index 46f737817c..53b2fc43e8 100644
--- a/packages/host/apiproxy/src/api/rpc.ts
+++ b/packages/host/apiproxy/src/api/rpc.ts
@@ -30,6 +30,7 @@ export function RpcId(id: string): RpcId {
 /** Error code → details type map (a second table isomorphic to RpcMethodMap). New code = one row here + one branch in the error schema. */
 export interface RpcErrorDetailsMap {
   'bad-request': { issues: ZodIssue[] }
+  'cancelled': {}
   'session-not-found': { sessionId: SessionId }
   'agent-busy': { reason: string }
   'internal': {}
@@ -49,6 +50,20 @@ export type RpcError = {
 /** Business success/failure result: the result slot of a unary response; methods never throw business errors. */
 export type RpcResult<T> = { ok: true; value: T } | { ok: false; error: RpcError }
 
+/**
+ * Fold a transport exception into the RpcResult error branch (unified error
+ * surface; 'internal' as the catch-all code). Lives with RpcResult so every
+ * carrier consumer folds the same way.
+ * @param error - the thrown value from the carrier.
+ * @returns the error branch of an RpcResult.
+ */
+export function transportError<T>(error: unknown): RpcResult<T> {
+  return {
+    ok: false,
+    error: { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} },
+  }
+}
+
 /**
  * Signature-layer narrow form, request side (domain-interface view, shared by
  * both directions): rpcId is explicit in the signature, never mixed into the
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index 764c9673b9..0c3eb2b320 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -29,6 +29,7 @@ describe('RpcId', () => {
 describe('rpcErrorSchema', () => {
   it('accepts every code branch with its required details', () => {
     expect(rpcErrorSchema.parse({ code: 'bad-request', message: 'm', details: { issues: [] } }).code).toBe('bad-request')
+    expect(rpcErrorSchema.parse({ code: 'cancelled', message: 'm', details: {} }).code).toBe('cancelled')
     expect(rpcErrorSchema.parse({ code: 'session-not-found', message: 'm', details: { sessionId: 's' } }).code).toBe('session-not-found')
     expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
     expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
@@ -123,6 +124,7 @@ describe('events frame schemas', () => {
     const frames = [
       { type: 'session/event', sessionId: 's', event: { type: 't', seq: 0, time: 1, data: null } },
       { type: 'session/subscribed', sessionId: 's', lastSeq: -1 },
+      { type: 'session/title', sessionId: 's', title: 'Durable title', eventSeq: 2, updatedAt: 3 },
       { type: 'approval/requested', sessionId: 's', approvalId: 'a', toolName: 'bash', callId: 'c', reason: 'r' },
       { type: 'approval/resolved', sessionId: 's', approvalId: 'a', outcome: 'allowed-once' },
       { type: 'question/requested', sessionId: 's', questions: [{ id: 'q', question: 'Q?', options: [{ label: 'L' }], multiSelect: true }] },
@@ -131,9 +133,20 @@ describe('events frame schemas', () => {
     ]
     for (const frame of frames) expect(muxFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
     expect(() => muxFrameSchema.parse({ type: 'unknown/frame' })).toThrow()
+    for (const invalid of [
+      { type: 'session/title', sessionId: 's', title: '', eventSeq: 0, updatedAt: 1 },
+      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: -1, updatedAt: 1 },
+      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0.5, updatedAt: 1 },
+      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0, updatedAt: 'now' },
+      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0, updatedAt: Number.NaN },
+    ]) expect(() => muxFrameSchema.parse(invalid)).toThrow()
     expect(askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?' }).id).toBe('q')
   })
 
+  it('rejects an empty question batch (ask() guarantees at least one, so an empty frame is host breakage)', () => {
+    expect(() => muxFrameSchema.parse({ type: 'question/requested', sessionId: 's', questions: [] })).toThrow()
+  })
+
   it('accepts every host frame branch', () => {
     const frames = [
       { type: 'host/session-added', sessionId: 's', parentSessionId: 'p' },
diff --git a/packages/host/runtime/README.md b/packages/host/runtime/README.md
index 60fe4b22fa..f7cf7d9de8 100644
--- a/packages/host/runtime/README.md
+++ b/packages/host/runtime/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-host-runtime
 
-Host runtime assembly for `dsh`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence, system prompt, tools, agents, agent loop, workspace instructions, local bash), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
+Host runtime assembly for `dsh`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence and immediate fallback titles, optional first-message model summaries, system prompt, tools, agents, agent loop, workspace instructions, local bash, and the provider-neutral user-interaction service), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
 
 Which plugins mount and with what defaults is decided only here — shells must not `ctx.plugin` to alter the assembly. `RunningHost.ctx` is a formal seam with exactly two sanctioned uses: mounting protocol front-door plugins (e.g. a future `dsh acp`) and headless session-event subscription; consuming clients must not bypass `api` through it.
 
@@ -12,21 +12,24 @@ Which plugins mount and with what defaults is decided only here — shells must
 | `workspaceContext` | (required) | [`AGENTS.md`/`CLAUDE.md` loader](../../context/workspace-context/README.md) config with an explicit `maxBytes`, or `false` to disable it. |
 | `provider` | `'deepseek'` | Default provider route injected as agentOptions on create/resume and reported by `host.describe`. |
 | `model` | `'deepseek-v4-flash'` | Default model id, same single source as `provider`. |
+| `cwd` | `process.cwd()` | Default project directory for a session whose create request omits `cwd`. |
+| `sessionTitle` | 5 words / 40 fallback bytes / 80 accepted bytes | Deterministic fallback and accepted-title limits. |
+| `sessionTitleLlm` | disabled | `true` enables the 5-word / 10-CJK-character, 4,096-input-byte, 64-output-token, 60-second first-message policy; an explicit config overrides it. An omitted route inherits the logged main-request provider and model. |
 
 ## ApiProxy implementation notes
 
-Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session on open; the host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
+Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session and every still-pending question with its original rpcId. Question responses, including blank per-item answers, are validated against the owning session and exact request before an atomic first-wins claim; answer, whole-request cancellation, owner abort, and provider disposal broadcast `question/resolved`. The host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
 
 ## Model Experience
 
-Indirectly, through the model-facing plugins bootHost mounts and the provider/model defaults injected into created and resumed agents. When `workspaceContext` is enabled, each agent-loop instance freezes the applicable workspace instructions into its logged request prefix; the owning package documents the exact [model-visible framing](../../context/workspace-context/README.md#prompt-shape).
+Indirectly, through the non-blocking first-message title request owned by [`dsh-session-title-llm`](../../session-title/session-title-llm/README.md) when `sessionTitleLlm` is enabled, the provider/model defaults injected into created and resumed agents, the other model-facing plugins `bootHost` mounts, and the logged [workspace-instruction prefix](../../context/workspace-context/README.md#prompt-shape) when `workspaceContext` is enabled.
 
 #### KV Cache effect
 
-No direct invalidation; the mounted model-facing plugins own their request-prefix changes.
+No main-request invalidation; when enabled, the auxiliary title request has its own cache behavior and leaves the conversation prefix unchanged.
 
 ## Known Limitations and Deferred Work
 
-- **`respond` is a stub** — it always returns `not-pending`; the approval/question pending registry (stable-rpcId mint on accept, baseline replay on stream reopen, wire answerer) is the next host-side step.
+- **Question waits are process-memory state** — browser reconnects recover them, but a host process restart aborts the owning tool call instead of restoring the wait from persistence.
 - **`host.describe.version` is a placeholder** — it does not yet report the `apps/cli` package version.
 - **The assembly is fixed** — per-deployment plugin selection (user profile, log sinks, alternative persistence) has a documented home here but no configuration surface yet.
diff --git a/packages/host/runtime/package.json b/packages/host/runtime/package.json
index be3e9e1050..94a544fb74 100644
--- a/packages/host/runtime/package.json
+++ b/packages/host/runtime/package.json
@@ -32,14 +32,6 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-bash-local": "workspace:^",
-    "@deepseek-ai/dsh-client-connection": "workspace:^",
-    "@deepseek-ai/dsh-client-i18n": "workspace:^",
-    "@deepseek-ai/dsh-client-runtime": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
     "@deepseek-ai/dsh-compact-basic": "workspace:^",
     "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-fs-policy": "workspace:^",
@@ -49,6 +41,8 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-session-title-first-message-llm": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-skill-local": "workspace:^",
     "@deepseek-ai/dsh-spill-local": "workspace:^",
@@ -69,8 +63,9 @@
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@deepseek-ai/dsh-tool-workflow": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-workspace-context": "workspace:^",
-    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^"
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^",
+    "@deepseek-ai/dsh-workspace-context": "workspace:^"
   },
   "peerDependencies": {
     "cordis": "^4.0.0-rc.7",
diff --git a/packages/host/runtime/src/api-proxy.ts b/packages/host/runtime/src/api-proxy.ts
index 0621fbecb9..acf77751af 100644
--- a/packages/host/runtime/src/api-proxy.ts
+++ b/packages/host/runtime/src/api-proxy.ts
@@ -1,20 +1,26 @@
 /**
- * Host-side ApiProxy implementation (minimal-first —
- * describe/list/create/history/prompt/cancel and both streams are real,
- * respond is a stub). Signature discipline: unary takes the narrow
- * RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
+ * Host-side ApiProxy implementation. Signature discipline: unary takes the
+ * narrow RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
  */
 
 import { randomUUID } from 'node:crypto'
-import { stat } from 'node:fs/promises'
+import { mkdir, stat } from 'node:fs/promises'
 import type { Context } from 'cordis'
 import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
-import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
-import type { ApiProxy, HistoryEntry, HostFrame, MuxFrame, SessionSummary, ToolEventView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
+import type {
+  ApiProxy, HistoryEntry, HostFrame, MuxFrame, QuestionResponsePayload, SessionSummary, ToolEventView,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+import { questionResponsePayloadSchema } from '@deepseek-ai/dsh-host-apiproxy/api/questions.schema'
 import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import type {
+  AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionRequest,
+} from '@deepseek-ai/dsh-user-interaction'
+import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
 
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -104,6 +110,28 @@ function frame<F>(payload: F): RpcRequest<F> {
   return { rpcId: RpcId(randomUUID()), payload }
 }
 
+type SessionTitleFrame = Extract<MuxFrame, { type: 'session/title' }>
+
+/** Project the latest durable title without exposing title-generation policy. */
+function titleFrame(session: Session): SessionTitleFrame | undefined {
+  const title = foldSessionTitle(session.events)
+  if (title === undefined) return undefined
+  return {
+    type: 'session/title',
+    sessionId: session.id,
+    title: title.title,
+    eventSeq: title.eventSeq,
+    updatedAt: title.updatedAt,
+  }
+}
+
+/** Queue the subscription baseline followed by its optional title snapshot. */
+function subscribeSession(queue: FrameQueue<RpcRequest<MuxFrame>>, session: Session): void {
+  queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+  const title = titleFrame(session)
+  if (title !== undefined) queue.push(frame(title))
+}
+
 /** SessionSummary projection for attached (in-memory) sessions. */
 function summarize(session: Session, running: boolean): SessionSummary {
   return {
@@ -153,7 +181,36 @@ export interface ApiProxyDefaults {
 /** The tool/call payload fields the presenter path reads. */
 interface ToolCallData { callId: string; name: string; arguments: string }
 /** The tool/result payload fields the presenter path reads. */
-interface ToolResultData { callId: string; content: ContentBlock[]; isError: boolean; meta?: unknown }
+interface ToolResultData { callId: string; content: ContentBlock[]; isError: boolean; meta?: JsonValue }
+
+/** One host-owned question wait, addressed by the stable server-request id. */
+interface PendingQuestion {
+  rpcId: RpcId
+  sessionId: SessionId
+  questions: AskUserQuestionItem[]
+  resolve: (answer: AskUserQuestionAnswer) => void
+  reject: (error: UserInteractionError) => void
+  signal?: AbortSignal
+  onAbort?: () => void
+}
+
+/** Validate one answer batch against the exact question request it resolves. */
+function matchesQuestions(payload: QuestionResponsePayload, pending: PendingQuestion): boolean {
+  if (payload.sessionId !== pending.sessionId) return false
+  const answers = payload.answer.answers
+  if (answers.length !== pending.questions.length) return false
+  return answers.every((answer, index) => {
+    const question = pending.questions[index] as AskUserQuestionItem
+    if (answer.id !== question.id) return false
+    if (new Set(answer.selected).size !== answer.selected.length) return false
+    const custom = answer.custom?.trim()
+    if (custom !== undefined && custom === '') return false
+    if (custom !== undefined && answer.selected.length > 0) return false
+    if (question.multiSelect !== true && answer.selected.length > 1) return false
+    const labels = new Set(question.options?.map(option => option.label) ?? [])
+    return answer.selected.every(label => labels.has(label))
+  })
+}
 
 /**
  * Compute the render intent for a tool/call or tool/result event through the
@@ -219,12 +276,70 @@ class SessionNotFound extends Error {}
  * @param ctx - the root context returned by bootHost (sessions/agents services mounted).
  * @param defaults - host-level default provider/model: injected as
  * agentOptions on create/resume, reported by describe from the same source.
- * @returns the ApiProxy implementation (minimal-first; stubs noted per method).
+ * @returns the ApiProxy implementation.
  */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
   const agentOptions = { provider: defaults.provider, model: defaults.model }
   /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
   const resumes = new Map<SessionId, Promise<Agent>>()
+  const pendingQuestions = new Map<RpcId, PendingQuestion>()
+  const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()
+
+  /** Send one transient frame to every connected mux consumer. */
+  function broadcast(payload: MuxFrame): void {
+    const envelope = frame(payload)
+    for (const queue of muxQueues) queue.push(envelope)
+  }
+
+  /** Remove a wait before settling it: synchronous deletion makes the first claimant win. */
+  function claimQuestion(pending: PendingQuestion, outcome: 'answered' | 'cancelled'): void {
+    pendingQuestions.delete(pending.rpcId)
+    if (pending.signal !== undefined && pending.onAbort !== undefined) {
+      pending.signal.removeEventListener('abort', pending.onAbort)
+    }
+    broadcast({
+      type: 'question/resolved', sessionId: pending.sessionId,
+      questionRpcId: pending.rpcId, outcome,
+    })
+  }
+
+  const disposeProvider = ctx.userInteraction.registerProvider({
+    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer> {
+      const sessionId = request.agent?.id
+      if (sessionId === undefined) {
+        return Promise.reject(new UserInteractionError(
+          'web user interaction requires an agent-owned session', 'ASK_MISSING_AGENT'))
+      }
+      return new Promise<AskUserQuestionAnswer>((resolve, reject) => {
+        const rpcId = RpcId(randomUUID())
+        const pending: PendingQuestion = {
+          rpcId, sessionId, questions: request.questions, resolve, reject,
+          ...(request.signal === undefined ? {} : { signal: request.signal }),
+        }
+        const onAbort = (): void => {
+          claimQuestion(pending, 'cancelled')
+          reject(new UserInteractionError(
+            'ask_user_question was aborted before the user answered', 'ASK_ABORTED'))
+        }
+        pending.onAbort = onAbort
+        pendingQuestions.set(rpcId, pending)
+        request.signal?.addEventListener('abort', onAbort, { once: true })
+        const envelope: RpcRequest<MuxFrame> = {
+          rpcId,
+          payload: { type: 'question/requested', sessionId, questions: request.questions },
+        }
+        for (const queue of muxQueues) queue.push(envelope)
+      })
+    },
+  })
+  ctx.effect(() => () => {
+    disposeProvider()
+    for (const pending of [...pendingQuestions.values()]) {
+      claimQuestion(pending, 'cancelled')
+      pending.reject(new UserInteractionError(
+        'web user-interaction provider was disposed', 'ASK_ABORTED'))
+    }
+  }, 'api-proxy: user-interaction provider')
 
   /**
    * Gate the cold path on the store: an id absent from it, or naming a legacy
@@ -292,8 +407,18 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         const sessionId = `session-${randomUUID()}` as SessionId
         // A session's cwd is its project path. When the creator does not choose
         // one, the default project is the host-level default (the host process
-        // working directory unless boot overrides it).
+        // working directory unless boot overrides it). Ensure the directory
+        // exists so Create-workspace and typed paths land on a real folder.
         const cwd = request.payload.cwd ?? defaults.cwd
+        try {
+          await mkdir(cwd, { recursive: true })
+        } catch (error: unknown) {
+          return err(request, {
+            code: 'internal',
+            message: `failed to ensure project directory "${cwd}": ${String(error)}`,
+            details: {},
+          })
+        }
         const handle = await ctx.agents.create({ sessionId, agentOptions, meta: { cwd } })
         return ok(request, { sessionId: handle.agent.id })
       },
@@ -322,7 +447,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         const source: MessageSource = { kind: 'user', rpcId: request.rpcId }
         try {
           if (mode === 'steer') agent.steer(content, { source })
-          else agent.send(content, { source })
+          else agent.followup(content, { source })
         } catch (error: unknown) {
           // A synchronous throw from send/steer means disposed or invalid input; surface as agent-busy with the reason attached.
           return err(request, { code: 'agent-busy', message: 'prompt rejected', details: { reason: String(error) } })
@@ -361,8 +486,18 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     events: {
       mux(_request, signal) {
         const queue = new FrameQueue<RpcRequest<MuxFrame>>()
+        muxQueues.add(queue)
         for (const session of ctx.sessions.list()) {
-          queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+          subscribeSession(queue, session)
+        }
+        for (const pending of pendingQuestions.values()) {
+          queue.push({
+            rpcId: pending.rpcId,
+            payload: {
+              type: 'question/requested', sessionId: pending.sessionId,
+              questions: pending.questions,
+            },
+          })
         }
         // Per-session open-call table for result-view pairing. Bounded by the
         // per-turn call count: entries clear on turn/end; a table miss (stream
@@ -385,15 +520,22 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             const view = viewFor(ctx, event, callId =>
               openCalls.get(session.id)?.get(callId) ?? backscanArgs(session.events, callId))
             queue.push(frame({ type: 'session/event', sessionId: session.id, event, ...view === undefined ? {} : { view } }))
+            if (event.type === 'session/title') {
+              // The accepted raw event is already in session.events, so the fold must find it.
+              queue.push(frame(titleFrame(session) as SessionTitleFrame))
+            }
           }),
           ctx.on('session/created', (session: Session) => {
-            queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+            subscribeSession(queue, session)
           }),
           ctx.on('session/disposed', (session: Session) => {
             openCalls.delete(session.id)
           }),
         ]
-        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+        return queue.iterate(signal, () => {
+          muxQueues.delete(queue)
+          for (const dispose of disposers) dispose()
+        })
       },
 
       host(_request, signal) {
@@ -421,9 +563,38 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       },
     },
 
-    // TODO(step2): approval/question pending registry (wire answerer + proxy provider).
-    respond(_message: ClientResponse): Promise<RpcReceipt> {
-      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+    respond(message: ClientResponse): Promise<RpcReceipt> {
+      const pending = pendingQuestions.get(message.rpcId)
+      if (pending === undefined) return Promise.resolve({ accepted: false, reason: 'not-pending' })
+      if (!message.result.ok) {
+        if (message.result.error.code !== 'cancelled') {
+          return Promise.resolve({ accepted: false, reason: 'bad-response' })
+        }
+        claimQuestion(pending, 'cancelled')
+        pending.reject(new UserInteractionError(
+          'the user cancelled ask_user_question', 'ASK_CANCELLED'))
+        return Promise.resolve({ accepted: true })
+      }
+      const parsed = questionResponsePayloadSchema.safeParse(message.result.value)
+      if (!parsed.success) {
+        return Promise.resolve({ accepted: false, reason: 'bad-response' })
+      }
+      const payload: QuestionResponsePayload = {
+        sessionId: parsed.data.sessionId,
+        answer: {
+          answers: parsed.data.answer.answers.map(answer => ({
+            id: answer.id,
+            selected: answer.selected,
+            ...(answer.custom === undefined ? {} : { custom: answer.custom }),
+          })),
+        },
+      }
+      if (!matchesQuestions(payload, pending)) {
+        return Promise.resolve({ accepted: false, reason: 'bad-response' })
+      }
+      claimQuestion(pending, 'answered')
+      pending.resolve(payload.answer)
+      return Promise.resolve({ accepted: true })
     },
   }
 }
diff --git a/packages/host/runtime/src/boot.ts b/packages/host/runtime/src/boot.ts
index 40b4837c91..c0960ab678 100644
--- a/packages/host/runtime/src/boot.ts
+++ b/packages/host/runtime/src/boot.ts
@@ -8,6 +8,9 @@ import { Context } from 'cordis'
 import Timer from '@cordisjs/plugin-timer'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
+import SessionTitleService, { type Config as SessionTitleConfig } from '@deepseek-ai/dsh-session-title'
+import * as SessionTitleFirstMessageLlm from '@deepseek-ai/dsh-session-title-first-message-llm'
+import type { Config as SessionTitleLlmConfig } from '@deepseek-ai/dsh-session-title-first-message-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
@@ -38,6 +41,23 @@ import * as toolWorkflow from '@deepseek-ai/dsh-tool-workflow'
 import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
 import SpillLocal from '@deepseek-ai/dsh-spill-local'
 import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+
+/** Default deterministic title policy for sessions created through the host. */
+const DEFAULT_SESSION_TITLE_CONFIG: SessionTitleConfig = {
+  fallbackMaxWords: 5,
+  fallbackMaxBytes: 40,
+  maxTitleBytes: 80,
+}
+
+/** Default first-message model-title policy for sessions created through the host. */
+const DEFAULT_SESSION_TITLE_LLM_CONFIG: SessionTitleLlmConfig = {
+  targetWords: 5,
+  targetCjkCharacters: 10,
+  maxInputBytes: 4_096,
+  maxOutputTokens: 64,
+  timeoutMs: 60_000,
+}
 
 /** Options for bootHost — the assembly-layer composition knobs. */
 export interface BootHostOptions {
@@ -49,6 +69,10 @@ export interface BootHostOptions {
   provider?: string
   /** Default model id (defaults to 'deepseek-v4-flash', matching the demos). */
   model?: string
+  /** Deterministic fallback-title limits. */
+  sessionTitle?: SessionTitleConfig
+  /** Opt-in first-message model-title policy; `true` selects host defaults and an explicit config overrides them. */
+  sessionTitleLlm?: true | SessionTitleLlmConfig
   /**
    * Default project directory for sessions created without an explicit cwd
    * (defaults to the host process working directory). A session's cwd is its
@@ -92,13 +116,21 @@ export async function bootHost(options: BootHostOptions): Promise<HostHandle> {
   await ctx.plugin(Timer)
   await ctx.plugin(LlmService)
   await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionTitleService, options.sessionTitle ?? DEFAULT_SESSION_TITLE_CONFIG)
+  if (options.sessionTitleLlm !== undefined) {
+    await ctx.plugin(
+      SessionTitleFirstMessageLlm,
+      options.sessionTitleLlm === true ? DEFAULT_SESSION_TITLE_LLM_CONFIG : options.sessionTitleLlm,
+    )
+  }
   await ctx.plugin(SystemPrompt, { persona: '' })
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(TaskService)
   await ctx.plugin(AgentLoop, { agents: [] })
   await ctx.plugin(LlmDeepSeek, {})
-  await ctx.plugin(SessionPersistenceJsonl, { root: options.persistenceRoot, compression: 'none' })
+  await ctx.plugin(SessionPersistenceJsonl, { root: options.persistenceRoot })
   await ctx.plugin(LocalBashExecutor, {})
   // Tool suite mirroring the demo:repl composition (repl-agent/cordis.yml +
   // the agent-spine bundle) so web sessions get the same coding-agent tool
diff --git a/packages/host/runtime/src/index.ts b/packages/host/runtime/src/index.ts
index 55e143a495..af10f0be16 100644
--- a/packages/host/runtime/src/index.ts
+++ b/packages/host/runtime/src/index.ts
@@ -11,4 +11,4 @@ export { createApiProxy } from './api-proxy.ts'
 export type { ApiProxyDefaults } from './api-proxy.ts'
 export { startHost } from './start.ts'
 export type { StartHostOptions, RunningHost } from './start.ts'
-export { mountWebPlugins, WEB_UI_PLUGINS } from './web-plugins.ts'
+export { mountWebPlugins } from './web-plugins.ts'
diff --git a/packages/host/runtime/src/web-plugins.ts b/packages/host/runtime/src/web-plugins.ts
index 26ce5b3396..5866d46492 100644
--- a/packages/host/runtime/src/web-plugins.ts
+++ b/packages/host/runtime/src/web-plugins.ts
@@ -1,27 +1,16 @@
 /**
- * Web UI plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
- * entry tree listing the eight UI plugin packages (the P-I config-source bar —
- * a cordis.yml file form comes later; install/remove currently means editing
- * this list and restarting). The web plugin registry discovers the entries by
- * their package.json dshClient declarations; node halves are empty applies,
- * so mounting them here costs nothing beyond Loader governance.
+ * Web client plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
+ * entry tree over the caller-supplied client plugin roster. The roster is a
+ * composition decision and lives in the composing app (apps/cli); this module
+ * only owns the mount/settle/fail-loud mechanics. The web plugin registry
+ * discovers fetch-arrival entries among the mounted packages by their
+ * package.json dshClient declarations; node halves are empty applies, so
+ * mounting them here costs nothing beyond Loader governance.
  */
 import { createRequire } from 'node:module'
 import type { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 
-/** The eight UI plugin packages served to the browser (order = manifest order). */
-export const WEB_UI_PLUGINS = [
-  '@deepseek-ai/dsh-client-connection',
-  '@deepseek-ai/dsh-client-runtime',
-  '@deepseek-ai/dsh-client-ui-theme',
-  '@deepseek-ai/dsh-client-i18n',
-  '@deepseek-ai/dsh-client-ui-layout',
-  '@deepseek-ai/dsh-client-ui-sidebar',
-  '@deepseek-ai/dsh-client-ui-conversation',
-  '@deepseek-ai/dsh-client-ui-trajectory',
-] as const
-
 /** What the shell hands the web plugin registry (loader view + module resolution seam). */
 export interface MountedWebPlugins {
   /** Entry enumeration surface of the mounted Loader (registry scan source). */
@@ -31,31 +20,36 @@ export interface MountedWebPlugins {
 }
 
 /**
- * Mount the Loader (when absent) and create one in-memory entry per UI
- * plugin, then wait for the tree to settle. A plugin whose import fails
- * leaves its entry fiber-less — surfaced here as a loud throw listing the
- * failures (misconfiguration must not silently drop a UI plugin).
+ * Mount the Loader (when absent) and create one in-memory entry per client
+ * plugin package, then wait for the tree to settle. A plugin whose import
+ * fails leaves its entry fiber-less — surfaced here as a loud throw listing
+ * the failures (misconfiguration must not silently drop a client plugin).
  * @param ctx - host root context (bootHost product).
+ * @param plugins - client plugin package names to mount (the composition layer's roster).
+ * @param anchor - module URL anchoring bare-specifier resolution (the composing
+ * app's import.meta.url; the roster packages must be dependencies of that app).
  * @returns the loader view and package.json resolver the registry consumes.
  */
-export async function mountWebPlugins(ctx: Context): Promise<MountedWebPlugins> {
+export async function mountWebPlugins(
+  ctx: Context, plugins: readonly string[], anchor: string,
+): Promise<MountedWebPlugins> {
   // The Loader resolves bare specifiers against ctx.baseUrl; without one the
-  // import silently fails and every entry stays fiber-less. This package
-  // depends on all eight UI plugins, so its own URL is the right anchor.
-  ctx.baseUrl ??= import.meta.url
+  // import silently fails and every entry stays fiber-less. The composing app
+  // declares the roster packages as dependencies, so its URL is the right anchor.
+  ctx.baseUrl ??= anchor
   if (ctx.get('loader') === undefined) await ctx.plugin(Loader)
   const existing = new Set([...ctx.loader.entries()].map(entry => entry.options.name))
-  for (const name of WEB_UI_PLUGINS) {
+  for (const name of plugins) {
     if (!existing.has(name)) await ctx.loader.create({ name })
   }
   await ctx.loader.await()
   const dead = [...ctx.loader.entries()]
-    .filter(entry => (WEB_UI_PLUGINS as readonly string[]).includes(entry.options.name))
+    .filter(entry => plugins.includes(entry.options.name))
     .filter(entry => entry.fiber === undefined && !entry.disabled)
   if (dead.length > 0) {
-    throw new Error(`web-plugins: UI plugin(s) failed to load: ${dead.map(e => e.options.name).join(', ')}`)
+    throw new Error(`web-plugins: client plugin(s) failed to load: ${dead.map(e => e.options.name).join(', ')}`)
   }
-  const require = createRequire(import.meta.url)
+  const require = createRequire(anchor)
   return {
     loader: ctx.loader,
     resolvePkgJson: name => require.resolve(`${name}/package.json`),
diff --git a/packages/host/runtime/tests/api-proxy-cold.spec.ts b/packages/host/runtime/tests/api-proxy-cold.spec.ts
index 01f1da7d17..3d4ba8e15a 100644
--- a/packages/host/runtime/tests/api-proxy-cold.spec.ts
+++ b/packages/host/runtime/tests/api-proxy-cold.spec.ts
@@ -12,6 +12,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -32,6 +33,7 @@ describe('sessions.list cold merge', () => {
   it('summarizes unattached sessions: log mtime, locate-less and vanished-log createdAt fallbacks, lineage', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
+    await ctx.plugin(UserInteractionService)
     const root = mkdtempSync(join(tmpdir(), 'dsh-cold-'))
     const logPath = join(root, 'a.log')
     writeFileSync(logPath, 'log-bytes')
@@ -76,6 +78,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
     const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
 
     const listed = await api.sessions.list(request({}))
diff --git a/packages/host/runtime/tests/api-proxy-view.spec.ts b/packages/host/runtime/tests/api-proxy-view.spec.ts
index d000742262..a7dcdc73c5 100644
--- a/packages/host/runtime/tests/api-proxy-view.spec.ts
+++ b/packages/host/runtime/tests/api-proxy-view.spec.ts
@@ -1,8 +1,9 @@
 /**
  * Tool-card view computation over the mux live path: three standard card types
- * arrive on the frame, a presenterless tool ships no view field, and a throwing
- * presenter soft-falls to no view (the event still ships). Result pairing works
- * both through the live open-call table and the backscan fallback after
+ * arrive on the frame, a presenterless tool ships no view field, a call-only
+ * presenter keeps raw result content out of the view payload, and a throwing
+ * presenter soft-falls to no view (the event still ships). Result pairing
+ * works both through the live open-call table and the backscan fallback after
  * turn/end cleared it.
  */
 
@@ -12,11 +13,12 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
 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 ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { createApiProxy } from '../src/api-proxy.ts'
@@ -24,13 +26,13 @@ import { createApiProxy } from '../src/api-proxy.ts'
 const reply = (text: string): Promise<ContentBlock[]> => Promise.resolve([{ type: 'text', text }])
 
 function tool(name: string, presenters: Pick<ToolDefinition, 'presentCall' | 'presentResult'>): ToolDefinition {
-  return {
+  return defineContentToolFixture({
     name,
     description: `tool ${name}`,
-    parameters: { type: 'object', properties: {} },
+    parameters: {},
     execute: () => reply(`ran:${name}`),
     ...presenters,
-  }
+  })
 }
 
 async function harness(): Promise<{ ctx: Context }> {
@@ -38,6 +40,7 @@ async function harness(): Promise<{ ctx: Context }> {
   await ctx.plugin(SessionStore)
   await ctx.plugin(SystemPrompt, { persona: '' })
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   ctx.tools.register(tool('gen', {
     presentCall: () => ({ card: 'generic', title: 'gen call' }),
@@ -50,6 +53,9 @@ async function harness(): Promise<{ ctx: Context }> {
   ctx.tools.register(tool('diffy', {
     presentCall: () => ({ card: 'diff', title: 'Write f.txt', diffs: [{ path: 'f.txt', oldText: null, newText: 'x' }] }),
   }))
+  ctx.tools.register(tool('call-only', {
+    presentCall: () => ({ card: 'generic', title: 'program', kind: 'execute', rawInput: 'return value' }),
+  }))
   ctx.tools.register(tool('plain', {}))
   ctx.tools.register(tool('boom', {
     presentCall: () => { throw new Error('presenter exploded') },
@@ -73,13 +79,16 @@ describe('mux live view computation', () => {
     const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
-    const collected = collect(stream, 7, abort)
+    const collected = collect(stream, 9, abort)
+    const rawResult = `RAW_RESULT:${'x'.repeat(64 * 1024)}`
 
     const session = ctx.sessions.create()
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-gen'), name: 'gen', arguments: '{}' })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-term'), name: 'term', arguments: '{"cmd":"echo hi"}' })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-diff'), name: 'diffy', arguments: '{}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-call-only'), name: 'call-only', arguments: '{}' })
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-call-only'), content: [{ type: 'text', text: rawResult }], isError: false }, { surfaceOp: 'append' })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-plain'), name: 'plain', arguments: '{}' })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-boom'), name: 'boom', arguments: '{}' })
     session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-gen'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
@@ -93,6 +102,15 @@ describe('mux live view computation', () => {
     expect(byCall.get('tool/call:c-gen')?.view).toEqual({ for: 'call', view: { card: 'generic', title: 'gen call' } })
     expect(byCall.get('tool/call:c-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'echo hi' } })
     expect(byCall.get('tool/call:c-diff')?.view?.view.card).toBe('diff')
+    expect(byCall.get('tool/call:c-call-only')?.view).toEqual({
+      for: 'call',
+      view: { card: 'generic', title: 'program', kind: 'execute', rawInput: 'return value' },
+    })
+    const callOnlyResult = byCall.get('tool/result:c-call-only')
+    expect('view' in (callOnlyResult ?? {})).toBe(false)
+    const serializedResult = JSON.stringify(callOnlyResult)
+    expect(serializedResult.indexOf(rawResult)).toBeGreaterThanOrEqual(0)
+    expect(serializedResult.indexOf(rawResult)).toBe(serializedResult.lastIndexOf(rawResult))
     // No presenter → the frame carries no view property at all.
     expect('view' in (byCall.get('tool/call:c-plain') ?? {})).toBe(false)
     // Throwing presenter → soft-fall: event ships, no view.
diff --git a/packages/host/runtime/tests/host-runtime.spec.ts b/packages/host/runtime/tests/host-runtime.spec.ts
index 8f800dd08a..7dea7589a9 100644
--- a/packages/host/runtime/tests/host-runtime.spec.ts
+++ b/packages/host/runtime/tests/host-runtime.spec.ts
@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -8,6 +8,8 @@ import { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { Config as SessionTitleConfig } from '@deepseek-ai/dsh-session-title'
+import type { Config as SessionTitleLlmConfig } from '@deepseek-ai/dsh-session-title-first-message-llm'
 import type { HostFrame, MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -22,6 +24,10 @@ class ScriptedAdapter extends LlmAdapter {
   }
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    if ((options.tools?.length ?? 0) === 0) {
+      yield * textResponse('Durable append-only session titles')
+      return
+    }
     this.requests.push(options)
     const entry = this.script.shift()
     if (!entry) throw new Error('ScriptedAdapter: script exhausted')
@@ -68,6 +74,21 @@ function expectOk<T>(response: RpcResponse<T>): T {
   return response.result.value
 }
 
+async function nextMux(iterator: AsyncIterator<RpcRequest<MuxFrame>>): Promise<RpcRequest<MuxFrame>> {
+  const next = await iterator.next()
+  if (next.done === true) throw new Error('mux ended before the expected frame')
+  return next.value
+}
+
+/** Durably append a title event without mounting title-generation policy. */
+function appendTitle(ctx: Context, agent: Agent, title: string) {
+  return ctx.sessions.appendOutOfBand(agent.session, 'session/title', {
+    title,
+    messageSeqs: [1],
+    source: { kind: 'fallback' },
+  }, { kind: 'session-title' })
+}
+
 let host: RunningHost | undefined
 
 beforeEach(() => {
@@ -80,13 +101,19 @@ afterEach(async () => {
   vi.unstubAllEnvs()
 })
 
-async function boot(script: (StreamChunk[] | 'hang')[] = []): Promise<RunningHost> {
+async function boot(
+  script: (StreamChunk[] | 'hang')[] = [],
+  sessionTitle?: SessionTitleConfig,
+  sessionTitleLlm?: true | SessionTitleLlmConfig,
+): Promise<RunningHost> {
   host = await startHost({
     boot: {
       persistenceRoot: mkdtempSync(join(tmpdir(), 'dsh-host-runtime-')),
       workspaceContext: false,
       provider: 'scripted',
       model: 'test-model',
+      ...(sessionTitle === undefined ? {} : { sessionTitle }),
+      ...(sessionTitleLlm === undefined ? {} : { sessionTitleLlm }),
     },
   })
   host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter(script))
@@ -104,6 +131,16 @@ describe('bootHost / startHost', () => {
     await handle.dispose()
   })
 
+  it('uses the JSONL backend compressed default', async () => {
+    const handle: HostHandle = await bootHost({
+      persistenceRoot: mkdtempSync(join(tmpdir(), 'dsh-boot-zstd-')),
+      workspaceContext: false,
+    })
+    const session = handle.ctx.sessions.create()
+    expect(handle.ctx.sessionPersistence.locate(session.header)?.path).toMatch(/\.jsonl\.zstd$/)
+    await handle.dispose()
+  })
+
   it('startHost assembles api + handler over the same defaults and dedupes dispose', async () => {
     const running = await boot()
     expect(running.defaults).toMatchObject({ provider: 'scripted', model: 'test-model' })
@@ -151,6 +188,23 @@ describe('bootHost / startHost', () => {
     expect(requestText).toContain('Instructions from: AGENTS.md')
     expect(requestText).toContain('host-workspace-context-probe')
   })
+
+  it('keeps model title generation disabled when sessionTitleLlm is omitted', async () => {
+    const running = await boot([textResponse('pong')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(ctx, agent)
+    expectOk(await api.sessions.prompt(request({
+      sessionId,
+      mode: 'queue' as const,
+      content: [{ type: 'text' as const, text: 'Explain durable session titles.' }],
+    })))
+    await idle
+
+    expect((await ctx.sessionTitle.refresh(agent.session))?.source).toEqual({ kind: 'fallback' })
+    expect(agent.session.events.some(event => event.type === 'session/title-llm-request')).toBe(false)
+  })
 })
 
 describe('host.describe', () => {
@@ -177,9 +231,120 @@ describe('sessions.create / list', () => {
     expect(first?.running).toBe(false)
     expect(first?.parentSessionId).toBeUndefined()
   })
+
+  it('ensures a missing project directory before minting the session', async () => {
+    const { api } = await boot()
+    const root = mkdtempSync(join(tmpdir(), 'dsh-host-create-cwd-'))
+    const cwd = join(root, 'nested', 'workspace')
+    expect(existsSync(cwd)).toBe(false)
+    const { sessionId } = expectOk(await api.sessions.create(request({ cwd })))
+    expect(existsSync(cwd)).toBe(true)
+    const { items } = expectOk(await api.sessions.list(request({})))
+    expect(items.find(item => item.sessionId === sessionId)?.cwd).toBe(cwd)
+  })
+
+  it('fails loud when the project directory cannot be created', async () => {
+    const { api } = await boot()
+    const root = mkdtempSync(join(tmpdir(), 'dsh-host-create-cwd-fail-'))
+    const blocker = join(root, 'file-not-dir')
+    writeFileSync(blocker, 'x')
+    const response = await api.sessions.create(request({ cwd: join(blocker, 'child') }))
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('expected mkdir failure')
+    expect(response.result.error.code).toBe('internal')
+    expect(response.result.error.message).toMatch(/failed to ensure project directory/)
+  })
 })
 
 describe('sessions.prompt / cancel', () => {
+  it.each([
+    { name: 'host default', config: true, target: '5 words', maxTokens: 64 },
+    {
+      name: 'configured policy',
+      config: {
+        targetWords: 3,
+        targetCjkCharacters: 8,
+        maxInputBytes: 2_048,
+        maxOutputTokens: 24,
+        timeoutMs: 2_000,
+      },
+      target: '3 words',
+      maxTokens: 24,
+    },
+  ] satisfies {
+    name: string
+    config: true | SessionTitleLlmConfig
+    target: string
+    maxTokens: number
+  }[])('replaces the fallback with a model-backed first-message title using the $name', async ({ config, target, maxTokens }) => {
+    const modelTitle = 'Durable append-only session titles'
+    const running = await boot([textResponse('pong')], undefined, config)
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(ctx, agent)
+    expectOk(await api.sessions.prompt(request({
+      sessionId,
+      mode: 'queue' as const,
+      content: [{ type: 'text' as const, text: 'Explain why append-only logs make session titles durable.' }],
+    })))
+    await idle
+
+    await vi.waitFor(() => {
+      expect(agent.session.events.filter(event => event.type === 'session/title').map(event => event.data))
+        .toEqual([
+          {
+            title: 'Explain why append-only logs make',
+            messageSeqs: [1],
+            source: { kind: 'fallback' },
+          },
+          {
+            title: modelTitle,
+            messageSeqs: [1],
+            source: {
+              kind: 'provider',
+              provider: 'session-title-first-message-llm',
+              model: { provider: 'scripted', model: 'test-model' },
+            },
+          },
+        ])
+    })
+    const titleRequest = agent.session.events.find(event => event.type === 'session/title-llm-request')
+    expect(titleRequest?.data.system).toContain(target)
+    expect(titleRequest?.data.maxTokens).toBe(maxTokens)
+  })
+
+  it.each([
+    { name: 'host default', config: undefined, expected: 'Show the Web UI durable' },
+    {
+      name: 'configured limit',
+      config: { fallbackMaxWords: 2, fallbackMaxBytes: 40, maxTitleBytes: 80 },
+      expected: 'Show the',
+    },
+  ] satisfies { name: string; config: SessionTitleConfig | undefined; expected: string }[])(
+    'logs a durable fallback title with the $name',
+    async ({ config, expected }) => {
+      const running = await boot([textResponse('pong')], config)
+      const { api, ctx } = running
+      const { sessionId } = expectOk(await api.sessions.create(request({})))
+      const agent = ctx.agents.get(sessionId) as Agent
+      const idle = waitForIdle(ctx, agent)
+      expectOk(await api.sessions.prompt(request({
+        sessionId,
+        mode: 'queue' as const,
+        content: [{ type: 'text' as const, text: 'Show the Web UI durable session title' }],
+      })))
+      await idle
+
+      const title = agent.session.events.find(event => event.type === 'session/title')
+      expect(title?.data).toEqual({
+        title: expected,
+        messageSeqs: [1],
+        source: { kind: 'fallback' },
+      })
+    },
+  )
+
   it('queues a prompt whose rpcId rides into user/message, then the reply lands', async () => {
     const running = await boot([textResponse('pong')])
     const { api, ctx } = running
@@ -230,7 +395,7 @@ describe('sessions.prompt / cancel', () => {
     const { api, ctx } = running
     const { sessionId } = expectOk(await api.sessions.create(request({})))
     const agent = ctx.agents.get(sessionId) as Agent
-    agent.send([{ type: 'text', text: 'run forever' }])
+    agent.followup([{ type: 'text', text: 'run forever' }])
     expectOk(await api.sessions.cancel(request({ sessionId })))
 
     const missing = await api.sessions.cancel(request({ sessionId: 'session-none' as SessionId }))
@@ -249,8 +414,9 @@ describe('sessions.history', () => {
     const { sessionId } = expectOk(await first.api.sessions.create(request({})))
     const agent = first.ctx.agents.get(sessionId) as Agent
     const idle = waitForIdle(first.ctx, agent)
-    agent.send([{ type: 'text', text: 'save me' }])
+    agent.followup([{ type: 'text', text: 'save me' }])
     await idle
+    const titleEvent = await appendTitle(first.ctx, agent, 'Persisted title')
     await first.dispose()
 
     host = await startHost({
@@ -258,6 +424,8 @@ describe('sessions.history', () => {
     })
     host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter([]))
     expect(host.ctx.agents.get(sessionId)).toBeUndefined()
+    const abort = new AbortController()
+    const mux = host.api.events.mux(request({}), abort.signal)[Symbol.asyncIterator]()
     const [a, b] = await Promise.all([
       host.api.sessions.history(request({ sessionId })),
       host.api.sessions.history(request({ sessionId })),
@@ -268,6 +436,11 @@ describe('sessions.history', () => {
     }
     expect(host.ctx.agents.get(sessionId)).toBeDefined()
     expect(host.ctx.agents.list()).toHaveLength(1)
+    expect((await nextMux(mux)).payload).toMatchObject({ type: 'session/subscribed', sessionId })
+    expect((await nextMux(mux)).payload).toEqual(expect.objectContaining({
+      type: 'session/title', sessionId, title: 'Persisted title', eventSeq: titleEvent.seq,
+    }))
+    abort.abort()
   })
 
   it('errors session-not-found when resume fails, deduplicating concurrent resumes', async () => {
@@ -290,7 +463,7 @@ describe('sessions.history', () => {
     const agent = ctx.agents.get(sessionId) as Agent
     for (const text of ['q1', 'q2', 'q3']) {
       const idle = waitForIdle(ctx, agent)
-      agent.send([{ type: 'text', text }])
+      agent.followup([{ type: 'text', text }])
       await idle
     }
 
@@ -361,7 +534,7 @@ describe('events streams', () => {
 
     const agent = ctx.agents.get(sessionId) as Agent
     const idle = waitForIdle(ctx, agent)
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await idle
     const live = await stream.next()
     expect((live.value as RpcRequest<MuxFrame>).payload.type).toBe('session/event')
@@ -375,6 +548,43 @@ describe('events streams', () => {
     expect((await stream.next()).done).toBe(true)
   })
 
+  it('mux: projects durable titles after open baselines and immediately after live raw events', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const initial = await appendTitle(ctx, agent, 'Initial title')
+
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    expect((await nextMux(stream)).payload).toMatchObject({ type: 'session/subscribed', sessionId })
+    expect((await nextMux(stream)).payload).toEqual(expect.objectContaining({
+      type: 'session/title', sessionId, title: 'Initial title', eventSeq: initial.seq, updatedAt: initial.time,
+    }))
+
+    const revised = await appendTitle(ctx, agent, 'Revised title')
+    let raw: RpcRequest<MuxFrame>
+    do raw = await nextMux(stream)
+    while (!(raw.payload.type === 'session/event' && raw.payload.event.type === 'session/title'))
+    expect(raw.payload).toMatchObject({ type: 'session/event', sessionId, event: { seq: revised.seq } })
+    expect((await nextMux(stream)).payload).toEqual(expect.objectContaining({
+      type: 'session/title', sessionId, title: 'Revised title', eventSeq: revised.seq, updatedAt: revised.time,
+    }))
+    ac.abort()
+  })
+
+  it('mux: emits no title control for untitled subscriptions', async () => {
+    const { api } = await boot()
+    const first = expectOk(await api.sessions.create(request({}))).sessionId
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    expect((await nextMux(stream)).payload).toMatchObject({ type: 'session/subscribed', sessionId: first })
+
+    const second = expectOk(await api.sessions.create(request({}))).sessionId
+    expect((await nextMux(stream)).payload).toMatchObject({ type: 'session/subscribed', sessionId: second })
+    ac.abort()
+  })
+
   it('host: session lifecycle, status flips (disposed suppressed), and agent errors', async () => {
     const running = await boot([textResponse('x')])
     const { api, ctx } = running
@@ -387,7 +597,7 @@ describe('events streams', () => {
 
     const agent = ctx.agents.get(sessionId) as Agent
     const idle = waitForIdle(ctx, agent)
-    agent.send([{ type: 'text', text: 'run' }])
+    agent.followup([{ type: 'text', text: 'run' }])
     await idle
     const runningFrame = await stream.next()
     expect((runningFrame.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/session-status', running: true })
@@ -408,10 +618,175 @@ describe('events streams', () => {
   })
 })
 
-describe('respond stub', () => {
-  it('always reports not-pending (step2 registry pending)', async () => {
-    const { api } = await boot()
-    const receipt = await api.respond({ type: 'client-response', rpcId: RpcId('r'), result: { ok: true, value: null } })
-    expect(receipt).toEqual({ accepted: false, reason: 'not-pending' })
+describe('question request / response', () => {
+  const questions = [{
+    id: 'mode', question: 'Choose a mode',
+    options: [
+      { label: 'Fast (Recommended)', description: 'Move quickly.' },
+      { label: 'Careful', description: 'Review first.' },
+    ],
+  }]
+
+  it('waits, replays the same rpcId on reconnect, validates, and resolves first-wins', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    await stream.next() // subscribed baseline starts the generator and installs the queue
+
+    const answerPromise = ctx.userInteraction.ask({ questions, agent })
+    const requested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(requested.payload).toMatchObject({ type: 'question/requested', sessionId, questions })
+
+    const wrongSession = await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId: 'session-other', answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }] } },
+      },
+    })
+    expect(wrongSession).toEqual({ accepted: false, reason: 'bad-response' })
+    const badChoice = await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Unknown'] }] } },
+      },
+    })
+    expect(badChoice).toEqual({ accepted: false, reason: 'bad-response' })
+    const invalidResults = [
+      { ok: true as const, value: null },
+      { ok: true as const, value: { sessionId, answer: { answers: [] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'wrong', selected: ['Fast (Recommended)'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)', 'Fast (Recommended)'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)', 'Careful'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: [], custom: '   ' }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Careful'], custom: 'Other' }] } } },
+      { ok: false as const, error: { code: 'internal' as const, message: 'wrong error', details: {} } },
+    ]
+    for (const result of invalidResults) {
+      expect(await api.respond({
+        type: 'client-response', rpcId: requested.rpcId, result,
+      })).toEqual({ accepted: false, reason: 'bad-response' })
+    }
+
+    const reconnectAbort = new AbortController()
+    const replay = api.events.mux(request({}), reconnectAbort.signal)[Symbol.asyncIterator]()
+    await replay.next()
+    const replayed = (await replay.next()).value as RpcRequest<MuxFrame>
+    expect(replayed.rpcId).toBe(requested.rpcId)
+    expect(replayed.payload).toEqual(requested.payload)
+
+    const response = {
+      type: 'client-response' as const,
+      rpcId: requested.rpcId,
+      result: {
+        ok: true as const,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }] } },
+      },
+    }
+    const [first, duplicate] = await Promise.all([api.respond(response), api.respond(response)])
+    expect([first, duplicate]).toContainEqual({ accepted: true })
+    expect([first, duplicate]).toContainEqual({ accepted: false, reason: 'not-pending' })
+    await expect(answerPromise).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }],
+    })
+
+    const resolved = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(resolved.payload).toMatchObject({
+      type: 'question/resolved', sessionId, questionRpcId: requested.rpcId, outcome: 'answered',
+    })
+    expect(await api.respond(response)).toEqual({ accepted: false, reason: 'not-pending' })
+
+    const customQuestions = [{ id: 'detail', question: 'What else?' }]
+    const customAnswer = ctx.userInteraction.ask({ questions: customQuestions, agent })
+    const customRequested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: customRequested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'detail', selected: [], custom: 'Keep traces' }] } },
+      },
+    })).toEqual({ accepted: true })
+    await expect(customAnswer).resolves.toEqual({
+      answers: [{ id: 'detail', selected: [], custom: 'Keep traces' }],
+    })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: customRequested.rpcId, outcome: 'answered',
+    })
+
+    const blankAnswer = ctx.userInteraction.ask({ questions, agent })
+    const blankRequested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: blankRequested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: [] }] } },
+      },
+    })).toEqual({ accepted: true })
+    await expect(blankAnswer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: [] }],
+    })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: blankRequested.rpcId, outcome: 'answered',
+    })
+    ac.abort()
+    reconnectAbort.abort()
+  })
+
+  it('distinguishes user cancellation from owner abort and rejects late responses', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const streamAbort = new AbortController()
+    const stream = api.events.mux(request({}), streamAbort.signal)[Symbol.asyncIterator]()
+    await stream.next()
+
+    const cancelled = ctx.userInteraction.ask({ questions, agent }).catch((error: unknown) => error)
+    const requested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: { ok: false, error: { code: 'cancelled', message: 'skip', details: {} } },
+    })).toEqual({ accepted: true })
+    await expect(cancelled).resolves.toMatchObject({ code: 'ASK_CANCELLED' })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', outcome: 'cancelled',
+    })
+
+    const ownerAbort = new AbortController()
+    const aborted = ctx.userInteraction.ask({ questions, agent, signal: ownerAbort.signal })
+      .catch((error: unknown) => error)
+    const abortRequest = (await stream.next()).value as RpcRequest<MuxFrame>
+    ownerAbort.abort()
+    await expect(aborted).resolves.toMatchObject({ code: 'ASK_ABORTED' })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: abortRequest.rpcId, outcome: 'cancelled',
+    })
+    expect(await api.respond({
+      type: 'client-response', rpcId: abortRequest.rpcId,
+      result: { ok: false, error: { code: 'cancelled', message: 'late', details: {} } },
+    })).toEqual({ accepted: false, reason: 'not-pending' })
+    streamAbort.abort()
+  })
+
+  it('rejects missing routing and pre-abort, then aborts outstanding waits on disposal', async () => {
+    const running = await boot()
+    const { ctx } = running
+    await expect(ctx.userInteraction.ask({ questions })).rejects.toMatchObject({ code: 'ASK_MISSING_AGENT' })
+    const { sessionId } = expectOk(await running.api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const alreadyAborted = new AbortController()
+    alreadyAborted.abort()
+    await expect(ctx.userInteraction.ask({ questions, agent, signal: alreadyAborted.signal }))
+      .rejects.toMatchObject({ code: 'ASK_ABORTED' })
+
+    const outstanding = ctx.userInteraction.ask({ questions, agent })
+    const disposed = running.dispose()
+    host = undefined
+    await expect(outstanding).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await disposed
   })
 })
diff --git a/packages/host/runtime/tests/web-plugins.e2e.ts b/packages/host/runtime/tests/web-plugins.e2e.ts
deleted file mode 100644
index 45034dfa22..0000000000
--- a/packages/host/runtime/tests/web-plugins.e2e.ts
+++ /dev/null
@@ -1,71 +0,0 @@
-/**
- * Web UI plugin assembly: the in-memory Loader tree mounts all eight UI
- * packages (node halves), and the webserver registry built over it yields the
- * full __DSH_BOOT__ manifest — the P-I config-source bar end to end.
- *
- * The Loader imports plugin packages through their exports maps (lib/), so
- * this is a built-artifact e2e: it skips until the workspace build has run
- * (`pnpm run build`), like the other built-* e2e suites.
- */
-import { existsSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { Context } from 'cordis'
-import { afterEach, describe, expect, it } from 'vitest'
-import { createHostWebPluginRegistry } from '@deepseek-ai/dsh-host-webserver'
-import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
-
-const nodeRequire = createRequire(import.meta.url)
-const built = WEB_UI_PLUGINS.every((name) => {
-  try {
-    return existsSync(nodeRequire.resolve(name))
-  } catch {
-    return false
-  }
-})
-
-let root: Context | undefined
-
-afterEach(async () => {
-  await root?.fiber.dispose()
-  root = undefined
-})
-
-describe.skipIf(!built)('mountWebPlugins + registry', () => {
-  it('mounts the eight-package in-memory Loader tree and projects the boot manifest', async () => {
-    root = new Context()
-    const mounted = await mountWebPlugins(root)
-    const registry = createHostWebPluginRegistry({
-      ctx: root,
-      loader: mounted.loader,
-      resolvePkgJson: mounted.resolvePkgJson,
-      onError: (err) => { throw err },
-    })
-    const rows = registry.snapshot()
-    expect(rows.map(r => r.id)).toEqual([...WEB_UI_PLUGINS])
-    // The infra four are the early-load group; the UI four are not.
-    const immediate = rows.filter(r => r.immediately === true).map(r => r.id)
-    expect(immediate).toEqual([
-      '@deepseek-ai/dsh-client-connection',
-      '@deepseek-ai/dsh-client-runtime',
-      '@deepseek-ai/dsh-client-ui-theme',
-      '@deepseek-ai/dsh-client-i18n',
-    ])
-    // Every row resolves a client path under its own package lib/.
-    for (const row of rows) {
-      expect(registry.clientPath(row.id)).toMatch(/lib[/\\]client\.js$/)
-      expect(row.url).toBe(`/plugins/${row.id}/client.js`)
-    }
-    registry.dispose()
-  })
-
-  it('is idempotent: a second mount reuses the loader and creates no duplicate entries', async () => {
-    root = new Context()
-    await mountWebPlugins(root)
-    const second = await mountWebPlugins(root)
-    // ctx.loader hands out a fresh traced proxy per access, so loader identity
-    // is not assertable; the observable contract is a single entry per package.
-    const names = [...second.loader.entries()].map(e => e.options.name)
-      .filter(n => (WEB_UI_PLUGINS as readonly string[]).includes(n))
-    expect(names.length).toBe(WEB_UI_PLUGINS.length)
-  })
-})
diff --git a/packages/host/runtime/tests/web-plugins.spec.ts b/packages/host/runtime/tests/web-plugins.spec.ts
index 6c6a996517..b558c253c2 100644
--- a/packages/host/runtime/tests/web-plugins.spec.ts
+++ b/packages/host/runtime/tests/web-plugins.spec.ts
@@ -1,13 +1,20 @@
 /**
- * mountWebPlugins unit coverage (keyless; the real eight-package walk is the
- * built-artifact e2e). The Loader-facing behavior — baseUrl anchoring, entry
- * creation with idempotent reuse, the fiber-less fail-loud sweep, and the
- * resolver seam — is exercised against a stubbed loader service so it runs
- * without built lib/ artifacts.
+ * mountWebPlugins unit coverage (keyless). The Loader-facing behavior —
+ * baseUrl anchoring, entry creation with idempotent reuse, the fiber-less
+ * fail-loud sweep, and the resolver seam — is exercised against a stubbed
+ * loader service so it runs without built lib/ artifacts. The roster is
+ * caller-supplied now (composition moved to apps/cli), so these tests pass
+ * their own lists.
  */
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it } from 'vitest'
-import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
+import { mountWebPlugins } from '../src/web-plugins.ts'
+
+const ROSTER = [
+  '@deepseek-ai/dsh-plugin-a',
+  '@deepseek-ai/dsh-plugin-b',
+  '@deepseek-ai/dsh-plugin-c',
+] as const
 
 interface FakeEntry {
   options: { name: string }
@@ -47,60 +54,50 @@ function withLoader(entriesList: FakeEntry[], onCreate?: (name: string) => void)
 }
 
 describe('mountWebPlugins (stubbed loader)', () => {
-  it('creates one entry per UI plugin, awaits the tree, and returns the loader view + resolver', async () => {
+  it('creates one entry per roster package, awaits the tree, and returns the loader view + resolver', async () => {
     const entriesList: FakeEntry[] = []
     const { ctx, loader } = withLoader(entriesList, (name) => {
       entriesList.push({ options: { name }, fiber: {}, disabled: false })
     })
-    const mounted = await mountWebPlugins(ctx)
-    expect(loader.created).toEqual([...WEB_UI_PLUGINS])
+    const mounted = await mountWebPlugins(ctx, ROSTER, import.meta.url)
+    expect(loader.created).toEqual([...ROSTER])
     expect(loader.awaited).toBe(1)
-    expect([...mounted.loader.entries()].map(e => e.options.name)).toEqual([...WEB_UI_PLUGINS])
-    // The resolver resolves this package's own manifest through real module resolution.
+    expect([...mounted.loader.entries()].map(e => e.options.name)).toEqual([...ROSTER])
+    // The resolver resolves a real package manifest through real module resolution, anchored at this test file.
     expect(mounted.resolvePkgJson('@deepseek-ai/dsh-host-runtime')).toMatch(/package\.json$/)
     expect(ctx.baseUrl).toBeDefined()
   })
 
   it('reuses existing entries (idempotent mount creates no duplicates)', async () => {
-    const preexisting: FakeEntry[] = WEB_UI_PLUGINS.map(name => ({ options: { name }, fiber: {}, disabled: false }))
+    const preexisting: FakeEntry[] = ROSTER.map(name => ({ options: { name }, fiber: {}, disabled: false }))
     const { ctx, loader } = withLoader(preexisting)
-    await mountWebPlugins(ctx)
+    await mountWebPlugins(ctx, ROSTER, import.meta.url)
     expect(loader.created).toEqual([])
   })
 
-  it('throws listing every fiber-less entry (silent import failure must not drop a UI plugin)', async () => {
+  it('throws listing every fiber-less entry (silent import failure must not drop a client plugin)', async () => {
     const entriesList: FakeEntry[] = []
     const { ctx } = withLoader(entriesList, (name) => {
-      // First two load; the rest stay fiber-less (import failed silently).
-      entriesList.push({ options: { name }, fiber: entriesList.length < 2 ? {} : undefined, disabled: false })
+      // First one loads; the rest stay fiber-less (import failed silently).
+      entriesList.push({ options: { name }, fiber: entriesList.length < 1 ? {} : undefined, disabled: false })
     })
-    await expect(mountWebPlugins(ctx)).rejects.toThrow(/UI plugin\(s\) failed to load: .*dsh-client-ui-theme/)
+    await expect(mountWebPlugins(ctx, ROSTER, import.meta.url))
+      .rejects.toThrow(/client plugin\(s\) failed to load: .*dsh-plugin-c/)
   })
 
   it('skips disabled entries in the fail-loud sweep (disabled is the one valid fiber-less state)', async () => {
-    const entriesList: FakeEntry[] = WEB_UI_PLUGINS.map(name => ({ options: { name }, fiber: undefined, disabled: true }))
+    const entriesList: FakeEntry[] = ROSTER.map(name => ({ options: { name }, fiber: undefined, disabled: true }))
     const { ctx } = withLoader(entriesList)
-    await expect(mountWebPlugins(ctx)).resolves.toBeDefined()
+    await expect(mountWebPlugins(ctx, ROSTER, import.meta.url)).resolves.toBeDefined()
   })
 
   it('mounts the real Loader when none is present (the ctx.plugin(Loader) branch)', async () => {
     root = new Context()
-    // Environment-dependent outcome: with built lib/ the eight imports load
-    // and the mount resolves; without them every entry stays fiber-less and
-    // the sweep throws its loud list. Either way the branch under test is the
-    // Loader auto-mount. Manual try/catch keeps cordis-traced proxies out of
-    // expect()'s formatting path (pretty-format probes throw on them).
-    // Plain string: the success sentinel and error text share one channel.
-    let outcome: string
-    try {
-      await mountWebPlugins(root)
-      outcome = 'resolved'
-    } catch (error) {
-      outcome = error instanceof Error ? error.message : String(error)
-    }
-    expect(outcome === 'resolved' || /UI plugin\(s\) failed to load/.test(outcome)).toBe(true)
+    // An empty roster keeps this keyless and artifact-free: the branch under
+    // test is only the Loader auto-mount.
+    await mountWebPlugins(root, [], import.meta.url)
     expect(root.get('loader') !== undefined).toBe(true)
-  }, 30_000) // built-env run imports eight real plugin packages through the Loader
+  }, 30_000) // cold-cache import of the real vendored Loader crosses the network-disk 5s default
 
   it('keeps a caller-set baseUrl (anchors only when absent)', async () => {
     const entriesList: FakeEntry[] = []
@@ -108,7 +105,7 @@ describe('mountWebPlugins (stubbed loader)', () => {
       entriesList.push({ options: { name }, fiber: {}, disabled: false })
     })
     ctx.baseUrl = 'file:///caller/anchor/'
-    await mountWebPlugins(ctx)
+    await mountWebPlugins(ctx, ROSTER, import.meta.url)
     expect(ctx.baseUrl).toBe('file:///caller/anchor/')
   })
 })
diff --git a/packages/host/runtime/tsconfig.json b/packages/host/runtime/tsconfig.json
index 08efb88294..aee28b5371 100644
--- a/packages/host/runtime/tsconfig.json
+++ b/packages/host/runtime/tsconfig.json
@@ -23,6 +23,12 @@
     {
       "path": "../../core/session"
     },
+    {
+      "path": "../../session-title/session-title"
+    },
+    {
+      "path": "../../session-title/session-title-first-message-llm"
+    },
     {
       "path": "../../core/system-prompt"
     },
@@ -62,9 +68,6 @@
     {
       "path": "../../fs/tool-fs-search"
     },
-    {
-      "path": "../../context/workspace-context"
-    },
     {
       "path": "../../llm/token-meter"
     },
@@ -120,28 +123,10 @@
       "path": "../../../vendor/loader"
     },
     {
-      "path": "../../client/connection"
+      "path": "../../context/workspace-context"
     },
     {
-      "path": "../../client/runtime"
-    },
-    {
-      "path": "../../client/ui-theme"
-    },
-    {
-      "path": "../../client/i18n"
-    },
-    {
-      "path": "../../client/ui-layout"
-    },
-    {
-      "path": "../../client/ui-sidebar"
-    },
-    {
-      "path": "../../client/ui-conversation"
-    },
-    {
-      "path": "../../client/ui-trajectory"
+      "path": "../../ui/user-interaction"
     }
   ]
 }
diff --git a/packages/host/webserver/README.md b/packages/host/webserver/README.md
index 9e59699bd6..baa57dbfe1 100644
--- a/packages/host/webserver/README.md
+++ b/packages/host/webserver/README.md
@@ -8,6 +8,8 @@ Client-disconnect detection hangs off the **response** `close` event, not the re
 
 A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and reported to `onError`; it never becomes a process-killing unhandled rejection.
 
+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 pure HTTP carrier between the browser and the injected API handler; nothing here reaches a model request.
diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts
index 074bfe395c..60ad92d18c 100644
--- a/packages/host/webserver/src/index.ts
+++ b/packages/host/webserver/src/index.ts
@@ -13,12 +13,14 @@ import { readFile } from 'node:fs/promises'
 import type { AddressInfo } from 'node:net'
 import { dirname } from 'node:path'
 import { serveStatic } from './static.ts'
-import type { HostWebPluginRegistry } from './web-plugins.ts'
+import { createPluginEventChannel } from './plugin-events.ts'
+import type { HostWebPluginRegistry, WebBootGraph } from './web-plugins.ts'
 
 export { createHostWebPluginRegistry } from './web-plugins.ts'
 export type {
-  HostWebPluginRegistry, LoaderEntryView, LoaderView, WebPluginBootEntry, WebPluginRegistryDeps,
+  HostWebPluginRegistry, LoaderEntryView, LoaderView, WebBootEntry, WebBootGraph, WebPluginRegistryDeps,
 } from './web-plugins.ts'
+export type { PluginEventChannel, PluginEventFrame } from './plugin-events.ts'
 
 /** Options for startWebServer. */
 export interface WebServerOptions {
@@ -34,11 +36,14 @@ export interface WebServerOptions {
   /** Fetch-shaped API carrier; /api/*-prefixed requests are bridged to it. */
   apiHandler: { fetch: typeof fetch }
   /**
-   * Web plugin table. When present, every index.html response carries a
-   * `window.__DSH_BOOT__` manifest script and `/plugins/<id>/client.js` serves
-   * each plugin's client bundle. Absent = both surfaces off (carrier-only use).
+   * Web plugin table. When present, every index.html response carries the
+   * `window.__DSH_BOOT__` entry graph script, `/plugins/<id>/client.js` serves
+   * each fetch entry's client bundle, and `GET /plugins/events` streams graph/
+   * rebuilt frames (SSE) — rebuilt frames ride the registry's own bundle-watch
+   * notifications (`onRebuilt`). Absent = all three surfaces off (carrier-only
+   * use).
    */
-  webPlugins?: Pick<HostWebPluginRegistry, 'snapshot' | 'clientPath'>
+  webPlugins?: Pick<HostWebPluginRegistry, 'graph' | 'clientPath' | 'onRebuilt'>
 }
 
 /** Listening web server handle. */
@@ -70,8 +75,14 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
   const distRoot = dirname(distIndex)
   const renderIndex = webPlugins === undefined ? undefined : async (): Promise<string> => {
     const html = await readFile(distIndex, 'utf8')
-    return injectBootManifest(html, webPlugins.snapshot())
+    return injectBootManifest(html, webPlugins.graph())
   }
+  const pluginEvents = webPlugins === undefined ? undefined : createPluginEventChannel()
+  // Rebuilt frames come from the registry's own bundle watch (dev mode); a
+  // prod registry without watching simply never notifies.
+  const unsubscribeRebuilt = webPlugins !== undefined && pluginEvents !== undefined
+    ? webPlugins.onRebuilt((id, rev) => { pluginEvents.broadcast({ type: 'rebuilt', id, rev }) })
+    : undefined
 
   const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server
@@ -86,6 +97,10 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
       res.end()
       return
     }
+    if (webPlugins !== undefined && pluginEvents !== undefined && rawPath === '/plugins/events') {
+      pluginEvents.connect(res, webPlugins.graph())
+      return
+    }
     if (webPlugins !== undefined && rawPath.startsWith('/plugins/') && rawPath.endsWith('/client.js')) {
       await servePluginBundle(decodeURIComponent(rawPath), res, webPlugins)
       return
@@ -110,6 +125,7 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
 
   let closing: Promise<void> | undefined
   const close = (): Promise<void> => (closing ??= new Promise((resolveClose) => {
+    unsubscribeRebuilt?.()
     server.close(() => { resolveClose() })
     server.closeAllConnections()
   }))
@@ -125,15 +141,15 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
 }
 
 /**
- * Inject the boot manifest into index.html: `window.__DSH_BOOT__` as the first
- * script in <head> (before the shell bundle reads it). `<` is escaped in the
- * JSON so plugin-controlled strings cannot break out of the script element.
+ * Inject the boot entry graph into index.html: `window.__DSH_BOOT__` as the
+ * first script in <head> (before the shell bundle reads it). `<` is escaped in
+ * the JSON so plugin-controlled strings cannot break out of the script element.
  * @param html - the index.html source.
- * @param plugins - the manifest rows from the registry snapshot.
- * @returns the html with the manifest script injected.
+ * @param graph - the composed entry graph from the registry.
+ * @returns the html with the graph script injected.
  */
-export function injectBootManifest(html: string, plugins: readonly unknown[]): string {
-  const json = JSON.stringify({ plugins }).replaceAll('<', '\\u003c')
+export function injectBootManifest(html: string, graph: WebBootGraph): string {
+  const json = JSON.stringify(graph).replaceAll('<', '\\u003c')
   const script = `<script>window.__DSH_BOOT__ = ${json}</script>`
   const head = html.indexOf('<head>')
   if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`
@@ -141,7 +157,12 @@ export function injectBootManifest(html: string, plugins: readonly unknown[]): s
   return `${script}${html}`
 }
 
-/** Serve one plugin client bundle from the registry table (unknown id = 404; the id may contain a scope slash). */
+/**
+ * Serve one plugin client bundle from the registry table (unknown id = 404;
+ * the id may contain a scope slash). The `?rev=` query is a cache-busting
+ * parameter only — serving ignores it; `no-cache` makes the browser revalidate
+ * so a stale rev never sticks.
+ */
 async function servePluginBundle(
   pathname: string, res: ServerResponse, webPlugins: Pick<HostWebPluginRegistry, 'clientPath'>,
 ): Promise<void> {
@@ -154,7 +175,7 @@ async function servePluginBundle(
   }
   try {
     const body = await readFile(path)
-    res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' })
+    res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' })
     res.end(body)
   } catch {
     // Registered but unreadable (bundle not built yet): loud 404 beats a silent SPA-fallback HTML page.
diff --git a/packages/host/webserver/src/invariant.ts b/packages/host/webserver/src/invariant.ts
index 87e3463121..a204c93775 100644
--- a/packages/host/webserver/src/invariant.ts
+++ b/packages/host/webserver/src/invariant.ts
@@ -15,25 +15,27 @@ export const name = 'host-webserver-invariant'
 export const inject = ['invariants']
 
 /**
- * Owned relation: the web plugin registry's boot manifest must stay
- * self-consistent — every snapshot() row must resolve a clientPath under the
- * same id (the /plugins/<id>/client.js URL it advertises would otherwise 404
- * on a browser that just received the manifest). Checked synchronously on
- * every rescan trigger (cordis 'internal/plugin'): snapshot() and
- * clientPath() read the same table object, so the relation is
- * self-consistent at any instant — no need to wait out the registry's own
- * debounced rescan. The registry arrives through the context key the
- * assembly publishes it under.
+ * Owned relation: the web plugin registry's boot entry graph must stay
+ * self-consistent — every row must resolve a clientPath under the same id
+ * (the /plugins/<id>/client.js URL it advertises would otherwise 404 on a
+ * browser that just received the graph). Checked synchronously on every
+ * rescan trigger (cordis 'internal/plugin'): graph() and clientPath() read
+ * the same table object, so the relation is self-consistent at any instant —
+ * no need to wait out the registry's own debounced rescan. The registry
+ * arrives through the context key the assembly publishes it under.
  */
 const install: InvariantInstaller = (ctx, fail) => {
   ctx.on('internal/plugin', () => {
     const registry = ctx.get('webPlugins') as
-      | { snapshot(): { id: string; url: string }[]; clientPath(id: string): string | undefined }
+      | {
+        graph(): { entries: { id: string; url: string }[] }
+        clientPath(id: string): string | undefined
+      }
       | undefined
     if (registry === undefined) return // carrier-only deployments never publish the registry
-    for (const row of registry.snapshot()) {
+    for (const row of registry.graph().entries) {
       if (registry.clientPath(row.id) === undefined) {
-        fail(`web plugin manifest row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
+        fail(`web plugin graph row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
       }
     }
   }, { global: true })
diff --git a/packages/host/webserver/src/plugin-events.ts b/packages/host/webserver/src/plugin-events.ts
new file mode 100644
index 0000000000..b438edf948
--- /dev/null
+++ b/packages/host/webserver/src/plugin-events.ts
@@ -0,0 +1,56 @@
+/**
+ * `/plugins/events` SSE channel: the system-side push surface for the client
+ * entry graph (connect → current graph frame; dev rebuild → rebuilt frame).
+ * Presentation-only wire — frames never enter the session log (distinct from
+ * the /api/* session SSE, which is api-contract territory). Connections are
+ * plain node:http responses held in a set; the server's closeAllConnections
+ * tears them down on shutdown.
+ */
+
+import type { ServerResponse } from 'node:http'
+import type { WebBootGraph } from './web-plugins.ts'
+
+/** One `/plugins/events` frame: the full graph on connect, or one rebuilt bundle notice. */
+export type PluginEventFrame =
+  | { type: 'graph'; graph: WebBootGraph }
+  | { type: 'rebuilt'; id: string; rev: string }
+
+/** Broadcast surface owned by the webserver routing layer. */
+export interface PluginEventChannel {
+  /** Adopt one incoming SSE request: writes the SSE preamble and the current-graph frame, then keeps the response open. */
+  connect(res: ServerResponse, graph: WebBootGraph): void
+  /** Push one frame to every open connection. */
+  broadcast(frame: PluginEventFrame): void
+}
+
+/** Serialize one frame as an SSE data line. */
+function sseData(frame: PluginEventFrame): string {
+  return `data: ${JSON.stringify(frame)}\n\n`
+}
+
+/**
+ * Create the channel (one per running server).
+ * @returns the connect/broadcast surface.
+ */
+export function createPluginEventChannel(): PluginEventChannel {
+  const connections = new Set<ServerResponse>()
+  return {
+    connect(res, graph) {
+      res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        'connection': 'keep-alive',
+      })
+      // Comment line on open so clients/proxies see a live channel even when
+      // no rebuild ever happens; EventSource frame parsing skips it naturally.
+      res.write(': connected\n\n')
+      res.write(sseData({ type: 'graph', graph }))
+      connections.add(res)
+      res.on('close', () => { connections.delete(res) })
+    },
+    broadcast(frame) {
+      const line = sseData(frame)
+      for (const res of connections) res.write(line)
+    },
+  }
+}
diff --git a/packages/host/webserver/src/web-plugins.ts b/packages/host/webserver/src/web-plugins.ts
index ee1e72f34c..4e95e7a091 100644
--- a/packages/host/webserver/src/web-plugins.ts
+++ b/packages/host/webserver/src/web-plugins.ts
@@ -1,10 +1,17 @@
 /**
- * HostWebPluginRegistry: discovers web-client plugins among the host Loader's
- * loaded entries by their package.json `dshClient` declaration and resolves
- * each one's client bundle path from `exports["./client"]`. The webserver
- * consumes the table to emit `window.__DSH_BOOT__` and to serve
- * `GET /plugins/<id>/client.js`. Discovery is declaration-only: plugin authors
- * write package.json; no serve() call surface exists.
+ * HostWebPluginRegistry: composes the client entry graph served as
+ * `window.__DSH_BOOT__` ({rev, entries}). Every row is discovered among the
+ * host Loader's loaded entries by its package.json `dshClient` declaration
+ * (all client plugin packages arrive by fetch — one uniform bundle shape),
+ * resolving each one's client bundle path from `exports["./client"]` and
+ * hashing the bundle content into a `rev` (cache busting + HMR diff anchor).
+ * `inject` edges and the `immediately` prefetch mark come from the manifest
+ * (dshClient — the package owns its dependency edges and its boot tier); the
+ * composition layer contributes only the roster. The webserver consumes the
+ * table to emit the boot graph and to serve `GET /plugins/<id>/client.js`;
+ * in dev mode the registry additionally stat-polls each scanned bundle file
+ * and re-hashes + notifies `onRebuilt` subscribers on change (the rebuild
+ * signal is the registry's own observation — no builder protocol exists).
  *
  * The vendored loader emits no "entry loaded" event (only `loader/entry-init`,
  * which fires at Entry construction before import/apply), so the registry
@@ -14,33 +21,58 @@
  * fresh within a process lifetime.
  */
 
-import { readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { readFileSync, statSync, type Stats } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { Context } from 'cordis'
 
-/** One `window.__DSH_BOOT__.plugins` row (wire shape of api-contracts v3 §9.2). */
-export interface WebPluginBootEntry {
-  /** Plugin id = package name (may contain a scope slash). */
+/** One composed client entry (`window.__DSH_BOOT__.entries` row). */
+export interface WebBootEntry {
+  /** Entry name == package name. */
   id: string
-  /** Bundle URL served by this webserver (`/plugins/<id>/client.js`). */
+  /** Bundle URL served by this webserver (`/plugins/<id>/client.js?rev=<rev>`). */
   url: string
-  /** Client-half load dependencies (plugin ids), topologically ordered by the client loader. */
-  inject: string[]
-  /** Marks the early-load group: fetched in parallel and applied before all other plugins. */
+  /** Bundle content hash (sha1, shortened). */
+  rev: string
+  /** Package-name dependency edges from the manifest (dshClient.inject), informational (preflight/HMR display). */
+  inject?: string[]
+  /** Boot phase-one prefetch tier: the shell fetches these bundles in parallel before creating entries. */
   immediately?: boolean
 }
 
-/** The web plugin table consumed by the boot injection and the bundle endpoint. */
+/** The composed entry graph: injected into index.html and pushed on /plugins/events connect. */
+export interface WebBootGraph {
+  /** Consistency anchor over all rows: changes whenever any entry row changes. */
+  rev: string
+  /** All composed entries (order carries no semantics; governance ordering is the client Loader's job). */
+  entries: WebBootEntry[]
+}
+
+/** The web plugin table consumed by the boot injection, the bundle endpoint, and the rebuild channel. */
 export interface HostWebPluginRegistry {
-  /** Current manifest rows (stable order: loader entry order). */
-  snapshot(): WebPluginBootEntry[]
+  /** Current composed entry graph (stable object between changes). */
+  graph(): WebBootGraph
   /**
-   * Absolute path of a plugin's client bundle.
-   * @param id - plugin id (package name).
+   * 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
-  /** Remove the loader subscription. */
+  /**
+   * Re-hash one entry's bundle: updates the row's rev/url and the graph rev.
+   * The dev bundle watch calls this on every observed file change.
+   * @param id - entry id (package name).
+   * @returns the new bundle rev, or undefined for an unknown id.
+   */
+  rebuilt(id: string): string | undefined
+  /**
+   * Subscribe to bundle rebuilds observed by the dev watch (only fires when
+   * the re-hash produced a different rev — an unchanged bundle is silent).
+   * @param listener - receives the entry id and its new bundle rev.
+   * @returns the unsubscriber.
+   */
+  onRebuilt(listener: (id: string, rev: string) => void): () => void
+  /** Remove the loader subscription, all bundle watches, and all rebuild listeners. */
   dispose(): void
 }
 
@@ -72,20 +104,38 @@ export interface WebPluginRegistryDeps {
   resolvePkgJson: (name: string) => string
   /** Sink for rescan failures (the initial scan throws instead — misconfiguration fails loud at load). */
   onError: (err: Error) => void
+  /**
+   * Dev-mode bundle watching: stat-poll every scanned row's client bundle
+   * with an explicit stat baseline (polling by design: network mounts deliver
+   * no inotify events) and re-hash + notify onRebuilt subscribers on change.
+   * Absent = no watching (prod composition).
+   */
+  watch?: {
+    /** Stat-poll interval in milliseconds; default 500 (the build-side watcher's polling default). */
+    intervalMs?: number
+  }
 }
 
 /** package.json `dshClient` declaration shape (file boundary — validated field by field). */
 interface DshClientDeclaration {
   inject?: string[]
   platform: string
+  /** Boot phase-one prefetch mark; absent means lazy (fetched on demand). */
   immediately?: boolean
 }
 
 interface WebPluginRecord {
-  entry: WebPluginBootEntry
+  entry: WebBootEntry
   clientPath: string
 }
 
+interface WatchedBundle {
+  path: string
+  mtimeMs: number
+  size: number
+  dirty: boolean
+}
+
 /** Narrow an unknown parsed JSON value to the dshClient declaration, throwing on malformed fields. */
 function parseDshClient(name: string, value: unknown): DshClientDeclaration | undefined {
   if (value === undefined) return undefined
@@ -122,15 +172,132 @@ function clientExportOf(name: string, exportsField: unknown): string | undefined
   throw new Error(`web-plugins: ${name} exports["./client"] has an unsupported shape`)
 }
 
+/** sha1 content hash shortened to 12 hex chars (bundle rev / graph rev). */
+function shortHash(input: string | Buffer): string {
+  return createHash('sha1').update(input).digest('hex').slice(0, 12)
+}
+
+/** Graph row for one bundle rev (url carries the rev as its cache-busting query). */
+function graphRow(id: string, rev: string, inject: string[] | undefined, immediately: boolean): WebBootEntry {
+  return {
+    id,
+    url: `/plugins/${id}/client.js?rev=${rev}`,
+    rev,
+    ...(inject !== undefined ? { inject } : {}),
+    ...(immediately ? { immediately: true } : {}),
+  }
+}
+
+/** Compose the graph value from the current table. */
+function composeGraph(table: Map<string, WebPluginRecord>): WebBootGraph {
+  const entries = [...table.values()].map(record => record.entry)
+  return { rev: shortHash(JSON.stringify(entries)), entries }
+}
+
 /**
  * Build the web plugin registry: scan once synchronously (a malformed
- * declaration throws here — load-time fail loud), then rescan on
- * `internal/plugin`, microtask-debounced (failures go to `deps.onError`).
- * @param deps - loader view, resolution hook, and error sink (see {@link WebPluginRegistryDeps}).
+ * declaration, an unbuilt bundle, or an invalid watch interval throws here —
+ * load-time fail loud), then rescan on `internal/plugin`, microtask-debounced
+ * (failures go to `deps.onError`). With `deps.watch`, every scanned bundle
+ * file is stat-polled and a content change re-hashes the row and notifies
+ * `onRebuilt` subscribers.
+ * @param deps - loader view, resolution hook, error sink, and optional dev watch (see {@link WebPluginRegistryDeps}).
  * @returns the registry handle.
  */
 export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWebPluginRegistry {
+  const watchInterval = deps.watch === undefined ? undefined : deps.watch.intervalMs ?? 500
+  if (watchInterval !== undefined && (!Number.isInteger(watchInterval) || watchInterval <= 0)) {
+    throw new Error(`web-plugins: watch.intervalMs must be a positive integer (got ${String(deps.watch?.intervalMs)})`)
+  }
+
+  const stageWatches = (
+    candidateTable: Map<string, WebPluginRecord>,
+    currentWatches: Map<string, WatchedBundle>,
+  ): Map<string, WatchedBundle> => {
+    const candidateWatches = new Map<string, WatchedBundle>()
+    if (watchInterval === undefined) return candidateWatches
+    for (const [id, record] of candidateTable) {
+      const current = currentWatches.get(id)
+      if (current?.path === record.clientPath) {
+        candidateWatches.set(id, { ...current })
+        continue
+      }
+      const baseline = statSync(record.clientPath)
+      candidateWatches.set(id, {
+        path: record.clientPath,
+        mtimeMs: baseline.mtimeMs,
+        size: baseline.size,
+        dirty: false,
+      })
+    }
+    return candidateWatches
+  }
+
   let table = scan(deps)
+  let graph = composeGraph(table)
+  let watched = stageWatches(table, new Map())
+  const rebuildListeners = new Set<(id: string, rev: string) => void>()
+
+  const rebuilt = (id: string): string | undefined => {
+    const record = table.get(id)
+    if (record === undefined) return undefined
+    const rev = shortHash(readFileSync(record.clientPath))
+    record.entry = graphRow(id, rev, record.entry.inject, record.entry.immediately === true)
+    graph = composeGraph(table)
+    return rev
+  }
+
+  // Dev bundle watch: capture every row's baseline synchronously before the
+  // registry is returned, then poll those baselines. fs.watchFile establishes
+  // its first baseline asynchronously, so an immediate rebuild can otherwise
+  // become the baseline and disappear without an observed delta.
+  const pollWatches = (): void => {
+    for (const [id, watch] of watched) {
+      let current: Stats
+      try {
+        current = statSync(watch.path)
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code
+        if (code === 'ENOENT') {
+          watch.dirty = true
+          continue
+        }
+        deps.onError(error instanceof Error ? error : new Error(String(error)))
+        continue
+      }
+      if (!watch.dirty && current.mtimeMs === watch.mtimeMs && current.size === watch.size) continue
+      const before = table.get(id)?.entry.rev
+      let rev: string | undefined
+      try {
+        rev = rebuilt(id)
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code
+        if (code === 'ENOENT') {
+          watch.dirty = true
+          continue
+        }
+        watch.mtimeMs = current.mtimeMs
+        watch.size = current.size
+        deps.onError(error instanceof Error ? error : new Error(String(error)))
+        continue
+      }
+      watch.mtimeMs = current.mtimeMs
+      watch.size = current.size
+      watch.dirty = false
+      if (rev === undefined || rev === before) continue
+      for (const notify of rebuildListeners) {
+        // A throwing subscriber must not skip later subscribers or escape the
+        // polling callback into the process event loop.
+        try {
+          notify(id, rev)
+        } catch (error) {
+          deps.onError(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+    }
+  }
+  const watchTimer = watchInterval === undefined ? undefined : setInterval(pollWatches, watchInterval)
+  watchTimer?.unref()
 
   let pending = false
   const unsubscribe = deps.ctx.on('internal/plugin', () => {
@@ -139,9 +306,14 @@ export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWe
     queueMicrotask(() => {
       pending = false
       try {
-        table = scan(deps)
+        const candidateTable = scan(deps)
+        const candidateGraph = composeGraph(candidateTable)
+        const candidateWatches = stageWatches(candidateTable, watched)
+        table = candidateTable
+        graph = candidateGraph
+        watched = candidateWatches
       } catch (error) {
-        // Keep serving the previous table: a mid-flight rescan failure must not
+        // Keep serving the previous graph: a mid-flight rescan failure must not
         // take down the boot manifest for plugins that were fine.
         deps.onError(error instanceof Error ? error : new Error(String(error)))
       }
@@ -149,13 +321,23 @@ export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWe
   })
 
   return {
-    snapshot: () => [...table.values()].map(record => record.entry),
+    graph: () => graph,
     clientPath: id => table.get(id)?.clientPath,
-    dispose: () => { unsubscribe() },
+    rebuilt,
+    onRebuilt: (listener) => {
+      rebuildListeners.add(listener)
+      return () => { rebuildListeners.delete(listener) }
+    },
+    dispose: () => {
+      unsubscribe()
+      if (watchTimer !== undefined) clearInterval(watchTimer)
+      watched.clear()
+      rebuildListeners.clear()
+    },
   }
 }
 
-/** One full table build from the loader's current entries. */
+/** One full table build from the loader's current entries (bundle content is hashed here — an unreadable bundle throws). */
 function scan(deps: WebPluginRegistryDeps): Map<string, WebPluginRecord> {
   const table = new Map<string, WebPluginRecord>()
   for (const entry of deps.loader.entries()) {
@@ -170,15 +352,9 @@ function scan(deps: WebPluginRegistryDeps): Map<string, WebPluginRecord> {
     if (clientRel === undefined) {
       throw new Error(`web-plugins: ${name} declares dshClient but exports no "./client" bundle`)
     }
-    table.set(name, {
-      entry: {
-        id: name,
-        url: `/plugins/${name}/client.js`,
-        inject: decl.inject ?? [],
-        ...(decl.immediately === true ? { immediately: true } : {}),
-      },
-      clientPath: join(dirname(pkgPath), clientRel),
-    })
+    const clientPath = join(dirname(pkgPath), clientRel)
+    const rev = shortHash(readFileSync(clientPath))
+    table.set(name, { entry: graphRow(name, rev, decl.inject, decl.immediately === true), clientPath })
   }
   return table
 }
diff --git a/packages/host/webserver/tests/invariant.spec.ts b/packages/host/webserver/tests/invariant.spec.ts
index 8fddba992a..f9d5ba4490 100644
--- a/packages/host/webserver/tests/invariant.spec.ts
+++ b/packages/host/webserver/tests/invariant.spec.ts
@@ -1,7 +1,7 @@
 /**
- * Webserver invariant companion: the boot-manifest consistency audit — every
- * registry snapshot row must resolve a clientPath, checked on fiber lifecycle
- * events against the assembly-published 'webPlugins' context key.
+ * Webserver invariant companion: the boot-graph consistency audit — every
+ * fetch-arrival graph row must resolve a clientPath, checked on fiber
+ * lifecycle events against the assembly-published 'webPlugins' context key.
  */
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
@@ -9,7 +9,7 @@ import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as WebserverInvariant from '../src/invariant.ts'
 
 interface RegistryStub {
-  snapshot(): { id: string; url: string }[]
+  graph(): { entries: { id: string; url: string }[] }
   clientPath(id: string): string | undefined
 }
 
@@ -33,18 +33,18 @@ describe('webserver manifest invariant', () => {
     expect(() => { trigger(bare) }).not.toThrow() // no 'webPlugins' key published
 
     const consistent = await setup({
-      snapshot: () => [{ id: 'p1', url: '/plugins/p1/client.js' }],
-      clientPath: () => '/tmp/p1/lib/client.js',
+      graph: () => ({ entries: [{ id: 'p1', url: '/plugins/p1/client.js?rev=abc' }] }),
+      clientPath: id => id === 'p1' ? '/tmp/p1/lib/client.js' : undefined,
     })
     expect(() => { trigger(consistent) }).not.toThrow()
   })
 
-  it('throws on a manifest row whose bundle path no longer resolves', async () => {
+  it('throws on a graph row whose bundle path no longer resolves', async () => {
     const ctx = await setup({
-      snapshot: () => [{ id: 'ghost', url: '/plugins/ghost/client.js' }],
+      graph: () => ({ entries: [{ id: 'ghost', url: '/plugins/ghost/client.js?rev=abc' }] }),
       clientPath: () => undefined,
     })
     expect(() => { trigger(ctx) })
-      .toThrow(/manifest row "ghost".*resolves no client bundle path/)
+      .toThrow(/graph row "ghost".*resolves no client bundle path/)
   })
 })
diff --git a/packages/host/webserver/tests/web-plugins.spec.ts b/packages/host/webserver/tests/web-plugins.spec.ts
index bb08f2ac11..0acff4d78b 100644
--- a/packages/host/webserver/tests/web-plugins.spec.ts
+++ b/packages/host/webserver/tests/web-plugins.spec.ts
@@ -1,11 +1,41 @@
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import {
+  mkdirSync,
+  mkdtempSync,
+  statSync,
+  type PathLike,
+  type Stats,
+  unlinkSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createHostWebPluginRegistry, injectBootManifest } from '../src/index.ts'
 import type { LoaderEntryView, WebPluginRegistryDeps } from '../src/index.ts'
 
+const fsControl = vi.hoisted(() => ({ failNextStatPath: undefined as string | undefined }))
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>()
+  return {
+    ...actual,
+    statSync: (path: PathLike): Stats => {
+      if (String(path) === fsControl.failNextStatPath) {
+        fsControl.failNextStatPath = undefined
+        throw Object.assign(new Error('staged bundle missing'), { code: 'ENOENT' })
+      }
+      return actual.statSync(path)
+    },
+  }
+})
+
+afterEach(() => {
+  fsControl.failNextStatPath = undefined
+  vi.useRealTimers()
+})
+
 /** Write a fake installed package (package.json + optional client bundle) and return its package.json path. */
 function makePkg(root: string, name: string, pkg: Record<string, unknown>, withBundle = true): string {
   const dir = join(root, name.replaceAll('/', '__'))
@@ -25,6 +55,7 @@ interface Fixture {
   entries: LoaderEntryView[]
   errors: Error[]
   ctx: Context
+  root: string
 }
 
 function makeDeps(
@@ -48,32 +79,30 @@ function makeDeps(
     },
     onError: err => void errors.push(err),
   }
-  return { deps, entries, errors, ctx }
+  return { deps, entries, errors, ctx, root }
 }
 
 describe('createHostWebPluginRegistry', () => {
-  it('collects loaded web-declared plugins with url/inject/immediately and client paths', () => {
+  it('discovers dshClient rows with rev-stamped urls, manifest inject edges, and the declared immediately mark', () => {
     const { deps } = makeDeps([
       { name: '@deepseek-ai/dsh-client-connection', pkg: webDecl({ immediately: true }) },
       { name: '@deepseek-ai/dsh-client-ui-layout', pkg: webDecl({ inject: ['@deepseek-ai/dsh-client-runtime'] }) },
       { name: '@deepseek-ai/dsh-agent', pkg: { exports: { '.': './lib/index.js' } } }, // no dshClient: skipped
     ])
     const registry = createHostWebPluginRegistry(deps)
-    const rows = registry.snapshot()
-    expect(rows).toEqual([
-      {
-        id: '@deepseek-ai/dsh-client-connection',
-        url: '/plugins/@deepseek-ai/dsh-client-connection/client.js',
-        inject: [],
-        immediately: true,
-      },
-      {
-        id: '@deepseek-ai/dsh-client-ui-layout',
-        url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js',
-        inject: ['@deepseek-ai/dsh-client-runtime'],
-      },
-    ])
-    expect(registry.clientPath('@deepseek-ai/dsh-client-connection')).toMatch(/lib[/\\]client\.js$/)
+    const graph = registry.graph()
+    expect(graph.rev).toMatch(/^[0-9a-f]{12}$/)
+    const connection = graph.entries[0]
+    expect(connection?.id).toBe('@deepseek-ai/dsh-client-connection')
+    expect(connection?.rev).toMatch(/^[0-9a-f]{12}$/)
+    expect(connection?.url).toBe(`/plugins/@deepseek-ai/dsh-client-connection/client.js?rev=${connection?.rev ?? ''}`)
+    expect(connection?.immediately).toBe(true)
+    const layout = graph.entries[1]
+    expect(layout?.id).toBe('@deepseek-ai/dsh-client-ui-layout')
+    expect(layout?.inject).toEqual(['@deepseek-ai/dsh-client-runtime'])
+    expect(layout?.immediately).toBeUndefined()
+    expect(graph.entries).toHaveLength(2)
+    expect(registry.clientPath('@deepseek-ai/dsh-client-ui-layout')).toMatch(/lib[/\\]client\.js$/)
     expect(registry.clientPath('@deepseek-ai/dsh-agent')).toBeUndefined()
     registry.dispose()
   })
@@ -85,7 +114,7 @@ describe('createHostWebPluginRegistry', () => {
       { name: 'electron-only', pkg: { dshClient: { platform: 'electron' }, exports: { './client': './lib/client.js' } } },
     ])
     const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot()).toEqual([])
+    expect(registry.graph().entries).toEqual([])
     registry.dispose()
   })
 
@@ -96,6 +125,11 @@ describe('createHostWebPluginRegistry', () => {
     expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
   })
 
+  it('fails loud at build time on a registered bundle that is not built (rev hashing reads the file)', () => {
+    const { deps } = makeDeps([{ name: 'unbuilt', pkg: webDecl(), withBundle: false }])
+    expect(() => createHostWebPluginRegistry(deps)).toThrow(/ENOENT/)
+  })
+
   it('fails loud on malformed declaration fields', () => {
     for (const dshClient of [42, { platform: 7 }, { platform: 'web', inject: 'nope' }, { platform: 'web', immediately: 'yes' }]) {
       const { deps } = makeDeps([{ name: 'bad', pkg: { dshClient, exports: { './client': './lib/client.js' } } }])
@@ -103,26 +137,126 @@ describe('createHostWebPluginRegistry', () => {
     }
   })
 
-  it('rescans on internal/plugin (debounced) and keeps the old table when a rescan fails', async () => {
+  it('rebuilt(id) re-hashes the bundle, updates the row and graph rev, and keeps the immediately mark', () => {
+    const { deps, root } = makeDeps([{ name: 'hot', pkg: webDecl({ immediately: true }) }])
+    const registry = createHostWebPluginRegistry(deps)
+    const before = registry.graph()
+    const beforeRow = before.entries.find(e => e.id === 'hot')
+    writeFileSync(join(root, 'hot', 'lib', 'client.js'), '// rebuilt bundle contents')
+    const rev = registry.rebuilt('hot')
+    expect(rev).toMatch(/^[0-9a-f]{12}$/)
+    expect(rev).not.toBe(beforeRow?.rev)
+    const after = registry.graph()
+    const afterRow = after.entries.find(e => e.id === 'hot')
+    expect(afterRow?.rev).toBe(rev)
+    expect(afterRow?.url).toBe(`/plugins/hot/client.js?rev=${rev ?? ''}`)
+    expect(afterRow?.immediately).toBe(true)
+    expect(after.rev).not.toBe(before.rev)
+    // Unknown ids are not rebuildable.
+    expect(registry.rebuilt('nope')).toBeUndefined()
+    registry.dispose()
+  })
+
+  it('watch mode: a bundle content change re-hashes the row and notifies onRebuilt; dispose stops the watch', async () => {
+    const { deps, root } = makeDeps([{ name: 'watched', pkg: webDecl() }])
+    deps.watch = { intervalMs: 20 }
+    const registry = createHostWebPluginRegistry(deps)
+    const before = registry.graph().entries[0]?.rev
+    const rebuilds: { id: string; rev: string }[] = []
+    registry.onRebuilt((id, rev) => rebuilds.push({ id, rev }))
+
+    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// new bundle contents')
+    await vi.waitFor(() => { expect(rebuilds).toHaveLength(1) }, { timeout: 5000 })
+    expect(rebuilds[0]?.id).toBe('watched')
+    expect(rebuilds[0]?.rev).not.toBe(before)
+    expect(registry.graph().entries[0]?.rev).toBe(rebuilds[0]?.rev)
+
+    registry.dispose()
+    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// post-dispose contents')
+    await new Promise((resolve) => { setTimeout(resolve, 100) })
+    expect(rebuilds).toHaveLength(1)
+  })
+
+  it('watch mode: a failed rescan baseline preserves the published table and graph', async () => {
+    const { deps, entries, errors, ctx, root } = makeDeps([
+      { name: 'stable', pkg: webDecl() },
+      { name: 'late', pkg: webDecl(), loaded: false },
+    ])
+    deps.watch = { intervalMs: 1_000 }
+    const registry = createHostWebPluginRegistry(deps)
+    const before = registry.graph()
+
+    ;(entries[1] as { fiber?: unknown }).fiber = {}
+    fsControl.failNextStatPath = join(root, 'late', 'lib', 'client.js')
+    ctx.emit('internal/plugin', ctx.fiber)
+    await Promise.resolve()
+
+    expect(errors[0]?.message).toContain('staged bundle missing')
+    expect(registry.graph()).toBe(before)
+    expect(registry.clientPath('late')).toBeUndefined()
+
+    ctx.emit('internal/plugin', ctx.fiber)
+    await Promise.resolve()
+    expect(registry.graph().entries.map(row => row.id)).toEqual(['stable', 'late'])
+    registry.dispose()
+  })
+
+  it('watch mode: a missing bundle forces a re-hash when identical metadata reappears', async () => {
+    vi.useFakeTimers()
+    const { deps, root } = makeDeps([{ name: 'watched', pkg: webDecl() }])
+    const bundle = join(root, 'watched', 'lib', 'client.js')
+    const fixedTime = new Date(1_600_000_000_000)
+    utimesSync(bundle, fixedTime, fixedTime)
+    deps.watch = { intervalMs: 20 }
+    const registry = createHostWebPluginRegistry(deps)
+    const baseline = statSync(bundle)
+    const rebuilds: { id: string; rev: string }[] = []
+    registry.onRebuilt((id, rev) => rebuilds.push({ id, rev }))
+
+    unlinkSync(bundle)
+    await vi.advanceTimersByTimeAsync(20)
+    writeFileSync(bundle, 'x'.repeat(baseline.size))
+    utimesSync(bundle, fixedTime, fixedTime)
+    const restored = statSync(bundle)
+    expect({ mtimeMs: restored.mtimeMs, size: restored.size }).toEqual({
+      mtimeMs: baseline.mtimeMs,
+      size: baseline.size,
+    })
+    await vi.advanceTimersByTimeAsync(20)
+
+    expect(rebuilds).toHaveLength(1)
+    expect(registry.graph().entries[0]?.rev).toBe(rebuilds[0]?.rev)
+    registry.dispose()
+  })
+
+  it('rejects a non-positive or non-integer watch interval at build time', () => {
+    for (const intervalMs of [0, -5, 1.5]) {
+      const { deps } = makeDeps([{ name: 'p', pkg: webDecl() }])
+      deps.watch = { intervalMs }
+      expect(() => createHostWebPluginRegistry(deps)).toThrow(/watch\.intervalMs/)
+    }
+  })
+
+  it('rescans on internal/plugin (debounced) and keeps the old graph when a rescan fails', async () => {
     const { deps, entries, errors, ctx } = makeDeps([
       { name: 'late-loader', pkg: webDecl(), loaded: false },
     ])
     const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot()).toEqual([])
+    expect(registry.graph().entries).toEqual([])
 
     // Entry finishes loading; a fiber lifecycle event triggers the debounced rescan.
     ;(entries[0] as { fiber?: unknown }).fiber = {}
     ctx.emit('internal/plugin', ctx.fiber)
     ctx.emit('internal/plugin', ctx.fiber) // debounce: two emissions, one rescan
     await Promise.resolve()
-    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+    expect(registry.graph().entries.map(row => row.id)).toEqual(['late-loader'])
 
-    // A failing rescan reports the error and keeps serving the previous table.
+    // A failing rescan reports the error and keeps serving the previous graph.
     entries.push({ options: { name: 'ghost' }, fiber: {}, disabled: false })
     ctx.emit('internal/plugin', ctx.fiber)
     await Promise.resolve()
     expect(errors).toHaveLength(1)
-    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+    expect(registry.graph().entries.map(row => row.id)).toEqual(['late-loader'])
 
     // After dispose, further fiber events no longer rescan.
     registry.dispose()
@@ -134,16 +268,19 @@ describe('createHostWebPluginRegistry', () => {
 })
 
 describe('injectBootManifest', () => {
-  it('injects the manifest as the first script inside <head> and escapes </script> breakouts', () => {
+  it('injects the graph as the first script inside <head> and escapes </script> breakouts', () => {
     const html = '<html><head><script src="app.js"></script></head><body></body></html>'
-    const out = injectBootManifest(html, [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js', inject: [] }])
+    const out = injectBootManifest(html, {
+      rev: 'r1',
+      entries: [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js?rev=r2', rev: 'r2' }],
+    })
     expect(out.indexOf('window.__DSH_BOOT__')).toBeLessThan(out.indexOf('app.js'))
     expect(out).not.toContain('</script><script>alert(1)')
     expect(out).toContain('\\u003c/script')
   })
 
   it('prepends when the page has no <head>', () => {
-    const out = injectBootManifest('<body>x</body>', [])
+    const out = injectBootManifest('<body>x</body>', { rev: 'r0', entries: [] })
     expect(out.startsWith('<script>window.__DSH_BOOT__')).toBe(true)
   })
 })
@@ -181,7 +318,7 @@ describe('clientExportOf shapes (through the registry build)', () => {
     entries.push({ options: { name: 'dup-entry' }, fiber: {}, disabled: false })
     void first
     const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot().filter(r => r.id === 'dup-entry')).toHaveLength(1)
+    expect(registry.graph().entries.filter(r => r.id === 'dup-entry')).toHaveLength(1)
     registry.dispose()
   })
 
diff --git a/packages/host/webserver/tests/webserver.spec.ts b/packages/host/webserver/tests/webserver.spec.ts
index 0b9d1a8978..a4921f1b3e 100644
--- a/packages/host/webserver/tests/webserver.spec.ts
+++ b/packages/host/webserver/tests/webserver.spec.ts
@@ -1,22 +1,10 @@
 import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
-import { createServer as createNetServer, Server as NetServer, type AddressInfo } from 'node:net'
+import { Server as NetServer } from 'node:net'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { startWebServer, type RunningWebServer } from '../src/index.ts'
 
-/** Reserve a loopback port for tests that need to address a second server. */
-function freePort(): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const probe = createNetServer()
-    probe.once('error', reject)
-    probe.listen(0, '127.0.0.1', () => {
-      const port = (probe.address() as AddressInfo).port
-      probe.close(() => { resolve(port) })
-    })
-  })
-}
-
 /** dist fixture: index.html + one asset of each MIME class + a subdir. */
 function makeDist(): { distIndex: string; distRoot: string } {
   const distRoot = mkdtempSync(join(tmpdir(), 'dsh-webserver-'))
@@ -106,8 +94,7 @@ afterEach(async () => {
 
 async function boot(onError: (err: Error) => void = () => undefined): Promise<string> {
   const { distIndex } = makeDist()
-  const port = await freePort()
-  server = await startWebServer({ host: '127.0.0.1', port, distIndex, apiHandler: echoingApi }, onError)
+  server = await startWebServer({ host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi }, onError)
   return `http://127.0.0.1:${String(server.port)}`
 }
 
@@ -147,8 +134,8 @@ describe('startWebServer', () => {
 
   it('rejects when the port is already taken', async () => {
     const { distIndex } = makeDist()
-    const port = await freePort()
-    server = await startWebServer({ host: '127.0.0.1', port, distIndex, apiHandler: echoingApi }, () => undefined)
+    server = await startWebServer({ host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi }, () => undefined)
+    const { port } = server
     await expect(startWebServer({ host: '127.0.0.1', port, distIndex, apiHandler: echoingApi }, () => undefined))
       .rejects.toMatchObject({ code: 'EADDRINUSE' })
   })
@@ -192,32 +179,47 @@ describe.skipIf(process.platform === 'win32')('static serving', () => {
   })
 })
 
-describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injection + bundle endpoint)', () => {
-  const rows = [
-    { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js', inject: [], immediately: true },
-    { id: '@deepseek-ai/dsh-client-ui-layout', url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js', inject: ['@deepseek-ai/dsh-client-runtime'] },
-  ]
+describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injection + bundle endpoint + events channel)', () => {
+  const FETCH_ID = '@deepseek-ai/dsh-client-ui-layout'
+  const graphValue = {
+    rev: 'graphrev00001',
+    entries: [
+      { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js?rev=eeee2222ffff', rev: 'eeee2222ffff', immediately: true },
+      { id: FETCH_ID, url: `/plugins/${FETCH_ID}/client.js?rev=aaaa0000bbbb`, rev: 'aaaa0000bbbb', inject: [] },
+    ],
+  }
 
-  async function bootWithPlugins(): Promise<string> {
+  /** Captures the server's onRebuilt subscription so tests can fire registry notifications by hand. */
+  interface RebuiltHarness {
+    notify: (id: string, rev: string) => void
+    unsubscribed: boolean
+  }
+
+  async function bootWithPlugins(harness?: RebuiltHarness): Promise<string> {
     const { distIndex, distRoot } = makeDist()
     writeFileSync(join(distRoot, 'bundle.js'), 'window.DSHClientProxy.loadPlugin({})')
     const webPlugins = {
-      snapshot: () => rows,
-      clientPath: (id: string) => id === rows[0]?.id ? join(distRoot, 'bundle.js') : undefined,
+      graph: () => graphValue,
+      clientPath: (id: string) => id === FETCH_ID ? join(distRoot, 'bundle.js') : undefined,
+      onRebuilt: (listener: (id: string, rev: string) => void) => {
+        if (harness !== undefined) harness.notify = listener
+        return () => {
+          if (harness !== undefined) harness.unsubscribed = true
+        }
+      },
     }
-    const port = await freePort()
     server = await startWebServer(
-      { host: '127.0.0.1', port, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined,
+      { host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined,
     )
     return `http://127.0.0.1:${String(server.port)}`
   }
 
-  it('injects window.__DSH_BOOT__ into / and SPA fallbacks; asset requests stay verbatim', async () => {
+  it('injects the window.__DSH_BOOT__ graph into / and SPA fallbacks; asset requests stay verbatim', async () => {
     const base = await bootWithPlugins()
     const index = await (await fetch(`${base}/`)).text()
     expect(index).toContain('window.__DSH_BOOT__')
     const manifest = /window\.__DSH_BOOT__ = (.*?)<\/script>/.exec(index)?.[1]
-    expect(JSON.parse(manifest ?? '')).toEqual({ plugins: rows })
+    expect(JSON.parse(manifest ?? '')).toEqual(graphValue)
 
     const fallback = await (await fetch(`${base}/routes/deep/link`)).text()
     expect(fallback).toContain('window.__DSH_BOOT__')
@@ -227,11 +229,12 @@ describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injecti
     expect(await (await fetch(`${base}/app.js`)).text()).toBe('console.log(1)')
   })
 
-  it('serves registered client bundles and 404s unknown ids (no SPA fallback)', async () => {
+  it('serves registered client bundles with no-cache (rev query ignored) and 404s unknown ids (no SPA fallback)', async () => {
     const base = await bootWithPlugins()
-    const bundle = await fetch(`${base}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    const bundle = await fetch(`${base}/plugins/${FETCH_ID}/client.js?rev=whatever`)
     expect(bundle.status).toBe(200)
     expect(bundle.headers.get('content-type')).toBe('text/javascript; charset=utf-8')
+    expect(bundle.headers.get('cache-control')).toBe('no-cache')
     expect(await bundle.text()).toContain('DSHClientProxy')
 
     expect((await fetch(`${base}/plugins/unknown/client.js`)).status).toBe(404)
@@ -240,24 +243,59 @@ describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injecti
   it('404s a registered id whose bundle file is unreadable (unbuilt dist must fail loud, not fall back to HTML)', async () => {
     const { distIndex } = makeDist()
     const webPlugins = {
-      snapshot: () => rows,
+      graph: () => graphValue,
       clientPath: () => '/nonexistent/lib/client.js',
+      onRebuilt: () => () => undefined,
     }
-    const port = await freePort()
     server = await startWebServer(
-      { host: '127.0.0.1', port, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined,
+      { host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined,
     )
-    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/${FETCH_ID}/client.js`)
     expect(res.status).toBe(404)
   })
 
-  it('keeps both surfaces off without the webPlugins option', async () => {
+  it('keeps all plugin surfaces off without the webPlugins option', async () => {
     const base = await boot()
     expect(await (await fetch(`${base}/`)).text()).toBe('<html>INDEX</html>')
-    // No plugin route: falls through to static SPA fallback semantics.
+    // No plugin routes: fall through to static SPA fallback semantics.
     const res = await fetch(`${base}/plugins/x/client.js`)
     expect(res.status).toBe(200)
     expect(await res.text()).toBe('<html>INDEX</html>')
+    const events = await fetch(`${base}/plugins/events`)
+    expect(await events.text()).toBe('<html>INDEX</html>')
+  })
+
+  it('GET /plugins/events opens SSE with the current graph frame; a registry rebuild notification broadcasts', async () => {
+    const harness: RebuiltHarness = { notify: () => { throw new Error('onRebuilt never subscribed') }, unsubscribed: false }
+    const base = await bootWithPlugins(harness)
+    const events = await fetch(`${base}/plugins/events`)
+    expect(events.status).toBe(200)
+    expect(events.headers.get('content-type')).toBe('text/event-stream')
+    const reader = events.body?.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    async function readUntil(marker: string): Promise<void> {
+      while (!buffer.includes(marker)) {
+        const chunk = await reader?.read()
+        if (chunk?.done !== false) throw new Error('SSE stream ended early')
+        buffer += decoder.decode(chunk.value, { stream: true })
+      }
+    }
+    await readUntil('"type":"graph"')
+    expect(buffer).toContain(': connected')
+    const graphLine = /data: (.*)\n\n/.exec(buffer)?.[1]
+    expect(JSON.parse(graphLine ?? '')).toEqual({ type: 'graph', graph: graphValue })
+
+    // The registry's bundle watch observed a rebuild: the server relays it as an SSE frame.
+    harness.notify(FETCH_ID, 'cccc1111dddd')
+    await readUntil('"type":"rebuilt"')
+    expect(buffer).toContain(JSON.stringify({ type: 'rebuilt', id: FETCH_ID, rev: 'cccc1111dddd' }))
+    await reader?.cancel()
+
+    // Shutdown unsubscribes the relay (no broadcast into a closed channel).
+    await server?.close()
+    server = undefined
+    expect(harness.unsubscribed).toBe(true)
   })
 })
 
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 162843beb3..5a9a1bfdbc 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -17,10 +17,10 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
     thinking: enabled        # optional; provider default is enabled
     reasoningEffort: high    # optional; high | max — omitted ⇒ not sent
     streamIdleTimeoutMs: 300000 # optional; positive finite Node timer delay; five-minute default
+    defaultContextWindow: 256000 # optional positive-integer fallback for models without an exact value
     models:                  # optional; defaults to V4 Flash and V4 Pro
       - id: deepseek-v4-flash
         name: DeepSeek V4 Flash
-        contextWindow: 128000
       - id: private-reasoner
         description: Company-hosted reasoning model
         contextWindow: 64000
@@ -28,11 +28,11 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
 
 The plugin registers the single provider route `deepseek`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` and `deepseek-v4-pro`, each with a 128,000-token context window; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for clients such as ACP editors, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id.
 
-`contextWindow` is optional per configured model and is not exposed through the advisory catalog. `ctx.llm.resolveModelContext('deepseek', model)` returns it only for an exact configured id; omission or an unlisted pass-through model returns `undefined` without invalidating routing. Pressure-sensitive plugins therefore get deployment-owned capacity without treating the model selector as authoritative. Registering another adapter for `deepseek` throws `LlmError('DUPLICATE_ADAPTER')`.
+`contextWindow` is optional per configured model and is not exposed through the advisory catalog. `ctx.llm.resolveModelContext('deepseek', model)` returns an exact model value first, then `defaultContextWindow` for an entry without capacity or an unlisted pass-through id. When neither value exists it returns `undefined` without invalidating routing. Pressure-sensitive plugins therefore get deployment-owned capacity without treating the model selector as authoritative. Registering another adapter for `deepseek` throws `LlmError('DUPLICATE_ADAPTER')`.
 
 `reasoningEffort` is **omitted by default** — when unset, the `reasoning_effort` wire field is not sent and the server applies its own default for the model. The only accepted values are `high` and `max` (DeepSeek's official effort levels). It is meaningful only with thinking enabled (the provider default).
 
-`thinking`/`reasoningEffort` are adapter-level request defaults serialized as the official top-level `thinking: {type}` / `reasoning_effort` wire fields. They live in adapter config (not `GenerateOptions`) to keep the core vocabulary provider-neutral.
+`thinking`/`reasoningEffort` are adapter-level request defaults serialized as the official top-level `thinking: {type}` / `reasoning_effort` wire fields. They live in adapter config (not `GenerateOptions`) to keep the core vocabulary provider-neutral. A request with `GenerateOptions.purpose: 'session-title'` forces thinking disabled and omits `reasoning_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; agent-level retry is a separate plugin policy.
 
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 3ca81f678c..64faa3b725 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -40,6 +40,8 @@ export interface DeepSeekAdapterOptions {
   baseURL: string
   /** Request defaults applied to every call (thinking mode, effort). */
   defaults?: RequestDefaults
+  /** Positive context capacity used when the selected model has no exact value. */
+  defaultContextWindow?: number
   /** Advisory models exposed to discovery consumers; requests remain unrestricted. */
   models?: readonly DeepSeekCatalogModel[]
   /** Maximum provider idle time while one stream read is outstanding. */
@@ -96,6 +98,10 @@ export class DeepSeekAdapter extends LlmAdapter {
 
   constructor(private readonly options: DeepSeekAdapterOptions) {
     super()
+    if (options.defaultContextWindow !== undefined
+      && (!Number.isInteger(options.defaultContextWindow) || options.defaultContextWindow <= 0)) {
+      throw new Error('llm-deepseek: defaultContextWindow must be a positive integer')
+    }
     this.streamIdleTimeoutMs = options.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
     if (!Number.isFinite(this.streamIdleTimeoutMs)
       || this.streamIdleTimeoutMs <= 0
@@ -124,6 +130,7 @@ export class DeepSeekAdapter extends LlmAdapter {
     model: string,
   ): Promise<LlmModelContext | undefined> {
     const contextWindow = this.options.models?.find(entry => entry.id === model)?.contextWindow
+      ?? this.options.defaultContextWindow
     return Promise.resolve(contextWindow === undefined ? undefined : { contextWindow })
   }
 
diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index ed374f6ecc..66828fc954 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -40,6 +40,8 @@ export interface Config {
   thinking?: 'enabled' | 'disabled'
   /** Thinking effort (only meaningful with thinking enabled). */
   reasoningEffort?: 'high' | 'max'
+  /** Positive context capacity used when the selected model has no exact value. */
+  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). */
@@ -58,6 +60,7 @@ export const Config: z<Config> = z.object({
   baseURL: z.string(),
   thinking: z.union(['enabled', 'disabled']),
   reasoningEffort: z.union(['high', 'max']),
+  defaultContextWindow: z.number().step(1).min(1),
   models: z.array(catalogModel).default(DEFAULT_MODELS),
   streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
 })
@@ -103,6 +106,9 @@ export function apply(ctx: Context, config: Config): void {
       thinking: config.thinking,
       reasoningEffort: config.reasoningEffort,
     },
+    ...config.defaultContextWindow === undefined
+      ? {}
+      : { defaultContextWindow: config.defaultContextWindow },
     models: resolveModels(config.models),
     streamIdleTimeoutMs: config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   }))
diff --git a/packages/llm/llm-deepseek/src/serialize.ts b/packages/llm/llm-deepseek/src/serialize.ts
index f463a4e30e..bf9515c942 100644
--- a/packages/llm/llm-deepseek/src/serialize.ts
+++ b/packages/llm/llm-deepseek/src/serialize.ts
@@ -118,14 +118,18 @@ export function serializeRequest(options: GenerateOptions, defaults: RequestDefa
       parameters: tool.parameters,
     },
   }))
+  // A short title budget must produce visible text; conversation and
+  // compaction calls continue to inherit the adapter's thinking defaults.
+  const thinking = options.purpose === 'session-title' ? 'disabled' : defaults.thinking
+  const reasoningEffort = options.purpose === 'session-title' ? undefined : defaults.reasoningEffort
 
   return {
     model: options.model,
     messages,
     stream: true,
     stream_options: { include_usage: true },
-    ...defaults.thinking !== undefined ? { thinking: { type: defaults.thinking } } : {},
-    ...defaults.reasoningEffort !== undefined ? { reasoning_effort: defaults.reasoningEffort } : {},
+    ...thinking !== undefined ? { thinking: { type: thinking } } : {},
+    ...reasoningEffort !== undefined ? { reasoning_effort: reasoningEffort } : {},
     ...tools !== undefined && tools.length > 0 ? { tools } : {},
     ...options.temperature !== undefined ? { temperature: options.temperature } : {},
     ...options.maxTokens !== undefined ? { max_tokens: options.maxTokens } : {},
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index f147323645..145017ea3d 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -571,6 +571,27 @@ describe('plugin registration and config', () => {
       .resolves.toBeUndefined()
   })
 
+  it('uses exact model capacity before the adapter-wide default', async () => {
+    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: [
+        { id: 'inherits-default' },
+        { id: 'exact-override', contextWindow: 64_000 },
+      ],
+    })
+
+    await expect(ctx.llm.resolveModelContext('deepseek', 'inherits-default'))
+      .resolves.toEqual({ contextWindow: 256_000 })
+    await expect(ctx.llm.resolveModelContext('deepseek', 'exact-override'))
+      .resolves.toEqual({ contextWindow: 64_000 })
+    await expect(ctx.llm.resolveModelContext('deepseek', 'unlisted-pass-through'))
+      .resolves.toEqual({ contextWindow: 256_000 })
+  })
+
   it('allows an explicit empty model catalog', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -612,6 +633,26 @@ describe('plugin registration and config', () => {
     expect(ctx.llm.listProviders()).toEqual([])
   })
 
+  it.each([0, 1.5])(
+    'rejects invalid adapter-wide default context capacity %s',
+    async (defaultContextWindow) => {
+      expect(() => new DeepSeekAdapter({
+        apiKey: 'k',
+        baseURL: 'http://127.0.0.1:1',
+        defaultContextWindow,
+      })).toThrow(/defaultContextWindow must be a positive integer/)
+
+      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/)
+      expect(ctx.llm.listProviders()).toEqual([])
+    },
+  )
+
   it('falls back to DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL env vars', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
     vi.stubEnv('DEEPSEEK_BASE_URL', 'http://127.0.0.1:1')
diff --git a/packages/llm/llm-deepseek/tests/serialize.spec.ts b/packages/llm/llm-deepseek/tests/serialize.spec.ts
index e84909fc20..566c71b7f2 100644
--- a/packages/llm/llm-deepseek/tests/serialize.spec.ts
+++ b/packages/llm/llm-deepseek/tests/serialize.spec.ts
@@ -180,6 +180,15 @@ describe('serializeRequest', () => {
     expect(wire.reasoning_effort).toBe('max')
   })
 
+  it('disables thinking for session-title requests without changing adapter defaults', () => {
+    const wire = serializeRequest(
+      request({ messages: history, purpose: 'session-title' }),
+      { thinking: 'enabled', reasoningEffort: 'max' },
+    )
+    expect(wire.thinking).toEqual({ type: 'disabled' })
+    expect(wire.reasoning_effort).toBeUndefined()
+  })
+
   it('omits thinking fields when unset (provider default applies)', () => {
     const wire = serializeRequest(request({ messages: history }))
     expect(wire.thinking).toBeUndefined()
diff --git a/packages/llm/llm-retry/tests/loader-composition.spec.ts b/packages/llm/llm-retry/tests/loader-composition.spec.ts
index 1aafc91d92..bb08577d74 100644
--- a/packages/llm/llm-retry/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-retry/tests/loader-composition.spec.ts
@@ -114,7 +114,7 @@ describe('real Loader composition', () => {
     loaded.llm.registerAdapter(['mock'], adapter)
     const agent = loaded.agentLoop.create(SessionId('loader-retry'), { provider: 'mock', model: 'mock' })
     const idle = waitForIdle(loaded, agent)
-    agent.send([{ type: 'text', text: 'recover' }])
+    agent.followup([{ type: 'text', text: 'recover' }])
     await idle
 
     expect(adapter.requests).toBe(2)
diff --git a/packages/llm/llm-retry/tests/retry.spec.ts b/packages/llm/llm-retry/tests/retry.spec.ts
index b424718187..20e7862ebc 100644
--- a/packages/llm/llm-retry/tests/retry.spec.ts
+++ b/packages/llm/llm-retry/tests/retry.spec.ts
@@ -6,7 +6,7 @@ import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -129,7 +129,7 @@ describe('bounded transient retry policy', () => {
       })
     })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     const event = await scheduled
 
     expect(event.data).toEqual({
@@ -166,7 +166,7 @@ describe('bounded transient retry policy', () => {
     ])
     ;({ ctx: context } = await harness(adapter))
     let toolExecutions = 0
-    context.tools.register(defineTool({
+    context.tools.register(defineContentToolFixture({
       name: 'danger',
       description: 'must not run for a failed provider attempt',
       parameters: {},
@@ -178,7 +178,7 @@ describe('bounded transient retry policy', () => {
     const agent = context.agentLoop.create(SessionId('retry-partial'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await scheduled
     const idle = waitForIdle(context, agent)
     await vi.advanceTimersByTimeAsync(500)
@@ -213,7 +213,7 @@ describe('bounded transient retry policy', () => {
     const agent = context.agentLoop.create(SessionId('retry-exhausted'), { provider: 'mock', model: 'mock' })
     const first = waitForRetry(context, agent, 1)
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     expect((await first).data.delayMs).toBe(450)
 
     const second = waitForRetry(context, agent, 2)
@@ -246,7 +246,7 @@ describe('bounded transient retry policy', () => {
     const agent = context.agentLoop.create(SessionId('retry-zero-delay'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     expect((await scheduled).data.delayMs).toBe(0)
 
     const idle = waitForIdle(context, agent)
@@ -264,7 +264,7 @@ describe('bounded transient retry policy', () => {
     ;({ ctx: context } = await harness(accepted, { jitterRatio: 1 }))
     const acceptedAgent = context.agentLoop.create(SessionId('retry-after-accepted'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, acceptedAgent, 1)
-    acceptedAgent.send([{ type: 'text', text: 'go' }])
+    acceptedAgent.followup([{ type: 'text', text: 'go' }])
     expect((await scheduled).data.delayMs).toBe(2_000)
     const acceptedIdle = waitForIdle(context, acceptedAgent)
     await vi.advanceTimersByTimeAsync(2_000)
@@ -278,7 +278,7 @@ describe('bounded transient retry policy', () => {
     ;({ ctx: context } = await harness(rejected))
     const rejectedAgent = context.agentLoop.create(SessionId('retry-after-rejected'), { provider: 'mock', model: 'mock' })
     const rejectedIdle = waitForIdle(context, rejectedAgent)
-    rejectedAgent.send([{ type: 'text', text: 'go' }])
+    rejectedAgent.followup([{ type: 'text', text: 'go' }])
     await rejectedIdle
     expect(rejected.requests).toHaveLength(1)
     expect(rejectedAgent.session.events.some(event => event.type === 'llm/retry')).toBe(false)
@@ -290,7 +290,7 @@ describe('bounded transient retry policy', () => {
     ;({ ctx: context } = await harness(adapter))
     const agent = context.agentLoop.create(SessionId('retry-auth'), { provider: 'mock', model: 'mock' })
     const idle = waitForIdle(context, agent)
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await idle
     expect(adapter.requests).toHaveLength(1)
     expect(agent.session.events.some(event => event.type === 'llm/retry')).toBe(false)
@@ -307,7 +307,7 @@ describe('bounded transient retry policy', () => {
     context = mounted.ctx
     const agent = context.agentLoop.create(SessionId('retry-hmr'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await scheduled
     const idle = waitForIdle(context, agent)
 
@@ -335,7 +335,7 @@ describe('bounded transient retry policy', () => {
       model: 'mock',
     })
     const idle = waitForIdle(context, agent)
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await entered.promise
 
     const disposing = mounted.retryFiber.dispose()
@@ -376,7 +376,7 @@ describe('bounded transient retry policy', () => {
       model: 'mock',
     })
     const idle = waitForIdle(context, agent)
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await captured.promise
 
     await mounted.retryFiber.dispose()
@@ -397,7 +397,7 @@ describe('bounded transient retry policy', () => {
     ;({ ctx: context } = await harness(adapter))
     const agent = context.agentLoop.create(SessionId('retry-cancel'), { provider: 'mock', model: 'mock' })
     const scheduled = waitForRetry(context, agent, 1)
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await scheduled
     const idle = waitForIdle(context, agent)
     agent.cancel({ kind: 'user' })
@@ -426,7 +426,7 @@ describe('bounded transient retry policy', () => {
     const agent = context.agentLoop.create(SessionId('retry-pre-cancel'), { provider: 'mock', model: 'mock' })
     const idle = waitForIdle(context, agent)
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await idle
 
     expect(adapter.requests).toHaveLength(1)
@@ -450,7 +450,7 @@ describe('bounded transient retry policy', () => {
     })
     const idle = waitForIdle(context, agent)
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await idle
 
     expect(adapter.requests).toHaveLength(1)
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index 05ff3568b2..beac6d5e8e 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -39,7 +39,7 @@ Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta
 
 ### Call configuration (`call-config.ts`)
 
-`LlmCallConfig` is the provider + model + sampling scalars of one conversation's requests (`provider`, `model`, `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 and the loop logs a real change. `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.
+`LlmCallConfig` is the provider + model + sampling scalars of one conversation's requests (`provider`, `model`, `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 and the loop logs a real change. `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.
 
 ### App attribution (`attribution.ts`)
 
diff --git a/packages/llm/llm/src/call-config.ts b/packages/llm/llm/src/call-config.ts
index fe723ec162..fd6ecf9df4 100644
--- a/packages/llm/llm/src/call-config.ts
+++ b/packages/llm/llm/src/call-config.ts
@@ -58,7 +58,8 @@ export function isAgentLoopRequest(request: GenerateOptions): boolean {
 }
 
 /**
- * Deep-freeze a value in place, guarding cycles, so later mutation throws.
+ * Deep-freeze a value in place with an iterative traversal, guarding cycles,
+ * so later mutation throws without imposing a JavaScript call-stack depth cap.
  * {@link AbortSignal} objects are deliberately skipped because they are the
  * request's live cancellation channel and freezing them breaks abort.
  * @param value - the value to freeze in place.
@@ -66,16 +67,31 @@ export function isAgentLoopRequest(request: GenerateOptions): boolean {
  */
 export function deepFreeze<T>(value: T): T {
   const seen = new WeakSet<object>()
-  const walk = (node: unknown): void => {
-    if (node === null || typeof node !== 'object') return
-    if (node instanceof AbortSignal) return
-    if (seen.has(node)) return
+  const pending: (
+    | { kind: 'visit'; node: unknown }
+    | { kind: 'property'; source: Record<string, unknown>; key: string }
+  )[] = [{ kind: 'visit', node: value }]
+  while (pending.length > 0) {
+    const task = pending.pop()
+    /* v8 ignore next -- the loop condition guarantees one pending task. */
+    if (task === undefined) continue
+    if (task.kind === 'property') {
+      pending.push({ kind: 'visit', node: task.source[task.key] })
+      continue
+    }
+    const node = task.node
+    if (node === null || typeof node !== 'object') continue
+    if (node instanceof AbortSignal) continue
+    if (seen.has(node)) continue
     seen.add(node)
     Object.freeze(node)
-    for (const key of Object.keys(node)) {
-      walk((node as Record<string, unknown>)[key])
+    const keys = Object.keys(node)
+    for (let index = keys.length - 1; index >= 0; index--) {
+      const key = keys[index]
+      /* v8 ignore next -- the loop is bounded by the captured key count. */
+      if (key === undefined) continue
+      pending.push({ kind: 'property', source: node as Record<string, unknown>, key })
     }
   }
-  walk(value)
   return value
 }
diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts
index 12febecf42..f9f97d532a 100644
--- a/packages/llm/llm/src/types.ts
+++ b/packages/llm/llm/src/types.ts
@@ -228,8 +228,8 @@ export interface GenerateOptions {
   sessionId?: Branded<'SessionId'>
   /**
    * Provider-neutral classification for an auxiliary model call. Adapters may
-   * map the purpose to model-hidden transport metadata. Ordinary conversation
-   * requests leave it unset.
+   * map the purpose to model-hidden transport metadata or purpose-specific
+   * generation policy. Ordinary conversation requests leave it unset.
    */
-  purpose?: 'compaction'
+  purpose?: 'compaction' | 'session-title'
 }
diff --git a/packages/llm/llm/tests/call-config.spec.ts b/packages/llm/llm/tests/call-config.spec.ts
index 6479ec8f85..a5426e815f 100644
--- a/packages/llm/llm/tests/call-config.spec.ts
+++ b/packages/llm/llm/tests/call-config.spec.ts
@@ -56,6 +56,26 @@ describe('deepFreeze', () => {
     deepFreeze(cyclic)
     expect(Object.isFrozen(cyclic)).toBe(true)
   })
+
+  it('freezes nesting deeper than the JavaScript call stack', () => {
+    const depth = 5_000
+    const root: unknown[] = []
+    let cursor = root
+    for (let index = 0; index < depth; index++) {
+      const child: unknown[] = []
+      cursor.push(child)
+      cursor = child
+    }
+
+    deepFreeze(root)
+
+    cursor = root
+    for (let index = 0; index < depth; index++) {
+      expect(Object.isFrozen(cursor)).toBe(true)
+      cursor = cursor[0] as unknown[]
+    }
+    expect(Object.isFrozen(cursor)).toBe(true)
+  })
 })
 
 describe('agent-loop request identity', () => {
diff --git a/packages/lsp/tool-lsp/README.md b/packages/lsp/tool-lsp/README.md
index 4a844d2537..e2f15ba79a 100644
--- a/packages/lsp/tool-lsp/README.md
+++ b/packages/lsp/tool-lsp/README.md
@@ -8,7 +8,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. Locations render as 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, 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.
 
 ## Configuration
 
@@ -58,7 +58,7 @@ Prefix-stable while the visible tool definition and order are unchanged; registr
 
 #### What the model sees
 
-File-grouped `path:line:character` location lines or normalized hover text, capped first by `maxLocations` and then by `maxResultChars`; omission and truncation markers are included inside the complete character cap. Empty results use distinct `No results.` / `No hover information.` lines.
+File-grouped `path:line:character` location lines or normalized hover text, capped first by `maxLocations` and then by `maxResultChars`; omission and truncation markers are included inside the complete character cap. These caps affect only Native/model presentation, not the canonical value. Empty results use distinct `No results.` / `No hover information.` lines.
 
 #### Token effect
 
diff --git a/packages/lsp/tool-lsp/src/index.ts b/packages/lsp/tool-lsp/src/index.ts
index c298bdffb8..e47dbc87db 100644
--- a/packages/lsp/tool-lsp/src/index.ts
+++ b/packages/lsp/tool-lsp/src/index.ts
@@ -13,7 +13,7 @@
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { assertNever, type ContentBlock } from '@deepseek-ai/dsh-llm'
+import { assertNever } from '@deepseek-ai/dsh-llm'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {} from '@deepseek-ai/dsh-lsp'
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -72,6 +72,24 @@ export const Config: z<Config> = z.object({
 
 type ResolvedConfig = Required<Config>
 
+const LSP_POSITION_OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    line: { type: 'integer', required: true },
+    character: { type: 'integer', required: true },
+  },
+} as const
+
+const LSP_RANGE_OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    start: { ...LSP_POSITION_OUTPUT_SCHEMA, required: true },
+    end: { ...LSP_POSITION_OUTPUT_SCHEMA, required: true },
+  },
+} as const
+
 /**
  * Register the `lsp` tool and its system-prompt guidance.
  * @param ctx - the plugin context (must inject `tools`, `lsp`, `systemPrompt`).
@@ -100,8 +118,66 @@ export function apply(ctx: Context, config: Config): void {
       line: { type: 'number', required: true, description: 'One-based line of the cursor.' },
       character: { type: 'number', required: true, description: 'One-based UTF-16 column of the cursor.' },
     },
+    output: {
+      schema: {
+        oneOf: [
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'locations' },
+              locations: {
+                type: 'array',
+                required: true,
+                items: {
+                  type: 'object',
+                  additionalProperties: false,
+                  properties: {
+                    uri: { type: 'string', required: true },
+                    range: { ...LSP_RANGE_OUTPUT_SCHEMA, required: true },
+                  },
+                },
+              },
+              resolvedWorkspaceRoot: { type: 'string', required: true },
+            },
+          },
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'hover' },
+              hover: {
+                required: true,
+                oneOf: [
+                  { type: 'null' },
+                  {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                      contents: { type: 'string', required: true },
+                      range: LSP_RANGE_OUTPUT_SCHEMA,
+                    },
+                  },
+                ],
+              },
+            },
+          },
+        ],
+      },
+      render: (_args, value) => {
+        switch (value.kind) {
+          case 'locations':
+            return [{ type: 'text', text: formatLocations(value.locations, value.resolvedWorkspaceRoot, 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. */
+          default:
+            return assertNever(value, 'tool-lsp output')
+        }
+      },
+    },
     timeoutMs: resolved.timeoutMs,
-    async execute(args, exec): Promise<ContentBlock[]> {
+    async execute(args, exec) {
       const input = parseLspArgs(args)
       const workspaceRoot = sessionCwd(exec)
       if (workspaceRoot === undefined) {
@@ -115,12 +191,34 @@ export function apply(ctx: Context, config: Config): void {
       }, exec.signal)
       switch (result.kind) {
         case 'locations':
-          // Relativize against the provider's canonical workspace root (which its file: URIs are
-          // relative to), not the session cwd: a symlinked cwd would otherwise misclassify every
-          // in-workspace location as external and render it as an absolute path.
-          return [{ type: 'text', text: formatLocations(result.locations, result.resolvedWorkspaceRoot, resolved.maxLocations, resolved.maxResultChars) }]
+          return {
+            kind: 'locations' as const,
+            locations: result.locations.map(location => ({
+              uri: location.uri,
+              range: {
+                start: { line: location.range.start.line, character: location.range.start.character },
+                end: { line: location.range.end.line, character: location.range.end.character },
+              },
+            })),
+            resolvedWorkspaceRoot: result.resolvedWorkspaceRoot,
+          }
         case 'hover':
-          return [{ type: 'text', text: formatHover(result.hover, resolved.maxResultChars) }]
+          return {
+            kind: 'hover' as const,
+            hover: result.hover === null
+              ? null
+              : {
+                contents: result.hover.contents,
+                ...result.hover.range === undefined
+                  ? {}
+                  : {
+                    range: {
+                      start: { line: result.hover.range.start.line, character: result.hover.range.start.character },
+                      end: { line: result.hover.range.end.line, character: result.hover.range.end.character },
+                    },
+                  },
+              },
+          }
         /* v8 ignore next -- exhaustive over the closed LspQueryResult union; unreachable. */
         default:
           return assertNever(result, 'tool-lsp result')
diff --git a/packages/lsp/tool-lsp/tests/integration.spec.ts b/packages/lsp/tool-lsp/tests/integration.spec.ts
index c6b8ce60f3..0a0265b490 100644
--- a/packages/lsp/tool-lsp/tests/integration.spec.ts
+++ b/packages/lsp/tool-lsp/tests/integration.spec.ts
@@ -90,7 +90,7 @@ describe('tool-lsp integration', () => {
     const ctx = await mount(true, 300)
     const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 7 })
     expect(result.isError).toBe(true)
-    expect(result.error?.code).toBe('TOOL_TIMEOUT')
+    expect(result.error?.info?.code).toBe('TOOL_TIMEOUT')
     await ctx.fiber.dispose()
   }, 30_000)
 })
diff --git a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
index b141fd00dd..de7a5319ef 100644
--- a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
+++ b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
@@ -126,6 +126,29 @@ describe('tool-lsp execution', () => {
     const { ctx } = await mount(stubProvider(() => okLocations))
     const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
+    expect(result).toMatchObject({ isError: false, value: okLocations })
+  })
+
+  it('keeps all acquired locations in the canonical value when presentation is capped', async () => {
+    const cappedWorkspaceRoot = resolve('/virtual/capped-workspace')
+    const locations = [
+      { uri: pathToFileURL(join(cappedWorkspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } },
+      { uri: pathToFileURL(join(cappedWorkspaceRoot, 'b.ts')).href, range: { start: { line: 1, character: 2 }, end: { line: 1, character: 3 } } },
+    ]
+    const { ctx } = await mount(stubProvider(() => ({
+      kind: 'locations',
+      locations,
+      resolvedWorkspaceRoot: cappedWorkspaceRoot,
+    })), { maxLocations: 1 })
+    const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, cappedWorkspaceRoot)
+    expect(result.content[0]).toEqual({
+      type: 'text',
+      text: 'a.ts:1:1\n… 1 more location omitted (limit 1).',
+    })
+    expect(result).toMatchObject({
+      isError: false,
+      value: { kind: 'locations', locations, resolvedWorkspaceRoot: cappedWorkspaceRoot },
+    })
   })
 
   it('relativizes against the provider resolvedWorkspaceRoot, not the session cwd', async () => {
@@ -146,27 +169,42 @@ describe('tool-lsp execution', () => {
     const { ctx } = await mount(stubProvider(() => ({ kind: 'hover', hover: { contents: 'number' } })))
     const result = await call(ctx, { operation: 'hover', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     expect(result.content[0]).toEqual({ type: 'text', text: 'number' })
+    expect(result).toMatchObject({ isError: false, value: { kind: 'hover', hover: { contents: 'number' } } })
+  })
+
+  it('preserves an optional hover range in the canonical value', async () => {
+    const range = { start: { line: 2, character: 3 }, end: { line: 2, character: 7 } }
+    const { ctx } = await mount(stubProvider(() => ({ kind: 'hover', hover: { contents: 'number', range } })))
+    const result = await call(ctx, { operation: 'hover', file_path: 'a.ts', line: 3, character: 4 }, '/ws')
+    expect(result).toMatchObject({ isError: false, value: { kind: 'hover', hover: { contents: 'number', range } } })
+  })
+
+  it('preserves a null hover result as an explicit value', async () => {
+    const { ctx } = await mount(stubProvider(() => ({ kind: 'hover', hover: null })))
+    const result = await call(ctx, { operation: 'hover', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    expect(result.content[0]).toEqual({ type: 'text', text: 'No hover information.' })
+    expect(result).toMatchObject({ isError: false, value: { kind: 'hover', hover: null } })
   })
 
   it('fails LSP_WORKSPACE_REQUIRED without a session cwd', async () => {
     const { ctx } = await mount(stubProvider(() => okLocations))
     const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, null)
     expect(result.isError).toBe(true)
-    expect(result.error?.code).toBe('LSP_WORKSPACE_REQUIRED')
+    expect(result.error?.info?.code).toBe('LSP_WORKSPACE_REQUIRED')
   })
 
   it('surfaces a structured LSP_UNAVAILABLE when no provider handles the file', async () => {
     const { ctx } = await mount(stubProvider(() => okLocations, { '.py': 'python' }))
     const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     expect(result.isError).toBe(true)
-    expect(result.error?.code).toBe('LSP_UNAVAILABLE')
+    expect(result.error?.info?.code).toBe('LSP_UNAVAILABLE')
   })
 
   it('returns a structured INVALID_ARGS on a bad operation', async () => {
     const { ctx } = await mount(stubProvider(() => okLocations))
     const result = await call(ctx, { operation: 'rename', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     expect(result.isError).toBe(true)
-    expect(result.error?.code).toBe('INVALID_ARGS')
+    expect(result.error?.info?.code).toBe('INVALID_ARGS')
   })
 
   it('forwards exec.signal to the seam query', async () => {
diff --git a/packages/mcp/mcp-client/README.md b/packages/mcp/mcp-client/README.md
index ebcf29fad5..252cd27bfc 100644
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -56,8 +56,9 @@ Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`
 
 - On connect: `listTools()` → registers each tool via `ctx.tools.register()` under its public name.
 - 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.
-- Image content in results is discarded with a placeholder (the harness has no image block type).
+- 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.
 - On disconnect/crash: all tools are unregistered; no auto-reconnect.
 
 ## Services consumed
@@ -86,7 +87,7 @@ Prefix-stable while the discovered tool set and schemas are unchanged. A re-sync
 
 #### What the model sees
 
-The public tool name and JSON arguments remain in assistant history. Text result blocks are joined with newlines into one retained text result; image, audio, resource, and unsupported blocks become short placeholders, and MCP `isError` results follow the registry's model-visible error path.
+The public tool name and JSON arguments remain in assistant history. Text result blocks are joined with newlines into one retained Native text result; image, audio, resource, and unsupported blocks become short placeholders there. Their full JSON blocks and optional structured content remain in the execution-local canonical value, and MCP `isError` rejects the call through the registry's error path.
 
 #### Token effect
 
@@ -101,4 +102,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 - **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 unregisters the server's tools, but reconnect requires an HMR reload or harness restart.
-- **Non-text results are lossy** — image, audio, and resource payloads are replaced with placeholders, and a structured-only result has no model-visible structured representation.
+- **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/package.json b/packages/mcp/mcp-client/package.json
index cb3b51e1aa..3480b48e52 100644
--- a/packages/mcp/mcp-client/package.json
+++ b/packages/mcp/mcp-client/package.json
@@ -34,7 +34,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "schemastery": "^3.18.0"
+    "schemastery": "^3.18.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
@@ -42,7 +43,6 @@
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@modelcontextprotocol/server-everything": "^2026.7.4",
     "@modelcontextprotocol/server-filesystem": "^2026.7.4",
-    "cordis": "^4.0.0-rc.7",
-    "zod": "^4.4.3"
+    "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/mcp/mcp-client/src/index.ts b/packages/mcp/mcp-client/src/index.ts
index 4a18f85ff5..2e16e33b44 100644
--- a/packages/mcp/mcp-client/src/index.ts
+++ b/packages/mcp/mcp-client/src/index.ts
@@ -22,6 +22,8 @@ import { syncTools } from './tools.ts'
 // Side-effect type import: declaration-merges `ctx.tools` onto Context.
 import type {} from '@deepseek-ai/dsh-tools'
 
+export type { McpResult } from './tools.ts'
+
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'mcp-client'
 
diff --git a/packages/mcp/mcp-client/src/tools.ts b/packages/mcp/mcp-client/src/tools.ts
index 92f3742547..49e023ca4d 100644
--- a/packages/mcp/mcp-client/src/tools.ts
+++ b/packages/mcp/mcp-client/src/tools.ts
@@ -14,8 +14,12 @@
 
 import { createHash } from 'node:crypto'
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
 import type { Context } from 'cordis'
 import type { ToolDefinition, ToolExecution } from '@deepseek-ai/dsh-tools'
+import { assertSupportedJsonSchema } from '@deepseek-ai/dsh-tools'
+import type { JsonSchemaNode, JsonValue } from '@deepseek-ai/dsh-tools'
 
 /** Resolved options relevant to tool bridging. */
 export interface ToolBridgeOptions {
@@ -26,6 +30,12 @@ export interface ToolBridgeOptions {
 /** State for one sync generation: the current set of disposers keyed by public name. */
 export type ToolDisposers = Map<string, () => void>
 
+/** Canonical MCP result exposed to Code Mode without discarding protocol blocks. */
+export type McpResult<Structured extends JsonValue = JsonValue> = {
+  content: JsonValue[]
+  structuredContent?: Structured
+}
+
 /**
  * DeepSeek function-name contract: at most 64 characters. Wire-protocol
  * constant, not configuration.
@@ -38,6 +48,35 @@ const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g
 /** Hex chars of the SHA-256 identity hash appended on lossy normalization. */
 const HASH_LENGTH = 12
 
+/** Raw result record: the bridge owns JSON-value validation after transport. */
+const RawCallToolResultSchema = z.record(z.string(), z.unknown())
+
+/** List without mutating the SDK's per-page output-validator cache. */
+function listToolsUncached(client: Client, cursor?: string) {
+  return client.request(
+    { method: 'tools/list', ...cursor === undefined ? {} : { params: { cursor } } },
+    ListToolsResultSchema,
+  )
+}
+
+/** Call without the SDK pre-validating an output schema the bridge may not support. */
+function callToolUncached(
+  client: Client,
+  rawName: string,
+  args: Record<string, unknown>,
+  exec: ToolExecution,
+  opts: ToolBridgeOptions,
+) {
+  return client.request(
+    { method: 'tools/call', params: { name: rawName, arguments: args } },
+    RawCallToolResultSchema,
+    {
+      signal: exec.signal,
+      timeout: opts.toolCallTimeoutMs,
+    },
+  )
+}
+
 /**
  * Derive the model-facing public name for one MCP tool.
  *
@@ -65,7 +104,7 @@ export function publicToolName(serverName: string, rawName: string): string {
  *
  * Two phases keep the swap safe:
  *
- * 1. Fetch: drain `client.listTools()` pagination and build the full next
+ * 1. Fetch: drain uncached `tools/list` pagination and build the full next
  *    generation of `ToolDefinition`s under public names. Any failure here
  *    (network error, duplicate raw name in the server's list) rejects and
  *    leaves the previous generation registered untouched.
@@ -93,7 +132,7 @@ export async function syncTools(
   const definitions = new Map<string, ToolDefinition>()
   let cursor: string | undefined
   do {
-    const response = await client.listTools(cursor ? { cursor } : undefined)
+    const response = await listToolsUncached(client, cursor)
     for (const tool of response.tools) {
       const publicName = publicToolName(opts.serverName, tool.name)
       if (definitions.has(publicName)) {
@@ -105,7 +144,8 @@ export async function syncTools(
         name: publicName,
         description: tool.description ?? '',
         parameters: tool.inputSchema,
-        execute: createExecutor(client, tool.name, opts),
+        output: createOutput(tool.name, supportedOutputSchema(tool.outputSchema)),
+        execute: createExecutor(client, tool.name, tool.execution?.taskSupport === 'required', opts),
       })
     }
     cursor = response.nextCursor
@@ -141,11 +181,42 @@ interface McpContentBlock {
   mimeType?: string
 }
 
+/** Keep a supported advertised schema; unsupported MCP vocabulary falls back to JsonValue. */
+function supportedOutputSchema(candidate: unknown): JsonSchemaNode | undefined {
+  if (candidate === undefined) return undefined
+  try {
+    assertSupportedJsonSchema(candidate)
+    return candidate
+  } catch {
+    return undefined
+  }
+}
+
+/** Build the canonical result schema and existing Native text projection. */
+function createOutput(rawName: string, structuredSchema: JsonSchemaNode | undefined): ToolDefinition['output'] {
+  return {
+    schema: {
+      type: 'object',
+      properties: {
+        content: { type: 'array', items: {} },
+        structuredContent: structuredSchema ?? {},
+      },
+      required: structuredSchema === undefined ? ['content'] : ['content', 'structuredContent'],
+      additionalProperties: false,
+    },
+    render(_args, value) {
+      const result = value as unknown as McpResult
+      return [{ type: 'text', text: extractText(result.content, rawName) }]
+    },
+  }
+}
+
 /**
  * Create an execute function for one MCP tool. The executor closes over the
- * raw MCP tool name and calls `client.callTool` with it (never the public
- * name), with abort signal and timeout, then maps the result to harness
- * ContentBlocks.
+ * raw MCP tool name and sends an uncached `tools/call` request with it (never
+ * the public name), with abort signal and timeout, then maps the result to
+ * harness ContentBlocks. Owning the raw request prevents the SDK's internal
+ * per-page schema cache from pre-validating a different contract.
  *
  * When the MCP server returns `isError: true`, the executor throws so that
  * the ToolRegistry's catch path produces an `isError` result for the model.
@@ -153,45 +224,53 @@ interface McpContentBlock {
 function createExecutor(
   client: Client,
   rawName: string,
+  taskRequired: boolean,
   opts: ToolBridgeOptions,
 ): ToolDefinition['execute'] {
   return async (args: unknown, exec: ToolExecution) => {
+    if (taskRequired) {
+      throw new Error(`Tool "${rawName}" requires task-based execution, which this bridge does not support`)
+    }
     // The agent loop passes `JSON.parse(model_arguments)` which is usually an
     // object, but can be any JSON value if the model misbehaves (outputs a bare
     // string/number/null). Fallback to {} lets the MCP server produce a
     // specific "missing required param" error the model can learn from.
     const argsObj = (typeof args === 'object' && args !== null ? args : {}) as Record<string, unknown>
-    const result = await client.callTool(
-      { name: rawName, arguments: argsObj },
-      undefined,
-      {
-        signal: exec.signal,
-        timeout: opts.toolCallTimeoutMs,
-      },
-    )
+    const result = await callToolUncached(client, rawName, argsObj, exec, opts)
 
     // The SDK may return a legacy `toolResult` shape; normalize to content array.
-    if (!('content' in result) || !Array.isArray(result.content)) {
-      const text = 'toolResult' in result
+    if (!Array.isArray(result.content)) {
+      const rendered: unknown = 'toolResult' in result
         ? JSON.stringify(result.toolResult)
         : '(no output)'
-      return [{ type: 'text' as const, text }]
+      const text = typeof rendered === 'string' ? rendered : '(no output)'
+      if (result.isError === true) throw new Error(text)
+      return {
+        content: [{ type: 'text', text }],
+        ...result.structuredContent !== undefined
+          ? { structuredContent: result.structuredContent as JsonValue }
+          : {},
+      }
     }
 
     // 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).
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    const content: McpContentBlock[] = result.content
+    const content = result.content as unknown as JsonValue[]
     const text = extractText(content, rawName)
 
     // MCP isError → throw so ToolRegistry produces an isError result for the model.
-    if ('isError' in result && result.isError === true) {
+    if (result.isError === true) {
       throw new Error(text)
     }
 
-    return [{ type: 'text', text }]
+    return {
+      content,
+      ...result.structuredContent !== undefined
+        ? { structuredContent: result.structuredContent as JsonValue }
+        : {},
+    }
   }
 }
 
@@ -203,10 +282,15 @@ function createExecutor(
  * Defensive: fields that the MCP spec declares required (mimeType, text) are
  * guarded with fallbacks because this is a network trust boundary.
  */
-function extractText(mcpContent: McpContentBlock[], toolName: string): string {
+function extractText(mcpContent: JsonValue[], toolName: string): string {
   const parts: string[] = []
 
-  for (const block of mcpContent) {
+  for (const value of mcpContent) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      parts.push('[unsupported content type: unknown]')
+      continue
+    }
+    const block = value as unknown as McpContentBlock
     switch (block.type) {
       case 'text':
         if (block.text !== undefined) parts.push(block.text)
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 4b43411346..e36e091478 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -15,14 +15,26 @@ import type { Config } from '@deepseek-ai/dsh-mcp-client'
 const { mockConnect, mockClose, mockListTools, mockCallTool, mockSetNotificationHandler, MockClient } = vi.hoisted(() => {
   const mockConnect = vi.fn<() => Promise<void>>()
   const mockClose = vi.fn<() => Promise<void>>()
-  const mockListTools = vi.fn()
-  const mockCallTool = vi.fn()
+  const mockListTools = vi.fn<(_params?: Record<string, unknown>) => Promise<unknown>>()
+  const mockCallTool = vi.fn<(
+    _params?: Record<string, unknown>, _compatibilitySchema?: unknown, _options?: unknown,
+  ) => Promise<unknown>>()
   const mockSetNotificationHandler = vi.fn()
+  const mockRequest = vi.fn(async (
+    request: { method: string; params?: Record<string, unknown> },
+    _schema: unknown,
+    options?: unknown,
+  ): Promise<unknown> => {
+    if (request.method === 'tools/list') return await mockListTools(request.params)
+    if (request.method === 'tools/call') return await mockCallTool(request.params, undefined, options)
+    throw new Error(`unexpected MCP request: ${request.method}`)
+  })
   class MockClient {
     connect = mockConnect
     close = mockClose
     listTools = mockListTools
     callTool = mockCallTool
+    request = mockRequest
     setNotificationHandler = mockSetNotificationHandler
   }
   return { mockConnect, mockClose, mockListTools, mockCallTool, mockSetNotificationHandler, MockClient }
diff --git a/packages/mcp/mcp-client/tests/mcp-client.spec.ts b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
index 557379808c..3077d6b86b 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.spec.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
@@ -1,8 +1,10 @@
 import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { type JsonValue } from '@deepseek-ai/dsh-tools'
 import { publicToolName, syncTools, type ToolBridgeOptions } from '@deepseek-ai/dsh-mcp-client/src/tools.ts'
 import { createTransport } from '@deepseek-ai/dsh-mcp-client/src/transport.ts'
 import type { Config } from '@deepseek-ai/dsh-mcp-client'
@@ -15,17 +17,37 @@ interface MockTool {
   name: string
   description?: string
   inputSchema: Record<string, unknown>
+  outputSchema?: Record<string, unknown>
+  execution?: { taskSupport?: 'optional' | 'required' | 'forbidden' }
 }
 
 interface MockCallResult {
-  content: Array<{ type: string; text?: string; mimeType?: string }>
+  content: JsonValue[]
+  structuredContent?: JsonValue
   isError?: boolean
 }
 
 function createMockClient(tools: MockTool[], callResult: MockCallResult = { content: [{ type: 'text', text: 'ok' }] }) {
+  const listTools = vi.fn(async (
+    _params?: Record<string, unknown>,
+  ): Promise<{ tools: MockTool[]; nextCursor: string | undefined }> => ({ tools, nextCursor: undefined }))
+  const callTool = vi.fn(async (
+    _params?: Record<string, unknown>,
+    _compatibilitySchema?: unknown,
+    _options?: unknown,
+  ): Promise<Record<string, unknown>> => ({ ...callResult }))
   return {
-    listTools: vi.fn().mockResolvedValue({ tools, nextCursor: undefined }),
-    callTool: vi.fn().mockResolvedValue(callResult),
+    listTools,
+    callTool,
+    request: vi.fn(async (
+      request: { method: string; params?: Record<string, unknown> },
+      _schema: unknown,
+      options?: unknown,
+    ): Promise<unknown> => {
+      if (request.method === 'tools/list') return listTools(request.params)
+      if (request.method === 'tools/call') return callTool(request.params, undefined, options)
+      throw new Error(`unexpected MCP request: ${request.method}`)
+    }),
     setNotificationHandler: vi.fn(),
     connect: vi.fn().mockResolvedValue(undefined),
     close: vi.fn().mockResolvedValue(undefined),
@@ -116,7 +138,8 @@ describe('syncTools', () => {
       name: 'search',
       description: 'Native search',
       parameters: { type: 'object' },
-      execute: async () => [{ type: 'text', text: 'native' }],
+      output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value as string }] },
+      execute: async () => 'native',
     })
     const client = createMockClient([{ name: 'search', inputSchema: { type: 'object' } }])
 
@@ -158,7 +181,8 @@ describe('syncTools', () => {
       name: 'mcp__srv__taken',
       description: 'Squatter',
       parameters: { type: 'object' },
-      execute: async () => [{ type: 'text', text: 'squatter' }],
+      output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value as string }] },
+      execute: async () => 'squatter',
     })
     const client = createMockClient([
       { name: 'free', inputSchema: { type: 'object' } },
@@ -203,6 +227,82 @@ describe('syncTools', () => {
     expect(ctx.tools.get('mcp__srv__page1')).toBeDefined()
     expect(ctx.tools.get('mcp__srv__page2')).toBeDefined()
   })
+
+  it('owns output validation independently of the SDK per-page cache', async () => {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+    serverTransport.onmessage = (message) => {
+      if (!('id' in message) || !('method' in message)) return
+      const params = 'params' in message ? message.params : undefined
+      let result: Record<string, unknown>
+      if (message.method === 'initialize') {
+        const protocolVersion = params && 'protocolVersion' in params
+          ? params.protocolVersion
+          : '2025-11-25'
+        result = {
+          protocolVersion,
+          capabilities: { tools: {} },
+          serverInfo: { name: 'raw-test', version: '1' },
+        }
+      } else if (message.method === 'tools/list') {
+        const cursor = params && 'cursor' in params ? params.cursor : undefined
+        result = cursor === undefined
+          ? {
+            tools: [{
+              name: 'supported',
+              inputSchema: { type: 'object' },
+              outputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: { answer: { type: 'integer' } },
+                required: ['answer'],
+              },
+            }],
+            nextCursor: 'page-2',
+          }
+          : {
+            tools: [{
+              name: 'future-schema',
+              inputSchema: { type: 'object' },
+              outputSchema: { type: 'object', patternProperties: { '^x-': { type: 'string' } } },
+            }],
+          }
+      } else if (message.method === 'tools/call') {
+        const name = params && 'name' in params ? params.name : undefined
+        result = name === 'supported'
+          ? { content: [{ type: 'text', text: 'missing structured content' }] }
+          : { content: [42, null], structuredContent: ['kept', { nested: true }] }
+      } else {
+        result = {}
+      }
+      void serverTransport.send({ jsonrpc: '2.0', id: message.id, result })
+    }
+    await serverTransport.start()
+    const client = new Client({ name: 'cache-independent-test', version: '1' })
+    await client.connect(clientTransport)
+
+    try {
+      await syncTools(client, ctx, defaultOpts, new Map())
+
+      const missing = await ctx.tools.execute({
+        signal: testToolSignal,
+        callId: CallId('missing'), name: 'mcp__srv__supported', arguments: {},
+      })
+      expect(missing.error).toMatchObject({ info: { code: 'INVALID_TOOL_OUTPUT' } })
+      expect(missing.error?.message).toContain('structuredContent')
+
+      const fallback = await ctx.tools.execute({
+        signal: testToolSignal,
+        callId: CallId('fallback'), name: 'mcp__srv__future-schema', arguments: {},
+      })
+      if (fallback.isError) throw new Error('unsupported schema must use the bridge fallback')
+      expect(fallback.value).toEqual({
+        content: [42, null],
+        structuredContent: ['kept', { nested: true }],
+      })
+    } finally {
+      await client.close()
+    }
+  })
 })
 
 describe('tool execution', () => {
@@ -223,6 +323,8 @@ describe('tool execution', () => {
 
     expect(result.isError).toBe(false)
     expect(result.content).toEqual([{ type: 'text', text: 'hello world' }])
+    if (result.isError) throw new Error('expected MCP success')
+    expect(result.value).toEqual({ content: [{ type: 'text', text: 'hello world' }] })
     // The wire sees the raw MCP name, never the public name.
     expect(client.callTool).toHaveBeenCalledWith(
       { name: 'echo', arguments: { msg: 'hi' } },
@@ -261,16 +363,86 @@ describe('tool execution', () => {
     expect(result.content).toEqual([{ type: 'text', text: 'line1\nline2' }])
   })
 
-  it('discards image content with placeholder', async () => {
+  it('preserves full JSON MCP blocks while Native rendering uses placeholders', async () => {
+    const blocks = [
+      { type: 'text', text: 'before' },
+      { type: 'image', mimeType: 'image/png', data: 'base64-data', annotations: { audience: ['assistant'] } },
+    ] satisfies JsonValue[]
     const client = createMockClient(
       [{ name: 'img', inputSchema: { type: 'object' } }],
-      { content: [{ type: 'text', text: 'before' }, { type: 'image', mimeType: 'image/png' }] },
+      { content: blocks },
     )
 
     await syncTools(client as never, ctx, defaultOpts, new Map())
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'mcp__srv__img', arguments: {} })
 
     expect(result.content[0]).toEqual({ type: 'text', text: 'before\n[image: image/png, content discarded]' })
+    if (result.isError) throw new Error('expected MCP success')
+    expect(result.value).toEqual({ content: blocks })
+  })
+
+  it('preserves primitive JSON MCP blocks while Native rendering marks them unsupported', async () => {
+    const blocks = [42, null, ['nested']] satisfies JsonValue[]
+    const client = createMockClient(
+      [{ name: 'primitive-blocks', inputSchema: { type: 'object' } }],
+      { content: blocks },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('primitive'), name: 'mcp__srv__primitive-blocks', arguments: {},
+    })
+
+    expect(result.content[0]).toEqual({
+      type: 'text',
+      text: '[unsupported content type: unknown]\n[unsupported content type: unknown]\n[unsupported content type: unknown]',
+    })
+    if (result.isError) throw new Error('expected primitive MCP blocks to remain a successful JSON value')
+    expect(result.value).toEqual({ content: blocks })
+  })
+
+  it('validates structuredContent when the advertised output schema is supported', async () => {
+    const outputSchema = {
+      type: 'object',
+      additionalProperties: false,
+      properties: { answer: { type: 'integer' } },
+      required: ['answer'],
+    }
+    const valid = createMockClient(
+      [{ name: 'structured', inputSchema: { type: 'object' }, outputSchema }],
+      { content: [{ type: 'text', text: '42' }], structuredContent: { answer: 42 } },
+    )
+    await syncTools(valid as never, ctx, defaultOpts, new Map())
+    const success = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('valid'), name: 'mcp__srv__structured', arguments: {} })
+    if (success.isError) throw new Error('expected supported structuredContent to validate')
+    expect(success.value).toEqual({ content: [{ type: 'text', text: '42' }], structuredContent: { answer: 42 } })
+
+    const invalidCtx = await mountRegistry()
+    const invalid = createMockClient(
+      [{ name: 'structured', inputSchema: { type: 'object' }, outputSchema }],
+      { content: [{ type: 'text', text: 'wrong' }], structuredContent: { answer: 'forty-two' } },
+    )
+    await syncTools(invalid as never, invalidCtx, defaultOpts, new Map())
+    const failure = await invalidCtx.tools.execute({ signal: testToolSignal, callId: CallId('invalid'), name: 'mcp__srv__structured', arguments: {} })
+    expect(failure.error).toMatchObject({ info: { code: 'INVALID_TOOL_OUTPUT' } })
+    expect(failure.content[0]?.type === 'text' ? failure.content[0].text : '')
+      .toContain('value.structuredContent.answer')
+  })
+
+  it('falls back to JsonValue for unsupported advertised output schemas', async () => {
+    const client = createMockClient(
+      [{
+        name: 'future-schema',
+        inputSchema: { type: 'object' },
+        outputSchema: { type: 'object', patternProperties: { '^x-': { type: 'string' } } },
+      }],
+      { content: [], structuredContent: ['kept', { nested: true }] },
+    )
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('fallback'), name: 'mcp__srv__future-schema', arguments: {} })
+    if (result.isError) throw new Error('unsupported MCP output schemas must fall back')
+    expect(result.value).toEqual({ content: [], structuredContent: ['kept', { nested: true }] })
   })
 
   it('maps isError to an error result via throw', async () => {
@@ -284,6 +456,23 @@ describe('tool execution', () => {
 
     expect(result.isError).toBe(true)
     expect(result.content[0]).toEqual({ type: 'text', text: 'Error: something went wrong' })
+    expect('value' in result).toBe(false)
+  })
+
+  it('rejects tools that require task-based execution', async () => {
+    const client = createMockClient([
+      { name: 'task-only', inputSchema: { type: 'object' }, execution: { taskSupport: 'required' } },
+    ])
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('task-only'), name: 'mcp__srv__task-only', arguments: {},
+    })
+
+    expect(result.isError).toBe(true)
+    expect(result.error?.message).toContain('requires task-based execution')
+    expect(client.callTool).not.toHaveBeenCalled()
   })
 
   it('passes abort signal to callTool', async () => {
@@ -315,6 +504,40 @@ describe('tool execution', () => {
     expect(result.isError).toBe(false)
     expect(result.content[0]).toEqual({ type: 'text', text: '{"key":"value"}' })
   })
+
+  it('preserves structuredContent on a successful legacy result', async () => {
+    const client = createMockClient([{ name: 'legacy-structured', inputSchema: { type: 'object' } }])
+    client.callTool.mockResolvedValue({
+      toolResult: 'legacy',
+      structuredContent: { answer: 42 },
+    })
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('legacy-structured'), name: 'mcp__srv__legacy-structured', arguments: {},
+    })
+
+    if (result.isError) throw new Error('expected legacy structured result success')
+    expect(result.value).toEqual({
+      content: [{ type: 'text', text: '"legacy"' }],
+      structuredContent: { answer: 42 },
+    })
+  })
+
+  it('maps a legacy isError reply to failure', async () => {
+    const client = createMockClient([{ name: 'legacy-error', inputSchema: { type: 'object' } }])
+    client.callTool.mockResolvedValue({ toolResult: { reason: 'nope' }, isError: true })
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('legacy-error'), name: 'mcp__srv__legacy-error', arguments: {},
+    })
+
+    expect(result.isError).toBe(true)
+    expect(result.error?.message).toBe('{"reason":"nope"}')
+  })
 })
 
 describe('tool execution edge cases', () => {
@@ -425,7 +648,7 @@ describe('tool execution edge cases', () => {
     const client = createMockClient(
       [{ name: 'legacy2', inputSchema: { type: 'object' } }],
     )
-    client.callTool.mockResolvedValue({})
+    client.callTool.mockResolvedValue({ toolResult: undefined, structuredContent: undefined })
 
     await syncTools(client as never, ctx, defaultOpts, new Map())
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'mcp__srv__legacy2', arguments: {} })
@@ -433,6 +656,18 @@ describe('tool execution edge cases', () => {
     expect(result.content[0]).toEqual({ type: 'text', text: '(no output)' })
   })
 
+  it('handles a legacy result with neither content nor toolResult', async () => {
+    const client = createMockClient(
+      [{ name: 'legacy-empty', inputSchema: { type: 'object' } }],
+    )
+    client.callTool.mockResolvedValue({})
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('legacy-empty'), name: 'mcp__srv__legacy-empty', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '(no output)' })
+  })
+
   it('handles isError with non-text content (fallback error message)', async () => {
     const client = createMockClient(
       [{ name: 'err_notext', inputSchema: { type: 'object' } }],
diff --git a/packages/plan/README.md b/packages/plan/README.md
index a1f73d191f..f90d16ab51 100644
--- a/packages/plan/README.md
+++ b/packages/plan/README.md
@@ -4,6 +4,6 @@ Plan mode is one logged, per-agent collaboration state. It is a single **product
 
 | Package | Role | ctx key |
 |---|---|---|
-| `plan-mode/` | `plan/mode` vocabulary + fold, boundary-applied state, the `plan:policy` guidance section, `/plan [message]`, and the model-facing `exit_plan_mode` review tool | `ctx.planMode` |
+| `plan-mode/` | `plan/mode` vocabulary + fold, boundary-applied state, the `plan:policy` guidance section, `/plan [message]` entry and `/plan off` exit, and the model-facing `exit_plan_mode` review tool | `ctx.planMode` |
 
 The active state is a pure function of the session log, so resume and fork restore it without extra machinery. The deployment supplies plan instructions through Cordis config, while `exit_plan_mode` stays registered when planning is inactive to keep the request tool catalog stable. ACP maps this capability onto its generic `default` / `plan` picker; sandbox mode and approval policy remain independent enforcement settings. Design: [plan-mode Agent Note](../../.agents/notes/implemented/feature/2026-07-07-plan-mode.md) and [plan-specific state simplification](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).
diff --git a/packages/plan/plan-mode/README.md b/packages/plan/plan-mode/README.md
index 1c43c37b7f..0f24508d14 100644
--- a/packages/plan/plan-mode/README.md
+++ b/packages/plan/plan-mode/README.md
@@ -1,18 +1,18 @@
 # @deepseek-ai/dsh-plan-mode
 
-Logged, per-agent plan collaboration state with deployment-owned guidance, a direct `/plan [message]` entry command, and the reviewed `exit_plan_mode` exit. Plan mode is soft guidance; sandbox mode and approval policy remain independent enforcement axes.
+Logged, per-agent plan collaboration state with deployment-owned guidance, direct `/plan [message]` entry and `/plan off` exit commands, and the reviewed `exit_plan_mode` exit. Plan mode is soft guidance; sandbox mode and approval policy remain independent enforcement axes.
 
 ## Durable state
 
 `plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace `SessionEventMap` member. `foldPlanMode(events)` returns the last logged value or `false`, so resume, fork, and compaction recover plan state directly from the session log. UIs observe committed flips through `session/event`.
 
-`ctx.planMode.set(agent, active)` records a pending selection and flushes it inside the next turn boundary. `get(agent)` returns `{ active, pending? }`, separating the logged state shaping the current step from a user's optimistic selection. Prompt submission, ordinary continuation, and request-recovery retry are all covered; a changed user selection contributes one `context/message` notice when the last logged request header described the other state.
+`ctx.planMode.set(agent, active)` records a pending selection and flushes it inside the next turn boundary. `get(agent)` returns `{ active, pending? }`, separating the logged state shaping the current step from a user's optimistic selection. Prompt submission, ordinary continuation, and request-recovery retry are all covered; a changed user selection contributes one plugin-sourced `user/message` notice when the last logged request header described the other state.
 
 ## Model and human surfaces
 
 While active, `plan:policy` renders the configured `section`. The plugin always registers `exit_plan_mode`, keeping tool schemas stable across the transition; its execute path accepts only active plan mode and leaves it only after an exact user approval through `ctx.userInteraction`.
 
-When `ctx.commands` is composed, the package registers `/plan [message]`. The command selects plan mode first. A non-empty argument is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance; bare `/plan` only changes state.
+When `ctx.commands` is composed, the package registers `/plan [message]` and reserves the exact argument `off` for direct exit. Bare `/plan` selects plan mode; any other non-empty argument selects it first and is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance. `/plan off` selects inactive without sending model input; it also cancels a pending entry before plan mode reaches a request.
 
 ACP is an adapter, not the owner of this vocabulary: it advertises the fixed wire ids `default` and `plan`, maps `session/set_mode` to the boolean service, and translates committed `plan/mode` events back to `current_mode_update`.
 
@@ -53,25 +53,25 @@ Inactive mode adds no tokens; active mode adds the configured section to every r
 
 The section is stable within plan mode, but entering or leaving changes the system prompt from order 50 onward.
 
-### Optional command message
+### Human command
 
 #### What the model sees
 
-`/plan` and its terminal result stay outside model history; a non-empty suffix becomes one trimmed user text block through `agent.steer()` after plan mode is selected.
+`/plan`, `/plan off`, and their terminal results stay outside model history. A non-empty suffix other than the exact `off` argument becomes one trimmed user text block through `agent.steer()` after plan mode is selected. An active `/plan off` selection contributes the standard logged user-switch notice only when the last request header described plan mode; cancelling a pending entry contributes none because no request observed it.
 
 #### Token effect
 
-The suffix costs the same history tokens as submitting that text separately; a bare command adds none.
+The optional message costs the same history tokens as submitting that text separately; bare `/plan` and `/plan off` add none. A narrated active exit adds the small retained switch notice.
 
 #### KV Cache effect
 
-The user block is append-only conversation growth, while entering plan mode also changes the earlier policy section.
+The user block is append-only conversation growth. Entering or leaving plan mode changes the earlier policy section; a narrated exit notice is appended after the reusable request prefix.
 
 ### Exit tool schema and review exchange
 
 #### What the model sees
 
-The [`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) remains available in both states; execution outside plan mode fails, while an approved in-mode review returns the exit result and rejection returns feedback.
+The [`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) remains available in both states; execution outside plan mode fails, while an approved in-mode review returns the canonical `{ approved: true }` value and renders the existing confirmation text. Rejection remains a failed call carrying review feedback.
 
 #### Token effect
 
diff --git a/packages/plan/plan-mode/src/index.ts b/packages/plan/plan-mode/src/index.ts
index 27d54c5a69..26ad904d30 100644
--- a/packages/plan/plan-mode/src/index.ts
+++ b/packages/plan/plan-mode/src/index.ts
@@ -1,9 +1,10 @@
 /**
  * Plan mode is logged per-agent collaboration state: while active, a
  * deployment-owned guidance section shapes each model request, and
- * `exit_plan_mode` presents the completed plan for user review. It is
- * independent of sandbox mode and approval policy; those enforcement axes do
- * not read or write plan state.
+ * `exit_plan_mode` presents the completed plan for user review, while the
+ * `/plan off` command lets a user leave directly. Plan mode is independent of
+ * sandbox mode and approval policy; those enforcement axes do not read or
+ * write plan state.
  *
  * The state in force is folded from the session log (`plan/mode`, last one
  * wins), so resume and fork restore it without a live mirror. User selections
@@ -210,13 +211,27 @@ export class PlanModeService extends Service {
     ctx.inject(['commands'], (commandCtx) => {
       commandCtx.commands.register({
         name: 'plan',
-        description: 'Enter plan mode',
-        input: { hint: '[message]' },
+        description: 'Enter or leave plan mode',
+        input: { hint: '[off|message]' },
         handler: ({ agent, rawInput }) => {
           const message = rawInput.trim()
+          if (message === 'off') {
+            const state = this.get(agent)
+            this.set(agent, false)
+            if (state.active) {
+              return { kind: 'success', text: 'Leaving plan mode (applies from the next step).' }
+            }
+            if (state.pending === true) {
+              return { kind: 'success', text: 'Plan mode entry cancelled.' }
+            }
+            return { kind: 'success', text: 'Plan mode is already inactive.' }
+          }
           this.set(agent, true)
           if (message !== '') agent.steer([{ type: 'text', text: message }])
-          return { kind: 'success', text: 'Entering plan mode (applies from the next step).' }
+          return {
+            kind: 'success',
+            text: 'Entering plan mode (applies from the next step). Use /plan off to leave.',
+          }
         },
       })
     })
@@ -227,6 +242,16 @@ export class PlanModeService extends Service {
       parameters: {
         plan: { type: 'string', required: true, description: 'The complete plan, as markdown, starting with a # heading that names it.' },
       },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            approved: { type: 'boolean', const: true, required: true },
+          },
+        },
+        render: () => [{ type: 'text', text: 'Plan approved — plan mode exited; carry out the plan starting with your next step.' }],
+      },
       execute: async (args, exec) => {
         const agent = exec.agent
         if (agent === undefined) throw new Error(`${EXIT_PLAN_MODE} requires a calling agent (no session to switch)`)
@@ -270,7 +295,7 @@ export class PlanModeService extends Service {
         // Keep plan guidance for the rest of this assistant tool batch. The
         // silent intent flushes after the step, before the next assembly.
         this.pendingIntents.set(agent.session, { active: false, narrate: false })
-        return [{ type: 'text', text: 'Plan approved — plan mode exited; carry out the plan starting with your next step.' }]
+        return { approved: true }
       },
       presentCall: args => ({
         card: 'generic',
@@ -332,7 +357,7 @@ export class PlanModeService extends Service {
     const text = target
       ? 'The user switched this session to plan mode.'
       : 'The user switched this session back to the default mode.'
-    session.append('context/message', {
+    session.append('user/message', {
       content: [{ type: 'text', text }],
       source: { kind: 'plugin', plugin: 'plan-mode' },
     }, { surfaceOp: 'append' })
diff --git a/packages/plan/plan-mode/tests/integration.spec.ts b/packages/plan/plan-mode/tests/integration.spec.ts
index f1c57b5938..e195ed54b2 100644
--- a/packages/plan/plan-mode/tests/integration.spec.ts
+++ b/packages/plan/plan-mode/tests/integration.spec.ts
@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import LlmService, { type StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import PlanModeService, { foldPlanMode } from '@deepseek-ai/dsh-plan-mode'
@@ -30,7 +30,7 @@ async function harness(adapter: MockAdapter): Promise<Context> {
   await ctx.plugin(PlanModeService, PLAN_CONFIG)
   ctx.llm.registerAdapter(['mock'], adapter)
   for (const name of ['read', 'write']) {
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name,
       description: `test tool ${name}`,
       parameters: {},
@@ -75,7 +75,7 @@ describe('plan mode through the agent loop', () => {
     // the first prompt-submit, BEFORE the first assembly.
     ctx.planMode.set(agent, true)
 
-    agent.send([{ type: 'text', text: 'explore the repo' }])
+    agent.followup([{ type: 'text', text: 'explore the repo' }])
     await waitForIdle(ctx, agent)
 
     const log = agent.session.events
@@ -92,7 +92,7 @@ describe('plan mode through the agent loop', () => {
     const result = findEvent(log, 'tool/result')
     expect(result.data.isError).toBe(false)
     expect(foldPlanMode(log)).toBe(true)
-    expect(log.some(event => event.type === 'context/message')).toBe(false)
+    expect(log.some(event => event.type === 'user/message' && event.data.source.kind === 'plugin')).toBe(false)
   })
 
   it('a user flip between turns lands at the boundary: one notice and a changed header with stable tool schemas', async () => {
@@ -103,21 +103,21 @@ describe('plan mode through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-plan-flip'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'hello' }])
+    agent.followup([{ type: 'text', text: 'hello' }])
     await waitForIdle(ctx, agent)
     expect(foldPlanMode(agent.session.events)).toBe(false)
     const first = findEvent(agent.session.events, 'request/header')
     expect(first.data.header.tools?.map(tool => tool.name)).toEqual(['exit_plan_mode', 'read', 'write'])
 
     ctx.planMode.set(agent, true)
-    agent.send([{ type: 'text', text: 'now plan' }])
+    agent.followup([{ type: 'text', text: 'now plan' }])
     await waitForIdle(ctx, agent)
 
     const log = agent.session.events
     expect(foldPlanMode(log)).toBe(true)
-    const notices = log.filter(event => event.type === 'context/message')
+    const notices = log.filter(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
     expect(notices).toHaveLength(1)
-    expect(findEvent(log, 'context/message').data.content).toEqual([
+    expect(notices[0]?.type === 'user/message' && notices[0].data.content).toEqual([
       { type: 'text', text: 'The user switched this session to plan mode.' },
     ])
     // The changed request is logged as a complete snapshot.
@@ -146,7 +146,7 @@ describe('plan mode through the agent loop', () => {
     })
 
     const idle = waitForIdle(ctx, agent)
-    agent.send([{ type: 'text', text: 'plan after the transient failure' }])
+    agent.followup([{ type: 'text', text: 'plan after the transient failure' }])
     await recoveryEntered.promise
     ctx.planMode.set(agent, true)
     releaseRecovery.resolve(true)
@@ -163,7 +163,8 @@ describe('plan mode through the agent loop', () => {
     expect(firstEnd?.seq).toBeLessThan(planMode.seq)
     expect(planMode.seq).toBeLessThan(retryStart?.seq ?? 0)
     expect(findEvent(log, 'request/header', 'last').data.header.system).toContain(PLAN_CONFIG.section)
-    expect(findEvent(log, 'context/message').data.content).toEqual([
+    const notice = log.find(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
+    expect(notice?.type === 'user/message' && notice.data.content).toEqual([
       { type: 'text', text: 'The user switched this session to plan mode.' },
     ])
   })
diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts
index b5dc9723de..a7f7743497 100644
--- a/packages/plan/plan-mode/tests/plan-mode.spec.ts
+++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { RUN_CODE_NAME, defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { RUN_CODE_NAME, defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import { agentEvents, type Agent, type RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { createScope } from '@deepseek-ai/dsh-scope'
@@ -95,13 +95,13 @@ function header(session: Session): void {
 
 function noticeTexts(session: Session): string[] {
   return session.events
-    .filter(event => event.type === 'context/message')
+    .filter(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
     .map(event => (event.data as { content: { type: string; text?: string }[] }).content.map(block => block.text ?? '').join(''))
 }
 
 function registerNamedTools(ctx: Context, names: string[]): void {
   for (const name of names) {
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name,
       description: `test tool ${name}`,
       parameters: {},
@@ -110,6 +110,16 @@ function registerNamedTools(ctx: Context, names: string[]): void {
   }
 }
 
+/** Assert the mapped Code Mode SDK includes the stable plan exit binding and test tools. */
+function expectPlanCodeSdkBindings(sdk: string): void {
+  expect(sdk).toContain('interface ToolArgsMap {')
+  expect(sdk).toContain('read: Record<string, JsonValue>;')
+  expect(sdk).toContain('write: Record<string, JsonValue>;')
+  expect(sdk).toContain('interface ToolOutputMap {')
+  expect(sdk).toContain('exit_plan_mode: {\n    approved: true;\n  };')
+  expect(sdk).toContain('[K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;')
+}
+
 let callCounter = 0
 function execute(ctx: Context, name: string, agent?: Agent) {
   return ctx.tools.execute({
@@ -445,9 +455,7 @@ describe('the soft layer', () => {
     // The SDK documents the full binding set plus the exit; plan mode never
     // prunes capabilities and restrains through guidance alone.
     const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text ?? ''
-    expect(sdk).toContain('read(args:')
-    expect(sdk).toContain('write(args:')
-    expect(sdk).toContain('exit_plan_mode(args:')
+    expectPlanCodeSdkBindings(sdk)
   })
 
   it('keeps native wire schemas and the SDK in step under mode both', async () => {
@@ -468,9 +476,7 @@ describe('the soft layer', () => {
     // is present on the wire AND in the SDK alongside the untouched toolset.
     expect(assembly.tools.map(tool => tool.name).sort()).toEqual(['exit_plan_mode', 'read', 'run_code', 'write'])
     const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text ?? ''
-    expect(sdk).toContain('read(args:')
-    expect(sdk).toContain('write(args:')
-    expect(sdk).toContain('exit_plan_mode(args:')
+    expectPlanCodeSdkBindings(sdk)
   })
 
   it('keeps the Code Mode SDK byte-identical across mode switches', async () => {
@@ -487,9 +493,7 @@ describe('the soft layer', () => {
     registerNamedTools(withPlanMode, ['read', 'write'])
     const agent = await agentWithSession(withPlanMode)
     const defaultSdk = (await assembleFor(withPlanMode, agent)).sections.find(section => section.name === 'tools:sdk')?.text ?? ''
-    expect(defaultSdk).toContain('read(args:')
-    expect(defaultSdk).toContain('write(args:')
-    expect(defaultSdk).toContain('exit_plan_mode(args:')
+    expectPlanCodeSdkBindings(defaultSdk)
     agent.session.append('plan/mode', { active: true })
     const planSdk = (await assembleFor(withPlanMode, agent)).sections.find(section => section.name === 'tools:sdk')?.text ?? ''
     expect(planSdk).toBe(defaultSdk)
@@ -502,7 +506,7 @@ describe('the soft layer', () => {
     await bare.plugin(FakeRuntime)
     registerNamedTools(bare, ['read', 'write'])
     const bareSdk = (await bare.systemPrompt.assemble({ agent })).sections.find(section => section.name === 'tools:sdk')?.text ?? ''
-    expect(bareSdk).not.toContain('exit_plan_mode(args:')
+    expect(bareSdk).not.toContain('exit_plan_mode:')
     expect(defaultSdk).not.toBe(bareSdk)
   })
 })
@@ -542,14 +546,17 @@ describe('/plan', () => {
     const plainSteer = vi.fn()
     ;(plainAgent as unknown as { steer: typeof plainSteer }).steer = plainSteer
     expect(ctx.commands.list(plainAgent)).toEqual([
-      { name: 'plan', description: 'Enter plan mode', input: { hint: '[message]' } },
+      { name: 'plan', description: 'Enter or leave plan mode', input: { hint: '[off|message]' } },
     ])
 
     const signal = new AbortController().signal
     expect(await ctx.commands.execute(plainAgent, '/mode', signal)).toBeUndefined()
     expect(await ctx.commands.execute(plainAgent, '/review', signal)).toBeUndefined()
     const plain = await ctx.commands.execute(plainAgent, '/plan', signal)
-    expect(plain).toEqual({ kind: 'success', text: 'Entering plan mode (applies from the next step).' })
+    expect(plain).toEqual({
+      kind: 'success',
+      text: 'Entering plan mode (applies from the next step). Use /plan off to leave.',
+    })
     expect(ctx.planMode.get(plainAgent)).toEqual({ active: false, pending: true })
     expect(plainSteer).not.toHaveBeenCalled()
 
@@ -557,11 +564,50 @@ describe('/plan', () => {
     const messageSteer = vi.fn()
     ;(messageAgent as unknown as { steer: typeof messageSteer }).steer = messageSteer
     const plan = await ctx.commands.execute(messageAgent, '/plan   draft the migration  ', signal)
-    expect(plan).toEqual({ kind: 'success', text: 'Entering plan mode (applies from the next step).' })
+    expect(plan).toEqual({
+      kind: 'success',
+      text: 'Entering plan mode (applies from the next step). Use /plan off to leave.',
+    })
     expect(ctx.planMode.get(messageAgent)).toEqual({ active: false, pending: true })
     expect(messageSteer).toHaveBeenCalledExactlyOnceWith([{ type: 'text', text: 'draft the migration' }])
   })
 
+  it('leaves active plan mode, cancels a pending entry, and treats inactive exit as idempotent', async () => {
+    const ctx = await setup()
+    await ctx.plugin(CommandService)
+    await new Promise(resolve => setImmediate(resolve))
+    const signal = new AbortController().signal
+
+    const inactive = await agentWithSession(ctx, 'inactive-plan-command')
+    expect(await ctx.commands.execute(inactive, '/plan off', signal))
+      .toEqual({ kind: 'success', text: 'Plan mode is already inactive.' })
+    expect(ctx.planMode.get(inactive)).toEqual({ active: false })
+
+    const entering = await agentWithSession(ctx, 'entering-plan-command')
+    const enteringSteer = vi.fn()
+    ;(entering as unknown as { steer: typeof enteringSteer }).steer = enteringSteer
+    await ctx.commands.execute(entering, '/plan', signal)
+    expect(await ctx.commands.execute(entering, '/plan off', signal))
+      .toEqual({ kind: 'success', text: 'Plan mode entry cancelled.' })
+    expect(ctx.planMode.get(entering)).toEqual({ active: false, pending: false })
+    expect(enteringSteer).not.toHaveBeenCalled()
+    await boundary(ctx, entering, 'turn/start')
+    expect(ctx.planMode.get(entering)).toEqual({ active: false })
+    expect(entering.session.events.some(event => event.type === 'plan/mode')).toBe(false)
+
+    const active = await agentWithSession(ctx, 'active-plan-command', { active: true })
+    const activeSteer = vi.fn()
+    ;(active as unknown as { steer: typeof activeSteer }).steer = activeSteer
+    expect(await ctx.commands.execute(active, '/plan off', signal))
+      .toEqual({ kind: 'success', text: 'Leaving plan mode (applies from the next step).' })
+    expect(ctx.planMode.get(active)).toEqual({ active: true, pending: false })
+    expect(await ctx.commands.execute(active, '/plan off', signal))
+      .toEqual({ kind: 'success', text: 'Leaving plan mode (applies from the next step).' })
+    expect(activeSteer).not.toHaveBeenCalled()
+    await boundary(ctx, active, 'turn/start')
+    expect(ctx.planMode.get(active)).toEqual({ active: false })
+  })
+
   it('removes the contributed command when the plan-mode plugin is disposed', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
@@ -662,6 +708,8 @@ describe('exit_plan_mode', () => {
     const { ctx, agent, asked } = await setupWithReview({ selected: ['Approve'] })
     const result = await callExit(ctx, agent)
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected approved plan result')
+    expect(result.value).toEqual({ approved: true })
     expect(result.content).toEqual([{ type: 'text', text: 'Plan approved — plan mode exited; carry out the plan starting with your next step.' }])
     // Boundary-applied, not a direct append: the fold stays plan until the
     // step's end, so the plan policy covers any remaining call of the SAME batch.
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 00cd1b8b00..a2b3aec391 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -1,12 +1,14 @@
 # @deepseek-ai/dsh-pty-local
 
-Local `node-pty` backend for `ctx.pty`. 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.
+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.
 
 ## 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`. The current session-level sandbox override is resolved at spawn and remains fixed for the PTY lifetime.
+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`. 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 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.
 
-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. Unrecognized or unreadable process state is never a positive exact-idle signal. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit.
+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 until bash ownership is observable or the ordinary silence bound expires. 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. 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.
+
+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.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/package.json b/packages/pty/pty-local/package.json
index 339c3916ad..fb26d845e5 100644
--- a/packages/pty/pty-local/package.json
+++ b/packages/pty/pty-local/package.json
@@ -30,10 +30,12 @@
   },
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-pty": "^0.0.1",
     "@deepseek-ai/dsh-sandbox": "^0.0.1",
     "@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index 0b99d1b058..b466ecfc46 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -7,6 +7,9 @@
 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 type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
@@ -20,10 +23,37 @@ export type { Config as PtyLocalConfig } from './config.ts'
 
 /** Cordis plugin name. */
 export const name = 'pty-local'
-/** Required services: registry plus the one shared confinement policy. */
+/** Required services: PTY registry plus the one shared confinement policy. */
 export const inject = ['pty', 'sandbox', 'sandboxPolicy']
 
 const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
+interface SandboxModeFenceState {
+  pty: Context['pty']
+  sandboxPolicy: Context['sandboxPolicy']
+}
+
+const sandboxModeFences = new WeakMap<Agent, SandboxModeFenceState>()
+
+function ensureSandboxModeFence(ctx: Context, owner: Agent): void {
+  const existing = sandboxModeFences.get(owner)
+  if (existing !== undefined) {
+    existing.pty = ctx.pty
+    existing.sandboxPolicy = ctx.sandboxPolicy
+    return
+  }
+  const state: SandboxModeFenceState = { pty: ctx.pty, sandboxPolicy: ctx.sandboxPolicy }
+  sandboxModeFences.set(owner, state)
+  owner.ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'session/event') return
+    const [session, event] = args as [Session, SessionEvent]
+    if (session !== owner.session || event.type !== 'sandbox/mode') return
+    const currentMode = effectiveSandboxMode(session.events) ?? state.sandboxPolicy.defaultMode
+    if (event.data.mode === currentMode || !state.pty.hasOwnerActivity(owner)) return
+    throw new Error(
+      `cannot change sandbox mode from "${currentMode}" to "${event.data.mode}" while persistent terminal sessions are open or being created; wait for creation to settle and close them first`,
+    )
+  }, { global: true })
+}
 
 function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {}
@@ -73,7 +103,8 @@ export class LocalPtyBackend implements PtyBackend {
   }
 
   async spawn(spec: PtyBackendSpawnSpec): Promise<LocalPtySession> {
-    if (spec.signal?.aborted === true) throw new Error('PTY spawn aborted')
+    spec.signal?.throwIfAborted()
+    ensureSandboxModeFence(this.ctx, spec.owner)
     const argv = spawnArgv(this.ctx, this.config, spec)
     const file = argv[0]
     if (file === undefined) throw new Error('pty-local: sandbox returned empty argv')
@@ -93,7 +124,7 @@ export class LocalPtyBackend implements PtyBackend {
       try {
         await session.close('PTY startup failed')
       } catch (closeError: unknown) {
-        throw new AggregateError([error, closeError], 'PTY startup and cleanup both failed')
+        throw new PtyBackendCleanupError(error, closeError)
       }
       throw error
     }
diff --git a/packages/pty/pty-local/src/process-inspector.ts b/packages/pty/pty-local/src/process-inspector.ts
index 1115f6613d..5be25a224a 100644
--- a/packages/pty/pty-local/src/process-inspector.ts
+++ b/packages/pty/pty-local/src/process-inspector.ts
@@ -16,6 +16,7 @@ export interface ProcessInspector {
   isStdinWaiting(pgid: number): boolean
   /** Return the root and its current transitive descendants, children first. */
   processTree(rootPid: number): ProcessIdentity[]
+  /** Return whether the exact identity remains a non-quiescent process. */
   isAlive(identity: ProcessIdentity): boolean
   signalGroup(pgid: number, signal: PtySignal): void
   signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void
@@ -49,6 +50,7 @@ interface ProcStat {
   parentPid: number
   pgrp: number
   session: number
+  state: string
   tpgid: number
   started: string
 }
@@ -64,13 +66,15 @@ export function parseProcStat(text: string): ProcStat | undefined {
   if (open <= 0 || close <= open) return undefined
   const pid = Number(text.slice(0, open).trim())
   const rest = text.slice(close + 2).trim().split(/\s+/)
+  const state = rest[0] || ''
   const parentPid = Number(rest[1])
   const pgrp = Number(rest[2])
   const session = Number(rest[3])
   const tpgid = Number(rest[5])
   const started = rest[19]
-  if (![pid, parentPid, pgrp, session, tpgid].every(Number.isSafeInteger) || started === undefined) return undefined
-  return { pid, parentPid, pgrp, session, tpgid, started }
+  if (![pid, parentPid, pgrp, session, tpgid].every(Number.isSafeInteger)
+    || state.length !== 1 || started === undefined) return undefined
+  return { pid, parentPid, pgrp, session, state, tpgid, started }
 }
 
 function readLinuxStat(internals: ProcessInspectorInternals, pid: number): ProcStat | undefined {
@@ -269,7 +273,8 @@ class LinuxProcessInspector extends PosixProcessInspector {
   }
 
   isAlive(identity: ProcessIdentity): boolean {
-    return readLinuxStat(this.internals, identity.pid)?.started === identity.started
+    const stat = readLinuxStat(this.internals, identity.pid)
+    return stat?.started === identity.started && !/^[ZXx]$/.test(stat.state)
   }
 
 }
diff --git a/packages/pty/pty-local/src/sanitize.ts b/packages/pty/pty-local/src/sanitize.ts
index 6e109f6115..cc22c29c01 100644
--- a/packages/pty/pty-local/src/sanitize.ts
+++ b/packages/pty/pty-local/src/sanitize.ts
@@ -9,6 +9,8 @@ export const PROMPT_MARKER_PREFIX = '133;D;'
 export interface SanitizedChunk {
   text: string
   prompt: boolean
+  /** Present when printable text followed the latest owned prompt marker. */
+  promptText?: true
 }
 
 /**
@@ -20,6 +22,8 @@ export class TerminalSanitizer {
   private pending = ''
   private discardMode: 'osc' | 'csi' | undefined
   private discardOscEscape = false
+  private trailingCarriageReturn = false
+  private awaitingPromptText = false
 
   constructor(private readonly maxPendingBytes: number) {}
 
@@ -32,15 +36,24 @@ export class TerminalSanitizer {
     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) {
-        text += this.pending.slice(index)
+        promptText = appendText(this.pending.slice(index)) || promptText
         index = this.pending.length
         break
       }
-      text += this.pending.slice(index, escape)
+      promptText = appendText(this.pending.slice(index, escape)) || promptText
       if (escape + 1 >= this.pending.length) {
         index = escape
         break
@@ -59,7 +72,11 @@ export class TerminalSanitizer {
         }
         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
+        if (content.startsWith(PROMPT_MARKER_PREFIX)) {
+          prompt = true
+          promptText = false
+          this.awaitingPromptText = true
+        }
         index = end
         continue
       }
@@ -82,7 +99,7 @@ export class TerminalSanitizer {
     }
     this.pending = this.pending.slice(index)
     this.enforcePendingBound()
-    return { text: normalizeTerminalText(text), prompt }
+    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
   }
 
   /**
@@ -94,7 +111,21 @@ export class TerminalSanitizer {
     this.pending = ''
     this.discardMode = undefined
     this.discardOscEscape = false
-    return normalizeTerminalText(text)
+    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 normalizeTerminalText(complete)
   }
 
   private enforcePendingBound(): void {
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 52863db674..4b1faccc94 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -17,7 +17,7 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import type { ProcessInspector } from './process-inspector.ts'
+import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
 import { TerminalSanitizer } from './sanitize.ts'
 
 function delay(ms: number): Promise<void> {
@@ -148,9 +148,11 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private promptSeen = false
+  private promptTextSeen = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
+  private closing = false
   private closePromise: Promise<void> | undefined
 
   constructor(
@@ -184,27 +186,29 @@ export class LocalPtySession implements PtyBackendSession {
       if (result.waitReason === 'session_exit') throw new Error('PTY shell exited during startup')
       if (result.waitReason === 'timeout') throw new Error('PTY shell did not reach readiness before startup timeout')
       this.motd = result.viewport
+    } catch (error: unknown) {
+      signal?.throwIfAborted()
+      throw error
     } finally {
       this.initializing = false
     }
   }
 
   startSend(request: PtySendRequest): PtySendOperation {
-    if (this.closePromise !== undefined) throw new Error('PTY session is closing')
+    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 (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
-    const operation = new LocalSendOperation(this.config.maxReadBytes, Date.now(), () => {
-      try {
-        this.terminal.write('\x03')
-      } catch (error: unknown) {
-        operation.fail(error)
-      }
-    })
+    const operation = new LocalSendOperation(
+      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() }
@@ -267,8 +271,15 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   close(reason: string): Promise<void> {
-    this.closePromise ??= this.closeOnce(reason)
-    return this.closePromise
+    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
   }
 
   private onData(data: string): void {
@@ -277,10 +288,14 @@ export class LocalPtySession implements PtyBackendSession {
     if (sanitized.prompt) {
       const foregroundPgid = this.inspector.foregroundPgid(this.pid)
       if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
-      if (foregroundPgid !== undefined && foregroundPgid === this.shellPgid) {
-        this.promptSeen = true
-        this.lastOutputAt = Date.now()
-      }
+      // 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.lastOutputAt = Date.now()
+    } else if (this.promptSeen && sanitized.promptText === true) {
+      this.promptTextSeen = true
     }
   }
 
@@ -297,9 +312,12 @@ export class LocalPtySession implements PtyBackendSession {
       this.settleActive('session_exit')
       return
     }
-    if (this.promptSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
-      this.settleActive('stdin_read')
-      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
@@ -310,6 +328,10 @@ export class LocalPtySession implements PtyBackendSession {
         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.
     if (startupHasOutput && Date.now() - this.lastOutputAt >= this.config.idleSilenceMs) {
       this.settleActive('inferred_idle')
       return
@@ -337,58 +359,113 @@ export class LocalPtySession implements PtyBackendSession {
     this.active = undefined
   }
 
+  private failActive(error: unknown): void {
+    const operation = this.active
+    if (operation === undefined) return
+    this.clearActive()
+    operation.fail(error)
+  }
+
+  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}`)
+    }
+  }
+
   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 members = this.inspector.processTree(this.pid)
-    for (const member of members) {
-      try {
-        this.inspector.signalProcess(member, 'SIGTERM')
-      } catch (_alreadyExitedDuringTerm) {
-        // Identity is rechecked by the inspector; a same-tick exit is success.
-      }
-    }
-    try {
-      this.terminal.kill('SIGTERM')
-    } catch (_topLevelAlreadyExited) {
-      // onExit or identity checks below remain authoritative.
-    }
-
-    const deadline = Date.now() + this.config.disposeGraceMs
-    let survivors = members.filter(member => this.inspector.isAlive(member))
-    while (survivors.length > 0 && Date.now() < deadline) {
-      await delay(Math.min(25, this.config.disposeGraceMs))
-      survivors = members.filter(member => this.inspector.isAlive(member))
-    }
-    for (const survivor of survivors) {
-      try {
-        this.inspector.signalProcess(survivor, 'SIGKILL')
-      } catch (_alreadyExitedDuringKill) {
-        // Final identity check below decides success.
-      }
-    }
-    try {
-      this.terminal.kill('SIGKILL')
-    } catch (_topLevelAlreadyKilled) {
-      // The root may already have delivered onExit.
-    }
-
-    const killDeadline = Date.now() + this.config.disposeGraceMs
-    survivors = members.filter(member => this.inspector.isAlive(member))
-    while (survivors.length > 0 && Date.now() < killDeadline) {
-      await delay(Math.min(25, this.config.disposeGraceMs))
-      survivors = members.filter(member => this.inspector.isAlive(member))
-    }
-    const exitWaitMs = Math.max(0, killDeadline - Date.now())
-    await Promise.race([this.exitPromise.promise, delay(exitWaitMs)])
-    survivors = members.filter(member => this.inspector.isAlive(member))
-    this.settleActive('session_exit')
-    this.exitDisposable.dispose()
+    const survivors = await this.stopDescendants()
     if (survivors.length > 0) {
       throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
     }
+    await this.stopShell()
+    this.settleActive('session_exit')
+    this.exitDisposable.dispose()
   }
 }
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 1273824033..8fe6d9d4ae 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -2,12 +2,12 @@ import { describe, expect, it, vi } from 'vitest'
 import type { IPty, IPtyForkOptions } from 'node-pty'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { AgentMessageId, 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 from '@deepseek-ai/dsh-sandbox-policy'
-import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
+import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/dsh-pty'
 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'
@@ -42,7 +42,7 @@ function agent(ctx: Context): Agent {
   const id = SessionId('agent')
   return {
     id, options: {}, session: new Session(id), status: 'idle', ctx,
-    send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
   }
 }
 
@@ -62,6 +62,30 @@ function spec(owner: Agent, signal?: AbortSignal) {
   }
 }
 
+function stubLocalSession(initialize: () => Promise<void> = () => Promise.resolve()): LocalPtySession {
+  return {
+    motd: '',
+    initialize,
+    startSend: () => { throw new Error('unused') },
+    read: () => { throw new Error('unused') },
+    signal: () => Promise.resolve({ delivered: true, targetPgid: 1 }),
+    status: () => ({ kind: 'running' as const }),
+    close: () => Promise.resolve(),
+  } as unknown as LocalPtySession
+}
+
+function registerStubLocalBackend(ctx: Context, createSession: () => LocalPtySession) {
+  return ctx.inject(['pty', 'sandbox', 'sandboxPolicy'], (providerCtx) => {
+    providerCtx.pty.registerBackend(new LocalPtyBackend(
+      providerCtx,
+      { ...config(), backendType: 'stub' },
+      inspector,
+      (() => ({})) as never,
+      createSession,
+    ))
+  })
+}
+
 describe('LocalPtyBackend startup rollback', () => {
   it('rejects pre-aborted setup and empty sandbox argv', async () => {
     const ctx = new Context()
@@ -69,8 +93,9 @@ describe('LocalPtyBackend startup rollback', () => {
     await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/tmp' })
     const backend = new LocalPtyBackend(ctx, config(), inspector)
     const controller = new AbortController()
-    controller.abort()
-    await expect(backend.spawn(spec(agent(ctx), controller.signal))).rejects.toThrow('spawn aborted')
+    const abortReason = new Error('spawn aborted')
+    controller.abort(abortReason)
+    await expect(backend.spawn(spec(agent(ctx), controller.signal))).rejects.toBe(abortReason)
     await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('empty argv')
   })
 
@@ -86,12 +111,18 @@ describe('LocalPtyBackend startup rollback', () => {
     await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('startup failed')
     expect(closed).toHaveBeenCalledWith('PTY startup failed')
 
+    const startupFailure = new Error('startup failed')
+    const cleanupFailure = new Error('cleanup failed')
     const doublyFailed = {
-      initialize: () => Promise.reject(new Error('startup failed')),
-      close: () => Promise.reject(new Error('cleanup failed')),
+      initialize: () => Promise.reject(startupFailure),
+      close: () => Promise.reject(cleanupFailure),
     } as unknown as LocalPtySession
     const aggregate = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => doublyFailed)
-    await expect(aggregate.spawn(spec(agent(ctx)))).rejects.toThrow('startup and cleanup both failed')
+    await expect(aggregate.spawn(spec(agent(ctx)))).rejects.toEqual(expect.objectContaining({
+      name: 'PtyBackendCleanupError',
+      spawnError: startupFailure,
+      cleanupError: cleanupFailure,
+    } satisfies Partial<PtyBackendCleanupError>))
   })
 
   it('wraps confined argv, scrubs the environment, and returns initialized sessions', async () => {
@@ -156,7 +187,12 @@ describe('LocalPtyBackend startup rollback', () => {
       kill() { exitListener?.({ exitCode: 0, signal: 15 }) },
       resize() {}, clear() {}, pause() {}, resume() {},
     } as IPty
-    const backend = new LocalPtyBackend(ctx, config(), inspector, () => terminal)
+    const backend = new LocalPtyBackend(
+      ctx,
+      config(),
+      { ...inspector, foregroundPgid: () => terminal.pid },
+      () => terminal,
+    )
     const session = await backend.spawn(spec(agent(ctx)))
     expect(session.motd).toBe('dsh> ')
     await session.close('test complete')
@@ -175,6 +211,7 @@ describe('pty-local plugin shape', () => {
 
   it('validates config and registers the configured backend', async () => {
     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' })
@@ -183,4 +220,90 @@ describe('pty-local plugin shape', () => {
     await fiber.dispose()
     expect(ctx.pty.listBackends()).toEqual([])
   })
+
+  it('ignores unrelated session events and mode changes without a live owner', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    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(ptyLocal, config())
+
+    const session = ctx.sessions.create(SessionId('unowned-mode'))
+    expect(() => {
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    }).not.toThrow()
+    expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
+  })
+
+  it('keeps the owner-lifetime sandbox fence after the local provider unloads', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(PtyService)
+    await ctx.plugin(RecordingSandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+
+    const session = ctx.sessions.create(SessionId('mode-owner'))
+    const ownerFiber = await ctx.plugin(() => {})
+    const owner: Agent = {
+      id: session.id, options: {}, session, status: 'idle', ctx: ownerFiber.ctx,
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
+    }
+    ctx.agents.register(owner)
+    const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
+    const created = await ctx.pty.spawn(owner, { type: 'stub' })
+
+    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' } } })
+    }).not.toThrow()
+
+    expect(() => { setSandboxMode(session, 'danger-full-access') }).not.toThrow()
+    await providerFiber.dispose()
+    expect(ctx.pty.listBackends()).toEqual([])
+    expect(() => { setSandboxMode(session, 'read-only') }).toThrow(
+      'cannot change sandbox mode from "danger-full-access" to "read-only" while persistent terminal sessions are open or being created; wait for creation to settle and close them first',
+    )
+    expect(session.events.filter(event => event.type === 'sandbox/mode')).toHaveLength(1)
+
+    const replacementFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
+    const second = await ctx.pty.spawn(owner, { type: 'stub' })
+    await replacementFiber.dispose()
+    expect(() => { setSandboxMode(session, 'read-only') }).toThrow('open or being created')
+
+    await ctx.pty.kill(owner, created.sessionId)
+    await ctx.pty.kill(owner, second.sessionId)
+    expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
+    expect(session.events.filter(event => event.type === 'sandbox/mode')).toHaveLength(2)
+  })
+
+  it('also fences sandbox-mode changes across unpublished PTY creation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(PtyService)
+    await ctx.plugin(RecordingSandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+
+    const session = ctx.sessions.create(SessionId('pending-mode-owner'))
+    const ownerFiber = await ctx.plugin(() => {})
+    const owner: Agent = {
+      id: session.id, options: {}, session, status: 'idle', ctx: ownerFiber.ctx,
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
+    }
+    ctx.agents.register(owner)
+    const gate = Promise.withResolvers<undefined>()
+    await registerStubLocalBackend(ctx, () => stubLocalSession(() => gate.promise))
+    const spawning = ctx.pty.spawn(owner, { type: 'stub' })
+
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(true)
+    expect(() => { setSandboxMode(session, 'read-only') }).toThrow('open or being created')
+    gate.resolve(undefined)
+    const created = await spawning
+    await ctx.pty.kill(owner, created.sessionId)
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(false)
+  })
 })
diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts
index b2d6a38255..763ab5c871 100644
--- a/packages/pty/pty-local/tests/local.spec.ts
+++ b/packages/pty/pty-local/tests/local.spec.ts
@@ -4,9 +4,10 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import PtyService from '@deepseek-ai/dsh-pty'
+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'
@@ -34,7 +35,7 @@ function stubAgent(ctx: Context, rawId: string): Agent {
   const scope = ctx.plugin(() => {})
   return {
     id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx,
-    send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
   }
 }
 
@@ -62,6 +63,16 @@ async function harness(mode: 'danger-full-access' | 'workspace-write') {
   return { ctx, root, agent, fiber, sandbox: ctx.sandbox as PassthroughSandbox }
 }
 
+async function waitForOutput(operation: PtySendOperation, expected: string): Promise<void> {
+  const deadline = Date.now() + 2_000
+  let output = ''
+  while (!output.includes(expected) && Date.now() < deadline) {
+    output += operation.readOutput().delta
+    if (!output.includes(expected)) await new Promise(resolve => setTimeout(resolve, 10))
+  }
+  expect(output).toContain(expected)
+}
+
 describe('pty-local real shell', () => {
   it('persists cwd and environment across sends, scrubs secrets, and closes', async () => {
     const previous = process.env.DSH_TEST_SECRET
@@ -119,4 +130,26 @@ describe('pty-local real shell', () => {
     await ctx.pty.kill(agent, created.sessionId)
     expect(() => process.kill(pid, 0)).toThrow()
   }, 10_000)
+
+  it('cancels a raw-mode foreground process with a real SIGINT', async () => {
+    const { ctx, agent } = await harness('danger-full-access')
+    const created = await ctx.pty.spawn(agent, { type: 'shell' })
+    const controller = new AbortController()
+    const foreground = ctx.pty.startSend(agent, created.sessionId, {
+      text: 'python3 -c \'import signal,sys,termios,time; signal.signal(signal.SIGINT, lambda *_: (print("SIGINT_SEEN", flush=True), sys.exit(0))); attrs=termios.tcgetattr(0); attrs[3] &= ~termios.ISIG; termios.tcsetattr(0, termios.TCSANOW, attrs); print("RAW_READY", flush=True); time.sleep(60)\'',
+      submit: true,
+      signal: controller.signal,
+    })
+    await waitForOutput(foreground, 'RAW_READY')
+    controller.abort()
+    const result = await foreground.done
+    expect(result.waitReason).toBe('stdin_read')
+    const after = await ctx.pty.startSend(agent, created.sessionId, {
+      text: 'echo AFTER_SIGINT',
+      submit: true,
+    }).done
+    expect(after.viewport).toContain('AFTER_SIGINT')
+    expect(after.waitReason).toBe('stdin_read')
+    await ctx.pty.kill(agent, created.sessionId)
+  }, 10_000)
 })
diff --git a/packages/pty/pty-local/tests/process-inspector.spec.ts b/packages/pty/pty-local/tests/process-inspector.spec.ts
index 5ddefd34b3..218a3d77fe 100644
--- a/packages/pty/pty-local/tests/process-inspector.spec.ts
+++ b/packages/pty/pty-local/tests/process-inspector.spec.ts
@@ -2,8 +2,8 @@ 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'
 
-function stat(pid: number, pgrp: number, session: number, tpgid: number, started: string, parentPid = 1): string {
-  const rest = ['S', String(parentPid), String(pgrp), String(session), '99', String(tpgid)]
+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)]
   while (rest.length < 19) rest.push('0')
   rest.push(started)
   return `${pid} (command with space) ${rest.join(' ')}`
@@ -65,8 +65,10 @@ function fakeInternals() {
 describe('Linux process inspector', () => {
   it('parses stat safely, captures only the rooted process tree, and signals identities', () => {
     expect(parseProcStat('bad')).toBeUndefined()
+    expect(parseProcStat('1 () ')).toBeUndefined()
     expect(parseProcStat('1 () S')).toBeUndefined()
-    expect(parseProcStat(stat(10, 20, 30, 40, '500'))).toEqual({ pid: 10, parentPid: 1, pgrp: 20, session: 30, tpgid: 40, started: '500' })
+    expect(parseProcStat(stat(10, 20, 30, 40, '500', 1, 'SS'))).toBeUndefined()
+    expect(parseProcStat(stat(10, 20, 30, 40, '500'))).toEqual({ pid: 10, parentPid: 1, pgrp: 20, session: 30, state: 'S', tpgid: 40, started: '500' })
 
     const fake = fakeInternals()
     fake.dirs.set('/proc', ['x', '10', '11', '12', '13', '14'])
@@ -90,6 +92,10 @@ describe('Linux process inspector', () => {
     inspector.signalProcess({ pid: 10, started: '500' }, 'SIGTERM')
     inspector.signalProcess({ pid: 10, started: 'old' }, 'SIGKILL')
     expect(fake.kills).toEqual([[-40, 'SIGINT'], [10, 'SIGTERM']])
+    fake.files.set('/proc/10/stat', stat(10, 20, 30, 40, '500', 1, 'Z'))
+    expect(inspector.isAlive({ pid: 10, started: '500' })).toBe(false)
+    inspector.signalProcess({ pid: 10, started: '500' }, 'SIGKILL')
+    expect(fake.kills).toEqual([[-40, 'SIGINT'], [10, 'SIGTERM']])
   })
 
   it('detects read, select, poll, and epoll waits across non-leader threads', () => {
diff --git a/packages/pty/pty-local/tests/sanitize.spec.ts b/packages/pty/pty-local/tests/sanitize.spec.ts
index eee994e1e5..4da4ab0d73 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 })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
@@ -25,6 +25,20 @@ describe('TerminalSanitizer', () => {
     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 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 })
+    expect(sanitizer.flush()).toBe('\n')
+  })
+
+  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 })
+  })
+
   it('bounds and discards unterminated control sequences through their terminators', () => {
     const oscBel = new TerminalSanitizer(8)
     expect(oscBel.push(`\x1b]0;${'x'.repeat(16)}`)).toEqual({ text: '', prompt: false })
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 562aaf4eb3..4be21c79a6 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -15,6 +15,7 @@ class FakeTerminal {
   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>()
 
@@ -44,7 +45,7 @@ class FakeTerminal {
   kill(signal?: string): void {
     if (this.throwKill) throw new Error('kill failed')
     this.kills.push(signal ?? 'SIGHUP')
-    this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
+    if (this.autoExitOnKill) this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
   }
 
   resize() {}
@@ -148,7 +149,7 @@ describe('LocalPtySession readiness and output', () => {
     expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
   })
 
-  it('cancels with Ctrl-C, observes AbortSignal, and contains write failures', async () => {
+  it('cancels with foreground-group SIGINT, observes AbortSignal, and contains write failures', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
@@ -159,7 +160,8 @@ describe('LocalPtySession readiness and output', () => {
     const operation = session.startSend({ text: 'sleep', submit: true, signal: controller.signal })
     expect(() => session.startSend({ text: 'again', submit: true })).toThrow('active send')
     controller.abort()
-    expect(terminal.writes.at(-1)).toBe('\x03')
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    expect(terminal.writes).not.toContain('\x03')
     terminal.emitData('\x1b]133;D;130\x07dsh> ')
     await vi.advanceTimersByTimeAsync(10)
     await operation.done
@@ -196,11 +198,13 @@ describe('LocalPtySession readiness and output', () => {
     operationInternal.append('')
     const sessionInternal = session as unknown as {
       pollReadiness(operation: PtySendOperation): void
+      interrupt(operation: PtySendOperation): void
       statusValue: PtySessionStatus
       appendOutput(text: string): void
     }
     sessionInternal.appendOutput('')
     sessionInternal.pollReadiness({} as PtySendOperation)
+    sessionInternal.interrupt({} as PtySendOperation)
     sessionInternal.statusValue = { kind: 'exited', exitCode: 2, signal: null }
     sessionInternal.pollReadiness(operation)
     await operation.done
@@ -212,12 +216,23 @@ describe('LocalPtySession readiness and output', () => {
     expect(unknown.status()).toEqual({ kind: 'exited', exitCode: 1, signal: null })
 
     const cancelTerminal = new FakeTerminal()
-    const cancel = new LocalPtySession(cancelTerminal.asPty(), new FakeInspector(), config())
+    const cancelInspector = new FakeInspector()
+    const cancel = new LocalPtySession(cancelTerminal.asPty(), cancelInspector, config())
     await initialize(cancel, cancelTerminal)
     const cancellable = cancel.startSend({ text: '', submit: false })
-    cancelTerminal.throwWrite = true
+    cancelInspector.throwGroup = true
     expect(cancellable.cancel()).toBe(true)
-    await expect(cancellable.done).rejects.toThrow('write failed')
+    await expect(cancellable.done).rejects.toThrow('group failed')
+    expect(cancellable.cancel()).toBe(false)
+
+    const missingGroupTerminal = new FakeTerminal()
+    const missingGroupInspector = new FakeInspector()
+    const missingGroup = new LocalPtySession(missingGroupTerminal.asPty(), missingGroupInspector, config())
+    await initialize(missingGroup, missingGroupTerminal)
+    missingGroupInspector.pgid = undefined
+    const unresolved = missingGroup.startSend({ text: '', submit: false })
+    expect(unresolved.cancel()).toBe(true)
+    await expect(unresolved.done).rejects.toThrow('cannot resolve foreground process group')
   })
 
   it('does not treat zero-output startup silence as readiness and fails on startup timeout', async () => {
@@ -239,7 +254,39 @@ describe('LocalPtySession readiness and output', () => {
     await timedOut
   })
 
-  it('trusts prompt markers only while the startup shell owns the foreground group', async () => {
+  it('preserves the caller abort reason when startup cannot resolve a foreground group', async () => {
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    inspector.pgid = undefined
+    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const controller = new AbortController()
+    const reason = new Error('startup cancelled')
+
+    const initializing = session.initialize(controller.signal)
+    const rejected = expect(initializing).rejects.toBe(reason)
+    controller.abort(reason)
+
+    await rejected
+  })
+
+  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())
+    let settled = false
+    const initializing = session.initialize().then(() => { settled = true })
+
+    terminal.emitData('\x1b]133;D;0\x07')
+    await vi.advanceTimersByTimeAsync(20)
+    expect(settled).toBe(false)
+
+    terminal.emitData('dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await initializing
+    expect(session.motd).toBe('dsh> ')
+  })
+
+  it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
@@ -250,15 +297,30 @@ describe('LocalPtySession readiness and output', () => {
     let settled = false
     void operation.done.then(() => { settled = true })
     inspector.pgid = 789
-    terminal.emitData('\x1b]133;D;0\x07spoofed')
-    await vi.advanceTimersByTimeAsync(10)
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(40)
     expect(settled).toBe(false)
 
     inspector.pgid = 456
-    terminal.emitData('\x1b]133;D;0\x07dsh> ')
     await vi.advanceTimersByTimeAsync(10)
+    expect(settled).toBe(true)
     expect((await operation.done).waitReason).toBe('stdin_read')
   })
+
+  it('falls back to inferred idle when a foreground child emits an inherited prompt marker', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    await initialize(session, terminal)
+
+    const operation = session.startSend({ text: 'bash -i', submit: true })
+    inspector.pgid = 789
+    terminal.emitData('\x1b]133;D;0\x07child> ')
+    await vi.advanceTimersByTimeAsync(100)
+
+    expect((await operation.done).waitReason).toBe('inferred_idle')
+  })
 })
 
 describe('LocalPtySession bounds, signals, and teardown', () => {
@@ -328,14 +390,15 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     // readiness poll would otherwise mis-settle this as stdin_read once close
     // begins, so teardown must stop polling before its grace period.
     terminal.emitData('\x1b]133;D;0\x07dsh> ')
-    terminal.throwKill = true
+    terminal.autoExitOnKill = false
     const closing = session.close('mid-send')
-    await vi.advanceTimersByTimeAsync(60)
+    await vi.advanceTimersByTimeAsync(20)
+    terminal.emitExit(0, 15)
     expect((await operation.done).waitReason).toBe('session_exit')
     await closing
   })
 
-  it('waits for SIGKILL recipients to leave the process table after the shell exits', async () => {
+  it('keeps the shell alive until SIGKILL recipients leave the process table', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
@@ -348,11 +411,81 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     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/pty-local/tsconfig.json b/packages/pty/pty-local/tsconfig.json
index 06b5dcd4e7..45a03248db 100644
--- a/packages/pty/pty-local/tsconfig.json
+++ b/packages/pty/pty-local/tsconfig.json
@@ -17,6 +17,12 @@
     {
       "path": "../../../vendor/schemastery"
     },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
     {
       "path": "../pty"
     },
diff --git a/packages/pty/pty/README.md b/packages/pty/pty/README.md
index 3620d8eaab..77bc23e546 100644
--- a/packages/pty/pty/README.md
+++ b/packages/pty/pty/README.md
@@ -4,11 +4,16 @@ Owner-scoped persistent PTY seam. `PtyService` registers as `ctx.pty`, mints opa
 
 ## Contract
 
-- Backends register one stable `type` and return an unpublished `PtyBackendSession`; failed or cancelled setup must clean partial resources.
+- Backends register one stable `type` and return an unpublished `PtyBackendSession`; failed or cancelled setup must clean partial resources, and a failed cleanup rejects with `PtyBackendCleanupError` so the registry can retain it across cancellation.
+- Spawn cancellation preserves the caller's exact abort reason. Service disposal and owner loss remain distinct machine-routable failures after backend setup.
+- Owner and service disposal abort unpublished setup through a service-owned signal and await backend settlement plus rollback before returning.
+- A rollback-close or backend-reported startup cleanup failure rejects the disposing lifecycle instead of claiming quiescence. Caller-triggered cancellation still receives its exact reason; lifecycle-triggered rollback failure also rejects the pending spawn.
+- A backend cleanup failure that follows caller cancellation remains owner activity until owner or service disposal consumes and reports it, so lifecycle policy cannot mistake failed cleanup for quiescence.
+- `hasOwnerActivity(owner)` spans unpublished setup through final close, so lifecycle policy can fence the exact owner without a publication race.
 - A successful spawn publishes one `PtySessionId`. The optional `name` is owner-local display metadata, never authority.
 - One session accepts at most one live send operation. Reads and signals may observe it; another send fails until the operation settles.
 - `PtySendResult.waitReason` and `sessionStatus` are independent. `session_exit` describes the top-level PTY process, not an arbitrary foreground command.
-- `kill()` and disposal resolve only after the backend's captured process tree is quiescent. A cleanup failure rejects instead of claiming success.
+- `kill()` and disposal resolve only after the backend's captured process tree is quiescent. A cleanup failure rejects instead of claiming success and clears the matching backend and registry fences so a later close can retry without disturbing a newer attempt.
 
 The seam contains no `node-pty`, sandbox, tool-schema, prompt, task, or terminal-rendering policy. Implementations own terminal mechanics; consumers own model presentation and optional background-task registration.
 
diff --git a/packages/pty/pty/src/index.ts b/packages/pty/pty/src/index.ts
index 7bef5f709f..f4f5ba64e1 100644
--- a/packages/pty/pty/src/index.ts
+++ b/packages/pty/pty/src/index.ts
@@ -6,6 +6,7 @@
 
 import { Context, Service } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import { PtyBackendCleanupError } from './types.ts'
 import type {
   PtyBackend,
   PtyBackendSession,
@@ -39,6 +40,7 @@ export type {
   PtySpawnResult,
   PtyWaitReason,
 } from './types.ts'
+export { PtyBackendCleanupError } from './types.ts'
 
 /** Opaque identity minted by {@link PtyService} for one live PTY session. */
 export type PtySessionId = PtySessionIdValue
@@ -77,10 +79,6 @@ export function PtySessionId(value: string): PtySessionId {
   return value as PtySessionId
 }
 
-function isAborted(signal: AbortSignal | undefined): boolean {
-  return signal?.aborted === true
-}
-
 interface SessionRecord {
   readonly id: PtySessionId
   readonly owner: Agent
@@ -91,11 +89,24 @@ interface SessionRecord {
   closing: Promise<void> | undefined
 }
 
+interface PendingSpawn {
+  readonly owner: Agent
+  readonly controller: AbortController
+  readonly settled: Promise<void>
+  cleanupFailure: { error: unknown } | undefined
+}
+
+interface SpawnReservation {
+  readonly signal: AbortSignal
+  release(cleanupFailure: { error: unknown } | undefined): void
+}
+
 /** In-process registry for replaceable PTY backends and exact-Agent sessions. */
 export class PtyService extends Service {
   private readonly backends = new Map<string, PtyBackend>()
   private readonly sessions = new Map<PtySessionId, SessionRecord>()
   private readonly reservedNames = new Map<Agent, Set<string>>()
+  private readonly pendingSpawns = new Map<Agent, Set<PendingSpawn>>()
   private readonly ownerCleanups = new Map<Agent, () => Promise<void> | void>()
   private readonly disposedOwners = new WeakSet<Agent>()
   private nextId = 0
@@ -142,15 +153,19 @@ export class PtyService extends Service {
    */
   async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult> {
     this.assertActive()
+    signal?.throwIfAborted()
     this.ensureOwnerCleanup(owner)
     const backend = this.backends.get(request.type)
     if (backend === undefined) throw new PtyError(`no PTY backend registered for "${request.type}"`, 'NO_BACKEND')
     if (request.name !== undefined && request.name.length === 0) throw new Error('PTY session name must be non-empty')
-    if (isAborted(signal)) throw new Error('PTY spawn aborted')
-
     const releaseName = this.reserveName(owner, request.name)
+    const spawnReservation = this.reserveSpawn(owner)
+    const backendSignal = signal === undefined
+      ? spawnReservation.signal
+      : AbortSignal.any([signal, spawnReservation.signal])
     const sessionId = PtySessionId(`pty-${++this.nextId}`)
     let session: PtyBackendSession | undefined
+    let cleanupFailure: { error: unknown } | undefined
     try {
       session = await backend.spawn({
         sessionId,
@@ -158,9 +173,13 @@ export class PtyService extends Service {
         type: request.type,
         ...request.name !== undefined ? { name: request.name } : {},
         ...request.cwd !== undefined ? { cwd: request.cwd } : {},
-        ...signal !== undefined ? { signal } : {},
+        signal: backendSignal,
       })
-      if (this.disposing || isAborted(signal) || !this.isLiveOwner(owner)) {
+      signal?.throwIfAborted()
+      if (this.disposing) {
+        throw new PtyError('PTY service is disposing', 'SERVICE_DISPOSING')
+      }
+      if (!this.isLiveOwner(owner)) {
         throw new PtyError('PTY owner is no longer live', 'OWNER_NOT_LIVE')
       }
       const record: SessionRecord = {
@@ -175,19 +194,45 @@ export class PtyService extends Service {
       this.sessions.set(sessionId, record)
       return this.snapshot(record, session.motd)
     } catch (error) {
+      if (error instanceof PtyBackendCleanupError) {
+        cleanupFailure = { error: error.cleanupError }
+      }
+      let rollbackFailure: { error: unknown } | undefined
       if (session !== undefined && !this.sessions.has(sessionId)) {
         try {
           await session.close('PTY spawn rolled back')
         } catch (closeError: unknown) {
-          throw new AggregateError([error, closeError], 'PTY spawn and rollback both failed')
+          rollbackFailure = { error: closeError }
+          cleanupFailure = rollbackFailure
         }
       }
-      throw error
+      let failure: unknown = error
+      try {
+        signal?.throwIfAborted()
+        spawnReservation.signal.throwIfAborted()
+      } catch (cancellation: unknown) {
+        failure = cancellation
+      }
+      if (rollbackFailure !== undefined && signal?.aborted !== true) {
+        throw new AggregateError([failure, rollbackFailure.error], 'PTY spawn and rollback both failed')
+      }
+      throw failure
     } finally {
+      spawnReservation.release(cleanupFailure)
       releaseName()
     }
   }
 
+  /**
+   * 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 {
+    return (this.pendingSpawns.get(owner)?.size ?? 0) > 0
+      || [...this.sessions.values()].some(record => record.owner === owner)
+  }
+
   /**
    * Start one exclusive interactive send.
    * @param owner - exact session owner.
@@ -302,6 +347,43 @@ export class PtyService extends Service {
     }
   }
 
+  private reserveSpawn(owner: Agent): SpawnReservation {
+    const controller = new AbortController()
+    const settlement = Promise.withResolvers<void>()
+    const pending: PendingSpawn = { owner, controller, settled: settlement.promise, cleanupFailure: undefined }
+    const owned = this.pendingSpawns.get(owner) ?? new Set<PendingSpawn>()
+    owned.add(pending)
+    this.pendingSpawns.set(owner, owned)
+    return {
+      signal: controller.signal,
+      release: (cleanupFailure) => {
+        pending.cleanupFailure = cleanupFailure
+        if (cleanupFailure === undefined) this.removePendingSpawn(pending)
+        settlement.resolve()
+      },
+    }
+  }
+
+  private removePendingSpawn(pending: PendingSpawn): void {
+    const owned = this.pendingSpawns.get(pending.owner)
+    if (owned === undefined) return
+    owned.delete(pending)
+    if (owned.size === 0) this.pendingSpawns.delete(pending.owner)
+  }
+
+  private async abortPendingSpawns(owner: Agent | undefined, reason: PtyError): Promise<void> {
+    const pending = owner === undefined
+      ? [...this.pendingSpawns.values()].flatMap(owned => [...owned])
+      : [...(this.pendingSpawns.get(owner) ?? [])]
+    for (const spawn of pending) spawn.controller.abort(reason)
+    await Promise.all(pending.map(spawn => spawn.settled))
+    const failures = pending.flatMap(spawn => spawn.cleanupFailure === undefined ? [] : [spawn.cleanupFailure.error])
+    for (const spawn of pending) this.removePendingSpawn(spawn)
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'failed to roll back unpublished PTY setup')
+    }
+  }
+
   private expectOwned(owner: Agent, id: PtySessionId): SessionRecord {
     const record = this.sessions.get(id)
     if (record === undefined) throw new PtyError(`unknown PTY session ${id}`, 'NO_SESSION')
@@ -322,23 +404,49 @@ export class PtyService extends Service {
     }
   }
 
+  private async abortAndClose(owner: Agent | undefined, abortReason: PtyError, closeReason: string): Promise<void> {
+    const failures: unknown[] = []
+    try {
+      await this.abortPendingSpawns(owner, abortReason)
+    } catch (error: unknown) {
+      failures.push(error)
+    }
+    const records = [...this.sessions.values()].filter(record => owner === undefined || record.owner === owner)
+    try {
+      await this.closeRecords(records, closeReason)
+    } catch (error: unknown) {
+      failures.push(error)
+    }
+    if (failures.length > 0) throw new AggregateError(failures, 'failed to clean up PTY lifecycle')
+  }
+
   private async disposeOwned(owner: Agent): Promise<void> {
-    const owned = [...this.sessions.values()].filter(record => record.owner === owner)
-    await this.closeRecords(owned, 'PTY owner disposed')
-    this.reservedNames.delete(owner)
+    try {
+      await this.abortAndClose(
+        owner,
+        new PtyError('PTY owner is no longer live', 'OWNER_NOT_LIVE'),
+        'PTY owner disposed',
+      )
+    } finally {
+      this.reservedNames.delete(owner)
+    }
   }
 
   private async disposeAll(): Promise<void> {
     this.disposing = true
-    const records = [...this.sessions.values()]
     // Teardown is best-effort: a close failure still clears registries and runs
     // owner cleanups before the aggregated error propagates, so one stuck
     // session cannot orphan backends, reservations, or owner detachers.
     try {
-      await this.closeRecords(records, 'PTY service disposed')
+      await this.abortAndClose(
+        undefined,
+        new PtyError('PTY service is disposing', 'SERVICE_DISPOSING'),
+        'PTY service disposed',
+      )
     } finally {
       this.backends.clear()
       this.reservedNames.clear()
+      this.pendingSpawns.clear()
       const cleanups = [...this.ownerCleanups.values()]
       this.ownerCleanups.clear()
       await Promise.all(cleanups.map(cleanup => Promise.resolve(cleanup())))
@@ -349,8 +457,14 @@ export class PtyService extends Service {
     const results = await Promise.allSettled(records.map(async (record) => {
       const closing = record.closing ?? record.session.close(reason)
       record.closing = closing
-      await closing
-      this.sessions.delete(record.id)
+      try {
+        await closing
+        this.sessions.delete(record.id)
+      } catch (error: unknown) {
+        // A concurrent retry may already own a newer fence; never clear it.
+        if (record.closing === closing) record.closing = undefined
+        throw error
+      }
     }))
     const failures = results
       .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
diff --git a/packages/pty/pty/src/types.ts b/packages/pty/pty/src/types.ts
index 7bb3f2c711..a4985ead93 100644
--- a/packages/pty/pty/src/types.ts
+++ b/packages/pty/pty/src/types.ts
@@ -10,6 +10,21 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 /** Internal exported basis for the public `PtySessionId` type/value pair. */
 export type PtySessionIdValue = Branded<'PtySessionId'>
 
+/**
+ * Backend-reported failure to clean partial resources after unpublished setup failed.
+ * @param spawnError - original setup or cancellation failure.
+ * @param cleanupError - failure that may leave backend-owned resources alive.
+ */
+export class PtyBackendCleanupError extends AggregateError {
+  constructor(
+    readonly spawnError: unknown,
+    readonly cleanupError: unknown,
+  ) {
+    super([spawnError, cleanupError], 'PTY backend startup and cleanup both failed')
+    this.name = 'PtyBackendCleanupError'
+  }
+}
+
 /** Why one interactive send returned control to its caller. */
 export type PtyWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
 
@@ -147,7 +162,7 @@ export interface PtyBackendSession {
 export interface PtyBackend {
   /** Stable type selected by {@link PtySpawnRequest.type}. */
   readonly type: string
-  /** Create an unpublished session or reject after cleaning partial resources. */
+  /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link PtyBackendCleanupError}. */
   spawn(spec: PtyBackendSpawnSpec): Promise<PtyBackendSession>
 }
 
diff --git a/packages/pty/pty/tests/service.spec.ts b/packages/pty/pty/tests/service.spec.ts
index 17b0302ea6..42622f2712 100644
--- a/packages/pty/pty/tests/service.spec.ts
+++ b/packages/pty/pty/tests/service.spec.ts
@@ -1,9 +1,9 @@
 import { describe, expect, expectTypeOf, it } from 'vitest'
 import { Context } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import PtyService, { PtyError, PtySessionId } from '@deepseek-ai/dsh-pty'
+import PtyService, { PtyBackendCleanupError, PtyError, PtySessionId } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackend,
   PtyBackendSession,
@@ -27,9 +27,11 @@ function stubAgent(ctx: Context, rawId: string): Agent {
     session: new Session(id),
     status: 'idle',
     ctx: scopeFiber.ctx,
-    send() {},
-    steer() {},
-    inject() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
+    inject: () => AgentMessageId('stub'),
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle: () => Promise.resolve(),
   }
@@ -160,6 +162,7 @@ describe('PtyService ownership and lifecycle', () => {
 
     const created = await ctx.pty.spawn(owner, { type: 'stub', name: 'main', cwd: '/tmp' })
     expect(created).toMatchObject({ sessionId: 'pty-1', name: 'main', type: 'stub', pid: 123, motd: 'stub ready', status: { kind: 'running' } })
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(true)
     expect(ctx.pty.list(owner)).toHaveLength(1)
     expect(ctx.pty.list(foreign)).toEqual([])
     expect(() => ctx.pty.read(foreign, created.sessionId)).toThrow('belongs to another agent')
@@ -178,8 +181,9 @@ describe('PtyService ownership and lifecycle', () => {
     const created = await ctx.pty.spawn(owner, { type: 'stub', name: 'main' })
     await expect(ctx.pty.spawn(owner, { type: 'stub', name: '' })).rejects.toThrow('must be non-empty')
     const aborted = new AbortController()
-    aborted.abort()
-    await expect(ctx.pty.spawn(owner, { type: 'stub' }, aborted.signal)).rejects.toThrow('spawn aborted')
+    const abortReason = new Error('spawn aborted')
+    aborted.abort(abortReason)
+    await expect(ctx.pty.spawn(owner, { type: 'stub' }, aborted.signal)).rejects.toBe(abortReason)
     await expect(ctx.pty.spawn(owner, { type: 'stub', name: 'main' })).rejects.toMatchObject({ code: 'DUPLICATE_NAME' })
 
     const operation = ctx.pty.startSend(owner, created.sessionId, { text: 'echo hi', submit: true })
@@ -205,12 +209,222 @@ describe('PtyService ownership and lifecycle', () => {
     ctx.agents.register(owner)
     const pending = ctx.pty.spawn(owner, { type: 'slow', name: 'main' })
     await expect(ctx.pty.spawn(owner, { type: 'slow', name: 'main' })).rejects.toMatchObject({ code: 'DUPLICATE_NAME' })
-    await disposeAgentScope(owner)
+    const disposal = disposeAgentScope(owner)
     gate.resolve(session)
     await expect(pending).rejects.toMatchObject({ code: 'OWNER_NOT_LIVE' })
+    await disposal
     expect(session.closed).toEqual(['PTY spawn rolled back'])
   })
 
+  it('preserves caller cancellation when a pending backend spawn completes', async () => {
+    const ctx = await harness()
+    const gate = Promise.withResolvers<PtyBackendSession>()
+    const session = new StubSession()
+    ctx.pty.registerBackend({ type: 'slow', spawn: () => gate.promise })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+    const controller = new AbortController()
+    const reason = new Error('cancelled by caller')
+
+    const pending = ctx.pty.spawn(owner, { type: 'slow' }, controller.signal)
+    controller.abort(reason)
+    gate.resolve(session)
+
+    await expect(pending).rejects.toBe(reason)
+    expect(session.closed).toEqual(['PTY spawn rolled back'])
+    expect(ctx.agents.get(owner.id)).toBe(owner)
+  })
+
+  it('preserves caller cancellation when unpublished rollback fails', async () => {
+    const ctx = await harness()
+    const gate = Promise.withResolvers<PtyBackendSession>()
+    const session = new StubSession()
+    session.rejectClose = true
+    ctx.pty.registerBackend({ type: 'slow', spawn: () => gate.promise })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+    const controller = new AbortController()
+    const reason = new Error('cancelled by caller')
+
+    const pending = ctx.pty.spawn(owner, { type: 'slow' }, controller.signal)
+    controller.abort(reason)
+    gate.resolve(session)
+
+    await expect(pending).rejects.toBe(reason)
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(true)
+    const internal = ctx.pty as unknown as { disposeAll(): Promise<void> }
+    await expect(internal.disposeAll()).rejects.toThrow('failed to clean up PTY lifecycle')
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(false)
+    expect(session.closed).toEqual(['PTY spawn rolled back'])
+  })
+
+  it('preserves caller cancellation when a backend rejects in response to it', async () => {
+    const ctx = await harness()
+    const started = Promise.withResolvers<undefined>()
+    const backendFailure = new Error('backend observed cancellation')
+    ctx.pty.registerBackend({
+      type: 'abortable',
+      spawn: ({ signal }) => new Promise((_resolve, reject) => {
+        if (signal === undefined) throw new Error('missing spawn signal')
+        started.resolve(undefined)
+        signal.addEventListener('abort', () => { reject(backendFailure) }, { once: true })
+      }),
+    })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+    const controller = new AbortController()
+    const reason = new Error('cancelled by caller')
+
+    const pending = ctx.pty.spawn(owner, { type: 'abortable' }, controller.signal)
+    await started.promise
+    controller.abort(reason)
+
+    await expect(pending).rejects.toBe(reason)
+  })
+
+  it.each(['owner', 'service'] as const)('retains caller-triggered backend cleanup failure until %s disposal', async (scope) => {
+    const ctx = await harness()
+    const started = Promise.withResolvers<undefined>()
+    const cleanupFailure = new Error('backend cleanup failed')
+    ctx.pty.registerBackend({
+      type: 'cleanup-failing',
+      spawn: ({ signal }) => new Promise((_resolve, reject) => {
+        if (signal === undefined) throw new Error('missing spawn signal')
+        started.resolve(undefined)
+        signal.addEventListener('abort', () => {
+          reject(new PtyBackendCleanupError(signal.reason, cleanupFailure))
+        }, { once: true })
+      }),
+    })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+    const controller = new AbortController()
+    const reason = new Error('cancelled by caller')
+
+    const pending = ctx.pty.spawn(owner, { type: 'cleanup-failing' }, controller.signal)
+    await started.promise
+    controller.abort(reason)
+
+    await expect(pending).rejects.toBe(reason)
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(true)
+    const internal = ctx.pty as unknown as {
+      disposeOwned(owner: Agent): Promise<void>
+      disposeAll(): Promise<void>
+    }
+    const disposal = scope === 'owner' ? internal.disposeOwned(owner) : internal.disposeAll()
+    await expect(disposal).rejects.toThrow('failed to clean up PTY lifecycle')
+    expect(ctx.pty.hasOwnerActivity(owner)).toBe(false)
+  })
+
+  it.each([
+    { scope: 'owner', code: 'OWNER_NOT_LIVE' },
+    { scope: 'service', code: 'SERVICE_DISPOSING' },
+  ] as const)('$scope disposal aborts and awaits unpublished backend setup', async ({ scope, code }) => {
+    const ctx = await harness()
+    const gate = Promise.withResolvers<PtyBackendSession>()
+    const started = Promise.withResolvers<undefined>()
+    const session = new StubSession()
+    let backendSignal: AbortSignal | undefined
+    ctx.pty.registerBackend({
+      type: 'slow',
+      spawn: (spec) => {
+        backendSignal = spec.signal
+        started.resolve(undefined)
+        return gate.promise
+      },
+    })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+
+    const pending = ctx.pty.spawn(owner, { type: 'slow' })
+    const pendingFailure = pending.then(
+      () => { throw new Error('pending spawn unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    await started.promise
+    let disposalSettled = false
+    const disposal = (scope === 'owner' ? disposeAgentScope(owner) : disposePtyService(ctx))
+      .then(() => { disposalSettled = true })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const signalAbortedBeforeRelease = backendSignal?.aborted ?? false
+    const signalReasonBeforeRelease = backendSignal?.reason as unknown
+    const disposalSettledBeforeRelease = disposalSettled
+    gate.resolve(session)
+
+    expect(await pendingFailure).toMatchObject({ code })
+    await disposal
+    expect(signalAbortedBeforeRelease).toBe(true)
+    expect(signalReasonBeforeRelease).toMatchObject({ code })
+    expect(disposalSettledBeforeRelease).toBe(false)
+    expect(session.closed).toEqual(['PTY spawn rolled back'])
+  })
+
+  it('reports unpublished rollback failure through service disposal', async () => {
+    const ctx = await harness()
+    const gate = Promise.withResolvers<PtyBackendSession>()
+    const session = new StubSession()
+    session.rejectClose = true
+    ctx.pty.registerBackend({ type: 'slow', spawn: () => gate.promise })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+
+    const pending = ctx.pty.spawn(owner, { type: 'slow' })
+    const pendingFailure = expect(pending).rejects.toThrow('PTY spawn and rollback both failed')
+    const internal = ctx.pty as unknown as { disposeAll(): Promise<void> }
+    const disposalFailure = expect(internal.disposeAll()).rejects.toThrow('failed to clean up PTY lifecycle')
+    gate.resolve(session)
+
+    await pendingFailure
+    await disposalFailure
+    expect(session.closed).toEqual(['PTY spawn rolled back'])
+  })
+
+  it.each([
+    { scope: 'owner', code: 'OWNER_NOT_LIVE' },
+    { scope: 'service', code: 'SERVICE_DISPOSING' },
+  ] as const)('$scope disposal retains backend-side startup cleanup failure', async ({ scope, code }) => {
+    const ctx = await harness()
+    const started = Promise.withResolvers<undefined>()
+    const cleanupFailure = new Error('backend cleanup failed')
+    let backendAbortReason: unknown
+    ctx.pty.registerBackend({
+      type: 'cleanup-failing',
+      spawn: ({ signal }) => new Promise((_resolve, reject) => {
+        if (signal === undefined) throw new Error('missing spawn signal')
+        started.resolve(undefined)
+        signal.addEventListener('abort', () => {
+          backendAbortReason = signal.reason
+          reject(new PtyBackendCleanupError(signal.reason, cleanupFailure))
+        }, { once: true })
+      }),
+    })
+    const owner = stubAgent(ctx, 'owner')
+    ctx.agents.register(owner)
+
+    const pending = ctx.pty.spawn(owner, { type: 'cleanup-failing' })
+    await started.promise
+    const internal = ctx.pty as unknown as {
+      disposeOwned(owner: Agent): Promise<void>
+      disposeAll(): Promise<void>
+    }
+    const disposal = scope === 'owner' ? internal.disposeOwned(owner) : internal.disposeAll()
+    const pendingError = await pending.then(
+      () => { throw new Error('pending spawn unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+
+    expect(pendingError).toBe(backendAbortReason)
+    expect(pendingError).toMatchObject({ code })
+    const disposalError = await disposal.then(
+      () => { throw new Error('disposal unexpectedly succeeded') },
+      (error: unknown) => error,
+    )
+    expect(disposalError).toMatchObject({ message: 'failed to clean up PTY lifecycle' })
+    const rollbackError = (disposalError as AggregateError).errors[0] as unknown
+    const cleanupErrors = (rollbackError as AggregateError).errors as unknown[]
+    expect(cleanupErrors).toEqual([cleanupFailure])
+  })
+
   it('keeps independent reservations and handles provider failure before publication', async () => {
     const ctx = await harness()
     const firstGate = Promise.withResolvers<PtyBackendSession>()
@@ -254,14 +468,27 @@ describe('PtyService ownership and lifecycle', () => {
     ctx.agents.register(owner)
     const failedSpawn = new StubSession()
     failedSpawn.rejectClose = true
+    let ownerDisposal = Promise.resolve()
+    const internal = ctx.pty as unknown as {
+      disposedOwners: WeakSet<Agent>
+      disposeOwned(owner: Agent): Promise<void>
+    }
     ctx.pty.registerBackend({
       type: 'bad-spawn',
-      async spawn() {
-        await disposeAgentScope(owner)
+      async spawn({ signal }) {
+        if (signal === undefined) throw new Error('missing spawn signal')
+        internal.disposedOwners.add(owner)
+        ownerDisposal = internal.disposeOwned(owner)
+        if (!signal.aborted) {
+          await new Promise<undefined>((resolve) => {
+            signal.addEventListener('abort', () => { resolve(undefined) }, { once: true })
+          })
+        }
         return failedSpawn
       },
     })
     await expect(ctx.pty.spawn(owner, { type: 'bad-spawn' })).rejects.toThrow('spawn and rollback both failed')
+    await expect(ownerDisposal).rejects.toThrow('failed to clean up PTY lifecycle')
 
     const nextOwner = stubAgent(ctx, 'next')
     ctx.agents.register(nextOwner)
@@ -338,8 +565,15 @@ describe('PtyService ownership and lifecycle', () => {
       sessions: Map<PtySessionIdType, unknown>
       closeRecords(records: unknown[], reason: string): Promise<void>
     }
-    await expect(internal.closeRecords([...internal.sessions.values()], 'test failure')).rejects.toThrow('failed to close 1 PTY session')
+    const records = [...internal.sessions.values()]
+    const firstFailure = expect(internal.closeRecords(records, 'test failure')).rejects.toThrow('failed to close 1 PTY session')
+    const joinedFailure = expect(internal.closeRecords(records, 'joined failure')).rejects.toThrow('failed to close 1 PTY session')
+    await firstFailure
+    await joinedFailure
     b.sessions[0]!.rejectClose = false
+    await expect(internal.closeRecords([...internal.sessions.values()], 'retry')).resolves.toBeUndefined()
+    expect(b.sessions[0]!.closed).toEqual(['test failure', 'retry'])
+    expect(internal.sessions.size).toBe(0)
     await disposePtyService(ctx)
     await expect(service.spawn(owner, { type: 'stub' })).rejects.toMatchObject({ code: 'SERVICE_DISPOSING' })
   })
@@ -360,7 +594,7 @@ describe('PtyService ownership and lifecycle', () => {
     }
     // Teardown surfaces the close failure, but its finally still clears the
     // backend and owner-cleanup registries instead of orphaning them.
-    await expect(internal.disposeAll()).rejects.toThrow('failed to close 1 PTY session')
+    await expect(internal.disposeAll()).rejects.toThrow('failed to clean up PTY lifecycle')
     expect(internal.backends.size).toBe(0)
     expect(internal.ownerCleanups.size).toBe(0)
   })
diff --git a/packages/pty/tool-pty/README.md b/packages/pty/tool-pty/README.md
index 5a0edca33a..3f9733496a 100644
--- a/packages/pty/tool-pty/README.md
+++ b/packages/pty/tool-pty/README.md
@@ -2,7 +2,16 @@
 
 Six model-facing tools over `ctx.pty`: `terminal_open`, `terminal_send`, `terminal_read`, `terminal_signal`, `terminal_close`, and `terminal_list`. Every operation requires the exact initiating `Agent`, so a model cannot address another agent's terminal even if it learns the id.
 
-`terminal_send(run_in_background: true)` reuses `ctx.tasks`; task preflight occurs before any terminal write, completion is collected with `task_output`, and `task_kill` requests `Ctrl-C`. Foreground sends use terminal ACP cards; lifecycle, history, signal, and list calls use generic cards.
+`terminal_send(run_in_background: true)` reuses `ctx.tasks`; task preflight and the PTY service's exclusive per-session send reservation occur before the task id is returned, completion is collected with `task_output`, and `task_kill` delivers `SIGINT` to the foreground process group. Foreground sends use terminal ACP call/result cards. Background sends use a generic execute card; open, read, signal, close, and list use generic `execute`, `read`, `execute`, `delete`, and `read` cards respectively. None declares source locations.
+
+## Config
+
+| key | default | meaning |
+|---|---:|---|
+| `enableRunInBackground` | `true` | expose and accept `run_in_background`; false omits the schema field and rejects a forced undeclared argument |
+| `maxResultBytes` | `262144` | UTF-8 cap (minimum `64`) for each complete terminal result or PTY task output after wait, session, pagination, truncation, and task-status metadata |
+
+Both values are validated at load. The minimum result cap keeps every registry-issued session or task id visible in its creation acknowledgement. When a result exceeds `maxResultBytes`, rendering reserves space for control metadata and a truncation marker when they fit; cuts preserve UTF-8 boundaries. Each terminal definition's final-content callback applies the same cap after normalized pre-, around-, and post-execute policy failures, denials, short-circuits, replacements, or blocks; a structured multi-block policy result retains its shape.
 
 ## Model Experience
 
@@ -44,11 +53,11 @@ Prefix-stable while tool visibility and definitions are unchanged.
 
 #### What the model sees
 
-Spawn returns the id and bounded MOTD. Send/read return bounded terminal text plus readiness/history markers. Background mode returns a generic task id. Results remain in session history until compaction; incremental task reads do not repeat consumed output.
+Spawn returns the id and bounded MOTD. Send/read return bounded terminal text plus readiness/history markers. Background mode returns a generic task id. Every terminal-owned or policy-produced single-text result is capped by `maxResultBytes` after normalized tool or pipeline errors, denials, short-circuits, replacements, blocks, and generic task status text. Structured multi-block policy results retain their shape. Results remain in session history until compaction; incremental task reads do not repeat consumed output. Programmatic callers receive typed session snapshots, bounded provider read/send DTOs, signal and close outcomes, or `{ kind: "background", taskId }`; Native rendering applies the presentation cap above.
 
 #### Token effect
 
-Data-dependent and bounded by the backend; each returned result remains in history until compaction.
+Terminal-owned and policy-produced single-text results are data-dependent and bounded by `maxResultBytes`; a policy that deliberately substitutes structured multi-block content owns that content's bound. Each returned result remains in history until compaction.
 
 #### KV Cache effect
 
diff --git a/packages/pty/tool-pty/package.json b/packages/pty/tool-pty/package.json
index 6bc602699c..2d36fb5c9b 100644
--- a/packages/pty/tool-pty/package.json
+++ b/packages/pty/tool-pty/package.json
@@ -26,11 +26,15 @@
     "src"
   ],
   "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-pty": "^0.0.1",
+    "@deepseek-ai/dsh-retention": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
@@ -44,6 +48,7 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-pty": "workspace:^",
     "@deepseek-ai/dsh-pty-local": "workspace:^",
+    "@deepseek-ai/dsh-retention": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/pty/tool-pty/src/index.ts b/packages/pty/tool-pty/src/index.ts
index f145102dea..fc66d2646e 100644
--- a/packages/pty/tool-pty/src/index.ts
+++ b/packages/pty/tool-pty/src/index.ts
@@ -5,14 +5,15 @@
  */
 
 import { Context } from 'cordis'
+import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { PtySessionId } from '@deepseek-ai/dsh-pty'
 import type { PtySendResult, PtySessionId as PtySessionIdType, PtySignal } from '@deepseek-ai/dsh-pty'
 import type {} from '@deepseek-ai/dsh-tasks'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ToolExecutionResult, ToolResult } from '@deepseek-ai/dsh-tools'
-import { renderList, renderRead, renderSend, renderSendRead, renderSpawn } from './render.ts'
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import { boundTerminalText, renderList, renderRead, renderSend, renderSendRead, renderSpawn } from './render.ts'
 
 declare module '@deepseek-ai/dsh-tasks' {
   interface TaskKindMap {
@@ -25,6 +26,25 @@ export const name = 'tool-pty'
 /** Required capability, registry, and prompt services. */
 export const inject = ['pty', 'tools', 'systemPrompt']
 
+/** Default cap for one complete model-facing terminal result. */
+export const DEFAULT_MAX_RESULT_BYTES = 256 * 1024
+/** Smallest cap that preserves every counter-backed PTY and task id in its creation acknowledgement. */
+export const MIN_MAX_RESULT_BYTES = 64
+
+/** 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
+}
+
+/** Schemastery configuration for the terminal tool consumer. */
+export const Config: z<Config> = z.object({
+  enableRunInBackground: z.boolean().default(true),
+  maxResultBytes: z.number().step(1).min(MIN_MAX_RESULT_BYTES).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RESULT_BYTES),
+})
+
 interface SpawnArgs {
   type: string
   name?: string
@@ -50,6 +70,50 @@ interface SignalArgs extends SessionArgs {
   signal: PtySignal
 }
 
+const SESSION_STATUS_SCHEMA = {
+  oneOf: [
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        kind: { type: 'string', required: true, const: 'running' },
+      },
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        kind: { type: 'string', required: true, const: 'exited' },
+        exitCode: { required: true, oneOf: [{ type: 'integer' }, { type: 'null' }] },
+        signal: { required: true, oneOf: [{ type: 'string' }, { type: 'null' }] },
+      },
+    },
+  ],
+} as const
+
+const SESSION_SNAPSHOT_PROPERTIES = {
+  sessionId: { type: 'string', required: true },
+  name: { type: 'string' },
+  type: { type: 'string', required: true },
+  pid: { type: 'integer' },
+  status: { ...SESSION_STATUS_SCHEMA, required: true },
+} as const
+
+const SESSION_SNAPSHOT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: SESSION_SNAPSHOT_PROPERTIES,
+} as const
+
+const BACKGROUND_TASK_OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    kind: { type: 'string', required: true, const: 'background' },
+    taskId: { type: 'string', required: true },
+  },
+} as const
+
 function requireAgent(agent: Agent | undefined): Agent {
   if (agent === undefined) throw new Error('terminal tools require an initiating agent')
   return agent
@@ -62,13 +126,13 @@ function sessionId(args: SessionArgs): PtySessionIdType {
   return PtySessionId(args.sessionId)
 }
 
-function textResult(text: string): ContentBlock[] {
-  return [{ type: 'text', text }]
+function textResult(text: string, maxBytes: number): ContentBlock[] {
+  return [{ type: 'text', text: boundTerminalText(text, maxBytes) }]
 }
 
-function rawResultText(result: ToolResult): string | undefined {
-  if (result.content.length !== 1) return undefined
-  const block = result.content[0]
+function rawContentText(content: readonly ContentBlock[]): string | undefined {
+  if (content.length !== 1) return undefined
+  const block = content[0]
   return block?.type === 'text' ? block.text : undefined
 }
 
@@ -79,7 +143,16 @@ function sendDetail(result: PtySendResult): string {
 }
 
 /** Register all terminal tools and the minimal usage guidance. */
-export function apply(ctx: Context): void {
+export function apply(ctx: Context, config: Config = {}): void {
+  const enableRunInBackground = config.enableRunInBackground ?? true
+  const maxResultBytes = config.maxResultBytes ?? DEFAULT_MAX_RESULT_BYTES
+  if (!Number.isSafeInteger(maxResultBytes) || maxResultBytes < MIN_MAX_RESULT_BYTES) {
+    throw new Error(`tool-pty: maxResultBytes must be a safe integer of at least ${MIN_MAX_RESULT_BYTES}`)
+  }
+  const finalizeContent: NonNullable<ToolDefinition['finalizeContent']> = (_exec, result) => {
+    const raw = rawContentText(result.content)
+    return raw === undefined ? undefined : textResult(raw, maxResultBytes)
+  }
   ctx.systemPrompt.section({
     name: 'tool:pty',
     order: 106,
@@ -94,6 +167,18 @@ export function apply(ctx: Context): void {
       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.' },
     },
+    finalizeContent,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ...SESSION_SNAPSHOT_PROPERTIES,
+          motd: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderSpawn(value, maxResultBytes) }],
+    },
     async execute(args: SpawnArgs, exec) {
       if (args.type.length === 0) throw new Error('type must be a non-empty string')
       const result = await ctx.pty.spawn(requireAgent(exec.agent), {
@@ -101,7 +186,7 @@ export function apply(ctx: Context): void {
         ...args.name !== undefined ? { name: args.name } : {},
         ...args.cwd !== undefined ? { cwd: args.cwd } : {},
       }, exec.signal)
-      return textResult(renderSpawn(result))
+      return result
     },
     presentCall: (args) => {
       const parsed = args
@@ -111,18 +196,59 @@ export function apply(ctx: Context): void {
 
   ctx.tools.register(defineTool({
     name: 'terminal_send',
-    description: 'Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit. Background mode returns a task id for task_output/task_kill.',
+    description: 'Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit.'
+      + (enableRunInBackground ? ' Background mode returns a task id for task_output/task_kill.' : ''),
     parameters: {
       sessionId: { type: 'string', required: true, description: 'Terminal session id returned by terminal_open or terminal_list.' },
       text: { type: 'string', required: true, 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.' },
+      ...enableRunInBackground
+        ? { run_in_background: { type: 'boolean' as const, description: 'Return a task id immediately; collect with task_output or stop with task_kill.' } }
+        : {},
     },
-    async execute(args: SendArgs, exec): Promise<ToolExecutionResult> {
+    finalizeContent,
+    output: {
+      schema: {
+        oneOf: [
+          BACKGROUND_TASK_OUTPUT_SCHEMA,
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'foreground' },
+              viewport: { type: 'string', required: true },
+              waitReason: {
+                type: 'string',
+                required: true,
+                enum: ['stdin_read', 'inferred_idle', 'timeout', 'session_exit'],
+              },
+              sessionStatus: { ...SESSION_STATUS_SCHEMA, required: true },
+              truncated: { type: 'boolean', required: true },
+            },
+          },
+        ],
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.kind === 'background'
+          ? `started background task ${value.taskId}`
+          : renderSend(value, maxResultBytes),
+      }],
+      presentationMeta: (_args, value) => value.kind === 'foreground'
+        ? {
+          viewport: value.viewport,
+          waitReason: value.waitReason,
+          sessionStatus: value.sessionStatus,
+          truncated: value.truncated,
+        }
+        : null,
+    },
+    async execute(args: SendArgs, exec) {
       const owner = requireAgent(exec.agent)
       const id = sessionId(args)
       const request = { text: args.text, submit: args.submit ?? true }
       if (args.run_in_background === true) {
+        if (!enableRunInBackground) throw new Error('background terminal sends are disabled by tool-pty configuration')
         const tasks = ctx.get('tasks')
         if (tasks === undefined) throw new Error('background terminal sends require @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
         let cancelRequested = false
@@ -130,6 +256,7 @@ export function apply(ctx: Context): void {
           kind: 'pty-send',
           label: `${id}: ${args.text || '(input)'}`,
           owner,
+          outputLimitBytes: maxResultBytes,
           run: () => {
             const operation = ctx.pty.startSend(owner, id, request)
             return {
@@ -145,12 +272,12 @@ export function apply(ctx: Context): void {
             }
           },
         })
-        return { content: textResult(`started background task ${taskId}`), isError: false }
+        return { kind: 'background' as const, taskId }
       }
       const operation = ctx.pty.startSend(owner, id, { ...request, signal: exec.signal })
       const result = await operation.done
       if (exec.signal.aborted) throw new Error('terminal send aborted')
-      return { content: textResult(renderSend(result)), isError: false, meta: result }
+      return { kind: 'foreground' as const, ...result }
     },
     presentCall(args) {
       const parsed = args as Partial<SendArgs>
@@ -161,7 +288,7 @@ export function apply(ctx: Context): void {
     },
     presentResult(args, result) {
       if ((args as Partial<SendArgs>).run_in_background === true || result.isError) return undefined
-      const raw = rawResultText(result)
+      const raw = rawContentText(result.content)
       return raw === undefined ? undefined : { card: 'terminal', output: raw }
     },
   }))
@@ -174,12 +301,27 @@ export function apply(ctx: Context): void {
       offset: { type: 'number', description: 'Newest-relative line offset (default 0).' },
       count: { type: 'number', description: 'Requested line count (default 500; backend caps apply).' },
     },
+    finalizeContent,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          text: { type: 'string', required: true },
+          totalLines: { type: 'integer', required: true },
+          lineBegin: { type: 'integer', required: true },
+          lineEnd: { type: 'integer', required: true },
+          truncated: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderRead(value, maxResultBytes) }],
+    },
     execute(args: ReadArgs, exec) {
       const result = ctx.pty.read(requireAgent(exec.agent), sessionId(args), {
         ...args.offset !== undefined ? { offset: args.offset } : {},
         ...args.count !== undefined ? { count: args.count } : {},
       })
-      return Promise.resolve(textResult(renderRead(result)))
+      return Promise.resolve(result)
     },
     presentCall: args => ({ card: 'generic', title: `Read terminal ${(args).sessionId}`, kind: 'read', rawInput: args }),
   }))
@@ -191,11 +333,22 @@ export function apply(ctx: Context): void {
       sessionId: { type: 'string', required: true, description: 'Terminal session id.' },
       signal: { type: 'string', required: true, enum: ['SIGINT', 'SIGTERM', 'SIGKILL', 'SIGTSTP', 'SIGHUP'], description: 'Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.' },
     },
-    async execute(args: SignalArgs, exec) {
-      const result = await ctx.pty.signal(requireAgent(exec.agent), sessionId(args), args.signal)
-      return textResult(`delivered ${args.signal} to foreground process group ${result.targetPgid}`)
+    finalizeContent,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          delivered: { type: 'boolean', required: true, const: true },
+          targetPgid: { type: 'integer', required: true },
+        },
+      },
+      render: (args, value) => [{ type: 'text', text: `delivered ${args.signal} to foreground process group ${value.targetPgid}` }],
     },
-    presentCall: args => ({ card: 'generic', title: `Signal terminal ${(args as SignalArgs).sessionId}`, kind: 'execute', rawInput: args }),
+    async execute(args: SignalArgs, exec) {
+      return ctx.pty.signal(requireAgent(exec.agent), sessionId(args), args.signal)
+    },
+    presentCall: args => ({ card: 'generic', title: `Signal terminal ${args.sessionId}`, kind: 'execute', rawInput: args }),
   }))
 
   ctx.tools.register(defineTool({
@@ -204,10 +357,27 @@ export function apply(ctx: Context): void {
     parameters: {
       sessionId: { type: 'string', required: true, description: 'Terminal session id.' },
     },
+    finalizeContent,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          sessionId: { type: 'string', required: true },
+          outcome: { type: 'string', required: true, enum: ['closed', 'already-closing'] },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.outcome === 'closed'
+          ? `closed terminal session ${value.sessionId}`
+          : `terminal session ${value.sessionId} was already closing`,
+      }],
+    },
     async execute(args: SessionArgs, exec) {
       const id = sessionId(args)
       const closed = await ctx.pty.kill(requireAgent(exec.agent), id)
-      return textResult(closed ? `closed terminal session ${id}` : `terminal session ${id} was already closing`)
+      return { sessionId: id, outcome: closed ? 'closed' as const : 'already-closing' as const }
     },
     presentCall: args => ({ card: 'generic', title: `Close terminal ${(args).sessionId}`, kind: 'delete' }),
   }))
@@ -216,8 +386,13 @@ export function apply(ctx: Context): void {
     name: 'terminal_list',
     description: 'List persistent terminal sessions owned by the current agent.',
     parameters: {},
+    finalizeContent,
+    output: {
+      schema: { type: 'array', items: SESSION_SNAPSHOT_SCHEMA },
+      render: (_args, value) => [{ type: 'text', text: renderList(value, maxResultBytes) }],
+    },
     execute(_args: Record<string, never>, exec) {
-      return Promise.resolve(textResult(renderList(ctx.pty.list(requireAgent(exec.agent)))))
+      return Promise.resolve(ctx.pty.list(requireAgent(exec.agent)))
     },
     presentCall: () => ({ card: 'generic', title: 'List terminal sessions', kind: 'read' }),
   }))
diff --git a/packages/pty/tool-pty/src/render.ts b/packages/pty/tool-pty/src/render.ts
index bed176e890..361de1eab5 100644
--- a/packages/pty/tool-pty/src/render.ts
+++ b/packages/pty/tool-pty/src/render.ts
@@ -1,57 +1,171 @@
 /** Model and ACP rendering for persistent terminal tool results. */
 
-import type { PtyReadResult, PtySendRead, PtySendResult, PtySessionSnapshot, PtySpawnResult } from '@deepseek-ai/dsh-pty'
+import { TextRetainer } from '@deepseek-ai/dsh-retention'
+
+interface RenderedSessionStatusRunning {
+  kind: 'running'
+}
+
+interface RenderedSessionStatusExited {
+  kind: 'exited'
+  exitCode: number | null
+  signal: string | null
+}
+
+type RenderedSessionStatus = RenderedSessionStatusRunning | RenderedSessionStatusExited
+
+interface RenderedSessionSnapshot {
+  sessionId: string
+  name?: string
+  type: string
+  pid?: number
+  status: RenderedSessionStatus
+}
+
+interface RenderedSpawnResult extends RenderedSessionSnapshot {
+  motd: string
+}
+
+interface RenderedSendResult {
+  viewport: string
+  waitReason: 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
+  sessionStatus: RenderedSessionStatus
+  truncated: boolean
+}
+
+interface RenderedSendRead {
+  delta: string
+  truncated: boolean
+}
+
+interface RenderedReadResult {
+  text: string
+  totalLines: number
+  lineBegin: number
+  lineEnd: number
+  truncated: boolean
+}
+
+const encoder = new TextEncoder()
+const TRUNCATED = '\n[output truncated]'
+
+function byteLength(text: string): number {
+  return encoder.encode(text).byteLength
+}
+
+function retain(text: string, maxBytes: number, kind: 'head' | 'tail'): string {
+  const retainer = new TextRetainer({ kind, maxBytes })
+  retainer.push(text)
+  return retainer.finish().text
+}
+
+function fitWithSuffix(content: string, suffix: string, maxBytes: number): string {
+  const fixedBytes = byteLength(suffix)
+  if (fixedBytes >= maxBytes) return retain(suffix, maxBytes, 'tail')
+  return `${retain(content, maxBytes - fixedBytes, 'tail')}${suffix}`
+}
+
+function fitWithPrefix(prefix: string, content: string, maxBytes: number): string {
+  const fixed = `${prefix}${TRUNCATED}`
+  const fixedBytes = byteLength(fixed)
+  if (fixedBytes >= maxBytes) return retain(fixed, maxBytes, 'head')
+  return `${prefix}${retain(content, maxBytes - fixedBytes, 'tail')}${TRUNCATED}`
+}
+
+function boundBodyWithSuffix(
+  content: string,
+  metadata: string,
+  upstreamTruncated: boolean,
+  maxBytes: number,
+): string {
+  const suffix = `${metadata}${upstreamTruncated ? TRUNCATED : ''}`
+  const complete = `${content}${suffix}`
+  if (byteLength(complete) <= maxBytes) return complete
+  return fitWithSuffix(content, `${metadata}${TRUNCATED}`, maxBytes)
+}
+
+/**
+ * Bound one complete terminal acknowledgement while preserving UTF-8 cuts.
+ * @param text - complete acknowledgement text.
+ * @param maxBytes - positive final result cap.
+ * @returns bounded text with a truncation marker when it fits.
+ */
+export function boundTerminalText(text: string, maxBytes: number): string {
+  if (byteLength(text) <= maxBytes) return text
+  const markerBytes = byteLength(TRUNCATED)
+  if (markerBytes >= maxBytes) return retain(TRUNCATED, maxBytes, 'tail')
+  return `${retain(text, maxBytes - markerBytes, 'head')}${TRUNCATED}`
+}
 
 /**
  * Render one created session and its bounded MOTD.
  * @param result - published spawn result.
+ * @param maxBytes - complete UTF-8 result cap.
  * @returns Model-facing session acknowledgement.
  */
-export function renderSpawn(result: PtySpawnResult): string {
+export function renderSpawn(result: RenderedSpawnResult, maxBytes: number): string {
   const label = result.name === undefined ? result.sessionId : `${result.sessionId} (${result.name})`
-  return `started terminal session ${label} [type: ${result.type}]\n${result.motd || '(no startup output)'}`
+  const prefix = `started terminal session ${label} [type: ${result.type}]\n`
+  const motd = result.motd || '(no startup output)'
+  const complete = `${prefix}${motd}`
+  return byteLength(complete) <= maxBytes ? complete : fitWithPrefix(prefix, motd, maxBytes)
 }
 
 /**
  * Render one settled interactive send.
  * @param result - settled send outcome.
+ * @param maxBytes - complete UTF-8 result cap.
  * @returns Terminal output plus wait/session markers.
  */
-export function renderSend(result: PtySendResult): string {
+export function renderSend(result: RenderedSendResult, maxBytes: number): string {
   const output = result.viewport || '(no new output)'
   const status = result.sessionStatus.kind === 'running'
     ? 'running'
     : `exited code=${result.sessionStatus.exitCode ?? 'null'} signal=${result.sessionStatus.signal ?? 'null'}`
-  return `${output}\n[wait: ${result.waitReason}]\n[session: ${status}]${result.truncated ? '\n[output truncated]' : ''}`
+  return boundBodyWithSuffix(
+    output,
+    `\n[wait: ${result.waitReason}]\n[session: ${status}]`,
+    result.truncated,
+    maxBytes,
+  )
 }
 
 /**
  * Render one incremental background operation read.
  * @param read - consuming operation delta.
- * @returns Delta plus truncation marker when needed.
+ * @returns Delta plus its upstream truncation marker. The generic task control
+ *   applies the producer's complete-result cap after adding task status.
  */
-export function renderSendRead(read: PtySendRead): string {
-  return `${read.delta}${read.truncated ? `${read.delta.endsWith('\n') || read.delta.length === 0 ? '' : '\n'}[output truncated]` : ''}`
+export function renderSendRead(read: RenderedSendRead): string {
+  const separator = read.delta.endsWith('\n') || read.delta.length === 0 ? '' : '\n'
+  return `${read.delta}${read.truncated ? `${separator}[output truncated]` : ''}`
 }
 
 /**
  * Render one bounded historical page.
  * @param result - retained scrollback page.
+ * @param maxBytes - complete UTF-8 result cap.
  * @returns Page text plus pagination and truncation markers.
  */
-export function renderRead(result: PtyReadResult): string {
+export function renderRead(result: RenderedReadResult, maxBytes: number): string {
   const output = result.text || '(no retained output)'
-  return `${output}\n[lines: ${result.lineBegin}-${result.lineEnd} of ${result.totalLines}]${result.truncated ? '\n[output truncated]' : ''}`
+  return boundBodyWithSuffix(
+    output,
+    `\n[lines: ${result.lineBegin}-${result.lineEnd} of ${result.totalLines}]`,
+    result.truncated,
+    maxBytes,
+  )
 }
 
 /**
  * Render owner-visible live sessions.
  * @param sessions - fresh owner-scoped snapshots.
+ * @param maxBytes - complete UTF-8 result cap.
  * @returns One line per session or the empty marker.
  */
-export function renderList(sessions: PtySessionSnapshot[]): string {
+export function renderList(sessions: readonly RenderedSessionSnapshot[], maxBytes: number): string {
   if (sessions.length === 0) return '(no terminal sessions)'
-  return sessions.map((session) => {
+  const text = sessions.map((session) => {
     const name = session.name === undefined ? '' : ` (${session.name})`
     const pid = session.pid === undefined ? '' : ` pid=${session.pid}`
     const status = session.status.kind === 'running'
@@ -59,4 +173,5 @@ export function renderList(sessions: PtySessionSnapshot[]): string {
       : `exited code=${session.status.exitCode ?? 'null'} signal=${session.status.signal ?? 'null'}`
     return `${session.sessionId}${name} [${session.type}] ${status}${pid}`
   }).join('\n')
+  return boundBodyWithSuffix(text, '', false, maxBytes)
 }
diff --git a/packages/pty/tool-pty/tests/loader-composition.spec.ts b/packages/pty/tool-pty/tests/loader-composition.spec.ts
index 38a5cb4ed6..40477aeb7a 100644
--- a/packages/pty/tool-pty/tests/loader-composition.spec.ts
+++ b/packages/pty/tool-pty/tests/loader-composition.spec.ts
@@ -8,7 +8,7 @@ import Loader from '@cordisjs/plugin-loader'
 import Include from '@cordisjs/plugin-include'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -40,7 +40,7 @@ function agent(ctx: Context): Agent {
   const id = SessionId('pty-loader-agent')
   const value: Agent = {
     id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx,
-    send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
   }
   ctx.agents.register(value)
   return value
diff --git a/packages/pty/tool-pty/tests/render.spec.ts b/packages/pty/tool-pty/tests/render.spec.ts
index 33b288ab5f..b02ba3b8ef 100644
--- a/packages/pty/tool-pty/tests/render.spec.ts
+++ b/packages/pty/tool-pty/tests/render.spec.ts
@@ -1,23 +1,23 @@
 import { describe, expect, it } from 'vitest'
 import { PtySessionId } from '@deepseek-ai/dsh-pty'
-import { renderList, renderRead, renderSend, renderSendRead, renderSpawn } from '@deepseek-ai/dsh-tool-pty/src/render.ts'
+import { boundTerminalText, renderList, renderRead, renderSend, renderSendRead, renderSpawn } from '@deepseek-ai/dsh-tool-pty/src/render.ts'
 
 describe('tool-pty rendering', () => {
   it('renders spawn with and without names or MOTD', () => {
-    expect(renderSpawn({ sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' }, motd: '' }))
+    expect(renderSpawn({ sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' }, motd: '' }, 1024))
       .toBe('started terminal session pty-1 [type: shell]\n(no startup output)')
-    expect(renderSpawn({ sessionId: PtySessionId('pty-2'), name: 'main', type: 'shell', pid: 2, status: { kind: 'running' }, motd: 'ready' }))
+    expect(renderSpawn({ sessionId: PtySessionId('pty-2'), name: 'main', type: 'shell', pid: 2, status: { kind: 'running' }, motd: 'ready' }, 1024))
       .toContain('pty-2 (main)')
   })
 
   it('renders running, exited, empty, and truncated sends', () => {
-    expect(renderSend({ viewport: '', waitReason: 'timeout', sessionStatus: { kind: 'running' }, truncated: true }))
+    expect(renderSend({ viewport: '', waitReason: 'timeout', sessionStatus: { kind: 'running' }, truncated: true }, 1024))
       .toBe('(no new output)\n[wait: timeout]\n[session: running]\n[output truncated]')
-    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGTERM' }, truncated: false }))
+    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGTERM' }, truncated: false }, 1024))
       .toContain('exited code=null signal=SIGTERM')
-    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: 2, signal: null }, truncated: false }))
+    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: 2, signal: null }, truncated: false }, 1024))
       .toContain('exited code=2 signal=null')
-    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: null }, truncated: false }))
+    expect(renderSend({ viewport: 'bye', waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: null }, truncated: false }, 1024))
       .toContain('exited code=null signal=null')
     expect(renderSendRead({ delta: '', truncated: true })).toBe('[output truncated]')
     expect(renderSendRead({ delta: 'x', truncated: true })).toBe('x\n[output truncated]')
@@ -26,14 +26,48 @@ describe('tool-pty rendering', () => {
   })
 
   it('renders history and every list status shape', () => {
-    expect(renderRead({ text: '', totalLines: 0, lineBegin: 0, lineEnd: 0, truncated: true }))
+    expect(renderRead({ text: '', totalLines: 0, lineBegin: 0, lineEnd: 0, truncated: true }, 1024))
       .toBe('(no retained output)\n[lines: 0-0 of 0]\n[output truncated]')
-    expect(renderList([])).toBe('(no terminal sessions)')
+    expect(renderList([], 1024)).toBe('(no terminal sessions)')
     expect(renderList([
       { sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' } },
       { sessionId: PtySessionId('pty-2'), name: 'done', type: 'shell', pid: 9, status: { kind: 'exited', exitCode: 2, signal: null } },
       { sessionId: PtySessionId('pty-3'), type: 'shell', status: { kind: 'exited', exitCode: null, signal: 'SIGTERM' } },
       { sessionId: PtySessionId('pty-4'), type: 'shell', status: { kind: 'exited', exitCode: null, signal: null } },
-    ])).toBe('pty-1 [shell] running\npty-2 (done) [shell] exited code=2 signal=null pid=9\npty-3 [shell] exited code=null signal=SIGTERM\npty-4 [shell] exited code=null signal=null')
+    ], 1024)).toBe('pty-1 [shell] running\npty-2 (done) [shell] exited code=2 signal=null pid=9\npty-3 [shell] exited code=null signal=SIGTERM\npty-4 [shell] exited code=null signal=null')
+  })
+
+  it('bounds complete UTF-8 results while retaining terminal metadata when it fits', () => {
+    const send = renderSend({
+      viewport: `prefix-${'界'.repeat(40)}`,
+      waitReason: 'stdin_read',
+      sessionStatus: { kind: 'running' },
+      truncated: false,
+    }, 64)
+    expect(Buffer.byteLength(send)).toBeLessThanOrEqual(64)
+    expect(send).toContain('[wait: stdin_read]')
+    expect(send).toContain('[output truncated]')
+
+    const read = renderRead({
+      text: 'x'.repeat(200), totalLines: 20, lineBegin: 0, lineEnd: 10, truncated: false,
+    }, 48)
+    expect(Buffer.byteLength(read)).toBeLessThanOrEqual(48)
+    expect(read).toContain('[lines: 0-10 of 20]')
+
+    expect(Buffer.byteLength(renderSpawn({
+      sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' }, motd: 'x'.repeat(200),
+    }, 32))).toBeLessThanOrEqual(32)
+
+    const boundedSpawn = renderSpawn({
+      sessionId: PtySessionId('pty-1'), type: 'shell', status: { kind: 'running' }, motd: 'x'.repeat(200),
+    }, 96)
+    expect(boundedSpawn).toContain('started terminal session pty-1')
+    expect(boundedSpawn).toContain('[output truncated]')
+
+    expect(Buffer.byteLength(renderSend({
+      viewport: 'x'.repeat(200), waitReason: 'stdin_read', sessionStatus: { kind: 'running' }, truncated: false,
+    }, 8))).toBeLessThanOrEqual(8)
+    expect(boundTerminalText('x'.repeat(200), 8)).toHaveLength(8)
+    expect(boundTerminalText('x'.repeat(200), 32).endsWith('[output truncated]')).toBe(true)
   })
 })
diff --git a/packages/pty/tool-pty/tests/tools.spec.ts b/packages/pty/tool-pty/tests/tools.spec.ts
index 5adcaea441..e0b854ee43 100644
--- a/packages/pty/tool-pty/tests/tools.spec.ts
+++ b/packages/pty/tool-pty/tests/tools.spec.ts
@@ -2,10 +2,11 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { renderToolsSdk } from '@deepseek-ai/dsh-tools'
+import type { ToolSdkSchema } from '@deepseek-ai/dsh-tools/src/ts-types.ts'
 import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
 import type { PtyBackend, PtyBackendSession, PtySendOperation, PtySendRequest, PtySessionStatus, PtySignal } from '@deepseek-ai/dsh-pty'
 import TaskService from '@deepseek-ai/dsh-tasks'
@@ -17,7 +18,7 @@ function fakeAgent(ctx: Context, rawId: string): Agent {
   const id = SessionId(rawId)
   const agent: Agent = {
     id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx,
-    send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
   }
   ctx.agents.register(agent)
   return agent
@@ -31,20 +32,23 @@ class StubSession implements PtyBackendSession {
   autoSettle = true
   rejectOperation = false
   closeGate: PromiseWithResolvers<undefined> | undefined
+  viewport = 'command output'
+  delta = 'live output'
+  deltaTruncated = false
 
   startSend(_request: PtySendRequest): PtySendOperation {
     let settle!: () => void
     let reject!: (error: unknown) => void
     let cancelled = false
     const done = new Promise<void>((resolve, rejectPromise) => { settle = resolve; reject = rejectPromise }).then(() => ({
-      viewport: cancelled ? '^C' : 'command output',
+      viewport: cancelled ? '^C' : this.viewport,
       waitReason: 'stdin_read' as const,
       sessionStatus: this.statusValue,
       truncated: false,
     }))
     const operation: PtySendOperation = {
       done,
-      readOutput: () => ({ delta: 'live output', truncated: false }),
+      readOutput: () => ({ delta: this.delta, truncated: this.deltaTruncated }),
       cancel: () => {
         if (cancelled) return false
         cancelled = true
@@ -87,7 +91,13 @@ function stubBackend() {
   return { backend, sessions }
 }
 
-async function setup(tasks: boolean) {
+async function setup(tasks: boolean, config: ToolPty.Config = {}) {
+  const base = await setupBase(tasks)
+  await base.ctx.plugin(ToolPty, config)
+  return base
+}
+
+async function setupBase(tasks: boolean) {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
@@ -99,11 +109,11 @@ async function setup(tasks: boolean) {
     await ctx.plugin(TaskService)
     await ctx.plugin(ToolTasks)
   }
-  await ctx.plugin(ToolPty)
   return { ctx, stub, agent: fakeAgent(ctx, tasks ? 'with-tasks' : 'foreground') }
 }
 
 let callNumber = 0
+const TOOL_NAMES = ['terminal_open', 'terminal_send', 'terminal_read', 'terminal_signal', 'terminal_close', 'terminal_list'] as const
 const testToolSignal = new AbortController().signal
 function call(ctx: Context, name: string, args: unknown, agent?: Agent) {
   return ctx.tools.execute({ signal: testToolSignal, callId: CallId(`pty-call-${++callNumber}`), name, arguments: args, ...agent ? { agent } : {} })
@@ -120,17 +130,134 @@ function text(result: { content: { type: string; text?: string }[] }): string {
 describe('tool-pty foreground surface', () => {
   it('registers exactly six schemas and drives the full owner-scoped lifecycle', async () => {
     const { ctx, agent } = await setup(false)
-    expect(['terminal_open', 'terminal_send', 'terminal_read', 'terminal_signal', 'terminal_close', 'terminal_list'].every(name => ctx.tools.get(name) !== undefined)).toBe(true)
+    expect(TOOL_NAMES.every(name => ctx.tools.get(name) !== undefined)).toBe(true)
 
     const spawned = await call(ctx, 'terminal_open', { type: 'stub', name: 'main' }, agent)
     expect(text(spawned)).toContain('started terminal session pty-1 (main)')
-    expect(text(await call(ctx, 'terminal_list', {}, agent))).toContain('pty-1 (main) [stub] running pid=42')
-    expect(text(await call(ctx, 'terminal_read', { sessionId: 'pty-1' }, agent))).toContain('history\n[lines: 0-1 of 1]')
-    expect(text(await call(ctx, 'terminal_signal', { sessionId: 'pty-1', signal: 'SIGINT' }, agent))).toBe('delivered SIGINT to foreground process group 10')
+    expect(spawned).toMatchObject({
+      isError: false,
+      value: {
+        sessionId: 'pty-1',
+        name: 'main',
+        type: 'stub',
+        pid: 42,
+        status: { kind: 'running' },
+        motd: 'stub prompt',
+      },
+    })
+    const listed = await call(ctx, 'terminal_list', {}, agent)
+    expect(text(listed)).toContain('pty-1 (main) [stub] running pid=42')
+    expect(listed).toMatchObject({ isError: false, value: [{ sessionId: 'pty-1', name: 'main', type: 'stub', pid: 42, status: { kind: 'running' } }] })
+    const read = await call(ctx, 'terminal_read', { sessionId: 'pty-1' }, agent)
+    expect(text(read)).toContain('history\n[lines: 0-1 of 1]')
+    expect(read).toMatchObject({ isError: false, value: { text: 'history', totalLines: 1, lineBegin: 0, lineEnd: 1, truncated: false } })
+    const signalled = await call(ctx, 'terminal_signal', { sessionId: 'pty-1', signal: 'SIGINT' }, agent)
+    expect(text(signalled)).toBe('delivered SIGINT to foreground process group 10')
+    expect(signalled).toMatchObject({ isError: false, value: { delivered: true, targetPgid: 10 } })
     const sent = await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'echo hi' }, agent)
     expect(text(sent)).toContain('command output\n[wait: stdin_read]\n[session: running]')
-    expect(text(await call(ctx, 'terminal_close', { sessionId: 'pty-1' }, agent))).toBe('closed terminal session pty-1')
-    expect(text(await call(ctx, 'terminal_list', {}, agent))).toBe('(no terminal sessions)')
+    expect(sent).toMatchObject({
+      isError: false,
+      value: {
+        kind: 'foreground',
+        viewport: 'command output',
+        waitReason: 'stdin_read',
+        sessionStatus: { kind: 'running' },
+        truncated: false,
+      },
+      meta: {
+        viewport: 'command output',
+        waitReason: 'stdin_read',
+        sessionStatus: { kind: 'running' },
+        truncated: false,
+      },
+    })
+    const closed = await call(ctx, 'terminal_close', { sessionId: 'pty-1' }, agent)
+    expect(text(closed)).toBe('closed terminal session pty-1')
+    expect(closed).toMatchObject({ isError: false, value: { sessionId: 'pty-1', outcome: 'closed' } })
+    const empty = await call(ctx, 'terminal_list', {}, agent)
+    expect(text(empty)).toBe('(no terminal sessions)')
+    expect(empty).toMatchObject({ isError: false, value: [] })
+  })
+
+  it('projects every terminal DTO into the generated Code Mode output map', async () => {
+    const { ctx } = await setup(false)
+    const schemas = TOOL_NAMES.map((toolName): ToolSdkSchema => {
+      const definition = ctx.tools.get(toolName)
+      if (definition === undefined) throw new Error(`missing terminal tool ${toolName}`)
+      return {
+        name: definition.name,
+        description: definition.description,
+        parameters: definition.parameters,
+        output: definition.output.schema,
+      }
+    })
+    const sdk = renderToolsSdk(schemas)
+    const outputMapStart = sdk.indexOf('interface ToolOutputMap')
+    const outputMapEnd = sdk.indexOf('\n\ntype ToolName', outputMapStart)
+
+    expect(sdk.slice(outputMapStart, outputMapEnd)).toMatchInlineSnapshot(`
+      "interface ToolOutputMap {
+        terminal_close: {
+          sessionId: string;
+          outcome: "closed" | "already-closing";
+        };
+        terminal_list: ({
+          sessionId: string;
+          name?: string;
+          type: string;
+          pid?: number;
+          status: {
+            kind: "running";
+          } | {
+            kind: "exited";
+            exitCode: number | null;
+            signal: string | null;
+          };
+        })[];
+        terminal_open: {
+          sessionId: string;
+          name?: string;
+          type: string;
+          pid?: number;
+          status: {
+            kind: "running";
+          } | {
+            kind: "exited";
+            exitCode: number | null;
+            signal: string | null;
+          };
+          motd: string;
+        };
+        terminal_read: {
+          text: string;
+          totalLines: number;
+          lineBegin: number;
+          lineEnd: number;
+          truncated: boolean;
+        };
+        terminal_send: {
+          kind: "background";
+          taskId: string;
+        } | {
+          kind: "foreground";
+          viewport: string;
+          waitReason: "stdin_read" | "inferred_idle" | "timeout" | "session_exit";
+          sessionStatus: {
+            kind: "running";
+          } | {
+            kind: "exited";
+            exitCode: number | null;
+            signal: string | null;
+          };
+          truncated: boolean;
+        };
+        terminal_signal: {
+          delivered: true;
+          targetPgid: number;
+        };
+      }"
+    `)
   })
 
   it('fails without an initiating agent and rejects background before writing', async () => {
@@ -172,18 +299,132 @@ describe('tool-pty foreground surface', () => {
     expect(ctx.tools.get('terminal_close')?.presentCall?.({ sessionId: 'pty-1' })).toMatchObject({ card: 'generic', title: 'Close terminal pty-1' })
     expect(ctx.tools.get('terminal_list')?.presentCall?.({})).toMatchObject({ card: 'generic', title: 'List terminal sessions' })
   })
+
+  it('configuration-gates background sends and validates the final result bound', async () => {
+    const disabled = await setup(true, { enableRunInBackground: false })
+    const definition = disabled.ctx.tools.get('terminal_send')
+    expect(definition?.parameters).not.toHaveProperty('properties.run_in_background')
+    expect(definition?.description).not.toContain('Background mode')
+    await call(disabled.ctx, 'terminal_open', { type: 'stub' }, disabled.agent)
+    expect((await call(disabled.ctx, 'terminal_send', {
+      sessionId: 'pty-1', text: 'work', run_in_background: true,
+    }, disabled.agent)).isError).toBe(true)
+
+    const defaults = await setupBase(false)
+    ToolPty.apply(defaults.ctx)
+    expect(defaults.ctx.tools.get('terminal_send')?.parameters).toHaveProperty('properties.run_in_background')
+
+    const invalid = await setupBase(false)
+    expect(() => { ToolPty.apply(invalid.ctx, { maxResultBytes: 0 }) }).toThrow('maxResultBytes')
+    expect(() => { ToolPty.apply(invalid.ctx, { maxResultBytes: 63 }) }).toThrow('at least 64')
+  })
+
+  it('bounds normalized errors and preserves allocated ids at the minimum result cap', async () => {
+    const { ctx, agent } = await setup(true, { maxResultBytes: 64 })
+    const failed = await call(ctx, 'terminal_open', { type: 'x'.repeat(1_000) }, agent)
+    expect(failed.isError).toBe(true)
+    expect(Buffer.byteLength(text(failed))).toBeLessThanOrEqual(64)
+    expect(text(failed)).toContain('[output truncated]')
+
+    const opened = await call(ctx, 'terminal_open', { type: 'stub', name: 'n'.repeat(1_000) }, agent)
+    expect(text(opened)).toContain('pty-1')
+    expect(Buffer.byteLength(text(opened))).toBeLessThanOrEqual(64)
+    const background = await call(ctx, 'terminal_send', {
+      sessionId: 'pty-1', text: 'work', run_in_background: true,
+    }, agent)
+    expect(text(background)).toContain('pty-send-1')
+    expect(Buffer.byteLength(text(background))).toBeLessThanOrEqual(64)
+  })
+
+  it('bounds terminal results after policy decisions and pipeline failures', async () => {
+    const { ctx, agent } = await setup(false, { maxResultBytes: 64 })
+    ctx.on('tools/pre-execute', async (exec, next) => {
+      if (exec.name === 'terminal_list') return { kind: 'deny', reason: 'd'.repeat(1_000) }
+      if (exec.name === 'terminal_signal') throw new Error(`pre failed: ${'p'.repeat(1_000)}`)
+      return next()
+    })
+    ctx.on('tools/execute', async (exec, next) => {
+      if (exec.name === 'terminal_close') throw new Error(`around failed: ${'e'.repeat(1_000)}`)
+      return next()
+    })
+    ctx.on('tools/post-execute', async (exec, _result, next) => {
+      if (exec.name === 'terminal_open') {
+        return { kind: 'accept', content: [{ type: 'text', text: 'a'.repeat(1_000) }] }
+      }
+      if (exec.name === 'terminal_read') {
+        return { kind: 'block', feedback: [{ type: 'text', text: 'b'.repeat(1_000) }] }
+      }
+      if (exec.name === 'terminal_send') throw new Error(`post failed: ${'o'.repeat(1_000)}`)
+      return next()
+    })
+
+    const denied = await call(ctx, 'terminal_list', {}, agent)
+    expect(denied.isError).toBe(true)
+    expect(Buffer.byteLength(text(denied))).toBeLessThanOrEqual(64)
+    expect(text(denied)).toContain('[output truncated]')
+
+    const replaced = await call(ctx, 'terminal_open', { type: 'stub' }, agent)
+    expect(replaced.isError).toBe(false)
+    expect(Buffer.byteLength(text(replaced))).toBeLessThanOrEqual(64)
+    expect(text(replaced)).toContain('[output truncated]')
+
+    const blocked = await call(ctx, 'terminal_read', { sessionId: 'pty-1' }, agent)
+    expect(blocked.isError).toBe(true)
+    expect(Buffer.byteLength(text(blocked))).toBeLessThanOrEqual(64)
+    expect(text(blocked)).toContain('[output truncated]')
+
+    const failures = [
+      await call(ctx, 'terminal_signal', { sessionId: 'pty-1', signal: 'SIGINT' }, agent),
+      await call(ctx, 'terminal_close', { sessionId: 'pty-1' }, agent),
+      await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'work' }, agent),
+    ]
+    for (const failure of failures) {
+      expect(failure.isError).toBe(true)
+      expect(Buffer.byteLength(text(failure))).toBeLessThanOrEqual(64)
+      expect(text(failure)).toContain('[output truncated]')
+    }
+  })
+
+  it('leaves a structured around-dispatch failure unchanged', async () => {
+    const { ctx, agent } = await setup(false, { maxResultBytes: 64 })
+    ctx.on('tools/execute', async (exec, next) => exec.name === 'terminal_list'
+      ? { content: [], isError: true, error: { message: 'structured failure' } }
+      : next())
+    const result = await call(ctx, 'terminal_list', {}, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([])
+  })
 })
 
 describe('tool-pty task integration', () => {
   it('registers a generic task and exposes incremental output', async () => {
     const { ctx, agent } = await setup(true)
     await call(ctx, 'terminal_open', { type: 'stub' }, agent)
-    expect(text(await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'build', run_in_background: true }, agent))).toBe('started background task pty-send-1')
+    const started = await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'build', run_in_background: true }, agent)
+    expect(text(started)).toBe('started background task pty-send-1')
+    expect(started).toMatchObject({ isError: false, value: { kind: 'background', taskId: 'pty-send-1' } })
     const output = await call(ctx, 'task_output', { task_id: 'pty-send-1', wait: true }, agent)
     expect(text(output)).toContain('live output')
     expect(text(output)).toContain('[status: completed, wait: stdin_read]')
   })
 
+  it('bounds foreground and background results after terminal and task metadata', async () => {
+    const { ctx, agent, stub } = await setup(true, { maxResultBytes: 64 })
+    await call(ctx, 'terminal_open', { type: 'stub' }, agent)
+    stub.sessions[0]!.viewport = '界'.repeat(100)
+    const foreground = await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'foreground' }, agent)
+    expect(Buffer.byteLength(text(foreground))).toBeLessThanOrEqual(64)
+
+    stub.sessions[0]!.delta = '界'.repeat(100)
+    stub.sessions[0]!.deltaTruncated = true
+    await call(ctx, 'terminal_send', { sessionId: 'pty-1', text: 'background', run_in_background: true }, agent)
+    const background = await call(ctx, 'task_output', { task_id: 'pty-send-1', wait: true }, agent)
+    expect(Buffer.byteLength(text(background))).toBeLessThanOrEqual(64)
+    expect(text(background)).toContain('[status: completed')
+    expect(text(background).match(/\[output truncated\]/g)).toHaveLength(1)
+    expect(text(background)).toContain('[output truncated]\n[status: completed')
+  })
+
   it('rejects pre-aborted background calls, maps task cancellation, and contains operation failure', async () => {
     const { ctx, agent, stub } = await setup(true)
     await call(ctx, 'terminal_open', { type: 'stub' }, agent)
@@ -224,7 +465,9 @@ describe('tool-pty task integration', () => {
     const second = call(ctx, 'terminal_close', { sessionId: 'pty-1' }, agent)
     stub.sessions[0]!.closeGate?.resolve(undefined)
     await first
-    expect(text(await second)).toBe('terminal session pty-1 was already closing')
+    const result = await second
+    expect(text(result)).toBe('terminal session pty-1 was already closing')
+    expect(result).toMatchObject({ isError: false, value: { sessionId: 'pty-1', outcome: 'already-closing' } })
   })
 
   it('renders an exited session detail for background completion', async () => {
diff --git a/packages/pty/tool-pty/tsconfig.json b/packages/pty/tool-pty/tsconfig.json
index 7ba9633c2c..9674519034 100644
--- a/packages/pty/tool-pty/tsconfig.json
+++ b/packages/pty/tool-pty/tsconfig.json
@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../util/retention"
+    },
     {
       "path": "../pty"
     },
diff --git a/packages/sandbox/sandbox-policy/tests/policy.spec.ts b/packages/sandbox/sandbox-policy/tests/policy.spec.ts
index cd81caa6b4..9e3eae4605 100644
--- a/packages/sandbox/sandbox-policy/tests/policy.spec.ts
+++ b/packages/sandbox/sandbox-policy/tests/policy.spec.ts
@@ -69,7 +69,7 @@ describe('SandboxPolicyService', () => {
     })
   })
 
-  it('resolves a symlink-sensitive session cwd with filesystem semantics', async () => {
+  it.skipIf(process.platform === 'win32')('resolves a symlink-sensitive session cwd with POSIX component semantics', async () => {
     const root = mkdtempSync(join(tmpdir(), 'dsh-policy-cwd-'))
     try {
       const lexical = join(root, 'lexical')
@@ -78,7 +78,7 @@ describe('SandboxPolicyService', () => {
       mkdirSync(lexical)
       mkdirSync(child, { recursive: true })
       const link = join(lexical, 'link')
-      symlinkSync(child, link, process.platform === 'win32' ? 'junction' : 'dir')
+      symlinkSync(child, link, 'dir')
       const cwd = `${link}${sep}..`
       const ctx = await mounted({ mode: 'workspace-write', workspaceRoot: '/fallback' })
 
diff --git a/packages/sandbox/sandbox/tests/roots.spec.ts b/packages/sandbox/sandbox/tests/roots.spec.ts
index fd0d2cd7bd..49fdc03816 100644
--- a/packages/sandbox/sandbox/tests/roots.spec.ts
+++ b/packages/sandbox/sandbox/tests/roots.spec.ts
@@ -14,7 +14,7 @@ import { canonicalPath, writableRoots } from '@deepseek-ai/dsh-sandbox'
 describe('canonicalPath', () => {
   it('resolves symlinks (an existing path realpaths)', () => {
     const dir = mkdtempSync(join(tmpdir(), 'dsh-roots-'))
-    expect(canonicalPath(dir)).toBe(realpathSync(dir))
+    expect(canonicalPath(dir)).toBe(realpathSync.native(dir))
   })
 
   it('returns the spelling as-is when the path cannot be resolved (conservative — matches nothing until it exists)', () => {
@@ -30,9 +30,9 @@ describe('writableRoots', () => {
   it('workspace-write grants the workspace root plus the platform temp areas, canonical and deduplicated', () => {
     const ws = mkdtempSync(join(tmpdir(), 'dsh-ws-'))
     const roots = writableRoots({ mode: 'workspace-write', workspaceRoot: ws })
-    expect(roots).toContain(realpathSync(ws))
+    expect(roots).toContain(realpathSync.native(ws))
     expect(roots).toContain(canonicalPath('/tmp'))
-    expect(roots).toContain(realpathSync(tmpdir()))
+    expect(roots).toContain(realpathSync.native(tmpdir()))
     // Deduplicated after canonicalization (/tmp and os.tmpdir() may coincide).
     expect(new Set(roots).size).toBe(roots.length)
   })
diff --git a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts b/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
index 6e0b404dc6..0fefefdffa 100644
--- a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
+++ b/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
@@ -1,7 +1,7 @@
 import { execFile } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { homedir, tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
@@ -20,6 +20,15 @@ const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
 const builtScripts = join(repoRoot, 'packages/sdk/scripts/lib/bin.js')
 const temporary: string[] = []
 
+function resolveCorepackHome(): string {
+  return process.env.COREPACK_HOME ?? join(
+    process.env.XDG_CACHE_HOME
+      ?? process.env.LOCALAPPDATA
+      ?? join(homedir(), process.platform === 'win32' ? 'AppData/Local' : '.cache'),
+    'node/corepack',
+  )
+}
+
 afterEach(async () => {
   await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
 })
@@ -71,13 +80,16 @@ describe.skipIf(!existsSync(builtScripts))('live-linked generated projects', ()
         }
       `)
       const cacheRoot = join(tmpdir(), 'dsh-sdk-link-cache', name)
+      const pnpmStore = name === 'pnpm'
+        ? (await execFileAsync(name, ['store', 'path', '--silent'], { encoding: 'utf8' })).stdout.trim()
+        : undefined
       const commandEnvironment = {
         ...scrubEnvironment(),
-        COREPACK_HOME: join(cacheRoot, 'corepack'),
-        XDG_CACHE_HOME: join(cacheRoot, 'cache'),
+        COREPACK_HOME: resolveCorepackHome(),
+        ...name === 'pnpm' ? {} : { XDG_CACHE_HOME: join(cacheRoot, 'cache') },
         XDG_DATA_HOME: join(cacheRoot, 'data'),
         npm_config_cache: join(cacheRoot, 'npm'),
-        pnpm_config_store_dir: join(cacheRoot, 'pnpm-store'),
+        ...pnpmStore === undefined ? {} : { pnpm_config_store_dir: pnpmStore },
       }
       await execFileAsync(name, manager.installCommand(), {
         cwd: root,
diff --git a/packages/session-persistence/session-checkpoint-policy/src/index.ts b/packages/session-persistence/session-checkpoint-policy/src/index.ts
index 138e45db2d..0dcd2045a9 100644
--- a/packages/session-persistence/session-checkpoint-policy/src/index.ts
+++ b/packages/session-persistence/session-checkpoint-policy/src/index.ts
@@ -42,7 +42,10 @@ function abortedBeforeDispatchResult(): ToolExecutionResult {
   return {
     content: [{ type: 'text', text: 'Error: tool call aborted before dispatch' }],
     isError: true,
-    error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    error: {
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    },
   }
 }
 
diff --git a/packages/session-persistence/session-checkpoint-policy/tests/fixtures/crash-child.ts b/packages/session-persistence/session-checkpoint-policy/tests/fixtures/crash-child.ts
index 17a9aec997..412ff8203d 100644
--- a/packages/session-persistence/session-checkpoint-policy/tests/fixtures/crash-child.ts
+++ b/packages/session-persistence/session-checkpoint-policy/tests/fixtures/crash-child.ts
@@ -45,6 +45,7 @@ ctx.tools.register({
   name: 'crash_tool',
   description: 'records an external effect and never returns',
   parameters: {},
+  output: { schema: { type: 'null' }, render: () => [] },
   async execute() {
     await writeFile(failpoint, 'tool-side-effect')
     return waitForCrash()
@@ -55,5 +56,5 @@ const handle = await ctx.agents.create({
   sessionId: SessionId('semantic-checkpoint-crash'),
   agentOptions: { provider: 'crash', model: 'crash' },
 })
-handle.agent.send([{ type: 'text', text: 'exercise the crash boundary' }])
+handle.agent.followup([{ type: 'text', text: 'exercise the crash boundary' }])
 await waitForCrash()
diff --git a/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts b/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
index 2056d30729..3cbb3b9832 100644
--- a/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
+++ b/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
@@ -19,7 +19,11 @@ class TestPersistence extends SessionPersistence {
   load(_id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     return Promise.reject(new Error('not used'))
   }
+  inspect(_id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return Promise.reject(new Error('not used'))
+  }
   list(): Promise<SessionHeader[]> { return Promise.resolve([]) }
+  listSnapshots(): Promise<never[]> { return Promise.resolve([]) }
 }
 
 class RecordingAdapter extends LlmAdapter {
@@ -121,7 +125,8 @@ describe('session-checkpoint-policy tool and step boundaries', () => {
     })
     ctx.tools.register({
       name: 'write', description: 'side effect', parameters: {},
-      execute: async () => { order.push('tool'); return [] },
+      output: { schema: { type: 'null' }, render: () => [] },
+      execute: async () => { order.push('tool'); return null },
     })
 
     const pending = ctx.tools.execute({
@@ -149,7 +154,8 @@ describe('session-checkpoint-policy tool and step boundaries', () => {
     })
     ctx.tools.register({
       name: 'write', description: 'side effect', parameters: {},
-      execute: async () => { order.push('tool'); return [] },
+      output: { schema: { type: 'null' }, render: () => [] },
+      execute: async () => { order.push('tool'); return null },
     })
 
     const pending = ctx.tools.execute({
@@ -164,7 +170,10 @@ describe('session-checkpoint-policy tool and step boundaries', () => {
     await expect(pending).resolves.toEqual({
       content: [{ type: 'text', text: 'Error: tool call aborted before dispatch' }],
       isError: true,
-      error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      error: {
+        message: 'tool call aborted before dispatch',
+        info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+      },
     })
     expect(order).toEqual(['flush:start', 'flush:end'])
   })
@@ -177,7 +186,8 @@ describe('session-checkpoint-policy tool and step boundaries', () => {
     ctx.on('session/flush', () => Promise.reject(new Error('disk unavailable')))
     ctx.tools.register({
       name: 'write', description: 'side effect', parameters: {},
-      execute: async () => { ran = true; return [] },
+      output: { schema: { type: 'null' }, render: () => [] },
+      execute: async () => { ran = true; return null },
     })
     const result = await ctx.tools.execute({
       callId: CallId('write-2'), name: 'write', arguments: {}, agent,
@@ -194,7 +204,11 @@ describe('session-checkpoint-policy tool and step boundaries', () => {
     const agent = { session } as Agent
     let flushes = 0
     ctx.on('session/flush', () => { flushes += 1 })
-    ctx.tools.register({ name: 'nested', description: 'nested', parameters: {}, execute: async () => [] })
+    ctx.tools.register({
+      name: 'nested', description: 'nested', parameters: {},
+      output: { schema: { type: 'null' }, render: () => [] },
+      execute: async () => null,
+    })
     await ctx.tools.execute({
       callId: CallId('nested-1'), name: 'nested', arguments: {}, agent,
       parent: Symbol('outer') as never,
diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session-persistence/session-persistence-jsonl/README.md
index f6fff4fa42..bf86bf8633 100644
--- a/packages/session-persistence/session-persistence-jsonl/README.md
+++ b/packages/session-persistence/session-persistence-jsonl/README.md
@@ -19,7 +19,7 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence
 
 | Key | Type | Notes |
 |---|---|---|
-| `root` | `string` (required) | Root directory for all session files. **No default** — a `process.cwd()` default would scatter files as the process's cwd changes (bash calls, subprocesses). |
+| `root` | `string` (required) | Root directory for all session files. **No default** — a `process.cwd()` default would scatter files as the process's cwd changes (bash calls, subprocesses). An existing root must be a readable directory; an absent root is created on first materialization. |
 | `packChunks` | `boolean` (default `false`) | Write delta-chunk runs as packed rows (~60% smaller logical logs measured on a real coding session). Off, the written logical layout is byte-identical to the pre-packing format; reading packed rows works regardless of this switch. Off by default while the snapshot goldens stay one-event-per-line — recording with packing on rewrites every fixture `session.jsonl`. |
 | `compression` | `'zstd' \| 'none'` | Defaults to `'zstd'`; `'none'` retains newline-delimited UTF-8 text. |
 
@@ -33,14 +33,17 @@ A root belongs to one encoding. Startup discovery and targeted lookup reject the
 
 ## Durability and crash semantics
 
+- **Bound storage identity.** Lookup requires one matching encoded filename across the cwd buckets, then verifies that the header id equals the requested id and that the header's id/cwd derive the selected path. Listing applies the same path check and rejects duplicate ids. Identity failures occur before repair or append.
 - **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s the encoded header and first batch in a temporary file. POSIX publishes it without overwrite via a hard link and `fsync`s the parent directory. Windows publishes it without overwrite via `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` and creates missing directories through the same write-through pattern. A created-but-never-appended session leaves nothing on disk and is absent from `list`.
 - **Append-only.** Flushed events are never rewritten. Subsequent raw batches append lines; compressed batches append one frame. Both paths `fsync`, and a caught write or sync failure rolls the file back to its prior byte length.
 - **Crash recovery — preserve valid tail work.** `load` validates every complete compressed frame and scans their decompressed JSONL. If the last frame is structurally incomplete, the reader keeps its complete decoded records, truncates from that frame's start, and re-encodes those records with the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md). Raw mode truncates from its first incomplete line. A checksum/decompression failure in a complete frame, or a defect at or before the last committed `turn/end`, is corruption and rejects.
+- **Non-mutating inspection.** `inspect()` returns the detached valid prefix without truncating an incomplete tail or closing an interrupted turn, and leaves the lightweight revision unchanged.
 - **Contiguous-seq.** `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type.
+- **Lightweight revisions.** `listSnapshots()` identifies a log by its device, inode, size, and nanosecond timestamps, avoiding a full-log parse while changing after append, repair, replacement, or store changes.
 
 ## Write path
 
-The plugin buffers frozen session events and drains them on flush or disposal. A per-session cursor prevents resumed sessions from re-appending stored events, and live sessions are seeded when the plugin loads. Operations for one session are serialized; disposal waits for initialization and the final drain so no write lands after teardown.
+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.
 
 ## Model Experience
 
@@ -63,5 +66,5 @@ JSONL storage does not mutate live request prefixes. A resumed loop can reuse pr
 - **Only the configured encoding and current `SESSION_FORMAT_VERSION` (v0) load** — changing compression requires a separate/fresh root or selecting the legacy raw mode; the pre-release format has no migration.
 - **Compressed files are not directly line-readable** — use the backend to load them, or select `compression: 'none'` before writing a fresh root when text fixtures or external line readers are required.
 - **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion surface).
-- **Single-process assumption** — per-session serialization and the write cursor live in this process; two processes appending to the same `root` are not coordinated.
+- **One live writer per session** — append and repair are coordinated only inside the owning backend instance. Another backend instance or process must not write the same session until that owner reaches quiescent disposal; initial same-id publication remains collision-safe through the POSIX no-overwrite hard link or Windows write-through rename without replacement.
 - **POSIX materialization requires hard-link support** — first append uses `link()` so same-id races fail instead of overwriting a committed log; Windows uses write-through rename without replacement.
diff --git a/packages/session-persistence/session-persistence-jsonl/src/format.ts b/packages/session-persistence/session-persistence-jsonl/src/format.ts
index 2a34a1ce80..48f99e6610 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/format.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/format.ts
@@ -84,6 +84,9 @@ function isHeaderLine(value: unknown): value is HeaderLine {
     && typeof (value as { version?: unknown }).version === 'number'
     && typeof (value as { id?: unknown }).id === 'string'
     && typeof (value as { createdAt?: unknown }).createdAt === 'number'
+    && Number.isSafeInteger((value as { createdAt: number }).createdAt)
+    && (value as { createdAt: number }).createdAt >= 0
+    && !Object.is((value as { createdAt: number }).createdAt, -0)
     && typeof (value as { delegationDepth?: unknown }).delegationDepth === 'number'
     && Number.isSafeInteger((value as { delegationDepth: number }).delegationDepth)
     && (value as { delegationDepth: number }).delegationDepth >= 0
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index d2822505e8..629c0e3ff1 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -8,12 +8,14 @@
 
 import { Context } from 'cordis'
 import z from 'schemastery'
-import { open, mkdir, readFile, readdir, link, rm, stat as fsStat, truncate } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
+import { readdirSync } from 'node:fs'
+import { open, mkdir, readFile, readdir, link, rm, stat, truncate } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
 import { randomBytes } from 'node:crypto'
 import {
-  SessionPersistence, PersistenceCoordinator,
-  type PersistenceBackend, type SessionLocation, type StoredPrefix,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
+  type StoredPrefix,
 } from '@deepseek-ai/dsh-session-persistence'
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
@@ -38,7 +40,9 @@ 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 per-cwd subdirectories.
+   * (bash calls, subprocesses). Sessions group under per-cwd subdirectories. An
+   * existing root must be a readable directory; an absent root is created on
+   * first materialization.
    */
   root: string
   /**
@@ -101,6 +105,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     // the cast records that runtime fact for exactOptionalPropertyTypes.
     this.packChunks = (config as Required<Config>).packChunks
     this.compression = config.compression ?? DEFAULT_COMPRESSION
+    this.assertUsableRoot()
     this.coordinator = new PersistenceCoordinator<JsonlTornMarker>(this.ctx, this)
   }
 
@@ -126,6 +131,10 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     return this.coordinator.load(id)
   }
 
+  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id)
+  }
+
   // One method serves both public `list` and the backend hook; delegating it to
   // the coordinator would call this hook recursively.
 
@@ -135,40 +144,32 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
   /** Read a stored prefix by id across all cwd buckets when cwd is unknown. */
   async loadStored(id: SessionId): Promise<StoredPrefix<JsonlTornMarker> | undefined> {
     await this.ensureRootEncoding()
-    const file = await this.findLog(id)
-    if (file === undefined) return undefined
-    return this.readPrefix(file.path)
-  }
-
-  /**
-   * Read a stored prefix within one cwd for HMR adoption. `undefined` names the
-   * no-cwd bucket rather than an unknown cwd, so this never scans other buckets.
-   */
-  async loadLive(id: SessionId, cwd: string | undefined): Promise<StoredPrefix<JsonlTornMarker> | undefined> {
-    await this.ensureRootEncoding()
-    const path = logPath(this.root, cwd, id, this.compression)
-    if (!await this.exists(path)) {
-      await this.rejectOppositeArtifact(cwd, id)
-      return undefined
-    }
-    return this.readPrefix(path)
+    const path = await this.findLog(id)
+    if (path === undefined) return undefined
+    return this.readPrefix(path, id)
   }
 
   /**
    * Read a stored prefix and convert torn-tail state to the opaque marker the
    * coordinator can round-trip without knowing the physical encoding.
    */
-  private async readPrefix(path: string): Promise<StoredPrefix<JsonlTornMarker>> {
+  private async readPrefix(path: string, expectedId?: SessionId): Promise<StoredPrefix<JsonlTornMarker>> {
     const buffer = await readFile(path)
-    if (this.compression === 'zstd') return this.readZstdPrefix(buffer)
-    const { meta, events, committedBytes } = scanLog(buffer)
-    return {
-      meta,
-      events,
-      ...committedBytes < buffer.byteLength
-        ? { tornMarker: { truncateTo: committedBytes, recoveredEvents: [] } }
-        : {},
+    let prefix: StoredPrefix<JsonlTornMarker>
+    if (this.compression === 'zstd') {
+      prefix = await this.readZstdPrefix(buffer)
+    } else {
+      const { meta, events, committedBytes } = scanLog(buffer)
+      prefix = {
+        meta,
+        events,
+        ...committedBytes < buffer.byteLength
+          ? { tornMarker: { truncateTo: committedBytes, recoveredEvents: [] } }
+          : {},
+      }
     }
+    this.assertStoredIdentity(path, prefix.meta, expectedId)
+    return prefix
   }
 
   /** Decode complete frames and retain complete JSONL records from a torn final frame. */
@@ -245,23 +246,57 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     if (repairedEvents.length > 0) await this.appendLines(meta, repairedEvents)
   }
 
-  /** List all stored sessions' metadata (header line only — no full-log parse). */
+  /** List valid unique stored sessions' metadata (header line only — no full-log parse). */
   async list(): Promise<SessionHeader[]> {
+    return (await this.listArtifacts()).map(artifact => artifact.header)
+  }
+
+  /** List metadata plus a stat-derived identity for each append-only log. */
+  async listSnapshots(): Promise<SessionPersistenceSnapshot[]> {
+    const snapshots: SessionPersistenceSnapshot[] = []
+    for (const artifact of await this.listArtifacts()) {
+      try {
+        const identity = await stat(artifact.path, { bigint: true })
+        snapshots.push({
+          header: artifact.header,
+          revision: SessionPersistenceRevision([
+            identity.dev,
+            identity.ino,
+            identity.size,
+            identity.mtimeNs,
+            identity.ctimeNs,
+          ].join(':')),
+        })
+      } catch (error: unknown) {
+        if (!isENOENT(error)) throw error
+      }
+    }
+    return snapshots
+  }
+
+  private async listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>> {
     await this.ensureRootEncoding()
-    const metas: SessionHeader[] = []
+    const artifacts: Array<{ header: SessionHeader; path: string }> = []
+    const ids = new Set<SessionId>()
     for (const dir of await this.listCwdDirs()) {
-      for (const name of await this.listArtifacts(dir)) {
+      for (const name of await this.listArtifactNames(dir)) {
+        const path = join(dir, name)
         // Read only headers so listing scales with session count, not log size.
         const first = this.compression === 'zstd'
-          ? await this.readFirstZstdLine(`${dir}/${name}`)
-          : await this.readFirstLine(`${dir}/${name}`)
+          ? await this.readFirstZstdLine(path)
+          : await this.readFirstLine(path)
         if (first === undefined) continue // empty/half-written file
         const meta = parseHeaderMeta(first)
         if (meta === undefined) continue // not a session header
-        metas.push(meta)
+        this.assertStoredIdentity(path, meta)
+        if (ids.has(meta.id)) {
+          throw new Error(`duplicate JSONL session id "${meta.id}" appears in multiple cwd buckets`)
+        }
+        ids.add(meta.id)
+        artifacts.push({ header: meta, path })
       }
     }
-    return metas
+    return artifacts
   }
 
   // --- materialization / append / repair (file mechanics) ---
@@ -506,30 +541,54 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     }
   }
 
-  /**
-   * Find a session by id across cwd buckets for resume. Cwd-scoped HMR adoption
-   * bypasses this scan so a no-cwd session cannot claim another bucket.
-   */
-  private async findLog(id: SessionId): Promise<{ path: string; cwd: string | undefined } | undefined> {
+  /** Find the unique physical log for an id across every cwd bucket. */
+  private async findLog(id: SessionId): Promise<string | undefined> {
     const target = encodeSegment(id) + logSuffix(this.compression)
+    const oppositeTarget = encodeSegment(id) + logSuffix(this.oppositeCompression())
+    const matches: string[] = []
     for (const dir of await this.listCwdDirs()) {
-      const path = `${dir}/${target}`
-      const opposite = `${dir}/${encodeSegment(id)}${logSuffix(this.oppositeCompression())}`
+      const path = join(dir, target)
+      const opposite = join(dir, oppositeTarget)
       if (await this.exists(opposite)) throw this.encodingMismatch(opposite)
-      if (await this.exists(path)) {
-        // Recover the cwd from the header so the caller has the session's bucket.
-        const { meta } = await this.readPrefix(path)
-        return { path, cwd: meta.cwd }
-      }
+      if (await this.exists(path)) matches.push(path)
+    }
+    if (matches.length > 1) {
+      throw new Error(`duplicate JSONL session id "${id}" appears in multiple cwd buckets`)
+    }
+    return matches[0]
+  }
+
+  /** Require an existing configured root to be a readable directory. */
+  private assertUsableRoot(): void {
+    try {
+      readdirSync(this.root)
+    } catch (error) {
+      if (isENOENT(error)) return
+      throw error
+    }
+  }
+
+  /** Reject metadata that does not identify the selected physical log. */
+  private assertStoredIdentity(path: string, meta: SessionHeader, expectedId?: SessionId): void {
+    if (expectedId !== undefined && meta.id !== expectedId) {
+      throw new Error(`corrupt session log "${path}": requested id "${expectedId}" does not match header id "${meta.id}"`)
+    }
+    let expectedPath: string
+    try {
+      expectedPath = logPath(this.root, meta.cwd, meta.id, this.compression)
+    } catch (error) {
+      throw new Error(`corrupt session log "${path}": header id cannot name a storage path`, { cause: error })
+    }
+    if (path !== expectedPath) {
+      throw new Error(`corrupt session log "${path}": header id "${meta.id}" and cwd belong at "${expectedPath}"`)
     }
-    return undefined
   }
 
   /** The cwd-bucket directories under the root (absolute paths). */
   private async listCwdDirs(): Promise<string[]> {
     try {
       const entries = await readdir(this.root, { withFileTypes: true })
-      return entries.filter(e => e.isDirectory()).map(e => `${this.root}/${e.name}`)
+      return entries.filter(e => e.isDirectory()).map(e => join(this.root, e.name))
     } catch (error) {
       // Only an absent root means no sessions; rethrow every other I/O failure.
       if (isENOENT(error)) return []
@@ -537,7 +596,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     }
   }
 
-  private async listArtifacts(dir: string): Promise<string[]> {
+  private async listArtifactNames(dir: string): Promise<string[]> {
     const entries = await readdir(dir)
     const oppositeSuffix = logSuffix(this.oppositeCompression())
     const incompatible = entries.find(name => name.endsWith(oppositeSuffix))
@@ -602,7 +661,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
   private async assertLogParentAllowsAbsence(path: string): Promise<void> {
     try {
       const parent = dirname(path)
-      const info = await fsStat(parent)
+      const info = await stat(parent)
       if (info.isDirectory()) return
       const error = new Error(`ENOTDIR: parent path exists but is not a directory: ${parent}`) as NodeJS.ErrnoException
       error.code = 'ENOTDIR'
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 545d45acb2..68bd359b39 100644
--- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -20,6 +20,15 @@ function mutableHeader(header: SessionHeader): MutableSessionHeader {
   return header
 }
 
+/** Rewrite only a stored header while preserving every event byte below it. */
+async function rewriteHeader(path: string, update: (header: Record<string, unknown>) => void): Promise<void> {
+  const lines = (await readFile(path, 'utf8')).split('\n')
+  const header = JSON.parse(lines[0] as string) as Record<string, unknown>
+  update(header)
+  lines[0] = JSON.stringify(header)
+  await writeFile(path, lines.join('\n'))
+}
+
 async function expectFlushError(promise: Promise<unknown>, message: RegExp): Promise<void> {
   try {
     await promise
@@ -200,6 +209,60 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     expect(loaded.events).toEqual(log) // chunks preserved, contiguous seqs
   })
 
+  it('source-qualifies revisions across roots while preserving same-log reopen identity', async () => {
+    const m = meta('revision-source')
+    await ctx.sessionPersistence.create(m)
+    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const revision = (await ctx.sessionPersistence.listSnapshots())[0]?.revision
+
+    const reopenedCtx = new Context()
+    await reopenedCtx.plugin(SessionStore)
+    await reopenedCtx.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
+    expect((await reopenedCtx.sessionPersistence.listSnapshots())[0]?.revision).toBe(revision)
+
+    const otherRoot = await freshRoot()
+    const otherCtx = new Context()
+    await otherCtx.plugin(SessionStore)
+    await otherCtx.plugin(SessionPersistenceJsonl, { root: otherRoot, compression: 'none' })
+    await otherCtx.sessionPersistence.create(m)
+    await otherCtx.sessionPersistence.append(m.id, oneTurnLog())
+    expect((await otherCtx.sessionPersistence.listSnapshots())[0]?.revision).not.toBe(revision)
+
+    await reopenedCtx.fiber.dispose()
+    await otherCtx.fiber.dispose()
+  })
+
+  it('omits a snapshot artifact removed after discovery', async () => {
+    const m = meta('vanishing-snapshot')
+    await ctx.sessionPersistence.create(m)
+    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const persistence = ctx.sessionPersistence as unknown as {
+      listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>>
+    }
+    const listArtifacts = persistence.listArtifacts.bind(persistence)
+    const discovery = vi.spyOn(persistence, 'listArtifacts').mockImplementation(async () => {
+      const artifacts = await listArtifacts()
+      await rm(artifacts[0]!.path)
+      return artifacts
+    })
+
+    await expect(ctx.sessionPersistence.listSnapshots()).resolves.toEqual([])
+    discovery.mockRestore()
+  })
+
+  it('surfaces non-ENOENT snapshot stat failures after discovery', async () => {
+    const persistence = ctx.sessionPersistence as unknown as {
+      listArtifacts(): Promise<Array<{ header: SessionHeader; path: string }>>
+    }
+    const discovery = vi.spyOn(persistence, 'listArtifacts').mockResolvedValue([{
+      header: meta('snapshot-stat-failure'),
+      path: `${root}\0snapshot-stat-failure`,
+    }])
+
+    await expect(ctx.sessionPersistence.listSnapshots()).rejects.toThrow(/null bytes/)
+    discovery.mockRestore()
+  })
+
   it('rejects a stored v0 log containing a legacy request/header-delta event', async () => {
     const m = meta('legacy-header-delta', '/legacy')
     const path = rawLogPath(root, m.cwd, m.id)
@@ -399,6 +462,31 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
   })
 
+  it('rejects a mismatched header before repairing either session log', async () => {
+    const a = meta('identity-a', '/same')
+    const b = meta('identity-b', '/same')
+    await ctx.sessionPersistence.create(a)
+    await ctx.sessionPersistence.append(a.id, [{
+      type: 'turn/start',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+    }])
+    await ctx.sessionPersistence.create(b)
+    await ctx.sessionPersistence.append(b.id, oneTurnLog())
+
+    const aPath = rawLogPath(root, a.cwd, a.id)
+    const bPath = rawLogPath(root, b.cwd, b.id)
+    await rewriteHeader(aPath, (header) => { header.id = b.id })
+    const beforeA = await readFile(aPath)
+    const beforeB = await readFile(bPath)
+
+    await expect(ctx.sessionPersistence.load(a.id))
+      .rejects.toThrow(/requested id "identity-a" does not match header id "identity-b"/)
+    expect(await readFile(aPath)).toEqual(beforeA)
+    expect(await readFile(bPath)).toEqual(beforeB)
+  })
+
   it('rejects a re-append of an already-stored seq', async () => {
     const m = meta('reappend')
     await ctx.sessionPersistence.create(m)
@@ -469,6 +557,26 @@ describe('SessionPersistenceJsonl: scanLog unit', () => {
     expect(() => scanLog(Buffer.from('{"type":"event"}\n'))).toThrow(/session header/)
   })
 
+  it.each([
+    ['fractional', 1.5],
+    ['negative', -1],
+    ['unsafe', Number.MAX_SAFE_INTEGER + 1],
+  ])('rejects a session header with a %s createdAt', (_label, createdAt) => {
+    const log = JSON.stringify({
+      type: 'session',
+      version: 0,
+      id: 'invalid-created-at',
+      createdAt,
+      delegationDepth: 0,
+    }) + '\n'
+    expect(() => scanLog(Buffer.from(log))).toThrow(/session header/)
+  })
+
+  it('rejects a session header with negative-zero createdAt', () => {
+    const log = '{"type":"session","version":0,"id":"invalid-created-at","createdAt":-0,"delegationDepth":0}\n'
+    expect(() => scanLog(Buffer.from(log))).toThrow(/session header/)
+  })
+
   it.each([
     ['missing', undefined],
     ['a string', '1'],
@@ -743,6 +851,38 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     expect(ids).toContain('big')
   })
 
+  it('list rejects a header whose cwd does not identify its physical log', async () => {
+    const m = meta('misplaced', '/stored')
+    await ctx.sessionPersistence.create(m)
+    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    await rewriteHeader(rawLogPath(root, m.cwd, m.id), (header) => { header.cwd = '/elsewhere' })
+
+    await expect(ctx.sessionPersistence.list()).rejects.toThrow(/and cwd belong at/)
+  })
+
+  it('list rejects a session header whose id cannot name a storage path', async () => {
+    const bucket = sessionDir(root, undefined)
+    await mkdir(bucket, { recursive: true })
+    await writeFile(join(bucket, 'invalid-id.jsonl'), JSON.stringify({
+      type: 'session', version: 0, id: '', createdAt: 1, delegationDepth: 0,
+    }) + '\n')
+
+    await expect(ctx.sessionPersistence.list()).rejects.toThrow(/header id cannot name a storage path/)
+  })
+
+  it('load and list reject one id materialized in multiple cwd buckets', async () => {
+    const id = SessionId('duplicate')
+    for (const cwd of ['/a', '/b']) {
+      const m = meta(id, cwd)
+      await mkdir(sessionDir(root, cwd), { recursive: true })
+      const content = [JSON.stringify(toHeaderLine(m)), ...oneTurnLog().map(event => JSON.stringify(event))].join('\n') + '\n'
+      await writeFile(rawLogPath(root, cwd, id), content)
+    }
+
+    await expect(ctx.sessionPersistence.load(id)).rejects.toThrow(/appears in multiple cwd buckets/)
+    await expect(ctx.sessionPersistence.list()).rejects.toThrow(/appears in multiple cwd buckets/)
+  })
+
   it('a DIFFERENT live session object reusing a disposed id gets its own init (no stale cache)', async () => {
     // Session A materializes a log under id "reuse".
     const sessFiberA = await ctx.plugin(Object.assign((inner: Context) => {
@@ -763,18 +903,16 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     await expect(ctx.sessions.flush(b)).rejects.toThrow(/already bound to a different live session|already has a persisted log on disk/)
   })
 
-  it('a NO-CWD live session does NOT cross-cwd-adopt a same-id log from a real cwd bucket (loadLive is scope-exact)', async () => {
+  it('a no-cwd live session cannot adopt a same-id log from another cwd', async () => {
     // Backend 1: materialize a log under id "x" in the cwd "/w" bucket, then
     // dispose the WHOLE backend (so backend 2 mounts with an EMPTY states map —
-    // the HMR/reload path where onCreated goes through loadLive, not a tracked
-    // collision).
+    // the HMR/reload path with no tracked collision state).
     await ctx.sessionPersistence.create(meta('x', '/w'))
     await ctx.sessionPersistence.append(SessionId('x'), oneTurnLog())
     await ctx.fiber.dispose()
 
-    // Backend 2 creates a no-cwd session whose id exists only in `/w`. Exact `loadLive(id,
-    // undefined)` must not adopt across buckets; the any-cwd collision check then rejects instead
-    // of grafting no-cwd events onto a log with mismatched cwd.
+    // Backend 2 creates a no-cwd session whose id exists only in `/w`. The
+    // stored cwd check rejects instead of grafting no-cwd events onto that log.
     const ctx2 = new Context()
     await ctx2.plugin(SessionStore)
     await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
@@ -782,7 +920,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     await ctx2.plugin(Object.assign((inner: Context) => {
       b = inner.sessions.create(SessionId('x')) // no cwd
     }, { inject: ['sessions'] }))
-    await expect(ctx2.sessions.flush(b)).rejects.toThrow(/already has a persisted log on disk/)
+    await expect(ctx2.sessions.flush(b)).rejects.toThrow(/different cwd|id collision/)
 
     // The "/w" log is untouched — no no-cwd events were grafted onto it, and no
     // `_no-cwd` log for "x" was created.
@@ -841,21 +979,31 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     await ctx2.fiber.dispose()
   })
 
-  it('list surfaces a non-ENOENT root error (ENOTDIR) instead of reporting no sessions', async () => {
-    // A durable backend must not collapse a storage fault to "no sessions". Making the root a
-    // regular file forces ENOTDIR from `readdir`, which must propagate.
+  it('plugin load rejects an existing root that is not a directory', async () => {
     const filePath = join(root, 'not-a-dir')
     await writeFile(filePath, 'x')
     const ctx2 = new Context()
     await ctx2.plugin(SessionStore)
-    await ctx2.plugin(SessionPersistenceJsonl, { root: filePath, compression: 'none' })
-    await expect(ctx2.sessionPersistence.list()).rejects.toThrow(/ENOTDIR/)
+    await expect(ctx2.plugin(SessionPersistenceJsonl, { root: filePath, compression: 'none' })).rejects.toThrow(/ENOTDIR/)
     await ctx2.fiber.dispose()
   })
 
-  it('loadLive surfaces a non-ENOENT lookup error (ENOTDIR) instead of reporting absent', async () => {
-    // A non-ENOENT per-id open error must surface rather than become "not found" and permit false
-    // live adoption. Making the cwd bucket a regular file forces ENOTDIR for its child log path.
+  it('list surfaces a root that becomes unusable after plugin load', async () => {
+    await rm(root, { recursive: true })
+    await writeFile(root, 'not a directory')
+
+    await expect(ctx.sessionPersistence.list()).rejects.toThrow(/ENOTDIR/)
+  })
+
+  it('per-id lookup surfaces non-ENOENT storage errors', async () => {
+    const blocker = join(root, 'not-a-directory')
+    await writeFile(blocker, 'x')
+    const backend = ctx.sessionPersistence as unknown as { exists(path: string): Promise<boolean> }
+
+    await expect(backend.exists(join(blocker, 'child.jsonl'))).rejects.toThrow(/ENOTDIR/)
+  })
+
+  it('materialization surfaces a cwd-bucket storage fault', async () => {
     const cwd = '/x'
     const ctx2 = new Context()
     await ctx2.plugin(SessionStore)
@@ -864,8 +1012,9 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     let s!: Session
     await ctx2.plugin(Object.assign((inner: Context) => {
       s = inner.sessions.create(SessionId('exists-fault'), { meta: { cwd } })
+      appendClosedTurn(s)
     }, { inject: ['sessions'] }))
-    await expect(ctx2.sessions.flush(s)).rejects.toThrow(/ENOTDIR/)
+    await expect(ctx2.sessions.flush(s)).rejects.toThrow(/EEXIST|ENOTDIR/)
     await ctx2.fiber.dispose()
   })
 
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
index 34415063e6..fcadac1f04 100644
--- a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
@@ -460,7 +460,7 @@ describe('SessionPersistenceJsonl: encoding selection', () => {
       '',
     ].join('\n'))
     await expect(ctx.sessionPersistence.load(loadHeader.id)).rejects.toThrow(/uses \.jsonl/)
-    await expect((ctx.sessionPersistence as SessionPersistenceJsonl).loadLive(loadHeader.id, loadHeader.cwd))
+    await expect((ctx.sessionPersistence as SessionPersistenceJsonl).loadStored(loadHeader.id))
       .rejects.toThrow(/uses \.jsonl/)
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/uses \.jsonl/)
   })
diff --git a/packages/session-persistence/session-persistence-sqlite/README.md b/packages/session-persistence/session-persistence-sqlite/README.md
index 39619ff60a..011926d4b9 100644
--- a/packages/session-persistence/session-persistence-sqlite/README.md
+++ b/packages/session-persistence/session-persistence-sqlite/README.md
@@ -8,9 +8,9 @@ A SQLite durable session-persistence backend — a second `SessionPersistence` i
 
 ## 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`) lives in a `sessions` row. 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), so no separate column is needed.
+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).
 
-The repository's Node range supports unflagged `node:sqlite`. The database enables foreign keys and uses the configured journal mode (`wal` by default; use a rollback mode where WAL shared-memory files are unsuitable). `PRAGMA user_version` stores the table-layout version; databases with any other version are rejected because this unreleased format has no migrations.
+The repository's Node range supports unflagged `node:sqlite`. The database enables foreign keys and uses the configured journal mode (`wal` by default; use a rollback mode where WAL shared-memory files are unsuitable). `PRAGMA application_id` identifies the canonical persistence database, and `PRAGMA user_version` stores its layout version. A fresh database must have no application identity or user-defined schema objects; initialization creates every table and stamps both pragmas in one transaction. Non-pristine unversioned databases, foreign application identities, and every non-current version reject before journal-mode mutation because this unreleased format has no migrations.
 
 On filesystems with POSIX modes, the backend requests mode `0700` for missing directories and exclusively creates a missing database with mode `0600` before SQLite opens it; the process umask may further restrict both. New WAL, shared-memory, and persistent rollback-journal sidecars receive the database's resulting owner-only mode. Existing directories, database files, and sidecars keep their modes; filesystem setup errors other than an existing database fail initialization. These defaults prevent incidental exposure through a permissive process umask, but do not protect database confidentiality or integrity when another principal can replace the database entry in its parent directory.
 
@@ -19,6 +19,8 @@ On filesystems with POSIX modes, the backend requests mode `0700` for missing di
 - **Append = a transaction.** `append` runs `BEGIN`/`COMMIT` around the batch: it materializes the `sessions` row (if still lazy) and INSERTs every event, asserting the contiguous-seq contract first (the first event's `seq` must equal the stored next-seq). A mid-batch failure (a UNIQUE violation on a duplicated seq) rolls back entirely, so the stored log and the in-memory cursor stay consistent. (`load()` already balanced the stored log, so `append` never has to repair a crash tail.)
 - **Lazy materialization.** `create()` records intent in memory only — no row is written until the first `append`. A created-but-never-appended session has no `sessions` row, so it is absent from `list()` (which reports exactly the sessions that have a row).
 - **Interrupted-turn close on load.** `load()` implements the shared [crash-recovery contract](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md): preserve the valid interrupted turn, append its synthetic closing events in one transaction, and remove only a torn tail row. Committed parse errors or sequence gaps make the session unloadable. Because recovery mutates stored rows, the next append starts from a balanced log and accurate cursor.
+- **Non-mutating inspection.** `inspect()` returns the detached valid row prefix without deleting a torn tail row or appending recovery closers, and leaves the lightweight revision unchanged.
+- **Lightweight revisions.** `listSnapshots()` combines the immutable store and database-file identity, a per-materialization incarnation id, and a per-session counter incremented in each mutating transaction. This keeps unchanged observations stable without parsing event rows and distinguishes independent stores and recreated same-id logs.
 
 ## Configuration (schemastery)
 
@@ -31,7 +33,7 @@ interface Config {
 
 ## Write path
 
-Like the JSONL backend, the plugin also installs the `session/event` → buffer → `session/flush` drain: it copies each already-frozen event into a persistence-owned buffer, persists a fork's seed once on `session/created`, keeps a per-session write cursor so a resumed session never re-appends stored events, and seeds existing live sessions on apply (HMR does not replay `session/created`). Dispose awaits every in-flight init + final drain and then closes the database, so no write lands after teardown.
+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.
 
 ## Model Experience
 
@@ -53,5 +55,5 @@ SQLite storage does not mutate live request prefixes. A resumed loop can reuse p
 
 - **`DatabaseSync` is synchronous** — every append transaction blocks the event loop for its duration; acceptable for local stores, a throughput ceiling for busy multi-session servers.
 - **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 the current `SCHEMA_VERSION` opens** — a database with any other schema version is rejected rather than migrated (unreleased software; no persisted user data to preserve).
+- **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).
diff --git a/packages/session-persistence/session-persistence-sqlite/src/index.ts b/packages/session-persistence/session-persistence-sqlite/src/index.ts
index edba26d9ae..5804c18282 100644
--- a/packages/session-persistence/session-persistence-sqlite/src/index.ts
+++ b/packages/session-persistence/session-persistence-sqlite/src/index.ts
@@ -8,12 +8,15 @@
 
 import { Context } from 'cordis'
 import z from 'schemastery'
+import { randomUUID } from 'node:crypto'
+import { statSync } from 'node:fs'
 import { DatabaseSync } from 'node:sqlite'
 import { mkdir, open } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import {
-  SessionPersistence, PersistenceCoordinator,
-  type PersistenceBackend, type SessionLocation, type StoredPrefix,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
+  type StoredPrefix,
 } from '@deepseek-ai/dsh-session-persistence'
 import type { SessionEvent, SurfaceEventType, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
@@ -93,6 +96,7 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
   override readonly name = 'session-persistence-sqlite'
 
   private db!: DatabaseSync
+  private storeIdentity!: string
   private ready: Promise<void>
   private coordinator: PersistenceCoordinator<number>
 
@@ -105,13 +109,32 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
   }
 
   private async openDb(path: string, journalMode: JournalMode): Promise<void> {
-    if (path !== ':memory:') {
-      const abs = resolve(path)
-      await mkdir(dirname(abs), { recursive: true, mode: 0o700 })
-      await createDatabaseFile(abs)
-      this.db = openDatabase(abs, journalMode)
-    } else {
-      this.db = openDatabase(path, journalMode)
+    const actual = path === ':memory:' ? path : resolve(path)
+    if (actual !== ':memory:') {
+      await mkdir(dirname(actual), { recursive: true, mode: 0o700 })
+      await createDatabaseFile(actual)
+    }
+    this.db = openDatabase(actual, journalMode)
+    try {
+      const row = this.db.prepare(
+        'SELECT store_id FROM persistence_state WHERE singleton = 1',
+      ).get() as { store_id: string } | undefined
+      /* v8 ignore next -- openDatabase inserts the singleton before returning. */
+      if (row === undefined) {
+        throw new Error(`session database at "${actual}" has no store identity`)
+      }
+      if (row.store_id.length === 0) {
+        throw new Error(`session database at "${actual}" has no valid store identity`)
+      }
+      if (actual !== ':memory:') {
+        const identity = statSync(actual, { bigint: true })
+        this.storeIdentity = `file:${identity.dev}:${identity.ino}:${identity.birthtimeNs}:store:${row.store_id}`
+      } else {
+        this.storeIdentity = `memory:store:${row.store_id}`
+      }
+    } catch (error: unknown) {
+      this.db.close()
+      throw error
     }
   }
 
@@ -134,6 +157,10 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     return this.coordinator.load(id)
   }
 
+  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id)
+  }
+
   // One method serves both public `list` and the backend hook; delegating it to
   // the coordinator would call this hook recursively.
 
@@ -144,11 +171,6 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     return this.readPrefix(id)
   }
 
-  /** Read a stored prefix; `cwd` is ignored (the id is globally unique in SQLite). */
-  loadLive(id: SessionId, _cwd: string | undefined): Promise<StoredPrefix<number> | undefined> {
-    return this.readPrefix(id)
-  }
-
   /**
    * Read a session's row + ordered events into a {@link StoredPrefix}. The
    * torn-tail marker is the seq from which a never-committed tail must be deleted
@@ -184,6 +206,7 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
         const [surfaceSeqs, surfaceOp] = surfaceBindings(event)
         insertEvent.run(meta.id, event.seq, event.type, event.time, JSON.stringify(event.data), surfaceSeqs, surfaceOp)
       }
+      this.db.prepare('UPDATE sessions SET revision = revision + 1 WHERE id = ?').run(meta.id)
       this.db.exec('COMMIT')
     } catch (error) {
       this.db.exec('ROLLBACK')
@@ -212,6 +235,9 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
           insertEvent.run(meta.id, event.seq, event.type, event.time, JSON.stringify(event.data), surfaceSeqs, surfaceOp)
         }
       }
+      if (tornMarker !== undefined || closers.length > 0) {
+        this.db.prepare('UPDATE sessions SET revision = revision + 1 WHERE id = ?').run(meta.id)
+      }
       this.db.exec('COMMIT')
     } catch (error) {
       // The DELETE+INSERT cannot collide (a row at a closer's seq is preserved or
@@ -233,6 +259,18 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     return rows.map(rowToMeta)
   }
 
+  /** List metadata with a source-qualified monotonic revision per session. */
+  async listSnapshots(): Promise<SessionPersistenceSnapshot[]> {
+    await this.ready
+    const rows = this.db.prepare('SELECT * FROM sessions').all() as unknown as SessionRow[]
+    return rows.map(row => ({
+      header: rowToMeta(row),
+      revision: SessionPersistenceRevision(
+        `${this.storeIdentity}:incarnation:${row.incarnation}:revision:${row.revision}`,
+      ),
+    }))
+  }
+
   /** Close the database handle (awaited by the coordinator's dispose, post-drain). */
   async close(): Promise<void> {
     await this.ready
@@ -253,8 +291,9 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
    */
   private writeRow(meta: SessionHeader): void {
     this.db.prepare(`
-      INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length, delegation_depth)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO sessions
+        (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, incarnation, revision)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)
       ON CONFLICT(id) DO UPDATE SET
         version = excluded.version,
         created_at = excluded.created_at,
@@ -270,6 +309,7 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
       meta.parentSession ?? null,
       meta.seedLength ?? null,
       meta.delegationDepth ?? null,
+      randomUUID(),
     )
   }
 }
diff --git a/packages/session-persistence/session-persistence-sqlite/src/schema.ts b/packages/session-persistence/session-persistence-sqlite/src/schema.ts
index da29c73b5d..754d9d7e63 100644
--- a/packages/session-persistence/session-persistence-sqlite/src/schema.ts
+++ b/packages/session-persistence/session-persistence-sqlite/src/schema.ts
@@ -1,12 +1,14 @@
 /**
  * Schema + load-time helpers for the SQLite session-persistence backend: the
- * DDL (a `sessions` metadata table and a 1:1 `events` row per `SessionEvent`),
- * the database open/configure step, and the last-`turn/end` cut that gives the
- * SQLite backend the SAME crash-tail-on-load semantics as the JSONL backend.
+ * DDL (a store-identity row, `sessions` metadata, and a 1:1 `events` row per
+ * `SessionEvent`), the database open/configure step, and the last-`turn/end`
+ * cut that gives the SQLite backend the SAME crash-tail-on-load semantics as
+ * the JSONL backend.
  *
  * @module dsh-session-persistence-sqlite/schema
  */
 
+import { randomUUID } from 'node:crypto'
 import { DatabaseSync } from 'node:sqlite'
 import type { SessionEvent, SessionId, SessionHeader, SurfaceOp } from '@deepseek-ai/dsh-session'
 
@@ -15,7 +17,10 @@ import type { SessionEvent, SessionId, SessionHeader, SurfaceOp } from '@deepsee
  * layout; orthogonal to a session's own `version` (which versions the EVENT
  * vocabulary, stored per session in the `sessions` row).
  */
-export const SCHEMA_VERSION = 5
+export const SCHEMA_VERSION = 10
+
+/** SQLite application id protecting unrelated databases from persistence writes. */
+export const SESSION_PERSISTENCE_SQLITE_APPLICATION_ID = 0x44534850
 
 /**
  * A row of the `sessions` table — the out-of-log metadata ({@link SessionHeader}).
@@ -31,6 +36,10 @@ export interface SessionRow {
   cwd: string | null
   parent_session: string | null
   seed_length: number | null
+  /** Stable identity assigned when this log is materialized. */
+  incarnation: string
+  /** Monotonic log-change token incremented in each mutating transaction. */
+  revision: number
   delegation_depth: number | null
 }
 
@@ -57,52 +66,102 @@ export interface EventRow {
 export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 
 /**
- * Open the database and apply its schema and pragmas. A zero `user_version` is
- * stamped with {@link SCHEMA_VERSION}; every other non-current version rejects
- * rather than being migrated in place.
+ * Open the database and apply its schema and pragmas. An empty database with a
+ * zero `user_version` is initialized at {@link SCHEMA_VERSION}; a nonempty
+ * unversioned database and every other non-current version reject rather than
+ * being migrated in place.
  * @param path - the SQLite database file to open (created when absent).
  * @param journalMode - validated journal pragma.
- * @returns the open handle with pragmas applied and both tables ensured.
+ * @returns the open handle with pragmas applied and all three tables ensured.
  */
 export function openDatabase(path: string, journalMode: JournalMode): DatabaseSync {
   const db = new DatabaseSync(path)
-  db.exec('PRAGMA foreign_keys = ON')
-  // The validated union is safe to interpolate into a non-bindable PRAGMA.
-  db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
-  // `PRAGMA user_version` always returns exactly one row { user_version }.
-  const { user_version: onDisk } = db.prepare('PRAGMA user_version').get() as { user_version: number }
-  if (onDisk !== 0 && onDisk !== SCHEMA_VERSION) {
+  try {
+    configureDatabase(db, path, journalMode)
+    return db
+  } catch (error: unknown) {
     db.close()
-    throw new Error(`session database at "${path}" has schema version ${onDisk}, incompatible with this build (${SCHEMA_VERSION})`)
+    throw error
   }
-  if (onDisk === 0) {
-    // Stamp fresh or pre-versioning databases.
-    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
+}
+
+function configureDatabase(db: DatabaseSync, path: string, journalMode: JournalMode): void {
+  db.exec('PRAGMA foreign_keys = ON')
+  let began = false
+  try {
+    db.exec('BEGIN IMMEDIATE')
+    began = true
+    // Validate while holding the write lock so no other connection can change
+    // schema ownership between inspection and initialization.
+    const { user_version: onDisk } = db.prepare('PRAGMA user_version').get() as { user_version: number }
+    const { application_id: applicationId } = db.prepare('PRAGMA application_id').get() as { application_id: number }
+    const { count: userObjectCount } = db.prepare(
+      "SELECT COUNT(*) AS count FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*'",
+    ).get() as { count: number }
+    if (onDisk === 0 && (applicationId !== 0 || userObjectCount > 0)) {
+      throw new Error(`session database at "${path}" has an unversioned schema or application identity`)
+    }
+    if (onDisk !== 0 && onDisk !== SCHEMA_VERSION) {
+      throw new Error(`session database at "${path}" has schema version ${onDisk}, incompatible with this build (${SCHEMA_VERSION})`)
+    }
+    if (onDisk === SCHEMA_VERSION && applicationId !== SESSION_PERSISTENCE_SQLITE_APPLICATION_ID) {
+      throw new Error(
+        `session database at "${path}" has application id ${applicationId}, expected ${SESSION_PERSISTENCE_SQLITE_APPLICATION_ID}`,
+      )
+    }
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS persistence_state (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        store_id  TEXT NOT NULL
+      ) STRICT;
+
+      CREATE TABLE IF NOT EXISTS sessions (
+        id               TEXT PRIMARY KEY,
+        version          INTEGER NOT NULL,
+        created_at       INTEGER NOT NULL,
+        cwd              TEXT,
+        parent_session   TEXT,
+        seed_length      INTEGER,
+        delegation_depth INTEGER,
+        incarnation      TEXT NOT NULL,
+        revision         INTEGER NOT NULL
+      ) STRICT;
+
+      CREATE TABLE IF NOT EXISTS events (
+        session_id        TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        seq               INTEGER NOT NULL,
+        type              TEXT NOT NULL,
+        time              INTEGER NOT NULL,
+        data              TEXT NOT NULL,
+        source_event_seqs TEXT,
+        surface_op        TEXT,
+        PRIMARY KEY (session_id, seq)
+      ) STRICT
+    `)
+    db.prepare(
+      'INSERT OR IGNORE INTO persistence_state (singleton, store_id) VALUES (1, ?)',
+    ).run(randomUUID())
+    if (onDisk === 0) {
+      db.exec(`PRAGMA application_id = ${SESSION_PERSISTENCE_SQLITE_APPLICATION_ID}`)
+      db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
+    }
+    db.exec('COMMIT')
+    began = false
+  } catch (error: unknown) {
+    /* v8 ignore next -- a BEGIN failure leaves no transaction to roll back. */
+    if (began) {
+      /* v8 ignore next 5 -- preserve the original schema failure if SQLite also refuses rollback. */
+      try {
+        db.exec('ROLLBACK')
+      } catch {
+        // The original SQLite failure remains the actionable cause.
+      }
+    }
+    throw error
   }
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS sessions (
-      id             TEXT PRIMARY KEY,
-      version        INTEGER NOT NULL,
-      created_at     INTEGER NOT NULL,
-      cwd              TEXT,
-      parent_session   TEXT,
-      seed_length      INTEGER,
-      delegation_depth INTEGER
-    ) STRICT
-  `)
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS events (
-      session_id        TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-      seq               INTEGER NOT NULL,
-      type              TEXT NOT NULL,
-      time              INTEGER NOT NULL,
-      data              TEXT NOT NULL,
-      source_event_seqs TEXT,
-      surface_op        TEXT,
-      PRIMARY KEY (session_id, seq)
-    ) STRICT
-  `)
-  return db
+  // The validated union is safe to interpolate into a non-bindable PRAGMA.
+  // Apply it only after ownership validation and initialization commit.
+  db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
 }
 
 /**
@@ -111,6 +170,9 @@ export function openDatabase(path: string, journalMode: JournalMode): DatabaseSy
  * @returns the header, `NULL` columns mapped to omitted optional fields.
  */
 export function rowToMeta(row: SessionRow): SessionHeader {
+  if (!Number.isSafeInteger(row.created_at) || row.created_at < 0) {
+    throw new Error('stored session createdAt must be a non-negative safe integer')
+  }
   return {
     version: row.version,
     id: row.id as SessionId,
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 ee961b030f..8a47c7917f 100644
--- a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
+++ b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
@@ -1,13 +1,21 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { existsSync } from 'node:fs'
-import { chmod, mkdtemp, rm, stat, writeFile } from 'node:fs/promises'
+import { chmod, mkdtemp, rm, stat, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SurfaceEvent, SurfaceEventType } from '@deepseek-ai/dsh-session'
 import SessionPersistenceSqlite, { SCHEMA_VERSION } from '@deepseek-ai/dsh-session-persistence-sqlite'
-import { openDatabase, rowToEvent, scanRows, type EventRow } from '../src/schema.ts'
+import {
+  openDatabase,
+  rowToEvent,
+  rowToMeta,
+  scanRows,
+  SESSION_PERSISTENCE_SQLITE_APPLICATION_ID,
+  type EventRow,
+} from '../src/schema.ts'
 import { runPersistenceContract, meta, oneTurnLog, appendLog } from '../../session-persistence/tests/contract.ts'
 import { runCoordinatorContract, type CoordinatorFixture } from '../../session-persistence/tests/coordinator-contract.ts'
 
@@ -150,13 +158,29 @@ describe('scanRows', () => {
   })
 })
 
+describe('rowToMeta', () => {
+  it('rejects fractional stored creation metadata', () => {
+    expect(() => rowToMeta({
+      id: 'fractional',
+      version: 0,
+      created_at: 1.5,
+      cwd: null,
+      parent_session: null,
+      seed_length: null,
+      incarnation: 'fractional',
+      revision: 1,
+      delegation_depth: null,
+    })).toThrow('stored session createdAt must be a non-negative safe integer')
+  })
+})
+
 describe('SessionPersistenceSqlite: durability and crash semantics', () => {
   it('rejects a stored v0 log containing a legacy request/header-delta event', async () => {
     const path = await freshDbPath()
     const m = meta('legacy-header-delta', '/legacy')
     const db = openDatabase(path, 'wal')
-    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length) VALUES (?, ?, ?, ?, NULL, NULL)')
-      .run(m.id, m.version, m.createdAt, m.cwd ?? null)
+    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, incarnation, revision) VALUES (?, ?, ?, ?, NULL, NULL, NULL, ?, 1)')
+      .run(m.id, m.version, m.createdAt, m.cwd ?? null, 'legacy-header-delta')
     const insert = db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)')
     insert.run(m.id, 0, 'turn/start', 1, JSON.stringify({ turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }))
     insert.run(m.id, 1, 'request/header-delta', 2, JSON.stringify({ config: { model: 'legacy' } }))
@@ -172,8 +196,8 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     const path = await freshDbPath()
     const m = meta('legacy-header-fallback', '/legacy')
     const db = openDatabase(path, 'wal')
-    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length) VALUES (?, ?, ?, ?, NULL, NULL)')
-      .run(m.id, m.version, m.createdAt, m.cwd ?? null)
+    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, incarnation, revision) VALUES (?, ?, ?, ?, NULL, NULL, NULL, ?, 1)')
+      .run(m.id, m.version, m.createdAt, m.cwd ?? null, 'legacy-header-fallback')
     db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)')
       .run(m.id, 0, 'request/header', 1, JSON.stringify({
         header: { config: { model: 'legacy' } },
@@ -294,22 +318,135 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     dbNewer.close()
     expect(() => openDatabase(path, 'wal')).toThrow(/incompatible with this build/)
 
-    // A stale OLDER version (e.g. a pre-summary-drop v1 DB) is also rejected —
-    // we do not migrate (unreleased software, no backward-compat).
+    // The immediately preceding layout lacks the required store identity and is
+    // rejected rather than migrated (unreleased software, no backward-compat).
     const olderPath = await freshDbPath()
     openDatabase(olderPath, 'wal').close()
     const dbOlder = openDatabase(olderPath, 'wal')
-    dbOlder.exec('PRAGMA user_version = 1')
+    dbOlder.exec(`PRAGMA user_version = ${SCHEMA_VERSION - 1}`)
     dbOlder.close()
     expect(() => openDatabase(olderPath, 'wal')).toThrow(/incompatible with this build/)
   })
 
-  it('rejects a sibling v3 database (the merge-collided version) rather than opening it against missing columns', async () => {
-    // Two unmerged branches each shipped a DISTINCT layout under user_version 3 (one added only
-    // `seed_length`, the other only the surface columns). The merged v4 cannot interpret that
-    // ambiguous, incomplete layout and must reject it.
+  it('rejects a table-backed unversioned database before stamping or changing journal mode', async () => {
     const path = await freshDbPath()
-    openDatabase(path, 'wal').close() // creates + stamps user_version = SCHEMA_VERSION (4)
+    const legacy = new DatabaseSync(path)
+    legacy.exec('CREATE TABLE sessions (id TEXT PRIMARY KEY)')
+    legacy.close()
+
+    expect(() => openDatabase(path, 'wal')).toThrow(/unversioned schema or application identity/)
+
+    const unchanged = new DatabaseSync(path)
+    expect(unchanged.prepare('PRAGMA user_version').get()).toEqual({ user_version: 0 })
+    expect(unchanged.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'delete' })
+    expect(unchanged.prepare(
+      "SELECT name FROM sqlite_schema WHERE type = 'table' AND name = 'sessions'",
+    ).get()).toEqual({ name: 'sessions' })
+    unchanged.close()
+  })
+
+  it('counts a sqliteX table as user-owned instead of mistaking it for SQLite metadata', async () => {
+    const path = await freshDbPath()
+    const unrelated = new DatabaseSync(path)
+    unrelated.exec('CREATE TABLE sqliteX (value TEXT)')
+    unrelated.exec("INSERT INTO sqliteX VALUES ('safe')")
+    unrelated.close()
+
+    expect(() => openDatabase(path, 'wal')).toThrow(/unversioned schema or application identity/)
+
+    const unchanged = new DatabaseSync(path)
+    expect(unchanged.prepare('SELECT value FROM sqliteX').get()).toEqual({ value: 'safe' })
+    expect(unchanged.prepare('PRAGMA application_id').get()).toEqual({ application_id: 0 })
+    expect(unchanged.prepare('PRAGMA user_version').get()).toEqual({ user_version: 0 })
+    expect(unchanged.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'delete' })
+    unchanged.close()
+  })
+
+  it('rejects view-only and foreign-application unversioned databases without mutation', async () => {
+    const viewPath = await freshDbPath()
+    const viewOnly = new DatabaseSync(viewPath)
+    viewOnly.exec('CREATE VIEW foreign_view AS SELECT 1 AS value')
+    viewOnly.close()
+
+    expect(() => openDatabase(viewPath, 'wal')).toThrow(/unversioned schema or application identity/)
+    const unchangedView = new DatabaseSync(viewPath)
+    expect(unchangedView.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'delete' })
+    expect(unchangedView.prepare(
+      "SELECT type FROM sqlite_schema WHERE name = 'foreign_view'",
+    ).get()).toEqual({ type: 'view' })
+    unchangedView.close()
+
+    const applicationPath = await freshDbPath()
+    const foreignApplication = new DatabaseSync(applicationPath)
+    foreignApplication.exec('PRAGMA application_id = 12345')
+    foreignApplication.close()
+
+    expect(() => openDatabase(applicationPath, 'wal')).toThrow(/unversioned schema or application identity/)
+    const unchangedApplication = new DatabaseSync(applicationPath)
+    expect(unchangedApplication.prepare('PRAGMA application_id').get()).toEqual({ application_id: 12345 })
+    expect(unchangedApplication.prepare('PRAGMA user_version').get()).toEqual({ user_version: 0 })
+    expect(unchangedApplication.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'delete' })
+    unchangedApplication.close()
+  })
+
+  it('rejects a current-version database with a foreign application identity', async () => {
+    const path = await freshDbPath()
+    const foreign = new DatabaseSync(path)
+    foreign.exec('PRAGMA application_id = 12345')
+    foreign.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
+    foreign.close()
+
+    expect(() => openDatabase(path, 'wal')).toThrow(/has application id 12345/)
+
+    const unchanged = new DatabaseSync(path)
+    expect(unchanged.prepare('PRAGMA application_id').get()).toEqual({ application_id: 12345 })
+    expect(unchanged.prepare('PRAGMA user_version').get()).toEqual({ user_version: SCHEMA_VERSION })
+    expect(unchanged.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'delete' })
+    unchanged.close()
+  })
+
+  it('rolls back schema objects and identity stamps when initialization fails', async () => {
+    const path = await freshDbPath()
+    const conflicting = new DatabaseSync(path)
+    conflicting.exec(`PRAGMA application_id = ${SESSION_PERSISTENCE_SQLITE_APPLICATION_ID}`)
+    conflicting.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
+    conflicting.exec("CREATE VIEW persistence_state AS SELECT 1 AS singleton, 'foreign' AS store_id")
+    conflicting.close()
+
+    expect(() => openDatabase(path, 'wal')).toThrow()
+
+    const unchanged = new DatabaseSync(path)
+    expect(unchanged.prepare(
+      "SELECT type FROM sqlite_schema WHERE name = 'persistence_state'",
+    ).get()).toEqual({ type: 'view' })
+    expect(unchanged.prepare(
+      "SELECT type FROM sqlite_schema WHERE name = 'sessions'",
+    ).get()).toBeUndefined()
+    expect(unchanged.prepare(
+      "SELECT type FROM sqlite_schema WHERE name = 'events'",
+    ).get()).toBeUndefined()
+    expect(unchanged.prepare('PRAGMA application_id').get())
+      .toEqual({ application_id: SESSION_PERSISTENCE_SQLITE_APPLICATION_ID })
+    expect(unchanged.prepare('PRAGMA user_version').get()).toEqual({ user_version: SCHEMA_VERSION })
+    expect(unchanged.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'delete' })
+    unchanged.close()
+  })
+
+  it('stamps the persistence application identity with the schema version', async () => {
+    const path = await freshDbPath()
+    openDatabase(path, 'wal').close()
+
+    const db = new DatabaseSync(path)
+    expect(db.prepare('PRAGMA application_id').get())
+      .toEqual({ application_id: SESSION_PERSISTENCE_SQLITE_APPLICATION_ID })
+    expect(db.prepare('PRAGMA user_version').get()).toEqual({ user_version: SCHEMA_VERSION })
+    db.close()
+  })
+
+  it('rejects a sibling v3 database (the merge-collided version) rather than opening it against missing columns', async () => {
+    // Version 3 identified two incompatible sibling layouts, so it is always rejected.
+    const path = await freshDbPath()
+    openDatabase(path, 'wal').close() // creates + stamps user_version = SCHEMA_VERSION
     const db = openDatabase(path, 'wal')
     db.exec('PRAGMA user_version = 3')
     db.close()
@@ -382,12 +519,95 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     await fiber2.dispose()
   })
 
+  it('source-qualifies revisions across stores while preserving same-file reopen identity', async () => {
+    const pathA = await freshDbPath()
+    const pathB = await freshDbPath()
+    const m = meta('revision-source')
+    const a = await backend(pathA)
+    await a.ctx.sessionPersistence.create(m)
+    await a.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const revisionA = (await a.ctx.sessionPersistence.listSnapshots())[0]?.revision
+    await a.dispose()
+
+    const probeA = openDatabase(pathA, 'wal')
+    const storeIdA = (probeA.prepare(
+      'SELECT store_id FROM persistence_state WHERE singleton = 1',
+    ).get() as { store_id: string }).store_id
+    probeA.close()
+
+    const aliasA = `${pathA}.alias`
+    await symlink(pathA, aliasA)
+    const reopenedA = await backend(aliasA)
+    expect((await reopenedA.ctx.sessionPersistence.listSnapshots())[0]?.revision).toBe(revisionA)
+    await reopenedA.dispose()
+
+    const b = await backend(pathB)
+    await b.ctx.sessionPersistence.create(m)
+    await b.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const revisionB = (await b.ctx.sessionPersistence.listSnapshots())[0]?.revision
+    const probeB = openDatabase(pathB, 'wal')
+    const storeIdB = (probeB.prepare(
+      'SELECT store_id FROM persistence_state WHERE singleton = 1',
+    ).get() as { store_id: string }).store_id
+    probeB.close()
+    expect(storeIdB).not.toBe(storeIdA)
+    expect(revisionB).not.toBe(revisionA)
+    expect(String(revisionA)).toMatch(/:revision:1$/)
+    expect(String(revisionB)).toMatch(/:revision:1$/)
+    await b.dispose()
+  })
+
+  it('changes revisions when a deleted session id is materialized again in the same database', async () => {
+    const path = await freshDbPath()
+    const m = meta('recreated-revision')
+    const first = await backend(path)
+    await first.ctx.sessionPersistence.create(m)
+    await first.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const before = (await first.ctx.sessionPersistence.listSnapshots())[0]?.revision
+    await first.dispose()
+
+    const cleanup = openDatabase(path, 'wal')
+    cleanup.prepare('DELETE FROM sessions WHERE id = ?').run(m.id)
+    cleanup.close()
+
+    const second = await backend(path)
+    await second.ctx.sessionPersistence.create(m)
+    await second.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const after = (await second.ctx.sessionPersistence.listSnapshots())[0]?.revision
+    expect(after).not.toBe(before)
+    expect(String(before)).toMatch(/:revision:1$/)
+    expect(String(after)).toMatch(/:revision:1$/)
+    await second.dispose()
+  })
+
   it('exposes the schema version constant', () => {
-    expect(SCHEMA_VERSION).toBe(5)
+    expect(SCHEMA_VERSION).toBe(10)
+  })
+
+  it('keeps the revision stable for an empty repair hook', async () => {
+    const b = await backend()
+    const m = meta('empty-repair')
+    await b.ctx.sessionPersistence.create(m)
+    await b.ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const before = await b.ctx.sessionPersistence.listSnapshots()
+    await (b.ctx.sessionPersistence as SessionPersistenceSqlite).commitRepair(m, undefined, [])
+    expect(await b.ctx.sessionPersistence.listSnapshots()).toEqual(before)
+    await b.dispose()
   })
 })
 
 describe('SessionPersistenceSqlite: edge cases', () => {
+  it('rejects and closes a current-schema database with an invalid store identity', async () => {
+    const path = await freshDbPath()
+    const db = openDatabase(path, 'wal')
+    db.exec("UPDATE persistence_state SET store_id = '' WHERE singleton = 1")
+    db.close()
+
+    const b = await backend(path)
+    await expect(b.ctx.sessionPersistence.listSnapshots()).rejects.toThrow(/no valid store identity/)
+    await expect(b.dispose()).resolves.toBeUndefined()
+  })
+
   it('creates a new database and WAL sidecars with owner-only modes without changing its parent mode', async () => {
     if (process.platform === 'win32') return
     const path = await freshDbPath()
diff --git a/packages/session-persistence/session-persistence/README.md b/packages/session-persistence/session-persistence/README.md
index 045686ba5b..25429bd720 100644
--- a/packages/session-persistence/session-persistence/README.md
+++ b/packages/session-persistence/session-persistence/README.md
@@ -10,9 +10,11 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 |---|---|
 | `locate(meta): SessionLocation \| undefined` | Resolve an absolute per-session artifact target without I/O or materialization. Backends without an independent local artifact return `undefined`. |
 | `create(meta): Promise<void>` | Register a new session's metadata. MAY defer the physical write until the first `append` (lazy materialization). |
-| `append(id, events): Promise<void>` | Durably persist a batch (from the `session/flush` drain). Append-only; first event `seq` == stored next-seq after any repair; rejects non-JSON-serializable data naming the offending type. |
-| `load(id): Promise<{ meta; events }>` | Reload meta + log. Preserves an interrupted (unclosed) final turn and closes it with synthetic closers — an error `tool/result` per unanswered `tool-call`, then `step/end?`+`turn/end {interrupted}` (a turn can be huge — never truncated); only a torn tail fragment is dropped. Events contiguous (`events[i].seq === i`); rejects a committed-region gap/parse error or unknown `version`. |
+| `append(id, events): Promise<void>` | Durably persist a batch. Append-only; first event `seq` == stored next-seq after any repair; rejects non-JSON-serializable data naming the offending type. |
+| `load(id): Promise<{ meta; events }>` | Return a stored header plus a balanced contiguous log. A live load first flushes its snapshot and rejects while its turn is open; a cold load preserves an interrupted final turn and closes it with synthetic `tool/result`/`step/end?`/`turn/end {interrupted}` events. Only a torn tail fragment is dropped; committed corruption and unknown `version` reject. |
+| `inspect(id): Promise<{ meta; events }>` | Return a detached valid stored prefix without truncating a torn tail, synthesizing recovery closers, or publishing coordinator state. Serialized with same-id writes; intended for read models and other observers that must never recover a log. |
 | `list(): Promise<SessionHeader[]>` | Lightweight listing from metadata, no full-log parse. A zero-event lazily-materialized session is absent from `list`. |
+| `listSnapshots(): Promise<SessionPersistenceSnapshot[]>` | Lightweight metadata plus an opaque branded per-log revision, without loading event logs. A revision stays equal while that log and its backing store are unchanged, changes after append or mutating load repair, and cannot collide solely because two stores use the same local counter. |
 
 ## Invariants every backend must honor
 
@@ -23,31 +25,32 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 
 ## The write coordinator
 
-`PersistenceCoordinator` owns per-id state, write-behind buffers and serialization, the `session/event` → `session/flush` drain, 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 four public service 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).
+`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).
 
-The coordinator implements durability at checkpoints but does not select their schedule. Persisted deployments explicitly compose [`dsh-session-checkpoint-policy`](../session-checkpoint-policy) when they want request-, tool-dispatch-, and completed-step recovery boundaries; omitting it leaves the loop's coarser checkpoints intact.
+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.
 
-When a live session emits `session/disposed`, the coordinator waits for its initialization, serializes a final buffer drain, then releases every map entry owned by that exact `Session` object. A failed final drain keeps the pending buffer for backend teardown to retry. Backend teardown stops event admission first, awaits all in-flight session retirements and remaining per-id operations, drains any retained buffers, and only then closes the storage handle.
+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 with the coordinator's stored header only when balanced; an open live turn rejects instead of receiving synthetic interruption closers. A cold load reserves its id across backend reads and repair writes, so concurrent publication of a same-id live `Session` rejects and rolls back. HMR adoption reads through `loadStored`, applies the coordinator's cwd check, and never closes the active turn.
 
-The side-effect-free `locate` query remains backend-owned because it describes storage topology rather than write orchestration.
+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.
+
+The side-effect-free `locate` and lightweight `listSnapshots` queries remain backend-owned because they describe storage topology and revision identity rather than write orchestration.
 
 The `PersistenceBackend<TornMarker>` hooks (the only seam between the coordinator and storage):
 
 | Hook | Role |
 |---|---|
 | `name` | Backend label for the dispose-failure `AggregateError`. |
-| `loadStored(id)` | Read a stored prefix by id, scanning ANY storage scope. Used by resume/load and, via `!== undefined`, the create-collision probe. Returns an opaque `tornMarker` iff a torn tail must be truncated. |
-| `loadLive(id, cwd)` | Read a stored prefix SCOPED to `cwd` (HMR live-adoption must only adopt a log at the SAME cwd; a same-id log elsewhere is a collision, not a resume). A globally-unique-id backend ignores `cwd`. |
+| `loadStored(id)` | Read a stored prefix by id across every storage scope. Used by resume/load, non-mutating inspect, live adoption, and the create-collision probe. Returned metadata identifies `id`; an opaque `tornMarker` is present iff a torn tail must be truncated. |
 | `appendBatch(meta, events, isMaterialized)` | Durably append a contiguous batch, lazily materializing ATOMICALLY when not yet materialized. |
 | `commitRepair(meta, tornMarker, closers)` | Make a crash repair durable: truncate the torn tail (iff `tornMarker !== undefined` — a marker may be falsy, e.g. seq/offset `0`) and append `closers`. NOT required to be atomic. Used by load (truncate + closers) and live-adoption (truncate only). |
 | `list()` | List all stored metadata. |
 | `close?()` | Optional lifecycle teardown (e.g. close a db handle), awaited after the dispose drain. |
 
-The `tornMarker` is fully OPAQUE: the coordinator only tests `!== undefined` and round-trips it to `commitRepair`, never inspecting its value (the JSONL backend uses the byte offset to truncate to, the SQLite backend the seq to delete from). The public `SessionPersistence` service shape is unchanged, so a third-party backend MAY still implement the abstract service directly without the coordinator. See [the write-coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md).
+The coordinator asserts the stored id and compares stored/live cwd before repair or live adoption. Its `inspect()` path validates and clones the prefix without calling `commitRepair` or publishing write state. The `tornMarker` is fully OPAQUE: the coordinator only tests `!== undefined` and round-trips it to `commitRepair`, never inspecting its value (the JSONL backend uses the byte offset to truncate to, the SQLite backend the seq to delete from). A third-party backend MAY implement the abstract service directly without the coordinator, but it must provide the same non-mutating inspection and trustworthy lightweight snapshot revisions. See [the write-coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md).
 
 ## Testing backends
 
-Import `runPersistenceContract` from `tests/contract.ts` (the public-API contract) and `runCoordinatorContract` from `tests/coordinator-contract.ts` (the shared write-path orchestration: adoption, HMR, collision, dispose-drain, crash-tail repair) and call each with a fixture for your backend. Every backend is held to the same append-only / contiguous-seq / lazy-materialization / serializability semantics AND the same orchestration, so a backend's own spec is left with only storage-mechanics tests (path sanitization, fsync rollback; schema version, transaction rollback) on top.
+Import `runPersistenceContract` from `tests/contract.ts` (the public API, including stable/change-sensitive lightweight revisions) and `runCoordinatorContract` from `tests/coordinator-contract.ts` (the shared write-path orchestration: adoption, HMR, collision, dispose-drain, crash-tail repair) and call each with a fixture for your backend. Every backend is held to the same append-only / contiguous-seq / lazy-materialization / serializability semantics AND the same orchestration, so a backend's own spec is left with only storage-mechanics tests (path sanitization, fsync rollback; schema version, transaction rollback) on top.
 
 Three backends run these suites: an in-memory reference (in `tests/`), `dsh-session-persistence-jsonl` (append-only file log) and `dsh-session-persistence-sqlite` (`node:sqlite`, each `SessionEvent` one row `(session_id, seq, type, time, data, source_event_seqs, surface_op)`). All passing the same contract + coordinator suite is the proof that the seam is genuinely backend-agnostic — lazy materialization, crash-tail-on-load, and contiguous-seq hold identically over file bytes and over a transactional store.
 
@@ -73,6 +76,6 @@ Persistence does not mutate live request prefixes. A resumed loop can reuse prov
 
 ## Known Limitations and Deferred Work
 
-- **No deletion or retention surface** — the seam is `create`/`append`/`load`/`list` only; pruning stored sessions is out-of-band backend maintenance.
+- **No deletion or retention surface** — pruning stored sessions is out-of-band backend maintenance.
 - **`list()` is unpaginated and unfiltered** — it returns every stored session's header; fine for local stores, unindexed at scale.
 - **Repair-time synthetic closers are the only crash story** — a backend must synthesize `tool/result`/`step/end`/`turn/end` closers on load; there is no partial-turn resume that continues an interrupted turn instead of closing it.
diff --git a/packages/session-persistence/session-persistence/package.json b/packages/session-persistence/session-persistence/package.json
index a503b146ae..ca74dd487d 100644
--- a/packages/session-persistence/session-persistence/package.json
+++ b/packages/session-persistence/session-persistence/package.json
@@ -27,11 +27,13 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^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-invariants": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/session-persistence/session-persistence/src/coordinator.ts b/packages/session-persistence/session-persistence/src/coordinator.ts
index 7dc0c9a0ba..089a4f7d83 100644
--- a/packages/session-persistence/session-persistence/src/coordinator.ts
+++ b/packages/session-persistence/session-persistence/src/coordinator.ts
@@ -35,22 +35,14 @@ export interface PersistenceBackend<TornMarker = unknown> {
   readonly name: string
 
   /**
-   * Read a stored prefix by id, scanning ANY storage scope (for JSONL: every
-   * cwd bucket). Returns `undefined` if no stored artifact exists. Used by
-   * resume/load, and — via `!== undefined` — by the create-collision probe.
-   * The returned `tornMarker` is present iff there is a torn tail to truncate.
+   * Read a stored prefix by id, scanning every backend storage scope. Returns
+   * `undefined` if no stored artifact exists. Returned metadata must identify
+   * `id` before repair or state publication. Used by resume/load, live adoption,
+   * and — via `!== undefined` — the create-collision probe. The returned
+   * `tornMarker` is present iff there is a torn tail to truncate.
    */
   loadStored(id: SessionId): Promise<StoredPrefix<TornMarker> | undefined>
 
-  /**
-   * Read a stored prefix SCOPED to `cwd`. Deliberately distinct from
-   * {@link loadStored}: HMR live-adoption must only adopt a persisted log at the
-   * SAME cwd as the live session (a same-id log at a different cwd is a
-   * collision, not a resume) — conflating the two reintroduces a cross-cwd
-   * adoption bug. For a globally-unique-id backend (SQLite) `cwd` is ignored.
-   */
-  loadLive(id: SessionId, cwd: string | undefined): Promise<StoredPrefix<TornMarker> | undefined>
-
   /**
    * Durably append a CONTIGUOUS batch, lazily materializing the session first
    * when `!isMaterialized`. The materialize-write and the first event batch MUST
@@ -99,6 +91,13 @@ interface SessionState {
   owner?: Session
 }
 
+/** One live session's initialization and eager write-behind controller. */
+interface LiveSessionState {
+  pending: SessionEvent[]
+  init: Promise<void>
+  flush: Promise<void> | undefined
+}
+
 /** Collect the rejection reasons from a set of promises (none-throwing). */
 async function settledErrors(promises: Iterable<Promise<unknown>>): Promise<unknown[]> {
   const settled = await Promise.allSettled([...promises])
@@ -140,7 +139,7 @@ function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId):
 /**
  * Owns the backend-agnostic session write-path orchestration. A backend
  * constructs one (`new PersistenceCoordinator(ctx, this)`), implements
- * {@link PersistenceBackend}, and delegates its four public service methods to
+ * {@link PersistenceBackend}, and delegates its write/read service methods to
  * the matching coordinator methods.
  *
  * All per-id operations are serialized (a per-id promise chain) so concurrent
@@ -153,21 +152,15 @@ function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId):
 export class PersistenceCoordinator<TornMarker = unknown> {
   /** Backend bookkeeping keyed by session id (NOT the live Session object). */
   private states = new Map<SessionId, SessionState>()
-  /** Write-behind buffers keyed by the live Session (write path). */
-  private buffers = new Map<Session, SessionEvent[]>()
+  /** Lifecycle and write-behind state keyed by the exact live Session. */
+  private live = new Map<Session, LiveSessionState>()
+  /** Cold loads currently reserving an id across backend reads and repair writes. */
+  private coldLoads = new Set<SessionId>()
   /**
    * Per-session serialization: every operation chains onto the prior one for the
    * same id, so writes for one session never interleave. Keyed by session id.
    */
   private chains = new Map<SessionId, Promise<unknown>>()
-  /**
-   * Init promises keyed by live session object, preventing an id-reusing
-   * replacement from inheriting stale initialization. Flush is the public
-   * observation boundary; callers do not inspect this bookkeeping directly.
-   */
-  private inits = new Map<Session, Promise<void>>()
-  /** Final drains started by fire-and-forget session disposal notifications. */
-  private retirements = new Set<Promise<void>>()
 
   constructor(private ctx: Context, private backend: PersistenceBackend<TornMarker>) {
     this.installWritePath()
@@ -185,6 +178,9 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     if (snapshot === undefined) {
       return Promise.reject(new TypeError('session metadata must be losslessly JSON-serializable'))
     }
+    if (!Number.isSafeInteger(snapshot.createdAt) || snapshot.createdAt < 0) {
+      return Promise.reject(new TypeError('session metadata createdAt must be a non-negative safe integer'))
+    }
     return this.serialize(snapshot.id, () => this.createCore(snapshot))
   }
 
@@ -256,14 +252,47 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * @param id - the persisted session to reload.
    * @returns the header plus the event log, ending on a balanced `turn/end`.
    */
-  load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    return this.serialize(id, () => this.loadCore(id))
+  async load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    const selected = await this.serialize(id, async () => {
+      const live = this.ctx.sessions.get(id)
+      if (live !== undefined) return { live }
+      this.coldLoads.add(id)
+      try {
+        return { loaded: await this.loadCore(id) }
+      } finally {
+        this.coldLoads.delete(id)
+      }
+    })
+    return 'loaded' in selected ? selected.loaded : this.loadLiveSnapshot(selected.live)
+  }
+
+  /**
+   * Read a detached valid stored prefix without recovery mutations or
+   * coordinator-state publication.
+   * @param id - persisted session to inspect.
+   * @returns stored header and events before any synthetic recovery closers.
+   */
+  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.serialize(id, () => this.inspectCore(id))
+  }
+
+  private async inspectCore(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    const stored = await this.backend.loadStored(id)
+    if (stored === undefined) throw new Error(`session "${id}" not found`)
+    this.assertStoredId(id, stored.meta)
+    this.assertVersion(stored.meta)
+    assertSupportedEvents(stored.events, id)
+    return {
+      meta: structuredClone(stored.meta),
+      events: structuredClone(stored.events),
+    }
   }
 
   private async loadCore(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     const stored = await this.backend.loadStored(id)
     if (stored === undefined) throw new Error(`session "${id}" not found`)
     const { meta, events, tornMarker } = stored
+    this.assertStoredId(id, meta)
     this.assertVersion(meta)
     assertSupportedEvents(events, id)
 
@@ -280,6 +309,21 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     return { meta, events: balanced }
   }
 
+  /** Return a durable balanced live snapshot without applying cold crash repair. */
+  private async loadLiveSnapshot(session: Session): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    const events = session.events.map(event => structuredClone(event))
+    await this.flush(session)
+    const state = this.states.get(session.id)
+    /* v8 ignore next -- successful flush always publishes this live session's durable state */
+    if (state === undefined) throw new Error(`session "${session.id}" lost persistence state during load`)
+    const meta = structuredClone(state.meta)
+    if (events.length === 0) throw new Error(`session "${session.id}" not found`)
+    if (interruptedTurnClosers(events).length > 0) {
+      throw new Error(`cannot load session "${session.id}" while its live turn is open; use the live Session or wait for the turn to close`)
+    }
+    return { meta, events }
+  }
+
   // Listing is a direct backend read and needs no coordinator state.
 
   // --- per-id serialization + adoption helpers ---
@@ -290,7 +334,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * public methods must NOT call each other (deadlock); they call the unserialized
    * `*Core` helpers instead.
    */
-  private serialize<T>(id: SessionId, op: () => Promise<T>): Promise<T> {
+  private serialize<T>(id: SessionId, op: () => Promise<T> | T): Promise<T> {
     const prior = this.chains.get(id) ?? Promise.resolve()
     const next = prior.then(op, op)
     // Keep the chain alive but swallow this op's rejection for the NEXT waiter
@@ -322,6 +366,13 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     }
   }
 
+  /** Reject backend metadata that is not bound to the requested session id. */
+  private assertStoredId(id: SessionId, meta: SessionHeader): void {
+    if (meta.id !== id) {
+      throw new Error(`stored session identity mismatch: requested "${id}", header contains "${meta.id}"`)
+    }
+  }
+
   // --- write path (session/event → flush drain) ---
 
   private installWritePath(): void {
@@ -331,15 +382,10 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     // reverse registration order, so event admission closes before this final
     // drain reaches quiescence and closes the backend.
     ctx.effect(() => async () => {
-      await this.awaitRetirements()
-
       let disposeError: unknown
       try {
-        const errors = [
-          ...await settledErrors(this.inits.values()),
-          ...await settledErrors([...this.buffers.keys()].map(s => this.flush(s))),
-          ...await settledErrors(this.chains.values()),
-        ]
+        const errors = await settledErrors([...this.live.keys()].map(session => this.flush(session)))
+        while (this.chains.size > 0) await Promise.allSettled([...this.chains.values()])
         if (errors.length > 0) {
           throw new AggregateError(errors, `${this.backend.name} dispose failed`)
         }
@@ -360,25 +406,25 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       }
     }, `${this.backend.name} write path`)
 
-    // Capture the header on creation; persist a fork's seed once. Record the init
-    // promise so flush/dispose can await it (onCreated is async).
-    ctx.on('session/created', (session) => { void this.initFor(session) })
-
-    // Session emits an owned frozen event. Keep a persistence-owned copy anyway
-    // so the write-behind queue owns exactly the record it will flush rather than
-    // retaining a product-layer record by identity. Serializability is guaranteed
-    // at the source, so structuredClone is safe.
-    ctx.on('session/event', (session, event) => {
-      let buffer = this.buffers.get(session)
-      if (!buffer) this.buffers.set(session, buffer = [])
-      buffer.push(structuredClone(event))
+    // Capture the header on creation and persist a fork's seed once.
+    ctx.on('session/created', (session) => {
+      if (this.coldLoads.has(session.id)) {
+        throw new Error(`cannot publish session "${session.id}" while its persisted history is loading`)
+      }
+      void this.initFor(session)
     })
 
-    // Drain to the backend at the durability checkpoint.
+    // Keep a persistence-owned copy of each frozen event and start an eager drain.
+    ctx.on('session/event', (session, event) => {
+      const live = this.initFor(session)
+      live.pending.push(structuredClone(event))
+      if (live.flush === undefined) this.scheduleDrain(session, live)
+    })
+
+    // Callers use flush as the observation barrier for the eager write path.
     ctx.on('session/flush', session => this.flush(session))
 
-    // Session disposal is observe-only, so the coordinator observes the
-    // detached task itself and backend teardown awaits quiescence.
+    // Session disposal is observe-only, so retirement contains its own failure.
     ctx.on('session/disposed', (session) => { this.retire(session) })
 
     // HMR: a hot reload does not replay session/created, so seed existing live
@@ -386,52 +432,34 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     for (const session of ctx.sessions.list()) void this.initFor(session)
   }
 
-  /** Start, observe, and track one disposed session's final drain. */
+  /** Start and observe one disposed session's final drain. */
   private retire(session: Session): void {
-    const task = this.retireCore(session)
-    this.retirements.add(task)
-    const settled = (): void => { this.retirements.delete(task) }
-    void task.then(settled, (error: unknown) => {
-      settled()
+    if (!this.live.has(session)) return
+    void this.retireCore(session).catch((error: unknown) => {
       this.ctx.logger.warn(`${this.backend.name}: session "${session.id}" retirement failed: ${String(error)}`)
     })
   }
 
   /** Drain and release state owned by one exact disposed Session lifecycle. */
   private async retireCore(session: Session): Promise<void> {
-    await this.inits.get(session)
-
+    await this.flush(session)
     const id = session.header.id
-    await this.serialize(id, async () => {
-      await this.drain(session)
-      this.buffers.delete(session)
-      this.inits.delete(session)
+    await this.serialize(id, () => {
+      this.live.delete(session)
       if (this.states.get(id)?.owner === session) this.states.delete(id)
     })
   }
 
-  /** Await every retirement admitted before listener teardown. */
-  private async awaitRetirements(): Promise<void> {
-    while (this.retirements.size > 0) {
-      await Promise.allSettled([...this.retirements])
-    }
-  }
-
-  /** Start (once) the async init for a session and remember its promise. */
-  private initFor(session: Session): Promise<void> {
-    const existing = this.inits.get(session)
+  /** Return the one lifecycle controller for a live session, creating it if needed. */
+  private initFor(session: Session): LiveSessionState {
+    const existing = this.live.get(session)
     if (existing) return existing
-    // Snapshot the seed SYNCHRONOUSLY — initFor runs inside the `session/created`
-    // emit, before any later append invalidates the public array snapshot. Events
-    // are already frozen; cloning gives persistence independent ownership.
     const seed = session.events.map(e => structuredClone(e))
-    const p = this.onCreated(session, seed)
-    // Attach a no-op rejection handler so a failing init does not surface as an
-    // unhandled rejection if no flush observes `p` before it rejects. The REAL
-    // error is still delivered: flush/dispose await the same `p` from the map.
-    p.catch(() => { /* observed by flush/dispose via the stored promise */ })
-    this.inits.set(session, p)
-    return p
+    const live: LiveSessionState = { pending: [], init: Promise.resolve(), flush: undefined }
+    this.live.set(session, live)
+    live.init = this.serialize(session.header.id, () => this.onCreated(session, seed))
+    live.init.catch(() => { /* observed by flush/dispose through the controller */ })
+    return live
   }
 
   /**
@@ -444,6 +472,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     const stored = await this.backend.loadStored(id)
     /* v8 ignore next -- a cursor > 0 means the session was materialized, so it exists */
     if (stored === undefined) return false
+    this.assertStoredId(id, stored.meta)
     return seedCoversPrefix(seed, stored.events.slice(0, cursor))
   }
 
@@ -453,9 +482,10 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * Cases, by whether this backend tracks the id and whether an artifact exists:
    *   1. Already tracked → no-op (or claim ownerless state if the seed matches,
    *      or reclaim a truly-abandoned id, else reject as a collision).
-   *   2. Not tracked, an artifact EXISTS at this cwd and is a seq-aligned PREFIX
-   *      of the live events → ADOPT it (HMR/reload), persisting any live suffix.
-   *   3. Not tracked, an artifact EXISTS but is NOT a prefix → REJECT (collision).
+   *   2. Not tracked, an artifact EXISTS at the same cwd and is a seq-aligned
+   *      PREFIX of the live events → ADOPT it, persisting any live suffix.
+   *   3. Not tracked, an artifact EXISTS at another cwd or is NOT a prefix →
+   *      REJECT (collision).
    *   4. Not tracked and NO artifact → a genuinely new session: register meta
    *      (lazy) and persist its seed once.
    */
@@ -469,14 +499,11 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       if (tracked.owner === undefined) {
         // Ownerless state from the public create()/load() API. The FIRST live
         // session claims it — but ONLY if BOTH the cwd scope and the seed match.
-        // The cwd guard mirrors case-2's cwd-scoped loadLive(): a same-id
-        // ownerless artifact at a DIFFERENT cwd is a collision, not a claim
-        // (claiming it would append the live cwd's events under the stored
-        // header's cwd, the exact cross-cwd corruption the loadLive scope
-        // prevents). The seed guard then ensures the live events reproduce the
-        // persisted prefix (else a fresh, unrelated session reusing the id would
-        // have its seq 0..cursor-1 events filtered as already-written and
-        // grafted on).
+        // A same-id ownerless artifact at a different cwd is a collision, not a
+        // claim: accepting it would append this live session's events through
+        // the stored header's cwd. The seed guard then ensures the live events
+        // reproduce the persisted prefix; otherwise a fresh session reusing the
+        // id could have its leading events filtered as already written.
         if (tracked.meta.cwd !== session.header.cwd) {
           throw new Error(`session "${id}" is already persisted at a different cwd (persisted: ${String(tracked.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
         }
@@ -487,42 +514,38 @@ export class PersistenceCoordinator<TornMarker = unknown> {
         // Persist the seed SUFFIX beyond the persisted prefix. Constructor seed
         // events never emit session/event, so the buffer never sees them.
         const suffix = seed.slice(tracked.cursor)
-        if (suffix.length > 0) await this.append(id, suffix)
+        if (suffix.length > 0) await this.appendCore(id, suffix)
         return
       }
-      // Owned by a DIFFERENT live session. Reclaim ONLY a truly-abandoned id
-      // (never materialized, no pending buffer); else it is a real collision.
-      const ownerBuffer = this.buffers.get(tracked.owner)
-      if (!tracked.materialized && !ownerBuffer?.length) {
+      const owner = this.live.get(tracked.owner)
+      if (!tracked.materialized && !owner?.pending.length) {
         this.states.delete(id)
       } else {
         throw new Error(`session "${id}" is already bound to a different live session in this backend (id collision)`)
       }
     }
 
-    // case 2/3: an artifact at THIS cwd is adopted as a live prefix (or rejected
-    // as a collision inside adoptLivePrefix). cwd-scoped (loadLive), never
-    // any-scope: a same-id artifact at a different cwd is a collision, not a
-    // resume.
-    const live = await this.backend.loadLive(id, session.header.cwd)
+    // case 2/3: resolve the id once across storage, then let adoption reject a
+    // cwd mismatch before repair or state publication.
+    const live = await this.backend.loadStored(id)
     if (live !== undefined) {
       // Do NOT route through loadCore(): that crash-repairs open turns as
       // interrupted, which is wrong for HMR while the live Session is still the
       // authority and may append the real step/turn end later.
-      await this.serialize(id, () => this.adoptLivePrefix(session, seed, live))
+      await this.adoptLivePrefix(session, seed, live)
       return
     }
 
     // case 4: a genuinely new session. Register its meta (lazy), then persist its
     // seed (events present at creation time) once.
     const meta: SessionHeader = { ...session.header }
-    await this.create(meta)
+    await this.createCore(meta)
     // Bind this state to the live session so a later DIFFERENT session reusing
     // the id is detected as a collision (case 1) rather than silently no-opped.
     const created = this.states.get(id)
     /* v8 ignore next -- create() always sets the state for the id */
     if (created !== undefined) created.owner = session
-    if (seed.length > 0) await this.append(id, seed)
+    if (seed.length > 0) await this.appendCore(id, seed)
   }
 
   /**
@@ -533,6 +556,10 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    */
   private async adoptLivePrefix(session: Session, seed: readonly SessionEvent[], stored: StoredPrefix<TornMarker>): Promise<void> {
     const { meta, events, tornMarker } = stored
+    this.assertStoredId(session.header.id, meta)
+    if (meta.cwd !== session.header.cwd) {
+      throw new Error(`session "${session.header.id}" is already persisted at a different cwd (persisted: ${String(meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
+    }
     this.assertVersion(meta)
     assertSupportedEvents(events, session.header.id)
     if (!seedCoversPrefix(seed, events)) {
@@ -551,36 +578,43 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   }
 
   private async flush(session: Session): Promise<void> {
-    // Wait for the session's init (onCreated) so the state/cursor and any
-    // fork-seed persistence are in place before draining. Awaiting the same
-    // promise initFor stored also surfaces an init failure (e.g. a collision)
-    // here, where the caller of session/flush observes it.
-    await this.inits.get(session)
-    // Serialize the WHOLE drain (read cursor → append → splice) on the per-session
-    // chain so two concurrent flushes cannot both read the same cursor and
-    // seq-mismatch on the second append.
-    await this.serialize(session.header.id, () => this.drain(session))
+    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)
+    }
   }
 
-  /** Drain a session's write buffer to the backend. Caller serializes this per id. */
-  private async drain(session: Session): Promise<void> {
-    const buffer = this.buffers.get(session)
-    if (!buffer?.length) return
-    // Copy WITHOUT removing: the buffer is the only durable-pending copy of these
-    // events. Drain it only AFTER the append commits; events pushed during the
-    // await sit past batch.length and survive the prefix splice, so a
-    // retry/dispose re-drains the rest.
-    const batch = buffer.slice()
-    const state = this.states.get(session.header.id)
-    // Only append events at or beyond the write cursor (a resumed session's seed
-    // is already stored). flush awaits the init above, which always sets state,
-    // so the `?? 0` fallback is a defensive guard that never fires in practice.
+  /** 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)}`)
+    })
+  }
+
+  /** 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()
+    const state = this.states.get(id)
     /* v8 ignore next -- state is always set by the awaited init before flush */
     const cursor = state?.cursor ?? 0
     const fresh = batch.filter(e => e.seq >= cursor)
-    // appendCore (NOT the serialized append) — drain already runs inside the
-    // per-session chain, so re-entering via append() would deadlock.
-    if (fresh.length > 0) await this.appendCore(session.header.id, fresh)
-    buffer.splice(0, batch.length)
+    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 3c102e6ede..c785c9354c 100644
--- a/packages/session-persistence/session-persistence/src/index.ts
+++ b/packages/session-persistence/session-persistence/src/index.ts
@@ -7,9 +7,19 @@
 
 import { Context, Service } from 'cordis'
 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.
 export type { SessionHeader } from '@deepseek-ai/dsh-session'
+export { SessionPersistenceRevision } from './revision.ts'
+
+/** Lightweight immutable source identity returned without loading a full log. */
+export interface SessionPersistenceSnapshot {
+  /** Detached metadata for one materialized session. */
+  header: SessionHeader
+  /** Opaque source-qualified token that changes whenever this stored log changes. */
+  revision: SessionPersistenceRevision
+}
 
 // The backend-agnostic write-path orchestration first-party backends compose.
 export { PersistenceCoordinator } from './coordinator.ts'
@@ -63,10 +73,9 @@ export abstract class SessionPersistence extends Service {
   abstract create(meta: SessionHeader): Promise<void>
 
   /**
-   * Durably persist a batch of events (called from the write-behind drain at
-   * the `session/flush` checkpoint). 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-
+   * 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.
@@ -75,19 +84,45 @@ export abstract class SessionPersistence extends Service {
 
   /**
    * Load a header and balanced contiguous log. 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.
+   * 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 with its stored header as a durable snapshot, while an
+   * open live turn rejects.
+   * A coordinator-backed cold load reserves the identity across storage awaits,
+   * so concurrent publication of a same-id live Session rejects.
    * @param id - the persisted session to reload.
    * @returns the header and a log ending on a balanced `turn/end`.
    */
   abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
 
+  /**
+   * Inspect a header and its valid contiguous stored prefix without repairing
+   * a torn tail, closing an interrupted turn, or publishing coordinator state.
+   * This read is serialized with writes for the same id and returns detached
+   * values, so observers cannot mutate backend-owned state.
+   * @param id - the persisted session to inspect.
+   * @returns the header and valid stored event prefix exactly as observed.
+   */
+  abstract inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
   /**
    * Lightweight listing from metadata, without a full-log parse.
    * @returns one header per materialized session.
    */
   abstract list(): 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.
+   * @returns one header and opaque revision per materialized session without loading full logs.
+   */
+  abstract listSnapshots(): Promise<SessionPersistenceSnapshot[]>
 }
 
 export default SessionPersistence
diff --git a/packages/session-persistence/session-persistence/src/revision.ts b/packages/session-persistence/session-persistence/src/revision.ts
new file mode 100644
index 0000000000..cb037ffafc
--- /dev/null
+++ b/packages/session-persistence/session-persistence/src/revision.ts
@@ -0,0 +1,18 @@
+/** Opaque revision identity for lightweight persistence observations. */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/**
+ * Backend-owned token that identifies both one storage source and one revision
+ * of a persisted session log.
+ */
+export type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
+
+/**
+ * Brand a backend revision for the provider-neutral persistence contract.
+ * @param value - backend-owned opaque revision representation.
+ * @returns the same runtime string with persistence-revision identity.
+ */
+export function SessionPersistenceRevision(value: string): SessionPersistenceRevision {
+  return value as SessionPersistenceRevision
+}
diff --git a/packages/session-persistence/session-persistence/tests/contract.ts b/packages/session-persistence/session-persistence/tests/contract.ts
index aaea0ddfff..cf72f4d028 100644
--- a/packages/session-persistence/session-persistence/tests/contract.ts
+++ b/packages/session-persistence/session-persistence/tests/contract.ts
@@ -84,6 +84,22 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
       }
     })
 
+    it('rejects a fractional creation timestamp without reserving its session id', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = { ...meta('fractional-created-at'), createdAt: 1.5 }
+        await expect(persistence.create(m))
+          .rejects.toThrow('session metadata createdAt must be a non-negative safe integer')
+
+        const valid = meta('fractional-created-at')
+        await persistence.create(valid)
+        await persistence.append(valid.id, oneTurnLog())
+        expect((await persistence.load(valid.id)).meta.createdAt).toBe(valid.createdAt)
+      } finally {
+        await dispose()
+      }
+    })
+
     it('crash recovery: load preserves an interrupted (unclosed) turn and closes it with turn/end {interrupted}', async () => {
       const { persistence, dispose } = await make()
       try {
@@ -96,11 +112,25 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
           { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } },
         ])
+        const beforeRepair = (await persistence.listSnapshots())
+          .find(snapshot => snapshot.header.id === m.id)?.revision
+
+        const inspected = await persistence.inspect(m.id)
+        const afterInspect = (await persistence.listSnapshots())
+          .find(snapshot => snapshot.header.id === m.id)?.revision
+        expect(afterInspect).toBe(beforeRepair)
+        expect(inspected.events.map(e => e.type)).toEqual([
+          'turn/start', 'user/message', 'step/start', 'assistant/message', 'step/end', 'turn/end',
+          'turn/start', 'step/start',
+        ])
 
         // load PRESERVES the interrupted turn's events (a turn can be huge — they
         // must not be truncated) and closes the orphaned turn with synthetic
         // boundary events: step/end (the step was open) then turn/end {interrupted}.
         const loaded = await persistence.load(m.id)
+        const afterRepair = (await persistence.listSnapshots())
+          .find(snapshot => snapshot.header.id === m.id)?.revision
+        expect(afterRepair).not.toBe(beforeRepair)
         expect(loaded.events.map(e => e.type)).toEqual([
           'turn/start', 'user/message', 'step/start', 'assistant/message', 'step/end', 'turn/end', // turn 1
           'turn/start', 'step/start', 'step/end', 'turn/end', // turn 2: real events + synthetic closers
@@ -201,18 +231,33 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
       try {
         await persistence.create(meta('empty'))
         expect((await persistence.list()).map(m => m.id)).not.toContain(SessionId('empty'))
+        expect((await persistence.listSnapshots()).map(snapshot => snapshot.header.id))
+          .not.toContain(SessionId('empty'))
       } finally {
         await dispose()
       }
     })
 
-    it('list() includes a session once it has events', async () => {
+    it('lists stable lightweight revisions that change after an append', async () => {
       const { persistence, dispose } = await make()
       try {
         const m = meta('s2')
         await persistence.create(m)
         await persistence.append(m.id, oneTurnLog())
         expect((await persistence.list()).map(x => x.id)).toContain(m.id)
+        const first = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
+        const repeated = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
+        expect(first).toBeDefined()
+        expect(repeated?.revision).toBe(first?.revision)
+
+        await persistence.append(m.id, [{
+          type: 'turn/start',
+          seq: 6,
+          time: 7,
+          data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } },
+        }])
+        const changed = (await persistence.listSnapshots()).find(snapshot => snapshot.header.id === m.id)
+        expect(changed?.revision).not.toBe(first?.revision)
       } finally {
         await dispose()
       }
diff --git a/packages/session-persistence/session-persistence/tests/coordinator-contract.ts b/packages/session-persistence/session-persistence/tests/coordinator-contract.ts
index 620d069d32..61c42e5ad6 100644
--- a/packages/session-persistence/session-persistence/tests/coordinator-contract.ts
+++ b/packages/session-persistence/session-persistence/tests/coordinator-contract.ts
@@ -88,6 +88,84 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
+    it('rejects crash-repair load while a live session owns the persisted prefix', async () => {
+      const fix = await makeFixture()
+      const { ctx, fiber } = await freshCtx(fix)
+      let session!: Session
+      const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
+        session = inner.sessions.create(SessionId('live-load'), { meta: { cwd: WORK } })
+      }, { inject: ['sessions'] }))
+      try {
+        session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+        await ctx.sessions.flush(session)
+
+        await expect(ctx.sessionPersistence.load(session.id))
+          .rejects.toThrow(`cannot load session "${session.id}" while its live turn is open`)
+
+        send(session, oneTurnLog().slice(1))
+        await ctx.sessions.flush(session)
+        await sessionFiber.dispose()
+
+        await vi.waitFor(async () => {
+          const loaded = await ctx.sessionPersistence.load(session.id)
+          expect(loaded.events.map(event => event.type)).toEqual(oneTurnLog().map(event => event.type))
+          expect(loaded.events.at(-1)).toMatchObject({
+            type: 'turn/end',
+            data: { reason: { kind: 'completed' } },
+          })
+        })
+      } finally {
+        await sessionFiber.dispose()
+        await fiber.dispose()
+        await fix.cleanup()
+      }
+    })
+
+    it('rechecks live ownership after a cold load enters the per-id chain', async () => {
+      const fix = await makeFixture()
+      const { ctx, fiber } = await freshCtx(fix)
+      try {
+        const id = SessionId('queued-load-live-race')
+        const header = meta(id, WORK)
+        const start: SessionEvent = {
+          type: 'turn/start',
+          seq: 0,
+          time: 1,
+          data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+        }
+        await ctx.sessionPersistence.create(header)
+        await ctx.sessionPersistence.append(id, [start])
+
+        const loading = ctx.sessionPersistence.load(id)
+        const live = ctx.sessions.create(id, { seed: [start], meta: header })
+        await expect(loading).rejects.toThrow(/live turn is open/)
+
+        live.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+        await ctx.sessions.flush(live)
+        const loaded = await ctx.sessionPersistence.load(id)
+        expect(loaded.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
+        expect(loaded.events.at(-1)).toMatchObject({
+          type: 'turn/end',
+          data: { reason: { kind: 'completed' } },
+        })
+      } finally {
+        await fiber.dispose()
+        await fix.cleanup()
+      }
+    })
+
+    it('does not load an unmaterialized empty live session', async () => {
+      const fix = await makeFixture()
+      const { ctx, fiber } = await freshCtx(fix)
+      try {
+        const session = ctx.sessions.create(SessionId('empty-live'), { meta: { cwd: WORK } })
+        await expect(ctx.sessionPersistence.load(session.id)).rejects.toThrow(/not found/)
+      } finally {
+        await fiber.dispose()
+        await fix.cleanup()
+      }
+    })
+
     it('round-trips the seed boundary (seedLength) through persistence', async () => {
       // A forked child records how many leading events were inherited via the seed; the
       // boundary must survive a reload (so a resume/replay can tell the inherited prefix from
@@ -95,9 +173,13 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
-        const session = ctx.sessions.create(SessionId('forked-child'), { meta: { cwd: WORK, seedLength: 3 } })
+        let session!: Session
+        const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
+          session = inner.sessions.create(SessionId('forked-child'), { meta: { cwd: WORK, seedLength: 3 } })
+        }, { inject: ['sessions'] }))
         send(session, oneTurnLog())
         await ctx.sessions.flush(session)
+        await sessionFiber.dispose()
 
         const loaded = await ctx.sessionPersistence.load(SessionId('forked-child'))
         expect(loaded.meta.seedLength).toBe(3)
@@ -114,11 +196,15 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
-        const session = ctx.sessions.create(SessionId('delegated-child'), {
-          meta: { cwd: WORK, parentSession: SessionId('root'), delegationDepth: 2 },
-        })
+        let session!: Session
+        const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => {
+          session = inner.sessions.create(SessionId('delegated-child'), {
+            meta: { cwd: WORK, parentSession: SessionId('root'), delegationDepth: 2 },
+          })
+        }, { inject: ['sessions'] }))
         send(session, oneTurnLog())
         await ctx.parallel('session/flush', session)
+        await sessionFiber.dispose()
 
         const loaded = await ctx.sessionPersistence.load(SessionId('delegated-child'))
         expect(loaded.meta.delegationDepth).toBe(2)
@@ -526,20 +612,31 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       const { ctx, fiber } = await freshCtx(fix)
       try {
         // Materialize and load (ownerless, cursor = 6).
-        await ctx.sessionPersistence.create(meta('claim', WORK))
+        const storedMeta = meta('claim', WORK)
+        await ctx.sessionPersistence.create(storedMeta)
         await ctx.sessionPersistence.append(SessionId('claim'), oneTurnLog())
-        const { events } = await ctx.sessionPersistence.load(SessionId('claim'))
+        const { events, meta: durableMeta } = await ctx.sessionPersistence.load(SessionId('claim'))
 
         // A live session SEEDED with the loaded log PLUS a new turn claims the
         // ownerless state and persists only the suffix.
-        const cont = ctx.sessions.create(SessionId('claim'), { seed: [
-          ...events,
-          { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
-          { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
-        ], meta: { cwd: WORK } })
+        let cont!: Session
+        const contFiber = await ctx.plugin(Object.assign((inner: Context) => {
+          cont = inner.sessions.create(SessionId('claim'), { seed: [
+            ...events,
+            { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
+            { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } },
+          ], meta: { cwd: WORK, createdAt: 2000 } })
+        }, { inject: ['sessions'] }))
         await ctx.sessions.flush(cont)
         const loaded = await ctx.sessionPersistence.load(SessionId('claim'))
         expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+        expect(loaded.meta).toEqual(durableMeta)
+        expect(loaded.meta.createdAt).toBe(1000)
+
+        await contFiber.dispose()
+        await vi.waitFor(async () => {
+          expect((await ctx.sessionPersistence.load(SessionId('claim'))).meta).toEqual(durableMeta)
+        })
       } finally {
         await fiber.dispose()
         await fix.cleanup()
@@ -643,11 +740,12 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
-    it('load rejects a missing session', async () => {
+    it('load and inspect reject a missing session', async () => {
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
         await expect(ctx.sessionPersistence.load(SessionId('nope'))).rejects.toThrow(/not found/)
+        await expect(ctx.sessionPersistence.inspect(SessionId('nope'))).rejects.toThrow(/not found/)
       } finally {
         await fiber.dispose()
         await fix.cleanup()
diff --git a/packages/session-persistence/session-persistence/tests/persistence.spec.ts b/packages/session-persistence/session-persistence/tests/persistence.spec.ts
index 510ae38136..6b31d0843b 100644
--- a/packages/session-persistence/session-persistence/tests/persistence.spec.ts
+++ b/packages/session-persistence/session-persistence/tests/persistence.spec.ts
@@ -3,8 +3,8 @@ import { Context } from 'cordis'
 import SessionStore, { SessionId, isJsonValue } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
-  SessionPersistence, PersistenceCoordinator,
-  type PersistenceBackend, type StoredPrefix,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  type PersistenceBackend, type SessionPersistenceSnapshot, type StoredPrefix,
 } from '../src/index.ts'
 import { runPersistenceContract, meta, oneTurnLog } from './contract.ts'
 import { runCoordinatorContract, type CoordinatorFixture } from './coordinator-contract.ts'
@@ -48,10 +48,8 @@ interface MemoryConfig { store?: MemoryStore }
 /** Test-only view of the coordinator containers whose retirement is the contract under test. */
 interface CoordinatorInternals {
   states: Map<unknown, unknown>
-  buffers: Map<unknown, unknown>
+  live: Map<unknown, { pending: unknown[]; flush: Promise<void> | undefined }>
   chains: Map<unknown, unknown>
-  inits: Map<unknown, unknown>
-  retirements: Set<Promise<void>>
 }
 
 /**
@@ -73,7 +71,7 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     super(ctx)
     // Assign the store BEFORE constructing the coordinator: the coordinator's
     // constructor installs the write path and synchronously seeds existing live
-    // sessions (onCreated → loadLive → this.store), so store must exist first.
+    // sessions through loadStored(), so store must exist first.
     this.store = config?.store ?? new Map<string, { meta: SessionHeader; events: SessionEvent[] }>()
     this.coordinator = new PersistenceCoordinator<never>(this.ctx, this)
   }
@@ -96,20 +94,19 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     return this.coordinator.load(id)
   }
 
+  inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.inspect(id)
+  }
+
   // --- PersistenceBackend hooks (the Map storage primitives) ---
 
-  // A Map-backed store has no torn tails, so `tornMarker` is never set. Ids are
-  // globally unique, so loadStored and loadLive are identical (cwd is ignored).
+  // A Map-backed store has no torn tails, so `tornMarker` is never set.
   async loadStored(id: SessionId): Promise<StoredPrefix<never> | undefined> {
     const entry = this.store.get(id)
     if (!entry) return undefined
     return { meta: structuredClone(entry.meta), events: structuredClone(entry.events) }
   }
 
-  loadLive(id: SessionId, _cwd: string | undefined): Promise<StoredPrefix<never> | undefined> {
-    return this.loadStored(id)
-  }
-
   async appendBatch(m: SessionHeader, events: readonly SessionEvent[], _isMaterialized: boolean): Promise<void> {
     // Defense-in-depth: the coordinator already validates serializability, but a
     // durable store must reject non-JSON data at its own boundary too.
@@ -138,6 +135,13 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
   async list(): Promise<SessionHeader[]> {
     return [...this.store.values()].map(e => structuredClone(e.meta))
   }
+
+  async listSnapshots(): Promise<SessionPersistenceSnapshot[]> {
+    return [...this.store.values()].map(entry => ({
+      header: structuredClone(entry.meta),
+      revision: SessionPersistenceRevision(`events:${entry.events.length}`),
+    }))
+  }
 }
 
 /** Controllable storage primitive for serialization and retirement failure tests. */
@@ -147,6 +151,7 @@ class ControlledBackend implements PersistenceBackend<never> {
   readonly lifecycle: string[] = []
   appendAttempts = 0
   loadAttempts = 0
+  repairAttempts = 0
   beforeAppend?: (attempt: number) => Promise<void>
   beforeLoadStored?: (attempt: number) => Promise<void>
 
@@ -157,10 +162,6 @@ class ControlledBackend implements PersistenceBackend<never> {
     return { meta: structuredClone(entry.meta), events: structuredClone(entry.events) }
   }
 
-  loadLive(id: SessionId, _cwd: string | undefined): Promise<StoredPrefix<never> | undefined> {
-    return this.loadStored(id)
-  }
-
   async appendBatch(m: SessionHeader, events: readonly SessionEvent[], _isMaterialized: boolean): Promise<void> {
     const attempt = ++this.appendAttempts
     await this.beforeAppend?.(attempt)
@@ -172,7 +173,9 @@ class ControlledBackend implements PersistenceBackend<never> {
     }
   }
 
-  async commitRepair(_m: SessionHeader, _tornMarker: undefined, _closers: readonly SessionEvent[]): Promise<void> {}
+  async commitRepair(_m: SessionHeader, _tornMarker: undefined, _closers: readonly SessionEvent[]): Promise<void> {
+    this.repairAttempts += 1
+  }
 
   async list(): Promise<SessionHeader[]> {
     return [...this.store.values()].map(entry => structuredClone(entry.meta))
@@ -204,40 +207,176 @@ runCoordinatorContract('memory', async (): Promise<CoordinatorFixture> => {
   }
 })
 
+describe('PersistenceCoordinator eager writes', () => {
+  it('starts a follow-up batch for events admitted during an in-flight write', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const appendGate = Promise.withResolvers<boolean>()
+    backend.beforeAppend = async (attempt) => {
+      if (attempt === 1) await appendGate.promise
+    }
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+
+    try {
+      const session = ctx.sessions.create(SessionId('eager-follow-up'))
+      await ctx.sessions.flush(session)
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
+
+      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+      appendGate.resolve(true)
+
+      await vi.waitFor(() => {
+        expect(backend.appendAttempts).toBe(2)
+        expect(backend.store.get(session.id)?.events.map(event => event.seq)).toEqual([0, 1])
+      })
+    } finally {
+      appendGate.resolve(true)
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('retries a failed overlapping eager write at the explicit flush barrier', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const appendGate = Promise.withResolvers<boolean>()
+    backend.beforeAppend = async (attempt) => {
+      if (attempt === 1) {
+        await appendGate.promise
+        throw new Error('transient eager failure')
+      }
+    }
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+
+    try {
+      const session = ctx.sessions.create(SessionId('eager-flush-retry'))
+      await ctx.sessions.flush(session)
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
+
+      const barriers = [ctx.sessions.flush(session), ctx.sessions.flush(session)]
+      appendGate.resolve(true)
+
+      await expect(Promise.all(barriers)).resolves.toEqual([undefined, undefined])
+      expect(backend.appendAttempts).toBe(2)
+      expect(backend.store.get(session.id)?.events.map(event => event.seq)).toEqual([0, 1])
+    } finally {
+      appendGate.resolve(true)
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
+describe('PersistenceCoordinator stored identity', () => {
+  it('rejects a mismatched backend header before repair or state publication', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const requested = SessionId('requested')
+    backend.store.set(requested, {
+      meta: meta('different'),
+      events: [{
+        type: 'turn/start',
+        seq: 0,
+        time: 1,
+        data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+      }],
+    })
+    let coordinator!: PersistenceCoordinator<never>
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+    try {
+      await expect(coordinator.load(requested)).rejects.toThrow(/stored session identity mismatch/)
+      expect(backend.repairAttempts).toBe(0)
+      expect((coordinator as unknown as CoordinatorInternals).states.size).toBe(0)
+    } finally {
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('reserves a cold id across asynchronous storage repair', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const id = SessionId('cold-load-reservation')
+    const header = meta(id)
+    const start: SessionEvent = {
+      type: 'turn/start',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+    }
+    backend.store.set(id, { meta: header, events: [start] })
+    const loadGate = Promise.withResolvers<boolean>()
+    backend.beforeLoadStored = async () => { await loadGate.promise }
+    let coordinator!: PersistenceCoordinator<never>
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+
+    try {
+      const loading = coordinator.load(id)
+      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
+
+      await expect(ctx.plugin(Object.assign((inner: Context) => {
+        inner.sessions.create(id, { seed: [start], meta: header })
+      }, { inject: ['sessions'] }))).rejects.toThrow(/persisted history is loading/)
+      expect(ctx.sessions.get(id)).toBeUndefined()
+
+      loadGate.resolve(true)
+      const loaded = await loading
+      expect(loaded.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
+
+      const resumed = ctx.sessions.create(id, { seed: loaded.events, meta: loaded.meta })
+      await expect(ctx.sessions.flush(resumed)).resolves.toBeUndefined()
+    } finally {
+      loadGate.resolve(true)
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
 describe('PersistenceCoordinator retirement', () => {
   it('a retiring unmaterialized owner without buffered events releases its id', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const backend = new ControlledBackend()
-    let coordinator!: PersistenceCoordinator<never>
     const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend)
+      new PersistenceCoordinator(inner, backend)
     }, { inject: ['sessions'] }))
     const loadGate = Promise.withResolvers<boolean>()
+    backend.beforeLoadStored = async (attempt) => {
+      if (attempt === 1) await loadGate.promise
+    }
 
     try {
       const id = SessionId('retiring-lazy-owner')
-      let first!: Session
       const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
-        first = inner.sessions.create(id)
+        inner.sessions.create(id)
       }, { inject: ['sessions'] }))
-      await ctx.sessions.flush(first)
-
-      const baselineLoads = backend.loadAttempts
-      backend.beforeLoadStored = async () => { await loadGate.promise }
-      const blockingLoad = coordinator.load(id)
-      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(baselineLoads + 1) })
+      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
       await firstFiber.dispose()
 
       let reuse!: Session
       await ctx.plugin(Object.assign((inner: Context) => {
         reuse = inner.sessions.create(id)
       }, { inject: ['sessions'] }))
-      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(baselineLoads + 2) })
+      const reuseFlush = ctx.sessions.flush(reuse)
 
       loadGate.resolve(true)
-      await expect(blockingLoad).rejects.toThrow(/not found/)
-      await expect(ctx.sessions.flush(reuse)).resolves.toBeUndefined()
+      await expect(reuseFlush).resolves.toBeUndefined()
     } finally {
       loadGate.resolve(true)
       await backendFiber.dispose()
@@ -245,7 +384,45 @@ describe('PersistenceCoordinator retirement', () => {
     }
   })
 
-  it('a retiring owner with buffered events still rejects same-id reuse', async () => {
+  it('a replacement queued before retirement cleanup still collides with the live owner', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
+      new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+    const appendGate = Promise.withResolvers<boolean>()
+
+    try {
+      const id = SessionId('retiring-live-owner')
+      let first!: Session
+      const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
+        first = inner.sessions.create(id)
+      }, { inject: ['sessions'] }))
+      await ctx.sessions.flush(first)
+      backend.beforeAppend = async () => { await appendGate.promise }
+      first.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      first.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
+      await firstFiber.dispose()
+
+      let reuse!: Session
+      await ctx.plugin(Object.assign((inner: Context) => {
+        reuse = inner.sessions.create(id)
+      }, { inject: ['sessions'] }))
+      const reuseFlush = ctx.sessions.flush(reuse)
+
+      appendGate.resolve(true)
+      await expect(reuseFlush).rejects.toThrow(/bound to a different live session/)
+      expect(backend.store.get(id)?.events.map(event => event.seq)).toEqual([0, 1])
+    } finally {
+      appendGate.resolve(true)
+      await backendFiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('a racing cold load survives retirement cleanup and rejects same-id reuse', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const backend = new ControlledBackend()
@@ -253,6 +430,7 @@ describe('PersistenceCoordinator retirement', () => {
     const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
       coordinator = new PersistenceCoordinator(inner, backend)
     }, { inject: ['sessions'] }))
+    const appendGate = Promise.withResolvers<boolean>()
     const loadGate = Promise.withResolvers<boolean>()
 
     try {
@@ -262,27 +440,37 @@ describe('PersistenceCoordinator retirement', () => {
         first = inner.sessions.create(id)
       }, { inject: ['sessions'] }))
       await ctx.sessions.flush(first)
+      backend.beforeAppend = async () => { await appendGate.promise }
       first.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
       first.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-
+      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
+      await firstFiber.dispose()
       const baselineLoads = backend.loadAttempts
       backend.beforeLoadStored = async () => { await loadGate.promise }
-      const blockingLoad = coordinator.load(id)
+      const coldLoad = coordinator.load(id)
+
+      appendGate.resolve(true)
       await vi.waitFor(() => { expect(backend.loadAttempts).toBe(baselineLoads + 1) })
-      await firstFiber.dispose()
+
+      await expect(ctx.plugin(Object.assign((inner: Context) => {
+        inner.sessions.create(id)
+      }, { inject: ['sessions'] }))).rejects.toThrow(/persisted history is loading/)
+
+      loadGate.resolve(true)
+      await expect(coldLoad).resolves.toMatchObject({
+        events: [{ seq: 0 }, { seq: 1 }],
+      })
 
       let reuse!: Session
       await ctx.plugin(Object.assign((inner: Context) => {
         reuse = inner.sessions.create(id)
       }, { inject: ['sessions'] }))
-      await expect(ctx.sessions.flush(reuse)).rejects.toThrow(/bound to a different live session/)
-
-      loadGate.resolve(true)
-      await expect(blockingLoad).rejects.toThrow(/not found/)
+      await expect(ctx.sessions.flush(reuse)).rejects.toThrow(/id collision/)
       await vi.waitFor(() => {
         expect(backend.store.get(id)?.events.map(event => event.seq)).toEqual([0, 1])
       })
     } finally {
+      appendGate.resolve(true)
       loadGate.resolve(true)
       await backendFiber.dispose()
       await ctx.fiber.dispose()
@@ -346,8 +534,9 @@ describe('PersistenceCoordinator retirement', () => {
       coordinator = new PersistenceCoordinator(inner, backend)
     }, { inject: ['sessions'] }))
     const internals = coordinator as unknown as CoordinatorInternals
-    backend.beforeAppend = async (attempt) => {
-      if (attempt === 1) {
+    let retryEnabled = false
+    backend.beforeAppend = async () => {
+      if (!retryEnabled) {
         backend.lifecycle.push('append-failed')
         throw new Error('transient append failure')
       }
@@ -364,17 +553,18 @@ describe('PersistenceCoordinator retirement', () => {
       await sessionFiber.dispose()
 
       await vi.waitFor(() => {
-        expect(backend.appendAttempts).toBe(1)
-        expect(internals.retirements.size).toBe(0)
+        expect(backend.appendAttempts).toBeGreaterThanOrEqual(1)
+        expect([...internals.live.values()][0]?.pending).toEqual(expect.arrayContaining([
+          expect.objectContaining({ seq: 0 }),
+          expect.objectContaining({ seq: 1 }),
+        ]))
       })
-      expect([...internals.buffers.values()]).toEqual([expect.arrayContaining([
-        expect.objectContaining({ seq: 0 }),
-        expect.objectContaining({ seq: 1 }),
-      ])])
 
+      retryEnabled = true
       await backendFiber.dispose()
       expect(backend.store.get(SessionId('retry-retirement'))?.events.map(event => event.seq)).toEqual([0, 1])
-      expect(backend.lifecycle).toEqual(['append-failed', 'append-committed', 'close'])
+      expect(backend.lifecycle.at(-2)).toBe('append-committed')
+      expect(backend.lifecycle.at(-1)).toBe('close')
     } finally {
       await backendFiber.dispose()
       await ctx.fiber.dispose()
@@ -407,7 +597,8 @@ describe('PersistenceCoordinator retirement', () => {
       await sessionFiber.dispose()
       await vi.waitFor(() => {
         expect(backend.appendAttempts).toBe(1)
-        expect(internals.retirements.size).toBe(1)
+        expect(internals.live.size).toBe(1)
+        expect([...internals.live.values()][0]?.flush).toBeInstanceOf(Promise)
       })
 
       let disposed = false
@@ -426,6 +617,47 @@ describe('PersistenceCoordinator retirement', () => {
       await ctx.fiber.dispose()
     }
   })
+
+  it('backend teardown waits for a detached public append before close', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    let coordinator!: PersistenceCoordinator<never>
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+    const appendGate = Promise.withResolvers<boolean>()
+    backend.beforeAppend = async () => {
+      backend.lifecycle.push('append-started')
+      await appendGate.promise
+      backend.lifecycle.push('append-committed')
+    }
+
+    try {
+      const id = SessionId('inflight-public-append')
+      await coordinator.create(meta(id))
+      const append = coordinator.append(id, [{
+        type: 'turn/start',
+        seq: 0,
+        time: 1,
+        data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+      }])
+      await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
+
+      let disposed = false
+      const teardown = fiber.dispose().then(() => { disposed = true })
+      await Promise.resolve()
+      expect(disposed).toBe(false)
+
+      appendGate.resolve(true)
+      await Promise.all([append, teardown])
+      expect(backend.lifecycle).toEqual(['append-started', 'append-committed', 'close'])
+    } finally {
+      appendGate.resolve(true)
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
 })
 
 describe('SessionPersistence service registration', () => {
@@ -555,11 +787,9 @@ describe('SessionPersistence service registration', () => {
         expect(ctx.sessions.list()).toHaveLength(0)
         expect({
           states: coordinator.states.size,
-          buffers: coordinator.buffers.size,
+          live: coordinator.live.size,
           chains: coordinator.chains.size,
-          inits: coordinator.inits.size,
-          retirements: coordinator.retirements.size,
-        }).toEqual({ states: 0, buffers: 0, chains: 0, inits: 0, retirements: 0 })
+        }).toEqual({ states: 0, live: 0, chains: 0 })
       })
     } finally {
       await fiber.dispose()
diff --git a/packages/session-persistence/session-persistence/tsconfig.json b/packages/session-persistence/session-persistence/tsconfig.json
index cbd74a19e7..511e4475d8 100644
--- a/packages/session-persistence/session-persistence/tsconfig.json
+++ b/packages/session-persistence/session-persistence/tsconfig.json
@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../util/brand"
+    },
     {
       "path": "../../core/session"
     },
diff --git a/packages/session-query/README.md b/packages/session-query/README.md
index ec1ac6dd39..f79d35936c 100644
--- a/packages/session-query/README.md
+++ b/packages/session-query/README.md
@@ -1,9 +1,10 @@
 # session-query/ — session retrieval capability family
 
-Trusted exact reads and relationship traces over live and durable session logs. The family contains one interface package that owns `ctx.sessionQuery`, logical-corpus precedence, title folding, surface classification, bounded event reads, lineage, and direct event relationships.
+Trusted exact reads, relationship traces, provider-independent semantic filtering, and SQLite full-text search over live and durable session logs.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`session-query/`](session-query/README.md) | Logical-corpus title, event, lineage, and relationship reads | `ctx.sessionQuery` |
+| [`session-query/`](session-query/README.md) | Combined service contract with concrete logical-corpus reads, traces, and semantic filters plus abstract full-text methods | `ctx.sessionQuery` |
+| [`session-query-sqlite/`](session-query-sqlite/README.md) | Concrete service backend with SQLite FTS5 persistent bases and live overlays | `ctx.sessionQuery` |
 
-The family is independent of compaction: it reads canonical lineage, surface operations, and logged provenance but does not participate in compaction policy or execution. Full-text search remains a proposed SQLite package rather than a speculative provider seam in this interface package.
+The family is independent of compaction: it reads canonical lineage, surface operations, logged provenance, and semantic event text but does not participate in compaction policy or execution. One abstract service combines every query operation, and one concrete backend owns the full-text lifecycle without a provider registry or coordinator.
diff --git a/packages/session-query/session-query-sqlite/README.md b/packages/session-query/session-query-sqlite/README.md
new file mode 100644
index 0000000000..a2c48a669f
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/README.md
@@ -0,0 +1,51 @@
+# @deepseek-ai/dsh-session-query-sqlite
+
+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.
+
+## Search contract
+
+`searchSessions(request, exec?)` returns `SessionSearchHit` pages across the corpus; `searchEvents(request, exec?)` returns `SessionEventSearchHit` pages within one session. Queries are required, trimmed, whitespace-normalized literal phrases. FTS5 syntax such as quotes, `OR`, `NEAR`, and `*` is treated as data rather than executable MATCH syntax. Metadata filters are parameterized SQL predicates applied before ranking. To keep SQLite FTS5 MATCH in a supported outer-predicate context, cross-session requests may compile at most 14 combined session and event filter predicates; within-session requests may compile at most 13 filter predicates because the fixed target-session predicate consumes one slot. Each range endpoint compiles as one predicate. A request exceeding either predicate budget or SQLite's portable limit of 32,766 total bindings, including fixed query and pagination values, fails with `SESSION_QUERY_INVALID_FILTER` before statement preparation.
+
+Relevance is source-comparable across persistent and TEMP tables: actual FTS5 highlighted-match span count descending, then stored document code-point length ascending. Event time, session id where applicable, and seq break remaining ties. Cross-session results expose the selected event as `bestMatch`; both scopes derive whitespace-normalized plain text from FTS5 highlight positions and bound it in Unicode code points. Cursors are opaque branded values, bind to the normalized request and service instance, and fail when the relevant generation changes. A within-session cursor survives unrelated-session changes; a cross-session cursor does not.
+
+All three surfaces (`current`, `shadowed`, and `log-only`) are searchable by default. Pass a surface filter to narrow them.
+
+## Source and index lifecycle
+
+The service requires `ctx.sessions` and observes optional `ctx.sessionPersistence` dynamically. One serialized state machine compares source-qualified lightweight durable snapshot revisions, non-mutatingly inspects only new or changed logs, extracts shared semantic documents, reconciles changes transactionally, and runs the query. Session queries never invoke the persistence backend's crash-repairing `load()`; an owner attaching during inspection cannot mutate its log, and the stable-observation retry makes the result live-preferred. The TEMP live row still records persisted availability, and the durable base refreshes after that live owner detaches. Repeated queries and an unchanged same-store reopen perform no full durable-log inspection; switching stores, or observing new, changed, deleted, or externally load-repaired sources, reconciles on the next stable observation. Source or transaction failure commits nothing, and the next search retries.
+
+Persisted FTS rows live in a dedicated derived database. Connection-local TEMP tables hold live rows, which shadow the durable base for the same session and reveal it when the live owner disappears. Unmounting persistence hides durable rows without discarding the cache; remounting reconciles it. Closing or reopening the database drops every live overlay while retaining persisted rows.
+
+The database is disposable but reset is guarded: every recognized schema version rejects unknown user tables before mutating journal mode, and only a recognized incompatible schema containing derived tables rebuilds in place. An unrelated or canonical database is refused. Never point `path` at the session-persistence database. On filesystems with POSIX modes, missing directories and databases are created owner-only (`0700` and `0600` before the process umask), and SQLite sidecars inherit the database mode; existing modes are preserved. Exactly one service in one process owns a derived-index path; external writers or a second process are unsupported because generations and TEMP shadow state are connection-owned.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `path` | required | Dedicated derived-index SQLite path; `:memory:` is supported. Missing filesystem paths are created owner-only on POSIX filesystems. |
+| `journalMode` | `wal` | `wal`, `delete`, `truncate`, or `persist`. |
+| `defaultLimit` | `20` | Page size when a request omits `limit`; at most `Number.MAX_SAFE_INTEGER - 1`. |
+| `maxLimit` | `100` | Largest accepted request page size; at most `Number.MAX_SAFE_INTEGER - 1`. |
+| `snippetChars` | `240` | Maximum snippet length in Unicode code points. |
+| `readWindowMax` | `50` | Maximum `before` or `after` raw-event count for inherited `readEvent()`. |
+
+## 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.
+
+Abort signals stop queued work and caller waits around asynchronous source observation. Node's synchronous `DatabaseSync` API cannot interrupt a MATCH statement already executing on the JavaScript thread; the signal is checked immediately before and after the serialized observation/reconciliation boundary.
+
+## Model Experience
+
+None, as this trusted search backend returns hits only to callers and registers no model-facing prompt, schema, tool, or message.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No caller authorization** — this is a trusted context-wide service; a model tool or UI must enforce its own access policy.
+- **Synchronous query execution** — `DatabaseSync` blocks the JavaScript thread during MATCH execution and cannot interrupt a statement already running.
+- **Token recall, not arbitrary substrings** — the `unicode61` tokenizer does not match substrings inside a larger token; use `filterEvents()` for literal scans.
+- **Single-owner derived index** — one service in one process must own each index path; external writers and multi-process sharing are unsupported.
diff --git a/packages/session-query/session-query-sqlite/package.json b/packages/session-query/session-query-sqlite/package.json
new file mode 100644
index 0000000000..2d4758ba3e
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/package.json
@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-session-query-sqlite",
+  "description": "Concrete ctx.sessionQuery backend with SQLite FTS5 search",
+  "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",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
+    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/session-query/session-query-sqlite/src/index.ts b/packages/session-query/session-query-sqlite/src/index.ts
new file mode 100644
index 0000000000..5e795d4d2c
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/src/index.ts
@@ -0,0 +1,1001 @@
+/**
+ * Concrete session-query service with SQLite FTS5 over the live-preferred corpus.
+ *
+ * @module @deepseek-ai/dsh-session-query-sqlite
+ */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { DatabaseSync } from 'node:sqlite'
+import { Context, Service, type Fiber } from 'cordis'
+import z from 'schemastery'
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
+import type {
+  SessionPersistenceRevision,
+  SessionPersistenceSnapshot,
+} from '@deepseek-ai/dsh-session-persistence'
+import SessionQueryService, {
+  SESSION_QUERY_READ_WINDOW_MAX,
+  SessionQueryError,
+  SessionSearchCursor,
+  assertSessionHeadersCompatible,
+  buildSessionEventSearchDocuments,
+} from '@deepseek-ai/dsh-session-query'
+import type {
+  Config as SessionQueryConfig,
+  SessionEventSearchDocument,
+  SessionEventSearchHit,
+  SessionEventSearchRequest,
+  SessionSearchExecContext,
+  SessionSearchHit,
+  SessionSearchCursor as SessionSearchCursorValue,
+  SessionSearchPage,
+  SessionSearchRequest,
+} from '@deepseek-ai/dsh-session-query'
+import {
+  type JournalMode,
+  openSearchDatabase,
+} from './schema.ts'
+import {
+  type NormalizedEventRequest,
+  type NormalizedSessionRequest,
+  FTS_HIGHLIGHT_END,
+  FTS_HIGHLIGHT_START,
+  assertFts5OuterPredicateCount,
+  assertPortableBindingCount,
+  buildEventWhere,
+  buildSessionWhere,
+  makeSnippet,
+  normalizeEventRequest,
+  normalizeSessionRequest,
+  quoteFtsData,
+  requestFingerprint,
+  sanitizeFtsText,
+  SQLITE_MAX_PAGE_LIMIT,
+} from './query.ts'
+
+export {
+  SESSION_QUERY_SQLITE_APPLICATION_ID,
+  SESSION_QUERY_SQLITE_SCHEMA_VERSION,
+  type JournalMode,
+} from './schema.ts'
+
+/** Default result page size. */
+export const SESSION_QUERY_SQLITE_DEFAULT_LIMIT = 20
+/** Maximum accepted result page size. */
+export const SESSION_QUERY_SQLITE_MAX_LIMIT = 100
+/** Default maximum snippet length in Unicode code points. */
+export const SESSION_QUERY_SQLITE_SNIPPET_CHARS = 240
+
+// One transient source change gets a retry; repeated churn fails rather than monopolizing the queue.
+const STABLE_OBSERVATION_ATTEMPTS = 2
+
+/** Combined session-query configuration backed by SQLite full-text search. */
+export interface Config extends SessionQueryConfig {
+  /**
+   * Dedicated derived-index path; `:memory:` is supported for tests. Missing
+   * directories and database files are created owner-only on POSIX filesystems;
+   * existing modes are preserved.
+   */
+  path: string
+  /** 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
+}
+
+interface ResolvedConfig {
+  path: string
+  journalMode: JournalMode
+  defaultLimit: number
+  maxLimit: number
+  snippetChars: number
+  readWindowMax: number
+}
+
+interface ObservedSession {
+  header: SessionHeader
+  documents: SessionEventSearchDocument[]
+  fingerprint: string
+}
+
+interface ObservedPersistedSession {
+  header: SessionHeader
+  revision: SessionPersistenceRevision
+  loaded?: ObservedSession
+}
+
+interface PersistenceBinding {
+  readonly identity: symbol
+  readonly service?: SessionPersistence
+}
+
+interface Observation {
+  persistenceBinding: PersistenceBinding
+  persisted: Map<SessionId, ObservedPersistedSession>
+  live: Map<SessionId, ObservedSession>
+}
+
+interface IndexedPersistedRow {
+  id: string
+  revision: string
+  generation: number
+}
+
+interface IndexedLiveRow {
+  id: string
+  fingerprint: string
+  persisted: number
+  generation: number
+}
+
+interface SearchRow {
+  session_id: string
+  version: number
+  created_at: number
+  cwd: string | null
+  parent_session: string | null
+  seed_length: number | null
+  delegation_depth: number | null
+  live: number
+  persisted: number
+  seq: number
+  type: string
+  time: number
+  surface: string
+  marked_text: string
+  match_count: number
+  document_length: number
+}
+
+interface CursorPayload {
+  version: 1
+  instance: string
+  scope: 'sessions' | 'events'
+  fingerprint: string
+  generation: string
+  offset: number
+}
+
+/** Concrete SQLite owner of the combined `ctx.sessionQuery` service. */
+export class SessionQuerySqlite extends SessionQueryService {
+  static override inject = ['sessions']
+
+  static Config: z<Config> = z.object({
+    path: z.string().required(),
+    journalMode: z.union(['wal', 'delete', 'truncate', 'persist'] as const).default('wal'),
+    defaultLimit: z.number().step(1).min(1).max(SQLITE_MAX_PAGE_LIMIT).default(SESSION_QUERY_SQLITE_DEFAULT_LIMIT),
+    maxLimit: z.number().step(1).min(1).max(SQLITE_MAX_PAGE_LIMIT).default(SESSION_QUERY_SQLITE_MAX_LIMIT),
+    snippetChars: z.number().step(1).min(1).default(SESSION_QUERY_SQLITE_SNIPPET_CHARS),
+    readWindowMax: z.number().step(1).min(0).default(SESSION_QUERY_READ_WINDOW_MAX),
+  })
+
+  /** Validated and defaulted backend configuration. */
+  readonly config: ResolvedConfig
+
+  private readonly _instance = randomUUID()
+  private readonly _ready: Promise<void>
+  private _db: DatabaseSync | undefined
+  private _persistenceBinding: PersistenceBinding = { identity: Symbol() }
+  private _lastPersistenceIdentity: symbol | undefined
+  private _persistenceEpoch = 0
+  private _globalGeneration = 0
+  private _localGeneration = 0
+  private _tail: Promise<void> = Promise.resolve()
+  private _closed = false
+  private _closePromise: Promise<void> | undefined
+  private readonly _optionalPersistenceFiber: Fiber
+
+  constructor(ctx: Context, config: Config) {
+    // The assignment expression resolves before the base constructor can
+    // register `ctx.sessionQuery`; keep that same validated value afterward.
+    super(ctx, config = resolveConfig(config))
+    this.config = config as ResolvedConfig
+    this._ready = this._open()
+    this._optionalPersistenceFiber = ctx.inject(['sessionPersistence'], (childCtx: Context) => {
+      const service = childCtx.sessionPersistence
+      const binding = { identity: Symbol(), service }
+      this._persistenceBinding = binding
+      childCtx.effect(() => () => {
+        /* v8 ignore next -- a stale optional-service disposer cannot clear a replacement */
+        if (this._persistenceBinding !== binding) return
+        this._persistenceBinding = { identity: Symbol() }
+      }, 'sessionQuerySqlite.persistenceBinding')
+    })
+    ctx.effect(() => {
+      return () => this._optionalPersistenceFiber.dispose()
+    }, 'sessionQuerySqlite.optionalPersistence')
+    ctx.effect(() => async () => this.close(), 'sessionQuerySqlite.close')
+  }
+
+  /** Open the index before Cordis publishes this combined service as active. */
+  protected async [Service.init](): Promise<void> {
+    await this._ensureReady(undefined)
+  }
+
+  override async searchSessions(
+    request: SessionSearchRequest,
+    exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionSearchHit>> {
+    const normalized = normalizeSessionRequest(request, this.config)
+    const signal = exec?.signal
+    return this._serialized(signal, async () => {
+      await this._ensureReady(signal)
+      const persistenceBinding = await this._reconcile(signal)
+      assertNotAborted(signal)
+      const generation = String(this._globalGeneration)
+      const fingerprint = requestFingerprint(normalized)
+      const offset = normalized.cursor === undefined
+        ? 0
+        : decodeCursor(normalized.cursor, this._instance, 'sessions', fingerprint, generation)
+      const rows = this._querySessions(normalized, offset, persistenceBinding)
+      return page(rows, normalized.limit, row => this._sessionHit(row), cursorOffset => encodeCursor({
+        version: 1,
+        instance: this._instance,
+        scope: 'sessions',
+        fingerprint,
+        generation,
+        offset: cursorOffset,
+      }), offset)
+    })
+  }
+
+  override async searchEvents(
+    request: SessionEventSearchRequest,
+    exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionEventSearchHit>> {
+    const normalized = normalizeEventRequest(request, this.config)
+    const signal = exec?.signal
+    return this._serialized(signal, async () => {
+      await this._ensureReady(signal)
+      const persistenceBinding = await this._reconcile(signal)
+      assertNotAborted(signal)
+      const generation = this._targetGeneration(normalized.sessionId, persistenceBinding)
+      const fingerprint = requestFingerprint(normalized)
+      const offset = normalized.cursor === undefined
+        ? 0
+        : decodeCursor(normalized.cursor, this._instance, 'events', fingerprint, generation)
+      const rows = this._queryEvents(normalized, offset, persistenceBinding)
+      return page(rows, normalized.limit, row => this._eventHit(row), cursorOffset => encodeCursor({
+        version: 1,
+        instance: this._instance,
+        scope: 'events',
+        fingerprint,
+        generation,
+        offset: cursorOffset,
+      }), offset)
+    })
+  }
+
+  /** Close the database after every accepted operation reaches quiescence. */
+  close(): Promise<void> {
+    this._closePromise ??= this._close()
+    return this._closePromise
+  }
+
+  private async _close(): Promise<void> {
+    this._closed = true
+    await this._tail
+    try {
+      await this._ready
+    } catch {
+      // Opening already closed a partially-created handle; disposal only waits.
+    }
+    this._db?.close()
+    this._db = undefined
+  }
+
+  private async _open(): Promise<void> {
+    this._db = await openSearchDatabase(this.config.path, this.config.journalMode)
+    const state = this._db.prepare(
+      'SELECT global_generation FROM search_state WHERE singleton = 1',
+    ).get() as { global_generation: number }
+    this._globalGeneration = state.global_generation
+    this._localGeneration = state.global_generation
+  }
+
+  private async _ensureReady(signal: AbortSignal | undefined): Promise<void> {
+    try {
+      await waitWithAbort(this._ready, signal)
+    } catch (error: unknown) {
+      if (isAbort(error)) throw error
+      throw new SessionQueryError(
+        `session-search SQLite index failed to open: ${errorMessage(error)}`,
+        'SESSION_QUERY_INDEX_FAILED',
+        { cause: error },
+      )
+    }
+  }
+
+  private async _serialized<T>(signal: AbortSignal | undefined, operation: () => Promise<T>): Promise<T> {
+    if (this._isClosed()) throw indexClosed()
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    const prior = this._tail
+    this._tail = prior.then(() => gate)
+    try {
+      await waitWithAbort(prior, signal)
+    } catch (error: unknown) {
+      release()
+      throw error
+    }
+    if (this._isClosed()) {
+      release()
+      throw indexClosed()
+    }
+    try {
+      assertNotAborted(signal)
+      return await operation()
+    } finally {
+      release()
+    }
+  }
+
+  private async _reconcile(signal: AbortSignal | undefined): Promise<PersistenceBinding> {
+    const db = this._requireDb()
+    const persistedRows = db.prepare(
+      'SELECT id, revision, generation FROM persisted_sessions',
+    ).all() as unknown as IndexedPersistedRow[]
+    const liveRows = db.prepare(
+      'SELECT id, fingerprint, persisted, generation FROM temp.live_sessions',
+    ).all() as unknown as IndexedLiveRow[]
+    const persistedById = new Map(persistedRows.map(row => [row.id as SessionId, row]))
+    const liveById = new Map(liveRows.map(row => [row.id as SessionId, row]))
+    const observation = await this._observeStable(persistedById, signal)
+    assertNotAborted(signal)
+    const persistentChanges = observation.persistenceBinding.service === undefined
+      ? []
+      : [...observation.persisted.values()].filter(entry => entry.loaded !== undefined)
+    const persistentDeletes = observation.persistenceBinding.service === undefined
+      ? []
+      : persistedRows.filter(row => !observation.persisted.has(row.id as SessionId))
+    const liveChanges = [...observation.live.values()].filter((entry) => {
+      const indexed = liveById.get(entry.header.id)
+      const persisted = observation.persisted.has(entry.header.id) ? 1 : 0
+      return indexed?.fingerprint !== entry.fingerprint || indexed.persisted !== persisted
+    })
+    const liveDeletes = liveRows.filter(row => !observation.live.has(row.id as SessionId))
+    const pointerChanged = this._lastPersistenceIdentity !== undefined
+      && this._lastPersistenceIdentity !== observation.persistenceBinding.identity
+    const hasWrites = persistentChanges.length > 0
+      || persistentDeletes.length > 0
+      || liveChanges.length > 0
+      || liveDeletes.length > 0
+
+    let nextMainGeneration = this._mainGeneration()
+    let nextLocalGeneration = this._localGeneration
+    if (persistentChanges.length > 0 || persistentDeletes.length > 0) nextMainGeneration += 1
+    const liveReplacements = liveChanges.map((entry) => {
+      nextLocalGeneration = Math.max(nextLocalGeneration, nextMainGeneration) + 1
+      return {
+        entry,
+        generation: nextLocalGeneration,
+        persisted: observation.persisted.has(entry.header.id),
+      }
+    })
+
+    if (hasWrites) {
+      let began = false
+      try {
+        db.exec('BEGIN IMMEDIATE')
+        began = true
+        for (const row of persistentDeletes) this._deleteSession('persisted', row.id as SessionId)
+        for (const entry of persistentChanges) {
+          /* v8 ignore next -- observation loads every entry whose revision differs */
+          if (entry.loaded === undefined) throw new Error(`missing loaded revision for session "${entry.header.id}"`)
+          this._replacePersistedSession(entry.loaded, entry.revision, nextMainGeneration)
+        }
+        if (persistentChanges.length > 0 || persistentDeletes.length > 0) {
+          db.prepare('UPDATE search_state SET global_generation = ? WHERE singleton = 1').run(nextMainGeneration)
+        }
+        for (const row of liveDeletes) this._deleteSession('live', row.id as SessionId)
+        for (const { entry, generation, persisted } of liveReplacements) {
+          this._replaceLiveSession(entry, generation, persisted)
+        }
+        db.exec('COMMIT')
+      } catch (error: unknown) {
+        /* v8 ignore next -- a BEGIN failure has no transaction to roll back; the common wrapper still reports it. */
+        if (began) {
+          /* v8 ignore next 5 -- ROLLBACK failure requires a SQLite double fault; the original failure remains actionable. */
+          try {
+            db.exec('ROLLBACK')
+          } catch {
+            // The original SQLite failure remains the actionable cause.
+          }
+        }
+        throw new SessionQueryError(
+          `session-search reconciliation failed: ${errorMessage(error)}`,
+          'SESSION_QUERY_INDEX_FAILED',
+          { cause: error },
+        )
+      }
+    }
+
+    if (hasWrites || pointerChanged) this._globalGeneration += 1
+    if (pointerChanged) this._persistenceEpoch += 1
+    this._localGeneration = nextLocalGeneration
+    this._lastPersistenceIdentity = observation.persistenceBinding.identity
+    return observation.persistenceBinding
+  }
+
+  private async _observeStable(
+    indexed: ReadonlyMap<SessionId, IndexedPersistedRow>,
+    signal: AbortSignal | undefined,
+  ): Promise<Observation> {
+    for (let attempt = 0; attempt < STABLE_OBSERVATION_ATTEMPTS; attempt += 1) {
+      assertNotAborted(signal)
+      const persistenceBinding = this._persistenceBinding
+      const persistence = persistenceBinding.service
+      const initiallyLive = new Set(this.ctx.sessions.list().map(session => session.id))
+      let persisted = new Map<SessionId, ObservedPersistedSession>()
+      if (persistence !== undefined) {
+        try {
+          const canReuseIndexed = this._lastPersistenceIdentity === undefined
+            || this._lastPersistenceIdentity === persistenceBinding.identity
+          const before = await waitWithAbort(persistence.listSnapshots(), signal)
+          persisted = materializePersistenceSnapshots(before)
+          for (const entry of persisted.values()) {
+            if (canReuseIndexed && indexed.get(entry.header.id)?.revision === entry.revision) continue
+            // Skip work already shadowed by a live owner. `inspect()` is
+            // non-mutating, so an owner attaching after this check cannot cause
+            // crash-repair side effects; the live-membership retry below makes
+            // the returned observation live-preferred.
+            if (initiallyLive.has(entry.header.id) || this.ctx.sessions.get(entry.header.id) !== undefined) continue
+            const loaded = await waitWithAbort(persistence.inspect(entry.header.id), signal)
+            assertSessionHeadersCompatible(entry.header, loaded.meta)
+            entry.loaded = observeSession(loaded.meta, loaded.events)
+          }
+          const after = materializePersistenceSnapshots(
+            await waitWithAbort(persistence.listSnapshots(), signal),
+          )
+          if (!samePersistenceSnapshots(persisted, after)) continue
+          if (this._persistenceBinding !== persistenceBinding) continue
+        } catch (error: unknown) {
+          if (isAbort(error) || signal?.aborted) {
+            throw new SessionQueryError('session-search aborted', 'SESSION_QUERY_ABORTED', {
+              cause: error,
+            })
+          }
+          if (this._persistenceBinding !== persistenceBinding) continue
+          if (error instanceof SessionQueryError) throw error
+          throw new SessionQueryError(
+            `session-search persistence observation failed: ${errorMessage(error)}`,
+            'SESSION_QUERY_PERSISTENCE_FAILED',
+            { cause: error },
+          )
+        }
+      }
+      const live = new Map<SessionId, ObservedSession>()
+      for (const session of this.ctx.sessions.list()) {
+        const observed = observeLive(session)
+        const durable = persisted.get(session.id)
+        if (durable !== undefined) assertSessionHeadersCompatible(observed.header, durable.header)
+        live.set(session.id, observed)
+      }
+      if (!sameSessionIds(initiallyLive, live)) continue
+      return { persistenceBinding, persisted, live }
+    }
+    throw new SessionQueryError(
+      'session-search persistence observation did not stabilize after one retry',
+      'SESSION_QUERY_PERSISTENCE_FAILED',
+    )
+  }
+
+  private _mainGeneration(): number {
+    const row = this._requireDb().prepare(
+      'SELECT global_generation FROM search_state WHERE singleton = 1',
+    ).get() as { global_generation: number }
+    return row.global_generation
+  }
+
+  private _deleteSession(source: 'persisted' | 'live', id: SessionId): void {
+    const db = this._requireDb()
+    if (source === 'persisted') {
+      db.prepare('DELETE FROM persisted_docs WHERE session_id = ?').run(id)
+      db.prepare('DELETE FROM persisted_sessions WHERE id = ?').run(id)
+    } else {
+      db.prepare('DELETE FROM temp.live_docs WHERE session_id = ?').run(id)
+      db.prepare('DELETE FROM temp.live_sessions WHERE id = ?').run(id)
+    }
+  }
+
+  private _replacePersistedSession(
+    entry: ObservedSession,
+    revision: SessionPersistenceRevision,
+    generation: number,
+  ): void {
+    this._deleteSession('persisted', entry.header.id)
+    const db = this._requireDb()
+    db.prepare(`
+      INSERT INTO persisted_sessions
+        (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, revision, generation)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      entry.header.id,
+      entry.header.version,
+      entry.header.createdAt,
+      entry.header.cwd ?? null,
+      entry.header.parentSession ?? null,
+      entry.header.seedLength ?? null,
+      entry.header.delegationDepth ?? null,
+      revision,
+      generation,
+    )
+    const insert = db.prepare(`
+      INSERT INTO persisted_docs (text, session_id, seq, type, time, surface, codepoint_length)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `)
+    for (const document of entry.documents) {
+      const text = sanitizeFtsText(document.text)
+      insert.run(
+        text,
+        document.sessionId,
+        document.seq,
+        document.type,
+        document.time,
+        document.surface,
+        Array.from(text).length,
+      )
+    }
+  }
+
+  private _replaceLiveSession(entry: ObservedSession, generation: number, persisted: boolean): void {
+    this._deleteSession('live', entry.header.id)
+    const db = this._requireDb()
+    db.prepare(`
+      INSERT INTO temp.live_sessions
+        (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, fingerprint, persisted, generation)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      entry.header.id,
+      entry.header.version,
+      entry.header.createdAt,
+      entry.header.cwd ?? null,
+      entry.header.parentSession ?? null,
+      entry.header.seedLength ?? null,
+      entry.header.delegationDepth ?? null,
+      entry.fingerprint,
+      persisted ? 1 : 0,
+      generation,
+    )
+    const insert = db.prepare(`
+      INSERT INTO temp.live_docs (text, session_id, seq, type, time, surface, codepoint_length)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `)
+    for (const document of entry.documents) {
+      const text = sanitizeFtsText(document.text)
+      insert.run(
+        text,
+        document.sessionId,
+        document.seq,
+        document.type,
+        document.time,
+        document.surface,
+        Array.from(text).length,
+      )
+    }
+  }
+
+  private _querySessions(
+    request: NormalizedSessionRequest,
+    offset: number,
+    persistenceBinding: PersistenceBinding,
+  ): SearchRow[] {
+    const selected = selectedDocumentsSql()
+    const sessionWhere = buildSessionWhere(request.sessionFilters)
+    const eventWhere = buildEventWhere(request.eventFilters)
+    assertFts5OuterPredicateCount(sessionWhere.predicateCount + eventWhere.predicateCount)
+    const where = [sessionWhere.sql, eventWhere.sql].filter(Boolean).join(' AND ')
+    const bindings = [
+      ...selectedDocumentsParams(request.query, persistenceBinding.service !== undefined),
+      ...sessionWhere.params,
+      ...eventWhere.params,
+      request.limit + 1,
+      offset,
+    ]
+    assertPortableBindingCount(bindings.length)
+    return this._requireDb().prepare(`
+      ${selected.sql},
+      filtered AS (
+        SELECT * FROM matched ${where.length === 0 ? '' : `WHERE ${where}`}
+      ),
+      ranked AS (
+        SELECT *, ROW_NUMBER() OVER (
+          PARTITION BY session_id
+          ORDER BY match_count DESC, document_length ASC, time DESC, seq DESC
+        ) AS event_rank
+        FROM filtered
+      )
+      SELECT * FROM ranked
+      WHERE event_rank = 1
+      ORDER BY match_count DESC, document_length ASC, time DESC, session_id ASC, seq DESC
+      LIMIT ? OFFSET ?
+    `).all(...bindings) as unknown as SearchRow[]
+  }
+
+  private _queryEvents(
+    request: NormalizedEventRequest,
+    offset: number,
+    persistenceBinding: PersistenceBinding,
+  ): SearchRow[] {
+    const selected = selectedDocumentsSql()
+    const eventWhere = buildEventWhere(request.filters)
+    assertFts5OuterPredicateCount(1 + eventWhere.predicateCount)
+    const where = ['session_id = ?', eventWhere.sql].filter(Boolean).join(' AND ')
+    const bindings = [
+      ...selectedDocumentsParams(request.query, persistenceBinding.service !== undefined),
+      request.sessionId,
+      ...eventWhere.params,
+      request.limit + 1,
+      offset,
+    ]
+    assertPortableBindingCount(bindings.length)
+    return this._requireDb().prepare(`
+      ${selected.sql}
+      SELECT * FROM matched
+      WHERE ${where}
+      ORDER BY match_count DESC, document_length ASC, time DESC, seq DESC
+      LIMIT ? OFFSET ?
+    `).all(...bindings) as unknown as SearchRow[]
+  }
+
+  private _targetGeneration(sessionId: SessionId, persistenceBinding: PersistenceBinding): string {
+    const db = this._requireDb()
+    const live = db.prepare(
+      'SELECT generation FROM temp.live_sessions WHERE id = ?',
+    ).get(sessionId) as { generation: number } | undefined
+    if (live !== undefined) return `live:${live.generation}`
+    if (persistenceBinding.service !== undefined) {
+      const persisted = db.prepare(
+        'SELECT generation FROM persisted_sessions WHERE id = ?',
+      ).get(sessionId) as { generation: number } | undefined
+      if (persisted !== undefined) return `persisted:${this._persistenceEpoch}:${persisted.generation}`
+    }
+    throw new SessionQueryError(
+      `session "${sessionId}" not found`,
+      'SESSION_QUERY_SESSION_NOT_FOUND',
+    )
+  }
+
+  private _sessionHit(row: SearchRow): SessionSearchHit {
+    return {
+      header: rowHeader(row),
+      live: row.live === 1,
+      persisted: row.persisted === 1,
+      bestMatch: this._eventHit(row),
+    }
+  }
+
+  private _eventHit(row: SearchRow): SessionEventSearchHit {
+    return {
+      sessionId: row.session_id as SessionId,
+      seq: row.seq,
+      type: row.type as SessionEventSearchHit['type'],
+      time: row.time,
+      surface: row.surface as SessionEventSearchHit['surface'],
+      snippet: makeSnippet(row.marked_text, this.config.snippetChars),
+    }
+  }
+
+  private _requireDb(): DatabaseSync {
+    /* v8 ignore next -- callers await `_ready`; this guards lifecycle misuse */
+    if (this._db === undefined) throw indexClosed()
+    return this._db
+  }
+
+  private _isClosed(): boolean {
+    return this._closed
+  }
+}
+
+function selectedDocumentsSql(): { sql: string } {
+  return {
+    sql: `WITH candidates AS (
+      SELECT
+        pd.session_id AS session_id,
+        ps.version AS version,
+        ps.created_at AS created_at,
+        ps.cwd AS cwd,
+        ps.parent_session AS parent_session,
+        ps.seed_length AS seed_length,
+        ps.delegation_depth AS delegation_depth,
+        0 AS live,
+        1 AS persisted,
+        CAST(pd.seq AS INTEGER) AS seq,
+        pd.type AS type,
+        CAST(pd.time AS INTEGER) AS time,
+        pd.surface AS surface,
+        highlight(persisted_docs, 0, ?, ?) AS marked_text,
+        CAST(pd.codepoint_length AS INTEGER) AS document_length
+      FROM persisted_docs AS pd
+      JOIN persisted_sessions AS ps ON ps.id = pd.session_id
+      WHERE persisted_docs MATCH ?
+        AND ? = 1
+        AND NOT EXISTS (SELECT 1 FROM temp.live_sessions AS ls WHERE ls.id = pd.session_id)
+      UNION ALL
+      SELECT
+        ld.session_id AS session_id,
+        ls.version AS version,
+        ls.created_at AS created_at,
+        ls.cwd AS cwd,
+        ls.parent_session AS parent_session,
+        ls.seed_length AS seed_length,
+        ls.delegation_depth AS delegation_depth,
+        1 AS live,
+        CASE WHEN ? = 1 THEN ls.persisted ELSE 0 END AS persisted,
+        CAST(ld.seq AS INTEGER) AS seq,
+        ld.type AS type,
+        CAST(ld.time AS INTEGER) AS time,
+        ld.surface AS surface,
+        highlight(live_docs, 0, ?, ?) AS marked_text,
+        CAST(ld.codepoint_length AS INTEGER) AS document_length
+      FROM temp.live_docs AS ld
+      JOIN temp.live_sessions AS ls ON ls.id = ld.session_id
+      WHERE live_docs MATCH ?
+    ), matched AS (
+      SELECT *,
+        (
+          length(CAST(marked_text AS BLOB))
+          - length(CAST(replace(marked_text, ?, '') AS BLOB))
+        ) / ? AS match_count
+      FROM candidates
+    )`,
+  }
+}
+
+function selectedDocumentsParams(query: string, persistenceVisible: boolean): Array<string | number> {
+  const expression = quoteFtsData(query)
+  const visible = persistenceVisible ? 1 : 0
+  return [
+    FTS_HIGHLIGHT_START,
+    FTS_HIGHLIGHT_END,
+    expression,
+    visible,
+    visible,
+    FTS_HIGHLIGHT_START,
+    FTS_HIGHLIGHT_END,
+    expression,
+    FTS_HIGHLIGHT_START,
+    Buffer.byteLength(FTS_HIGHLIGHT_START, 'utf8'),
+  ]
+}
+
+function observeLive(session: Session): ObservedSession {
+  return observeSession(session.header, session.events)
+}
+
+function observeSession(header: SessionHeader, events: readonly SessionEvent[]): ObservedSession {
+  const detachedHeader = structuredClone(header)
+  const detachedEvents = events.map(event => structuredClone(event))
+  return {
+    header: detachedHeader,
+    documents: buildSessionEventSearchDocuments(detachedHeader.id, detachedEvents),
+    fingerprint: createHash('sha256')
+      .update(JSON.stringify({ header: detachedHeader, events: detachedEvents }))
+      .digest('base64url'),
+  }
+}
+
+function materializePersistenceSnapshots(
+  snapshots: readonly SessionPersistenceSnapshot[],
+): Map<SessionId, ObservedPersistedSession> {
+  if (!isRuntimeArray(snapshots)) throw new Error('persistence snapshots must be an array')
+  const result = new Map<SessionId, ObservedPersistedSession>()
+  for (const snapshot of snapshots) {
+    if (typeof snapshot.revision !== 'string') {
+      throw new Error('persistence snapshot revision must be a string')
+    }
+    const header = structuredClone(snapshot.header)
+    if (result.has(header.id)) {
+      throw new Error(`persistence listed duplicate session "${header.id}"`)
+    }
+    result.set(header.id, { header, revision: snapshot.revision })
+  }
+  return result
+}
+
+function samePersistenceSnapshots(
+  before: ReadonlyMap<SessionId, ObservedPersistedSession>,
+  after: ReadonlyMap<SessionId, ObservedPersistedSession>,
+): boolean {
+  if (before.size !== after.size) return false
+  for (const [id, first] of before) {
+    const second = after.get(id)
+    if (
+      second === undefined
+      || first.revision !== second.revision
+      || !sameHeader(first.header, second.header)
+    ) return false
+  }
+  return true
+}
+
+function sameSessionIds(
+  before: ReadonlySet<SessionId>,
+  after: ReadonlyMap<SessionId, ObservedSession>,
+): boolean {
+  if (before.size !== after.size) return false
+  for (const id of before) {
+    if (!after.has(id)) return false
+  }
+  return true
+}
+
+function sameHeader(a: SessionHeader, b: SessionHeader): boolean {
+  return a.version === b.version
+    && a.id === b.id
+    && a.createdAt === b.createdAt
+    && a.cwd === b.cwd
+    && a.parentSession === b.parentSession
+    && a.seedLength === b.seedLength
+    && (a.delegationDepth ?? 0) === (b.delegationDepth ?? 0)
+}
+
+function rowHeader(row: SearchRow): SessionHeader {
+  return {
+    version: row.version,
+    id: row.session_id as SessionId,
+    createdAt: row.created_at,
+    ...row.cwd === null ? {} : { cwd: row.cwd },
+    ...row.parent_session === null ? {} : { parentSession: row.parent_session as SessionId },
+    ...row.seed_length === null ? {} : { seedLength: row.seed_length },
+    ...row.delegation_depth === null ? {} : { delegationDepth: row.delegation_depth },
+  }
+}
+
+function page<Row, Item>(
+  rows: readonly Row[],
+  limit: number,
+  convert: (row: Row) => Item,
+  nextCursor: (offset: number) => SessionSearchCursorValue,
+  offset: number,
+): SessionSearchPage<Item> {
+  const hasMore = rows.length > limit
+  return {
+    items: rows.slice(0, limit).map(convert),
+    ...hasMore ? { nextCursor: nextCursor(offset + limit) } : {},
+  }
+}
+
+function encodeCursor(payload: CursorPayload): SessionSearchCursorValue {
+  return SessionSearchCursor(Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url'))
+}
+
+function decodeCursor(
+  cursor: SessionSearchCursorValue,
+  instance: string,
+  scope: CursorPayload['scope'],
+  fingerprint: string,
+  generation: string,
+): number {
+  let decoded: Partial<CursorPayload>
+  try {
+    decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as Partial<CursorPayload>
+  } catch (error: unknown) {
+    throw invalidCursor(error)
+  }
+  if (
+    decoded.version !== 1
+    || decoded.instance !== instance
+    || decoded.scope !== scope
+    || decoded.fingerprint !== fingerprint
+    || !Number.isSafeInteger(decoded.offset)
+    || decoded.offset === undefined
+    || decoded.offset < 0
+  ) {
+    throw invalidCursor(new Error('cursor does not belong to this normalized request'))
+  }
+  if (decoded.generation !== generation) {
+    throw new SessionQueryError(
+      'session-search cursor is stale because its relevant corpus changed',
+      'SESSION_QUERY_STALE_CURSOR',
+    )
+  }
+  return decoded.offset
+}
+
+function invalidCursor(cause: unknown): SessionQueryError {
+  return new SessionQueryError(
+    'session-search cursor is invalid',
+    'SESSION_QUERY_INVALID_CURSOR',
+    { cause },
+  )
+}
+
+function resolveConfig(config: Config): ResolvedConfig {
+  const resolved: ResolvedConfig = {
+    path: config.path,
+    journalMode: config.journalMode ?? 'wal',
+    defaultLimit: config.defaultLimit ?? SESSION_QUERY_SQLITE_DEFAULT_LIMIT,
+    maxLimit: config.maxLimit ?? SESSION_QUERY_SQLITE_MAX_LIMIT,
+    snippetChars: config.snippetChars ?? SESSION_QUERY_SQLITE_SNIPPET_CHARS,
+    readWindowMax: config.readWindowMax ?? SESSION_QUERY_READ_WINDOW_MAX,
+  }
+  if (typeof resolved.path !== 'string' || resolved.path.trim().length === 0) {
+    throw invalidConfig('path must not be blank')
+  }
+  assertPageLimit('defaultLimit', resolved.defaultLimit)
+  assertPageLimit('maxLimit', resolved.maxLimit)
+  assertPositiveInteger('snippetChars', resolved.snippetChars)
+  if (!Number.isInteger(resolved.readWindowMax) || resolved.readWindowMax < 0) {
+    throw invalidConfig('readWindowMax must be a non-negative integer')
+  }
+  if (resolved.defaultLimit > resolved.maxLimit) {
+    throw invalidConfig('defaultLimit must be less than or equal to maxLimit')
+  }
+  const journalModes: readonly string[] = ['wal', 'delete', 'truncate', 'persist']
+  if (!journalModes.includes(resolved.journalMode)) throw invalidConfig('journalMode is not supported')
+  return resolved
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1) throw invalidConfig(`${name} must be a positive integer`)
+}
+
+function assertPageLimit(name: string, value: number): void {
+  if (!Number.isSafeInteger(value) || value < 1 || value > SQLITE_MAX_PAGE_LIMIT) {
+    throw invalidConfig(`${name} must be an integer between 1 and ${SQLITE_MAX_PAGE_LIMIT}`)
+  }
+}
+
+function invalidConfig(detail: string): SessionQueryError {
+  return new SessionQueryError(
+    `session-search SQLite config: ${detail}`,
+    'SESSION_QUERY_INVALID_CONFIG',
+  )
+}
+
+function indexClosed(): SessionQueryError {
+  return new SessionQueryError('session-search SQLite index is closed', 'SESSION_QUERY_INDEX_FAILED')
+}
+
+function assertNotAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new SessionQueryError('session-search aborted', 'SESSION_QUERY_ABORTED')
+  }
+}
+
+function waitWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return promise
+  if (signal.aborted) return Promise.reject(new SessionQueryError('session-search aborted', 'SESSION_QUERY_ABORTED'))
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      reject(new SessionQueryError('session-search aborted', 'SESSION_QUERY_ABORTED'))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(asError(error))
+      },
+    )
+  })
+}
+
+function isAbort(error: unknown): boolean {
+  return error instanceof SessionQueryError && error.code === 'SESSION_QUERY_ABORTED'
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error
+    ? error
+    : new Error('session-search dependency rejected with a non-Error value', { cause: error })
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : 'unknown error'
+}
+
+function isRuntimeArray(value: unknown): boolean {
+  return Array.isArray(value)
+}
+
+export default SessionQuerySqlite
diff --git a/packages/session-query/session-query-sqlite/src/invariant.ts b/packages/session-query/session-query-sqlite/src/invariant.ts
new file mode 100644
index 0000000000..011b121eaf
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-query-sqlite`.
+ * @module @deepseek-ai/dsh-session-query-sqlite/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-query-sqlite'
+
+/** Cordis companion plugin name. */
+export const name = 'session-query-sqlite-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: reconciliation, cursor generations, and derived-index
+ * ownership are validated at each serialized query boundary.
+ */
+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/session-query/session-query-sqlite/src/query.ts b/packages/session-query/session-query-sqlite/src/query.ts
new file mode 100644
index 0000000000..5a67653911
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/src/query.ts
@@ -0,0 +1,477 @@
+/** Request normalization, parameterized predicates, and result presentation. */
+
+import {
+  SessionQueryError,
+  materializeSessionEventResultFilters,
+  materializeSessionResultFilters,
+} from '@deepseek-ai/dsh-session-query'
+import type {
+  SessionAvailability,
+  SessionEventMetadataFilter,
+  SessionEventResultFilter,
+  SessionEventSearchRequest,
+  SessionResultFilter,
+  SessionSearchCursor,
+  SessionSearchRequest,
+} from '@deepseek-ai/dsh-session-query'
+
+/** Collision-free marker inserted before an FTS5 match by `highlight()`. */
+export const FTS_HIGHLIGHT_START = '\uFDD0'
+/** Collision-free marker inserted after an FTS5 match by `highlight()`. */
+export const FTS_HIGHLIGHT_END = '\uFDD1'
+
+/** Largest page size whose internal lookahead remains an exact SQLite integer binding. */
+export const SQLITE_MAX_PAGE_LIMIT = Number.MAX_SAFE_INTEGER - 1
+
+/** Portable host-parameter ceiling shared by predicate and statement builders. */
+export const SQLITE_PORTABLE_VARIABLE_LIMIT = 32_766
+
+/** Supported outer-predicate budget that keeps SQLite FTS5 MATCH usable. */
+export const SQLITE_FTS5_OUTER_PREDICATE_LIMIT = 14
+
+/**
+ * Reject prospective SQLite binding growth beyond the portable ceiling.
+ * @param count - binding count at the current construction boundary.
+ */
+export function assertPortableBindingCount(count: number): void {
+  if (count > SQLITE_PORTABLE_VARIABLE_LIMIT) {
+    throw new SessionQueryError(
+      `session-search request exceeds SQLite's portable ${SQLITE_PORTABLE_VARIABLE_LIMIT}-variable limit; reduce filter values`,
+      'SESSION_QUERY_INVALID_FILTER',
+    )
+  }
+}
+
+/**
+ * Reject compiled outer predicates beyond the supported FTS5 planner budget.
+ * @param count - predicate count including fixed statement predicates.
+ */
+export function assertFts5OuterPredicateCount(count: number): void {
+  if (count > SQLITE_FTS5_OUTER_PREDICATE_LIMIT) {
+    throw new SessionQueryError(
+      `session-search request exceeds the supported SQLite FTS5 outer-predicate budget of ${SQLITE_FTS5_OUTER_PREDICATE_LIMIT}; reduce filters`,
+      'SESSION_QUERY_INVALID_FILTER',
+    )
+  }
+}
+
+/** Limit defaults needed to normalize a search request. */
+export interface QueryLimits {
+  /** Page size used when the request omits one. */
+  defaultLimit: number
+  /** Largest accepted page size. */
+  maxLimit: number
+}
+
+/** Normalized cross-session request. */
+export interface NormalizedSessionRequest {
+  query: string
+  sessionFilters: readonly SessionResultFilter[]
+  eventFilters: readonly SessionEventMetadataFilter[]
+  limit: number
+  cursor?: SessionSearchCursor
+}
+
+/** Normalized within-session request. */
+export interface NormalizedEventRequest {
+  sessionId: SessionEventSearchRequest['sessionId']
+  query: string
+  filters: readonly SessionEventMetadataFilter[]
+  limit: number
+  cursor?: SessionSearchCursor
+}
+
+/** Parameterized SQL predicate fragment. */
+export interface SqlWhere {
+  /** SQL without the leading `WHERE`. */
+  sql: string
+  /** Bindings in placeholder order. */
+  params: Array<string | number>
+  /** Number of compiled predicates in `sql`. */
+  predicateCount: number
+}
+
+/**
+ * Validate and canonicalize a cross-session request.
+ * @param request - caller-provided query, filters, limit, and cursor.
+ * @param limits - configured default and maximum page sizes.
+ * @returns normalized request with explicit arrays and limit.
+ */
+export function normalizeSessionRequest(
+  request: SessionSearchRequest,
+  limits: QueryLimits,
+): NormalizedSessionRequest {
+  const sessionFilters = materializeSessionResultFilters(request.sessionFilters ?? [])
+  const eventFilters = materializeMetadataFilters(request.eventFilters ?? [])
+  const cursor = materializeCursor(request.cursor)
+  return {
+    query: normalizeQuery(request.query),
+    sessionFilters,
+    eventFilters,
+    limit: normalizeLimit(request.limit, limits),
+    ...cursor === undefined ? {} : { cursor },
+  }
+}
+
+/**
+ * Validate and canonicalize a within-session request.
+ * @param request - caller-provided target, query, filters, limit, and cursor.
+ * @param limits - configured default and maximum page sizes.
+ * @returns normalized request with an explicit filter array and limit.
+ */
+export function normalizeEventRequest(
+  request: SessionEventSearchRequest,
+  limits: QueryLimits,
+): NormalizedEventRequest {
+  if (typeof request.sessionId !== 'string') {
+    throw new SessionQueryError('session-search session id must be text', 'SESSION_QUERY_INVALID_FILTER')
+  }
+  const filters = materializeMetadataFilters(request.filters ?? [])
+  const cursor = materializeCursor(request.cursor)
+  return {
+    sessionId: request.sessionId,
+    query: normalizeQuery(request.query),
+    filters,
+    limit: normalizeLimit(request.limit, limits),
+    ...cursor === undefined ? {} : { cursor },
+  }
+}
+
+/**
+ * Compile logical-session predicates against selected-document columns.
+ * @param filters - validated ANDed logical-session clauses.
+ * @returns parameterized SQL fragment and ordered bindings.
+ */
+export function buildSessionWhere(filters: readonly SessionResultFilter[]): SqlWhere {
+  const clauses: string[] = []
+  const params: Array<string | number> = []
+  for (const filter of filters) {
+    switch (filter.kind) {
+      case 'id':
+        addList(clauses, params, 'session_id', filter.values)
+        break
+      case 'cwd':
+        addNullableList(clauses, params, 'cwd', filter.values)
+        break
+      case 'created-at':
+        addRange(clauses, params, 'created_at', filter)
+        break
+      case 'parent':
+        addNullableList(clauses, params, 'parent_session', filter.values)
+        break
+      case 'availability': {
+        const availability = [...new Set(filter.values)]
+        if (availability.length === 0) clauses.push('0')
+        else if (availability.length === 1) {
+          const value = availability[0] as SessionAvailability
+          switch (value) {
+            case 'live':
+              clauses.push('live = 1')
+              break
+            case 'persisted':
+              clauses.push('persisted = 1')
+              break
+            default:
+              unknownAvailability(value)
+          }
+        }
+        break
+      }
+      default:
+        unknownFilter(filter)
+    }
+  }
+  assertFts5OuterPredicateCount(clauses.length)
+  return { sql: clauses.join(' AND '), params, predicateCount: clauses.length }
+}
+
+/**
+ * Compile event metadata predicates against selected-document columns.
+ * @param filters - validated ANDed event metadata clauses.
+ * @returns parameterized SQL fragment and ordered bindings.
+ */
+export function buildEventWhere(filters: readonly SessionEventMetadataFilter[]): SqlWhere {
+  const clauses: string[] = []
+  const params: Array<string | number> = []
+  for (const filter of filters) {
+    switch (filter.kind) {
+      case 'seq':
+        addRange(clauses, params, 'seq', filter)
+        break
+      case 'time':
+        addRange(clauses, params, 'time', filter)
+        break
+      case 'type':
+        addList(clauses, params, 'type', filter.values)
+        break
+      case 'surface':
+        addList(clauses, params, 'surface', filter.values)
+        break
+      default:
+        unknownFilter(filter)
+    }
+  }
+  assertFts5OuterPredicateCount(clauses.length)
+  return { sql: clauses.join(' AND '), params, predicateCount: clauses.length }
+}
+
+/**
+ * Quote caller text as one FTS5 phrase so query syntax remains inert data.
+ * @param query - normalized caller query.
+ * @returns FTS5 expression containing one escaped literal phrase.
+ */
+export function quoteFtsData(query: string): string {
+  return `"${query.replaceAll('"', '""')}"`
+}
+
+/**
+ * Remove reserved marker collisions before text enters FTS5 or MATCH.
+ * @param text - extracted document text or normalized caller query.
+ * @returns text with reserved noncharacters mapped to replacement characters.
+ */
+export function sanitizeFtsText(text: string): string {
+  return text
+    .replaceAll('\0', '\uFFFD')
+    .replaceAll(FTS_HIGHLIGHT_START, '\uFFFD')
+    .replaceAll(FTS_HIGHLIGHT_END, '\uFFFD')
+}
+
+/**
+ * Build the stable normalized request identity stored in opaque cursors.
+ * @param request - normalized request whose filter ordering is canonicalized.
+ * @returns deterministic JSON identity for cursor binding.
+ */
+export function requestFingerprint(request: NormalizedSessionRequest | NormalizedEventRequest): string {
+  if ('sessionId' in request) {
+    return JSON.stringify({
+      scope: 'events',
+      sessionId: request.sessionId,
+      query: request.query,
+      filters: canonicalFilters(request.filters),
+      limit: request.limit,
+    })
+  }
+  return JSON.stringify({
+    scope: 'sessions',
+    query: request.query,
+    sessionFilters: canonicalFilters(request.sessionFilters),
+    eventFilters: canonicalFilters(request.eventFilters),
+    limit: request.limit,
+  })
+}
+
+/**
+ * Build a whitespace-normalized excerpt no longer than `maxChars`.
+ * @param markedText - complete document with FTS5 `highlight()` markers.
+ * @param maxChars - maximum result length in Unicode code points.
+ * @returns bounded plain-text snippet.
+ */
+export function makeSnippet(markedText: string, maxChars: number): string {
+  const { text: clean, matchStart } = normalizeMarkedText(markedText)
+  const characters = Array.from(clean)
+  if (characters.length <= maxChars) return clean
+  if (maxChars === 1) return '…'
+  const matchedIndex = Math.min(matchStart, characters.length - 1)
+  let start = Math.max(0, matchedIndex - Math.floor(maxChars / 3))
+  const prefix = start > 0 ? '…' : ''
+  let suffix = '…'
+  let contentLength = maxChars - prefix.length - suffix.length
+  if (contentLength < 1) {
+    start = matchedIndex
+    suffix = ''
+    contentLength = maxChars - prefix.length - suffix.length
+  } else if (matchedIndex >= start + contentLength) {
+    start = matchedIndex - contentLength + 1
+  }
+  let end = Math.min(characters.length, start + contentLength)
+  if (end === characters.length) {
+    suffix = ''
+    contentLength = maxChars - prefix.length
+    start = Math.max(0, end - contentLength)
+  }
+  end = Math.min(characters.length, start + contentLength)
+  return `${prefix}${characters.slice(start, end).join('')}${suffix}`
+}
+
+function normalizeMarkedText(markedText: string): { text: string; matchStart: number } {
+  const characters: string[] = []
+  let matchStart: number | undefined
+  for (const character of markedText) {
+    if (character === FTS_HIGHLIGHT_START) {
+      matchStart ??= characters.length
+      continue
+    }
+    if (character === FTS_HIGHLIGHT_END) continue
+    if (/\s/u.test(character)) {
+      if (characters.length > 0 && characters.at(-1) !== ' ') characters.push(' ')
+    } else {
+      characters.push(character)
+    }
+  }
+  if (characters.at(-1) === ' ') characters.pop()
+  return {
+    text: characters.join(''),
+    matchStart: matchStart ?? 0,
+  }
+}
+
+function normalizeQuery(value: string): string {
+  if (typeof value !== 'string') {
+    throw new SessionQueryError('session-search query must be text', 'SESSION_QUERY_INVALID_QUERY')
+  }
+  const query = value.trim().replace(/\s+/gu, ' ')
+  if (query.length === 0) {
+    throw new SessionQueryError(
+      'session-search query must contain non-whitespace text',
+      'SESSION_QUERY_INVALID_QUERY',
+    )
+  }
+  if (query.includes('\0')) {
+    throw new SessionQueryError(
+      'session-search query must not contain NUL',
+      'SESSION_QUERY_INVALID_QUERY',
+    )
+  }
+  return sanitizeFtsText(query)
+}
+
+function materializeCursor(cursor: SessionSearchCursor | undefined): SessionSearchCursor | undefined {
+  if (cursor === undefined) return undefined
+  if (typeof cursor !== 'string') {
+    throw new SessionQueryError('session-search cursor must be text', 'SESSION_QUERY_INVALID_CURSOR')
+  }
+  return cursor
+}
+
+function materializeMetadataFilters(
+  filters: readonly SessionEventMetadataFilter[],
+): SessionEventMetadataFilter[] {
+  const candidates: readonly SessionEventResultFilter[] = filters
+  for (const filter of candidates) {
+    switch (filter.kind) {
+      case 'seq':
+      case 'time':
+      case 'type':
+      case 'surface':
+        break
+      case 'text':
+        throw new SessionQueryError(
+          'session-search metadata filters do not accept text clauses',
+          'SESSION_QUERY_INVALID_FILTER',
+        )
+      default:
+        unknownFilter(filter)
+    }
+  }
+  return materializeSessionEventResultFilters(filters) as SessionEventMetadataFilter[]
+}
+
+function normalizeLimit(value: number | undefined, limits: QueryLimits): number {
+  const limit = value ?? limits.defaultLimit
+  const maxLimit = Math.min(limits.maxLimit, SQLITE_MAX_PAGE_LIMIT)
+  if (
+    !Number.isSafeInteger(limit)
+    || limit < 1
+    || limit > maxLimit
+  ) {
+    throw new SessionQueryError(
+      `session-search limit must be an integer between 1 and ${maxLimit}`,
+      'SESSION_QUERY_INVALID_LIMIT',
+    )
+  }
+  return limit
+}
+
+function addList(
+  clauses: string[],
+  params: Array<string | number>,
+  column: string,
+  values: readonly (string | number)[],
+): void {
+  if (values.length === 0) {
+    clauses.push('0')
+    return
+  }
+  clauses.push(`${column} IN (${appendListBindings(params, values)})`)
+}
+
+function addNullableList(
+  clauses: string[],
+  params: Array<string | number>,
+  column: string,
+  values: readonly (string | null)[],
+): void {
+  if (values.length === 0) {
+    clauses.push('0')
+    return
+  }
+  const concrete = values.filter((value): value is string => value !== null)
+  const parts: string[] = []
+  if (concrete.length > 0) {
+    parts.push(`${column} IN (${appendListBindings(params, concrete)})`)
+  }
+  if (values.includes(null)) parts.push(`${column} IS NULL`)
+  clauses.push(`(${parts.join(' OR ')})`)
+}
+
+function addRange(
+  clauses: string[],
+  params: Array<string | number>,
+  column: string,
+  range: { from?: number; to?: number },
+): void {
+  if (range.from !== undefined) {
+    assertPortableBindingCount(params.length + 1)
+    clauses.push(`CAST(${column} AS INTEGER) >= ?`)
+    params.push(range.from)
+  }
+  if (range.to !== undefined) {
+    assertPortableBindingCount(params.length + 1)
+    clauses.push(`CAST(${column} AS INTEGER) <= ?`)
+    params.push(range.to)
+  }
+}
+
+function appendListBindings(
+  params: Array<string | number>,
+  values: readonly (string | number)[],
+): string {
+  assertPortableBindingCount(params.length + values.length)
+  for (const value of values) params.push(value)
+  return values.map(() => '?').join(', ')
+}
+
+function canonicalFilters(filters: readonly (SessionResultFilter | SessionEventMetadataFilter)[]): unknown[] {
+  return filters.map((filter) => {
+    if ('values' in filter) {
+      return { ...filter, values: [...filter.values].sort(compareNullable) }
+    }
+    return {
+      kind: filter.kind,
+      from: filter.from ?? null,
+      to: filter.to ?? null,
+    }
+  }).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))
+}
+
+function compareNullable(a: string | null, b: string | null): number {
+  if (a === b) return 0
+  if (a === null) return -1
+  if (b === null) return 1
+  return a.localeCompare(b)
+}
+
+function unknownAvailability(value: never): never {
+  throw new SessionQueryError(
+    `session availability filter contains unknown value "${String(value)}"`,
+    'SESSION_QUERY_INVALID_FILTER',
+  )
+}
+
+function unknownFilter(filter: never): never {
+  const kind = (filter as { kind?: unknown }).kind
+  throw new SessionQueryError(
+    `session filter contains unknown kind ${typeof kind === 'string' ? `"${kind}"` : '(missing)'}`,
+    'SESSION_QUERY_INVALID_FILTER',
+  )
+}
diff --git a/packages/session-query/session-query-sqlite/src/schema.ts b/packages/session-query/session-query-sqlite/src/schema.ts
new file mode 100644
index 0000000000..47f6374ba6
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/src/schema.ts
@@ -0,0 +1,170 @@
+/** SQLite schema for the disposable session full-text read model. */
+
+import { DatabaseSync } from 'node:sqlite'
+import { mkdir, open } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+
+/** Current derived-index schema version. Incompatible versions reset in place. */
+export const SESSION_QUERY_SQLITE_SCHEMA_VERSION = 5
+
+/** SQLite application id protecting unrelated databases from derived resets. */
+export const SESSION_QUERY_SQLITE_APPLICATION_ID = 0x44534851
+
+/** Supported SQLite journal modes. */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+
+const DERIVED_USER_TABLES = new Set([
+  'search_state',
+  'persisted_sessions',
+  'persisted_docs',
+  'persisted_docs_data',
+  'persisted_docs_idx',
+  'persisted_docs_content',
+  'persisted_docs_docsize',
+  'persisted_docs_config',
+])
+
+/**
+ * Exclusively create a missing database file with owner-only permissions.
+ * Existing files retain their modes, and errors other than `EEXIST` propagate.
+ */
+async function createDatabaseFile(path: string): Promise<void> {
+  try {
+    const handle = await open(path, 'wx', 0o600)
+    await handle.close()
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+  }
+}
+
+/**
+ * Open, validate, and initialize persistent and connection-local schemas.
+ * @param path - dedicated derived-index path or `:memory:`; missing filesystem paths are created owner-only.
+ * @param journalMode - validated SQLite journal mode.
+ * @returns initialized database handle owned by the search service.
+ */
+export async function openSearchDatabase(path: string, journalMode: JournalMode): Promise<DatabaseSync> {
+  const actual = path === ':memory:' ? path : resolve(path)
+  if (actual !== ':memory:') {
+    await mkdir(dirname(actual), { recursive: true, mode: 0o700 })
+    await createDatabaseFile(actual)
+  }
+  const db = new DatabaseSync(actual)
+  try {
+    const { application_id: applicationId } = db.prepare('PRAGMA application_id').get() as { application_id: number }
+    const { user_version: version } = db.prepare('PRAGMA user_version').get() as { user_version: number }
+    const userTables = listUserTables(db)
+    if (applicationId !== 0 && applicationId !== SESSION_QUERY_SQLITE_APPLICATION_ID) {
+      throw new Error(`session-search database at "${actual}" belongs to another application`)
+    }
+    if (applicationId === 0 && userTables.length > 0) {
+      throw new Error(`session-search database at "${actual}" is not an empty or recognized derived index`)
+    }
+    if (applicationId === SESSION_QUERY_SQLITE_APPLICATION_ID) {
+      assertDerivedUserTables(actual, userTables)
+      if (version !== SESSION_QUERY_SQLITE_SCHEMA_VERSION) resetDerivedSchema(db, userTables)
+    }
+    // Apply mutating pragmas only after refusing foreign or canonical files.
+    // journalMode is a validated closed union, not caller-controlled SQL.
+    db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
+    ensurePersistentSchema(db)
+    ensureTemporarySchema(db)
+    return db
+  } catch (error: unknown) {
+    db.close()
+    throw error
+  }
+}
+
+function listUserTables(db: DatabaseSync): string[] {
+  const rows = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT GLOB 'sqlite_*' ORDER BY name",
+  ).all() as Array<{ name: string }>
+  return rows.map(row => row.name)
+}
+
+function assertDerivedUserTables(path: string, userTables: readonly string[]): void {
+  const unknownTables = userTables.filter(name => !DERIVED_USER_TABLES.has(name))
+  if (unknownTables.length > 0) {
+    throw new Error(
+      `session-search database at "${path}" has unrecognized user tables: ${unknownTables.join(', ')}`,
+    )
+  }
+}
+
+function resetDerivedSchema(db: DatabaseSync, userTables: readonly string[]): void {
+  for (const name of userTables) {
+    db.exec(`DROP TABLE IF EXISTS ${quoteIdentifier(name)}`)
+  }
+  db.exec('PRAGMA user_version = 0')
+}
+
+function ensurePersistentSchema(db: DatabaseSync): void {
+  db.exec(`PRAGMA application_id = ${SESSION_QUERY_SQLITE_APPLICATION_ID}`)
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS search_state (
+      singleton         INTEGER PRIMARY KEY CHECK (singleton = 1),
+      global_generation INTEGER NOT NULL
+    ) STRICT
+  `)
+  db.exec('INSERT OR IGNORE INTO search_state (singleton, global_generation) VALUES (1, 0)')
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS persisted_sessions (
+      id             TEXT PRIMARY KEY,
+      version        INTEGER NOT NULL,
+      created_at     INTEGER NOT NULL,
+      cwd            TEXT,
+      parent_session TEXT,
+      seed_length    INTEGER,
+      delegation_depth INTEGER,
+      revision       TEXT NOT NULL,
+      generation     INTEGER NOT NULL
+    ) STRICT
+  `)
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS persisted_docs USING fts5(
+      text,
+      session_id UNINDEXED,
+      seq UNINDEXED,
+      type UNINDEXED,
+      time UNINDEXED,
+      surface UNINDEXED,
+      codepoint_length UNINDEXED,
+      tokenize = 'unicode61'
+    )
+  `)
+  db.exec(`PRAGMA user_version = ${SESSION_QUERY_SQLITE_SCHEMA_VERSION}`)
+}
+
+function ensureTemporarySchema(db: DatabaseSync): void {
+  db.exec(`
+    CREATE TEMP TABLE IF NOT EXISTS live_sessions (
+      id             TEXT PRIMARY KEY,
+      version        INTEGER NOT NULL,
+      created_at     INTEGER NOT NULL,
+      cwd            TEXT,
+      parent_session TEXT,
+      seed_length    INTEGER,
+      delegation_depth INTEGER,
+      fingerprint    TEXT NOT NULL,
+      persisted      INTEGER NOT NULL CHECK (persisted IN (0, 1)),
+      generation     INTEGER NOT NULL
+    ) STRICT
+  `)
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS temp.live_docs USING fts5(
+      text,
+      session_id UNINDEXED,
+      seq UNINDEXED,
+      type UNINDEXED,
+      time UNINDEXED,
+      surface UNINDEXED,
+      codepoint_length UNINDEXED,
+      tokenize = 'unicode61'
+    )
+  `)
+}
+
+function quoteIdentifier(value: string): string {
+  return `"${value.replaceAll('"', '""')}"`
+}
diff --git a/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts b/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts
new file mode 100644
index 0000000000..200d171b50
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/tests/load-path.e2e.ts
@@ -0,0 +1,62 @@
+/**
+ * Keyless real-Loader-path smoke for the combined SQLite session-query service.
+ *
+ * @module @deepseek-ai/dsh-session-query-sqlite/tests/load-path
+ */
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
+import SessionQuerySqlite, * as queryModule from '@deepseek-ai/dsh-session-query-sqlite'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const temporaryDirectories: string[] = []
+
+afterEach(async () => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    await rm(directory, { recursive: true, force: true })
+  }
+})
+
+async function temporaryPath(name: string): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-session-search-loader-'))
+  temporaryDirectories.push(directory)
+  return join(directory, name)
+}
+
+describe('dsh-session-query-sqlite real Loader path', () => {
+  it('unwraps, mounts, and searches the real persistence backend', async () => {
+    const persistencePath = await temporaryPath('canonical.db')
+    const searchPath = await temporaryPath('derived.db')
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const persistence = await ctx.plugin(SessionPersistenceSqlite, { path: persistencePath })
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(queryModule) as Parameters<Context['plugin']>[0]
+    expect(unwrapped).toBe(SessionQuerySqlite)
+    const query = await ctx.plugin(unwrapped, { path: searchPath })
+
+    const id = SessionId('loader-path')
+    await ctx.sessionPersistence.create({ version: SESSION_FORMAT_VERSION, id, createdAt: 10 })
+    await ctx.sessionPersistence.append(id, [{
+      type: 'user/message',
+      seq: 0,
+      time: 10,
+      data: { content: [{ type: 'text', text: 'real Loader needle' }], source: { kind: 'user' } },
+      surfaceOp: 'append',
+    }])
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'Loader needle' }))
+      .resolves.toMatchObject({ items: [{ header: { id }, persisted: true, live: false }] })
+    await expect(ctx.sessionQuery.listSessions())
+      .resolves.toMatchObject([{ header: { id }, persisted: true, live: false }])
+    await query.dispose()
+    await persistence.dispose()
+  })
+})
diff --git a/packages/session-query/session-query-sqlite/tests/query.spec.ts b/packages/session-query/session-query-sqlite/tests/query.spec.ts
new file mode 100644
index 0000000000..b40489d429
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/tests/query.spec.ts
@@ -0,0 +1,262 @@
+import { describe, expect, it } from 'vitest'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionSearchCursor, type SessionQueryErrorCode } from '@deepseek-ai/dsh-session-query'
+import {
+  buildEventWhere,
+  buildSessionWhere,
+  FTS_HIGHLIGHT_END,
+  FTS_HIGHLIGHT_START,
+  makeSnippet,
+  normalizeEventRequest,
+  normalizeSessionRequest,
+  quoteFtsData,
+  requestFingerprint,
+  SQLITE_FTS5_OUTER_PREDICATE_LIMIT,
+  SQLITE_MAX_PAGE_LIMIT,
+  type NormalizedEventRequest,
+  type NormalizedSessionRequest,
+} from '../src/query.ts'
+
+const limits = { defaultLimit: 2, maxLimit: 3 }
+
+function expectCode(code: SessionQueryErrorCode): Error {
+  return expect.objectContaining({ code }) as Error
+}
+
+describe('SQLite search request normalization', () => {
+  it('normalizes both scopes, defaults arrays and limits, and preserves cursors', () => {
+    expect(normalizeSessionRequest({ query: '  alpha\n beta  ' }, limits)).toEqual({
+      query: 'alpha beta',
+      sessionFilters: [],
+      eventFilters: [],
+      limit: 2,
+    })
+    expect(normalizeSessionRequest({
+      query: 'needle',
+      sessionFilters: [{ kind: 'availability', values: ['live'] }],
+      eventFilters: [{ kind: 'surface', values: ['current'] }],
+      limit: 3,
+      cursor: SessionSearchCursor('next'),
+    }, limits)).toEqual({
+      query: 'needle',
+      sessionFilters: [{ kind: 'availability', values: ['live'] }],
+      eventFilters: [{ kind: 'surface', values: ['current'] }],
+      limit: 3,
+      cursor: SessionSearchCursor('next'),
+    })
+    expect(normalizeEventRequest({ sessionId: SessionId('s'), query: 'needle' }, limits)).toEqual({
+      sessionId: SessionId('s'),
+      query: 'needle',
+      filters: [],
+      limit: 2,
+    })
+    expect(normalizeEventRequest({
+      sessionId: SessionId('s'),
+      query: 'needle',
+      filters: [{ kind: 'seq', from: 1 }],
+      cursor: SessionSearchCursor('next'),
+    }, limits)).toEqual({
+      sessionId: SessionId('s'),
+      query: 'needle',
+      filters: [{ kind: 'seq', from: 1 }],
+      limit: 2,
+      cursor: SessionSearchCursor('next'),
+    })
+  })
+
+  it('rejects non-text, blank, non-integer, non-positive, and oversized requests', () => {
+    expect(() => normalizeSessionRequest({ query: 1 as never }, limits))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_QUERY'))
+    expect(() => normalizeSessionRequest({ query: ' \n ' }, limits))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_QUERY'))
+    expect(() => normalizeSessionRequest({ query: 'bad\0query' }, limits))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_QUERY'))
+    expect(() => normalizeEventRequest({ sessionId: 1 as never, query: 'x' }, limits))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => normalizeEventRequest({
+      sessionId: SessionId('s'),
+      query: 'x',
+      cursor: 1 as never,
+    }, limits)).toThrow(expectCode('SESSION_QUERY_INVALID_CURSOR'))
+    expect(() => normalizeSessionRequest({
+      query: 'x',
+      eventFilters: [{ kind: 'text', text: 'x' } as never],
+    }, limits)).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => normalizeSessionRequest({
+      query: 'x',
+      eventFilters: [{} as never],
+    }, limits)).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    for (const limit of [1.5, 0, 4]) {
+      expect(() => normalizeEventRequest({ sessionId: SessionId('s'), query: 'x', limit }, limits))
+        .toThrow(expectCode('SESSION_QUERY_INVALID_LIMIT'))
+    }
+    expect(() => normalizeEventRequest({
+      sessionId: SessionId('s'),
+      query: 'x',
+      limit: SQLITE_MAX_PAGE_LIMIT + 1,
+    }, { defaultLimit: 1, maxLimit: SQLITE_MAX_PAGE_LIMIT + 1 }))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_LIMIT'))
+  })
+
+  it('materializes owned filter values during normalization', () => {
+    const values = ['live'] as Array<'live' | 'persisted'>
+    const filter = { kind: 'availability' as const, values }
+    const request = { query: 'needle', sessionFilters: [filter] }
+    const normalized = normalizeSessionRequest(request, limits)
+
+    values[0] = 'persisted'
+    request.sessionFilters.push({ kind: 'availability', values: ['persisted'] })
+    expect(normalized.sessionFilters).toEqual([{ kind: 'availability', values: ['live'] }])
+  })
+})
+
+describe('SQLite search predicate compilation', () => {
+  it('compiles all logical-session clauses including empty and nullable values', () => {
+    expect(buildSessionWhere([])).toEqual({ sql: '', params: [], predicateCount: 0 })
+    expect(buildSessionWhere([{ kind: 'id', values: [] }])).toEqual({
+      sql: '0',
+      params: [],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'id', values: [SessionId('a'), SessionId('b')] }])).toEqual({
+      sql: 'session_id IN (?, ?)',
+      params: [SessionId('a'), SessionId('b')],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'cwd', values: [] }])).toEqual({
+      sql: '0',
+      params: [],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'cwd', values: [null] }])).toEqual({
+      sql: '(cwd IS NULL)',
+      params: [],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'cwd', values: ['/a'] }])).toEqual({
+      sql: '(cwd IN (?))',
+      params: ['/a'],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'parent', values: [SessionId('p'), null] }])).toEqual({
+      sql: '(parent_session IN (?) OR parent_session IS NULL)',
+      params: [SessionId('p')],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([
+      { kind: 'created-at', from: 1, to: 2 },
+      { kind: 'availability', values: [] },
+      { kind: 'availability', values: ['live', 'live'] },
+      { kind: 'availability', values: ['live', 'persisted'] },
+    ])).toEqual({
+      sql: 'CAST(created_at AS INTEGER) >= ? AND CAST(created_at AS INTEGER) <= ? AND 0 AND live = 1',
+      params: [1, 2],
+      predicateCount: 4,
+    })
+    expect(buildSessionWhere([{ kind: 'created-at' }])).toEqual({
+      sql: '',
+      params: [],
+      predicateCount: 0,
+    })
+  })
+
+  it('compiles every event clause and empty lists', () => {
+    expect(buildEventWhere([
+      { kind: 'seq', from: 1 },
+      { kind: 'time', to: 9 },
+      { kind: 'type', values: ['user/message'] },
+      { kind: 'surface', values: ['current', 'log-only'] },
+    ])).toEqual({
+      sql: 'CAST(seq AS INTEGER) >= ? AND CAST(time AS INTEGER) <= ? AND type IN (?) AND surface IN (?, ?)',
+      params: [1, 9, 'user/message', 'current', 'log-only'],
+      predicateCount: 4,
+    })
+    expect(buildEventWhere([
+      { kind: 'type', values: [] },
+      { kind: 'surface', values: [] },
+    ])).toEqual({ sql: '0 AND 0', params: [], predicateCount: 2 })
+  })
+
+  it('rejects predicate builders above the supported FTS5 outer budget', () => {
+    const filters = Array.from(
+      { length: SQLITE_FTS5_OUTER_PREDICATE_LIMIT },
+      () => ({ kind: 'id' as const, values: [SessionId('safe')] }),
+    )
+
+    expect(buildSessionWhere(filters).predicateCount).toBe(SQLITE_FTS5_OUTER_PREDICATE_LIMIT)
+    expect(() => buildSessionWhere([
+      ...filters,
+      { kind: 'id', values: [SessionId('over')] },
+    ])).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('rejects runtime-unknown filter discriminants in both SQL builders', () => {
+    expect(() => buildSessionWhere([{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => buildEventWhere([{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => buildSessionWhere([{ kind: 'availability', values: ['future'] } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => buildSessionWhere([{} as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+})
+
+describe('SQLite query identity and presentation', () => {
+  it('quotes all caller MATCH syntax as data', () => {
+    expect(quoteFtsData('say "needle" OR *')).toBe('"say ""needle"" OR *"')
+  })
+
+  it('canonicalizes request and filter ordering in both scopes', () => {
+    const sessionA: NormalizedSessionRequest = {
+      query: 'needle',
+      limit: 2,
+      sessionFilters: [
+        { kind: 'cwd', values: ['/b', '/a'] },
+        { kind: 'parent', values: [null, SessionId('p')] },
+        { kind: 'id', values: [SessionId('same'), SessionId('same')] },
+        { kind: 'created-at', from: 1 },
+      ],
+      eventFilters: [{ kind: 'time', to: 9 }],
+    }
+    const sessionB: NormalizedSessionRequest = {
+      query: 'needle',
+      limit: 2,
+      sessionFilters: [
+        { kind: 'created-at', from: 1 },
+        { kind: 'id', values: [SessionId('same'), SessionId('same')] },
+        { kind: 'parent', values: [SessionId('p'), null] },
+        { kind: 'cwd', values: ['/a', '/b'] },
+      ],
+      eventFilters: [{ kind: 'time', to: 9 }],
+    }
+    expect(requestFingerprint(sessionA)).toBe(requestFingerprint(sessionB))
+
+    const eventA: NormalizedEventRequest = {
+      sessionId: SessionId('s'),
+      query: 'needle',
+      limit: 2,
+      filters: [{ kind: 'seq' }, { kind: 'surface', values: ['shadowed', 'current'] }],
+    }
+    const eventB: NormalizedEventRequest = {
+      sessionId: SessionId('s'),
+      query: 'needle',
+      limit: 2,
+      filters: [{ kind: 'surface', values: ['current', 'shadowed'] }, { kind: 'seq' }],
+    }
+    expect(requestFingerprint(eventA)).toBe(requestFingerprint(eventB))
+    expect(requestFingerprint(eventA)).not.toBe(requestFingerprint({ ...eventB, sessionId: SessionId('other') }))
+  })
+
+  it('normalizes, bounds, and positions snippets by Unicode code point', () => {
+    expect(makeSnippet('  short\ntext  ', 20)).toBe('short text')
+    expect(makeSnippet(`abcde${FTS_HIGHLIGHT_START}f${FTS_HIGHLIGHT_END}`, 1)).toBe('…')
+    expect(makeSnippet('abcdefghij', 5)).toBe('abcd…')
+    expect(makeSnippet(`ab${FTS_HIGHLIGHT_START}c${FTS_HIGHLIGHT_END}defghij`, 5)).toBe('…bcd…')
+    expect(makeSnippet(`ab${FTS_HIGHLIGHT_START}c${FTS_HIGHLIGHT_END}defghij`, 3)).toBe('…c…')
+    expect(makeSnippet(`abcde${FTS_HIGHLIGHT_START}f${FTS_HIGHLIGHT_END}`, 2)).toBe('…f')
+    expect(makeSnippet(`abcde${FTS_HIGHLIGHT_START}f${FTS_HIGHLIGHT_END}`, 5)).toBe('…cdef')
+    expect(makeSnippet(`  x—${FTS_HIGHLIGHT_START}café${FTS_HIGHLIGHT_END}\n y  `, 20))
+      .toBe('x—café y')
+  })
+})
diff --git a/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts b/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts
new file mode 100644
index 0000000000..1812a85428
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts
@@ -0,0 +1,1382 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context, type Fiber } from 'cordis'
+import { DatabaseSync } from 'node:sqlite'
+import { chmod, mkdtemp, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
+import SessionPersistence, { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionPersistenceSnapshot } from '@deepseek-ai/dsh-session-persistence'
+import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
+import SessionQuerySqlite, {
+  SESSION_QUERY_SQLITE_SCHEMA_VERSION,
+} from '@deepseek-ai/dsh-session-query-sqlite'
+import {
+  SessionQueryError,
+  SessionSearchCursor,
+  type SessionAvailability,
+  type SessionQueryErrorCode,
+  type SessionSearchRequest,
+} from '@deepseek-ai/dsh-session-query'
+
+const temporaryDirectories: string[] = []
+
+afterEach(async () => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    await rm(directory, { recursive: true, force: true })
+  }
+})
+
+async function temporaryPath(name = 'search.db'): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-session-search-'))
+  temporaryDirectories.push(directory)
+  return join(directory, name)
+}
+
+function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}): SessionHeader {
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, ...extra }
+}
+
+function messageEvents(text: string, time = 1): SessionEvent[] {
+  return [{
+    type: 'user/message',
+    seq: 0,
+    time,
+    data: { content: [{ type: 'text', text }], source: { kind: 'user' } },
+    surfaceOp: 'append',
+  }]
+}
+
+function expectCode(code: SessionQueryErrorCode): Error {
+  return expect.objectContaining({ code }) as Error
+}
+
+function replaceCursorOffset(
+  cursor: ReturnType<typeof SessionSearchCursor>,
+  offset: number,
+): ReturnType<typeof SessionSearchCursor> {
+  const payload = JSON.parse(
+    Buffer.from(cursor, 'base64url').toString('utf8'),
+  ) as Record<string, unknown>
+  return SessionSearchCursor(Buffer.from(JSON.stringify({ ...payload, offset }), 'utf8').toString('base64url'))
+}
+
+class TestPersistence extends SessionPersistence {
+  static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
+  static revisions = new Map<SessionIdType, number>()
+  static nextRevision = 0
+  static loads = new Map<SessionIdType, number>()
+  static inspections = new Map<SessionIdType, number>()
+  static loadEffect: ((entry: { meta: SessionHeader; events: SessionEvent[] }) => void) | undefined
+  static inspectEffect: ((entry: { meta: SessionHeader; events: SessionEvent[] }) => void | Promise<void>) | undefined
+  static listGate: Promise<void> | undefined
+  static listStarted: (() => void) | undefined
+  static snapshotEffect: (() => void | Promise<void>) | undefined
+  static snapshotOverride: (() => SessionPersistenceSnapshot[]) | undefined
+  static failure: unknown
+
+  locate(_meta: SessionHeader): undefined {
+    return undefined
+  }
+
+  static reset(entries: readonly { meta: SessionHeader; events: SessionEvent[] }[] = []): void {
+    this.entries = new Map()
+    this.revisions = new Map()
+    this.loads = new Map()
+    this.inspections = new Map()
+    this.loadEffect = undefined
+    this.inspectEffect = undefined
+    for (const entry of entries) this.set(entry)
+    this.listGate = undefined
+    this.listStarted = undefined
+    this.snapshotEffect = undefined
+    this.snapshotOverride = undefined
+    this.failure = undefined
+  }
+
+  static set(entry: { meta: SessionHeader; events: SessionEvent[] }): void {
+    this.entries.set(entry.meta.id, structuredClone(entry))
+    this.revisions.set(entry.meta.id, ++this.nextRevision)
+  }
+
+  create(meta: SessionHeader): Promise<void> {
+    TestPersistence.set({ meta, events: [] })
+    return Promise.resolve()
+  }
+
+  append(id: SessionIdType, events: readonly SessionEvent[]): Promise<void> {
+    const entry = TestPersistence.entries.get(id)
+    if (entry === undefined) return Promise.reject(new Error('missing test session'))
+    entry.events.push(...structuredClone(events))
+    TestPersistence.revisions.set(id, ++TestPersistence.nextRevision)
+    return Promise.resolve()
+  }
+
+  async load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    TestPersistence.loads.set(id, (TestPersistence.loads.get(id) ?? 0) + 1)
+    if (TestPersistence.failure !== undefined) throw TestPersistence.failure
+    const entry = TestPersistence.entries.get(id)
+    if (entry === undefined) throw new Error('missing test session')
+    if (TestPersistence.loadEffect !== undefined) {
+      const effect = TestPersistence.loadEffect
+      TestPersistence.loadEffect = undefined
+      effect(entry)
+      TestPersistence.revisions.set(id, ++TestPersistence.nextRevision)
+    }
+    return structuredClone(entry)
+  }
+
+  async inspect(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    TestPersistence.inspections.set(id, (TestPersistence.inspections.get(id) ?? 0) + 1)
+    if (TestPersistence.failure !== undefined) throw TestPersistence.failure
+    const entry = TestPersistence.entries.get(id)
+    if (entry === undefined) throw new Error('missing test session')
+    await TestPersistence.inspectEffect?.(entry)
+    TestPersistence.inspectEffect = undefined
+    return structuredClone(entry)
+  }
+
+  async list(): Promise<SessionHeader[]> {
+    TestPersistence.listStarted?.()
+    await TestPersistence.listGate
+    if (TestPersistence.failure !== undefined) throw TestPersistence.failure
+    return [...TestPersistence.entries.values()].map(entry => structuredClone(entry.meta))
+  }
+
+
+  async listSnapshots(): Promise<SessionPersistenceSnapshot[]> {
+    TestPersistence.listStarted?.()
+    await TestPersistence.listGate
+    if (TestPersistence.failure !== undefined) throw TestPersistence.failure
+    const snapshots = TestPersistence.snapshotOverride?.()
+      ?? [...TestPersistence.entries.values()].map(entry => ({
+        header: structuredClone(entry.meta),
+        revision: SessionPersistenceRevision(`test:${TestPersistence.revisions.get(entry.meta.id)}`),
+      }))
+    await TestPersistence.snapshotEffect?.()
+    return snapshots
+  }
+}
+
+async function liveContext(config: ConstructorParameters<typeof SessionQuerySqlite>[1] = { path: ':memory:' }): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionQuerySqlite, config)
+  return ctx
+}
+
+describe('SQLite session search', () => {
+  it('searches two-character Unicode61 tokens in live-only sessions', async () => {
+    const ctx = await liveContext({ path: ':memory:', snippetChars: 20 })
+    const session = ctx.sessions.create(SessionId('live'), {
+      meta: { cwd: '/work', createdAt: 10, seedLength: 1, delegationDepth: 2 },
+    })
+    session.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'An AI helper' }], source: { kind: 'user' } },
+      { surfaceOp: 'append' },
+    )
+
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: session.id, query: 'AI' }))
+      .resolves.toMatchObject({ items: [{ sessionId: session.id, seq: 0, snippet: 'An AI helper' }] })
+    await expect(ctx.sessionQuery.searchSessions({ query: 'AI' }))
+      .resolves.toMatchObject({ items: [{ header: { ...session.header, seedLength: 1 }, live: true, persisted: false }] })
+  })
+
+  it('searches all surfaces by default and applies metadata before ranking', async () => {
+    const ctx = await liveContext({ path: ':memory:', defaultLimit: 10, maxLimit: 20 })
+    const parent = SessionId('parent')
+    const events: SessionEvent[] = [
+      { type: 'user/message', seq: 0, time: 10, data: { content: [{ type: 'text', text: 'needle original' }], source: { kind: 'user' } }, surfaceOp: 'append' },
+      { type: 'assistant/chunk', seq: 1, time: 11, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'needle raw' } } },
+      { type: 'user/message', seq: 2, time: 12, data: { content: [{ type: 'text', text: 'needle summary' }], source: { kind: 'plugin', plugin: 'test' } }, surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] },
+      { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'error', step: 1, message: 'needle failure' } } },
+    ]
+    ctx.sessions.create(SessionId('a'), { seed: events, meta: { cwd: '/a', parentSession: parent, createdAt: 20 } })
+    ctx.sessions.create(SessionId('b'), { seed: messageEvents('needle peer', 12), meta: { createdAt: 20 } })
+
+    const all = await ctx.sessionQuery.searchEvents({ sessionId: SessionId('a'), query: 'needle' })
+    expect(new Set(all.items.map(item => item.surface))).toEqual(new Set(['current', 'shadowed', 'log-only']))
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: SessionId('a'),
+      query: 'needle',
+      filters: [
+        { kind: 'seq', from: 2, to: 2 },
+        { kind: 'time', from: 12, to: 12 },
+        { kind: 'type', values: ['user/message'] },
+        { kind: 'surface', values: ['current'] },
+      ],
+    })).resolves.toMatchObject({ items: [{ seq: 2, surface: 'current' }] })
+
+    const grouped = await ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      sessionFilters: [
+        { kind: 'id', values: [SessionId('a')] },
+        { kind: 'cwd', values: ['/a'] },
+        { kind: 'created-at', from: 20, to: 20 },
+        { kind: 'parent', values: [parent] },
+        { kind: 'availability', values: ['live'] },
+      ],
+      eventFilters: [{ kind: 'surface', values: ['shadowed'] }],
+    })
+    expect(grouped.items).toHaveLength(1)
+    expect(grouped.items[0]).toMatchObject({
+      header: { id: SessionId('a'), cwd: '/a', parentSession: parent },
+      live: true,
+      persisted: false,
+      bestMatch: { seq: 0, surface: 'shadowed' },
+    })
+  })
+
+  it('searches at the supported FTS5 outer-predicate boundary in both scopes', async () => {
+    const ctx = await liveContext()
+    const session = ctx.sessions.create(SessionId('predicate-boundary'), {
+      seed: messageEvents('needle'),
+      meta: { cwd: '/work' },
+    })
+    const sessionFilters = Array.from(
+      { length: 14 },
+      () => ({ kind: 'cwd' as const, values: ['/work', null] }),
+    )
+    const eventFilters = Array.from(
+      { length: 13 },
+      () => ({ kind: 'type' as const, values: ['user/message' as const] }),
+    )
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle', sessionFilters }))
+      .resolves.toMatchObject({ items: [{ header: { id: session.id } }] })
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      filters: eventFilters,
+    })).resolves.toMatchObject({ items: [{ sessionId: session.id, seq: 0 }] })
+  })
+
+  it('rejects unsupported FTS5 outer-predicate counts with typed errors', async () => {
+    const ctx = await liveContext()
+    const session = ctx.sessions.create(SessionId('predicate-limit'), { seed: messageEvents('needle') })
+    const sessionFilters = Array.from(
+      { length: 1_100 },
+      () => ({ kind: 'id' as const, values: [session.id] }),
+    )
+    const eventFilters = Array.from(
+      { length: 1_100 },
+      () => ({ kind: 'type' as const, values: ['user/message' as const] }),
+    )
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle', sessionFilters }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      filters: eventFilters,
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      sessionFilters: sessionFilters.slice(0, 7),
+      eventFilters: eventFilters.slice(0, 8),
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      filters: eventFilters.slice(0, 14),
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('uses literal phrase tokens, stable ties, and bounded Unicode snippets', async () => {
+    const ctx = await liveContext({ path: ':memory:', defaultLimit: 10, maxLimit: 10, snippetChars: 5 })
+    ctx.sessions.create(SessionId('a'), { seed: messageEvents('😀😀 alpha beta BRAID 😀😀', 10), meta: { createdAt: 1 } })
+    ctx.sessions.create(SessionId('b'), { seed: messageEvents('alpha beta', 10), meta: { createdAt: 1 } })
+    ctx.sessions.create(SessionId('c'), { seed: messageEvents('alpha middle beta', 10), meta: { createdAt: 1 } })
+    ctx.sessions.create(SessionId('d'), { seed: messageEvents('alpha beta', 10), meta: { createdAt: 1 } })
+    ctx.sessions.create(SessionId('operator'), { seed: messageEvents('needle OR absent', 10), meta: { createdAt: 1 } })
+    ctx.sessions.create(SessionId('only'), { seed: messageEvents('needle only', 10), meta: { createdAt: 1 } })
+    ctx.sessions.create(SessionId('quote'), { seed: messageEvents('say "needle" exactly', 10), meta: { createdAt: 1 } })
+
+    const phrase = await ctx.sessionQuery.searchSessions({ query: 'alpha beta' })
+    expect(phrase.items.map(item => item.header.id)).toEqual([SessionId('b'), SessionId('d'), SessionId('a')])
+    expect(phrase.items.every(item => Array.from(item.bestMatch.snippet).length <= 5)).toBe(true)
+    await expect(ctx.sessionQuery.searchSessions({ query: 'AI' })).resolves.toEqual({ items: [] })
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle OR absent' }))
+      .resolves.toMatchObject({ items: [{ header: { id: SessionId('operator') } }] })
+    await expect(ctx.sessionQuery.searchSessions({ query: 'say "needle"' }))
+      .resolves.toMatchObject({ items: [{ header: { id: SessionId('quote') } }] })
+    await expect(ctx.sessionQuery.searchSessions({ query: '*' })).resolves.toEqual({ items: [] })
+  })
+
+  it('ranks live and persisted matches on one source-comparable contract', async () => {
+    const persisted = header('z-persisted')
+    TestPersistence.reset([
+      { meta: persisted, events: messageEvents('needle needle', 10) },
+      ...Array.from({ length: 12 }, (_, index) => ({
+        meta: header(`filler-${index}`),
+        events: messageEvents('needle', 10),
+      })),
+    ])
+    const ctx = await liveContext()
+    const persistence = await ctx.plugin(TestPersistence)
+    ctx.sessions.create(SessionId('a-live'), {
+      seed: messageEvents('needle needle', 10),
+      meta: { createdAt: persisted.createdAt },
+    })
+
+    const result = await ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      sessionFilters: [{ kind: 'id', values: [SessionId('a-live'), persisted.id] }],
+    })
+    expect(result.items.map(item => item.header.id)).toEqual([SessionId('a-live'), persisted.id])
+    await persistence.dispose()
+  })
+
+  it('positions snippets from FTS5 matches across diacritics and punctuation', async () => {
+    const ctx = await liveContext({ path: ':memory:', snippetChars: 14 })
+    const session = ctx.sessions.create(SessionId('snippet'), {
+      seed: messageEvents('long long long—café,\nnext value', 10),
+    })
+
+    const page = await ctx.sessionQuery.searchEvents({ sessionId: session.id, query: 'CAFE' })
+    expect(page.items).toHaveLength(1)
+    expect(page.items[0]!.snippet).toContain('café')
+    expect(page.items[0]!.snippet).toContain('—')
+    expect(page.items[0]!.snippet).not.toContain('\n')
+    expect(Array.from(page.items[0]!.snippet).length).toBeLessThanOrEqual(14)
+  })
+
+  it('binds cursors to requests and only invalidates within-session pages for target changes', async () => {
+    const ctx = await liveContext({ path: ':memory:', defaultLimit: 1, maxLimit: 5 })
+    const target = ctx.sessions.create(SessionId('target'), {
+      seed: [
+        ...messageEvents('needle one', 10),
+        { ...messageEvents('needle two', 11)[0]!, seq: 1 },
+        { ...messageEvents('needle three', 12)[0]!, seq: 2 },
+      ],
+    })
+    ctx.sessions.create(SessionId('other'), { seed: messageEvents('needle other', 10) })
+
+    const eventPage = await ctx.sessionQuery.searchEvents({ sessionId: target.id, query: 'needle', limit: 1 })
+    const sessionPage = await ctx.sessionQuery.searchSessions({ query: 'needle', limit: 1 })
+    expect(eventPage.nextCursor).toEqual(expect.any(String))
+    expect(sessionPage.nextCursor).toEqual(expect.any(String))
+    if (eventPage.nextCursor === undefined || sessionPage.nextCursor === undefined) throw new Error('expected cursors')
+
+    const unsafeOffsetCursor = replaceCursorOffset(eventPage.nextCursor, 1e100)
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: target.id,
+      query: 'needle',
+      limit: 1,
+      cursor: unsafeOffsetCursor,
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_CURSOR'))
+
+    const eventKeys = eventPage.items.map(item => `${item.sessionId}:${item.seq}`)
+    let eventCursor: ReturnType<typeof SessionSearchCursor> | undefined = eventPage.nextCursor
+    while (eventCursor !== undefined) {
+      const next = await ctx.sessionQuery.searchEvents({
+        sessionId: target.id,
+        query: 'needle',
+        limit: 1,
+        cursor: eventCursor,
+      })
+      eventKeys.push(...next.items.map(item => `${item.sessionId}:${item.seq}`))
+      eventCursor = next.nextCursor
+    }
+    expect(eventKeys).toHaveLength(3)
+    expect(new Set(eventKeys).size).toBe(eventKeys.length)
+
+    const sessionIds = sessionPage.items.map(item => item.header.id)
+    let sessionCursor: ReturnType<typeof SessionSearchCursor> | undefined = sessionPage.nextCursor
+    while (sessionCursor !== undefined) {
+      const next = await ctx.sessionQuery.searchSessions({ query: 'needle', limit: 1, cursor: sessionCursor })
+      sessionIds.push(...next.items.map(item => item.header.id))
+      sessionCursor = next.nextCursor
+    }
+    expect(sessionIds).toHaveLength(2)
+    expect(new Set(sessionIds).size).toBe(sessionIds.length)
+
+    ctx.sessions.create(SessionId('unrelated'), { seed: messageEvents('needle unrelated', 20) })
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: target.id,
+      query: 'needle',
+      limit: 1,
+      cursor: eventPage.nextCursor,
+    })).resolves.toMatchObject({ items: [{ sessionId: target.id }] })
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle', limit: 1, cursor: sessionPage.nextCursor }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_STALE_CURSOR'))
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: target.id,
+      query: 'different',
+      limit: 1,
+      cursor: eventPage.nextCursor,
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_CURSOR'))
+
+    target.append('user/message', { content: [{ type: 'text', text: 'needle four' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: target.id,
+      query: 'needle',
+      limit: 1,
+      cursor: eventPage.nextCursor,
+    })).rejects.toThrow(expectCode('SESSION_QUERY_STALE_CURSOR'))
+  })
+
+  it('invalidates session cursors after transient persistence topology changes', async () => {
+    TestPersistence.reset()
+    const ctx = await liveContext({ path: ':memory:', defaultLimit: 1, maxLimit: 5 })
+    ctx.sessions.create(SessionId('first'), { seed: messageEvents('needle first') })
+    ctx.sessions.create(SessionId('second'), { seed: messageEvents('needle second') })
+    const page = await ctx.sessionQuery.searchSessions({ query: 'needle', limit: 1 })
+    if (page.nextCursor === undefined) throw new Error('expected cursor')
+
+    const persistence = await ctx.plugin(TestPersistence)
+    await persistence.dispose()
+
+    await expect(ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      limit: 1,
+      cursor: page.nextCursor,
+    })).rejects.toThrow(expectCode('SESSION_QUERY_STALE_CURSOR'))
+  })
+
+  it('rejects invalid requests, filters, cursors, and direct config', async () => {
+    const ctx = await liveContext({ path: ':memory:', defaultLimit: 2, maxLimit: 3 })
+    const session = ctx.sessions.create(SessionId('valid'), { seed: messageEvents('needle') })
+    for (const request of [
+      { sessionId: session.id, query: '' },
+      { sessionId: session.id, query: 'needle', limit: 0 },
+      { sessionId: session.id, query: 'needle', limit: 4 },
+      { sessionId: session.id, query: 'needle', filters: [{ kind: 'seq', from: 2, to: 1 }] },
+      { sessionId: session.id, query: 'needle', filters: [{ kind: 'surface', values: ['future'] }] },
+      { sessionId: session.id, query: 'bad\0query' },
+    ] as const) {
+      await expect(ctx.sessionQuery.searchEvents(request as never)).rejects.toBeInstanceOf(Error)
+    }
+    await expect(ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      sessionFilters: [{ kind: 'availability', values: ['remote' as never] }],
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      sessionFilters: [{ kind: 'future' } as never],
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      eventFilters: [{ kind: 'future' } as never],
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      filters: [{ kind: 'future' } as never],
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      cursor: SessionSearchCursor('not-json'),
+    }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_CURSOR'))
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: SessionId('absent'), query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
+
+    for (const config of [
+      { path: '' },
+      { path: ':memory:', defaultLimit: 0 },
+      { path: ':memory:', maxLimit: 0 },
+      { path: ':memory:', defaultLimit: 1e100 },
+      { path: ':memory:', maxLimit: 1e100 },
+      { path: ':memory:', snippetChars: 0 },
+      { path: ':memory:', readWindowMax: -1 },
+      { path: ':memory:', defaultLimit: 3, maxLimit: 2 },
+      { path: ':memory:', journalMode: 'memory' },
+    ]) {
+      const direct = new Context()
+      await direct.plugin(SessionStore)
+      expect(() => new SessionQuerySqlite(direct, config as never))
+        .toThrow(expectCode('SESSION_QUERY_INVALID_CONFIG'))
+      expect(direct.sessionQuery).toBeUndefined()
+    }
+  })
+
+  it('rejects aggregate filter bindings above SQLite\'s portable variable limit', async () => {
+    const ctx = await liveContext()
+    const session = ctx.sessions.create(SessionId('binding-limit'), { seed: messageEvents('needle') })
+    // Each clause is below the ceiling; combined with its sibling and fixed
+    // query bindings, the complete statement is not portable.
+    const halfPortableLimit = 16_383
+    const ids = Array.from(
+      { length: halfPortableLimit },
+      (_, index) => SessionId(`binding-${index}`),
+    )
+    const types = Array.from({ length: halfPortableLimit }, () => 'user/message' as const)
+    const surfaces = Array.from({ length: halfPortableLimit }, () => 'current' as const)
+
+    await expect(ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      sessionFilters: [{ kind: 'id', values: ids }],
+      eventFilters: [{ kind: 'type', values: types }],
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      filters: [
+        { kind: 'type', values: types },
+        { kind: 'surface', values: surfaces },
+      ],
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('rejects one 125,000-value filter list with a typed error', async () => {
+    const ctx = await liveContext()
+    const ids = Array.from(
+      { length: 125_000 },
+      (_, index) => SessionId(`oversized-binding-${index}`),
+    )
+
+    await expect(ctx.sessionQuery.searchSessions({
+      query: 'needle',
+      sessionFilters: [{ kind: 'id', values: ids }],
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+})
+
+describe('SQLite reconciliation and source lifecycle', () => {
+  it('owns queued request and filter values before waiting for the serializer', async () => {
+    const durable = header('owned')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('durable needle') }])
+    const ctx = await liveContext()
+    const persistence = await ctx.plugin(TestPersistence)
+    let release!: () => void
+    TestPersistence.listGate = new Promise<void>((resolve) => { release = resolve })
+    let markStarted!: () => void
+    const started = new Promise<void>((resolve) => { markStarted = resolve })
+    TestPersistence.listStarted = () => {
+      TestPersistence.listStarted = undefined
+      markStarted()
+    }
+    const blocking = ctx.sessionQuery.searchSessions({ query: 'needle' })
+    await started
+
+    const availability: SessionAvailability[] = ['persisted']
+    const request: SessionSearchRequest = {
+      query: 'needle',
+      sessionFilters: [{ kind: 'availability', values: availability }],
+    }
+    const queued = ctx.sessionQuery.searchSessions(request)
+    request.query = 'absent'
+    availability[0] = 'live'
+    release()
+
+    await expect(blocking).resolves.toMatchObject({ items: [{ header: durable }] })
+    await expect(queued).resolves.toMatchObject({ items: [{ header: durable }] })
+    await persistence.dispose()
+  })
+
+  it('mounts persistence dynamically, shadows with TEMP live rows, reveals, and hides on unmount', async () => {
+    const shared = header('shared', 10, { cwd: '/work' })
+    const durable = header('durable', 5)
+    TestPersistence.reset([
+      { meta: shared, events: messageEvents('persisted needle') },
+      { meta: durable, events: messageEvents('durable needle') },
+    ])
+    const ctx = await liveContext()
+    await expect(ctx.sessionQuery.searchSessions({ query: 'durable' })).resolves.toEqual({ items: [] })
+    const persistenceFiber = await ctx.plugin(TestPersistence)
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'durable' }))
+      .resolves.toMatchObject({ items: [{ header: durable, live: false, persisted: true }] })
+    const live = ctx.sessions.prepare(shared.id, { meta: { createdAt: 10, cwd: '/work' } })
+    live.append('user/message', { content: [{ type: 'text', text: 'live needle' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const detach = ctx.sessions.enter(live)
+    ctx.sessions.announce(live)
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'persisted' })).resolves.toEqual({ items: [] })
+    await expect(ctx.sessionQuery.searchSessions({ query: 'live' }))
+      .resolves.toMatchObject({ items: [{ header: shared, live: true, persisted: true }] })
+    detach()
+    await expect(ctx.sessionQuery.searchSessions({ query: 'persisted' }))
+      .resolves.toMatchObject({ items: [{ header: shared, live: false, persisted: true }] })
+
+    await persistenceFiber.dispose()
+    await expect(ctx.sessionQuery.searchSessions({ query: 'durable' })).resolves.toEqual({ items: [] })
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: durable.id, query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
+  })
+
+  it('does not load a persisted log while the same session is live', async () => {
+    const shared = header('checkpointed-live', 10)
+    TestPersistence.reset([{ meta: shared, events: messageEvents('persisted needle') }])
+    const ctx = await liveContext()
+    const live = ctx.sessions.prepare(shared.id, {
+      seed: messageEvents('live needle'),
+      meta: { createdAt: shared.createdAt },
+    })
+    const detach = ctx.sessions.enter(live)
+    ctx.sessions.announce(live)
+    const persistence = await ctx.plugin(TestPersistence)
+
+    await expect(ctx.sessionQuery.searchSessions({
+      query: 'live',
+      sessionFilters: [{ kind: 'availability', values: ['persisted'] }],
+    })).resolves.toMatchObject({
+      items: [{ header: shared, live: true, persisted: true }],
+    })
+    expect(TestPersistence.loads.get(shared.id)).toBeUndefined()
+    expect(TestPersistence.inspections.get(shared.id)).toBeUndefined()
+
+    detach()
+    await expect(ctx.sessionQuery.searchSessions({ query: 'persisted' }))
+      .resolves.toMatchObject({ items: [{ header: shared, live: false, persisted: true }] })
+    expect(TestPersistence.loads.get(shared.id)).toBeUndefined()
+    expect(TestPersistence.inspections.get(shared.id)).toBe(1)
+    await persistence.dispose()
+  })
+
+  it('retries when a live owner attaches during persistence observation', async () => {
+    TestPersistence.reset()
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    TestPersistence.snapshotEffect = () => {
+      TestPersistence.snapshotEffect = undefined
+      ctx.sessions.create(SessionId('attached'), { seed: messageEvents('attached needle') })
+    }
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'attached' }))
+      .resolves.toMatchObject({ items: [{ header: { id: SessionId('attached') } }] })
+  })
+
+  it('cannot crash-repair a log when live ownership begins during persisted inspection', async () => {
+    const shared = header('attach-during-inspect', 10)
+    const persistedEvents = messageEvents('persisted needle')
+    TestPersistence.reset([{ meta: shared, events: persistedEvents }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    TestPersistence.loadEffect = (entry) => {
+      entry.events = messageEvents('incorrect repair')
+    }
+    TestPersistence.inspectEffect = () => {
+      ctx.sessions.create(shared.id, {
+        seed: messageEvents('live needle'),
+        meta: { createdAt: shared.createdAt },
+      })
+    }
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'live' }))
+      .resolves.toMatchObject({ items: [{ header: shared, live: true, persisted: true }] })
+    expect(TestPersistence.loads.get(shared.id)).toBeUndefined()
+    expect(TestPersistence.entries.get(shared.id)?.events).toEqual(persistedEvents)
+  })
+
+  it('retries when one live owner replaces another during persistence observation', async () => {
+    TestPersistence.reset()
+    const ctx = await liveContext()
+    const first = ctx.sessions.prepare(SessionId('first'), { seed: messageEvents('first needle') })
+    const detachFirst = ctx.sessions.enter(first)
+    ctx.sessions.announce(first)
+    await ctx.plugin(TestPersistence)
+    TestPersistence.snapshotEffect = () => {
+      TestPersistence.snapshotEffect = undefined
+      detachFirst()
+      ctx.sessions.create(SessionId('second'), { seed: messageEvents('second needle') })
+    }
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'second' }))
+      .resolves.toMatchObject({ items: [{ header: { id: SessionId('second') } }] })
+  })
+
+  it('uses the reconciled persistence binding through the query boundary', async () => {
+    const durable = header('post-reconcile-unmount')
+    TestPersistence.reset([{ meta: durable, events: [
+      ...messageEvents('durable needle', 1),
+      { ...messageEvents('durable needle again', 2)[0]!, seq: 1 },
+    ] }])
+    const ctx = await liveContext({ path: ':memory:', defaultLimit: 1, maxLimit: 2 })
+    const persistence = await ctx.plugin(TestPersistence)
+    const internals = ctx.sessionQuery as unknown as {
+      _reconcile(signal: AbortSignal | undefined): Promise<{
+        identity: symbol
+        service?: SessionPersistence
+      }>
+    }
+    const reconcile = internals._reconcile.bind(internals)
+    const boundary = vi.spyOn(internals, '_reconcile').mockImplementation(async (signal) => {
+      const binding = await reconcile(signal)
+      await persistence.dispose()
+      return binding
+    })
+
+    const page = await ctx.sessionQuery.searchEvents({
+      sessionId: durable.id,
+      query: 'needle',
+      limit: 1,
+    })
+    expect(page.items).toMatchObject([{ sessionId: durable.id }])
+    expect(page.nextCursor).toEqual(expect.any(String))
+    boundary.mockRestore()
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: durable.id, query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
+  })
+
+  it('discards a stale list rejection when persistence unmounts during observation', async () => {
+    const durable = header('racing')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('durable needle') }])
+    const ctx = await liveContext()
+    const persistenceFiber = await ctx.plugin(TestPersistence)
+    let release!: () => void
+    TestPersistence.listGate = new Promise<void>((resolve) => { release = resolve })
+    let markStarted!: () => void
+    const started = new Promise<void>((resolve) => { markStarted = resolve })
+    TestPersistence.listStarted = () => {
+      TestPersistence.listStarted = undefined
+      markStarted()
+    }
+
+    const search = ctx.sessionQuery.searchSessions({ query: 'needle' })
+    await started
+    await persistenceFiber.dispose()
+    TestPersistence.failure = new Error('stale backend rejection')
+    release()
+    await expect(search).resolves.toEqual({ items: [] })
+  })
+
+  it('retries against a replacement after the prior binding rejects', async () => {
+    const durable = header('replacement')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('durable needle') }])
+    const ctx = await liveContext()
+    const prior = await ctx.plugin(TestPersistence)
+    let rejectPrior!: (reason: unknown) => void
+    TestPersistence.listGate = new Promise<void>((_resolve, reject) => { rejectPrior = reject })
+    let markStarted!: () => void
+    const started = new Promise<void>((resolve) => { markStarted = resolve })
+    TestPersistence.listStarted = () => {
+      TestPersistence.listStarted = undefined
+      markStarted()
+    }
+
+    const search = ctx.sessionQuery.searchSessions({ query: 'needle' })
+    await started
+    await prior.dispose()
+    TestPersistence.listGate = undefined
+    const replacement = await ctx.plugin(TestPersistence)
+    rejectPrior(new Error('stale prior binding'))
+    await expect(search).resolves.toMatchObject({ items: [{ header: durable }] })
+    await replacement.dispose()
+  })
+
+  it('reloads a replacement source even when its opaque revisions collide', async () => {
+    const durable = header('colliding-replacement')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('old content') }])
+    const revision = TestPersistence.revisions.get(durable.id)!
+    const ctx = await liveContext()
+    const prior = await ctx.plugin(TestPersistence)
+    await expect(ctx.sessionQuery.searchSessions({ query: 'old' }))
+      .resolves.toMatchObject({ items: [{ header: durable }] })
+    await prior.dispose()
+
+    TestPersistence.set({ meta: durable, events: messageEvents('new needle') })
+    TestPersistence.revisions.set(durable.id, revision)
+    const replacement = await ctx.plugin(TestPersistence)
+    const page = await ctx.sessionQuery.searchSessions({ query: 'new needle' })
+    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    expect(page).toMatchObject({ items: [{ header: durable }] })
+    await expect(ctx.sessionQuery.searchSessions({ query: 'old' })).resolves.toEqual({ items: [] })
+    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    await replacement.dispose()
+  })
+
+  it('retries when a successful observation belongs to a source unmounted during listing', async () => {
+    const durable = header('successful-unmount')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('durable needle') }])
+    const ctx = await liveContext()
+    const persistence = await ctx.plugin(TestPersistence)
+    let lists = 0
+    TestPersistence.snapshotEffect = async () => {
+      lists += 1
+      if (lists === 2) await persistence.dispose()
+    }
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' })).resolves.toEqual({ items: [] })
+    expect(lists).toBe(2)
+  })
+
+  it('retries when the snapshot population changes during observation', async () => {
+    const first = header('first')
+    const added = header('added-during-list')
+    TestPersistence.reset([{ meta: first, events: messageEvents('first needle') }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    TestPersistence.snapshotEffect = () => {
+      TestPersistence.snapshotEffect = undefined
+      TestPersistence.set({ meta: added, events: messageEvents('added needle') })
+    }
+
+    const page = await ctx.sessionQuery.searchSessions({ query: 'needle' })
+    expect(page.items.map(item => item.header.id).sort()).toEqual([added.id, first.id].sort())
+    expect(TestPersistence.inspections.get(first.id)).toBe(2)
+    expect(TestPersistence.inspections.get(added.id)).toBe(1)
+  })
+
+  it('fails after one retry when persistence snapshots keep changing', async () => {
+    const durable = header('continuous-mutation')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('durable needle') }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    let lists = 0
+    TestPersistence.snapshotEffect = () => {
+      lists += 1
+      TestPersistence.set({ meta: durable, events: messageEvents(`durable needle ${lists}`) })
+    }
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+    expect(lists).toBe(4)
+  })
+
+  it('retries if the persistence binding changes while live sessions are observed', async () => {
+    const durable = header('live-boundary-retry')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('durable needle') }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    const internals = ctx.sessionQuery as unknown as {
+      _persistenceBinding: { identity: symbol; service?: SessionPersistence }
+    }
+    const originalList = ctx.sessions.list.bind(ctx.sessions)
+    let bumped = false
+    const list = vi.spyOn(ctx.sessions, 'list').mockImplementation(() => {
+      if (!bumped) {
+        bumped = true
+        internals._persistenceBinding = {
+          ...internals._persistenceBinding,
+          identity: Symbol(),
+        }
+      }
+      return originalList()
+    })
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .resolves.toMatchObject({ items: [{ header: durable }] })
+    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    list.mockRestore()
+  })
+
+  it('rejects malformed snapshots and preserves typed persistence failures', async () => {
+    const durable = header('invalid-snapshot')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('durable needle') }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+
+    TestPersistence.snapshotOverride = () => 'not-an-array' as never
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+    TestPersistence.snapshotOverride = () => [{ header: durable, revision: 1 as never }]
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+    TestPersistence.snapshotOverride = () => [
+      { header: durable, revision: SessionPersistenceRevision('duplicate:1') },
+      { header: durable, revision: SessionPersistenceRevision('duplicate:2') },
+    ]
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+
+    TestPersistence.snapshotOverride = undefined
+    const typed = new SessionQueryError('typed persistence failure', 'SESSION_QUERY_PERSISTENCE_FAILED')
+    TestPersistence.failure = typed
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' })).rejects.toBe(typed)
+  })
+
+  it('rejects immutable header conflicts between live and persisted sources', async () => {
+    const shared = header('conflict', 10, { delegationDepth: 1 })
+    TestPersistence.reset([{ meta: shared, events: messageEvents('persisted needle') }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    ctx.sessions.create(shared.id, {
+      seed: messageEvents('live needle'),
+      meta: { createdAt: 10, delegationDepth: 2 },
+    })
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
+  })
+
+  it('preserves unchanged persisted generations while reconciling new, changed, and deleted rows', async () => {
+    const path = await temporaryPath()
+    const unchanged = header('unchanged')
+    const changed = header('changed')
+    const deleted = header('deleted')
+    TestPersistence.reset([
+      { meta: unchanged, events: messageEvents('unchanged needle') },
+      { meta: changed, events: messageEvents('old needle') },
+      { meta: deleted, events: messageEvents('deleted needle') },
+    ])
+    const first = new Context()
+    await first.plugin(SessionStore)
+    const firstPersistence = await first.plugin(TestPersistence)
+    const firstSearch = await first.plugin(SessionQuerySqlite, { path })
+    await first.sessionQuery.searchSessions({ query: 'needle' })
+    expect(Object.fromEntries(TestPersistence.inspections)).toEqual({ unchanged: 1, changed: 1, deleted: 1 })
+    await first.sessionQuery.searchSessions({ query: 'needle' })
+    expect(Object.fromEntries(TestPersistence.inspections)).toEqual({ unchanged: 1, changed: 1, deleted: 1 })
+    await firstSearch.dispose()
+    await firstPersistence.dispose()
+
+    const beforeDb = new DatabaseSync(path)
+    const beforeRows = beforeDb.prepare('SELECT id, generation FROM persisted_sessions ORDER BY id').all() as Array<{ id: string; generation: number }>
+    beforeDb.close()
+    const before = new Map(beforeRows.map(row => [row.id, row.generation]))
+
+    const added = header('added')
+    TestPersistence.entries.delete(deleted.id)
+    TestPersistence.set({ meta: changed, events: messageEvents('changed needle') })
+    TestPersistence.set({ meta: added, events: messageEvents('added needle') })
+    const second = new Context()
+    await second.plugin(SessionStore)
+    const secondPersistence = await second.plugin(TestPersistence)
+    const secondSearch = await second.plugin(SessionQuerySqlite, { path })
+    const result = await second.sessionQuery.searchSessions({ query: 'needle' })
+    expect(result.items.map(item => item.header.id).sort()).toEqual([added.id, changed.id, unchanged.id].sort())
+    expect(Object.fromEntries(TestPersistence.inspections)).toEqual({
+      unchanged: 1,
+      changed: 2,
+      deleted: 1,
+      added: 1,
+    })
+    await secondSearch.dispose()
+    await secondPersistence.dispose()
+
+    const afterDb = new DatabaseSync(path)
+    const afterRows = afterDb.prepare('SELECT id, generation FROM persisted_sessions ORDER BY id').all() as Array<{ id: string; generation: number }>
+    afterDb.close()
+    const after = new Map(afterRows.map(row => [row.id, row.generation]))
+    expect(after.get(unchanged.id)).toBe(before.get(unchanged.id))
+    expect(after.get(changed.id)).toBeGreaterThan(before.get(changed.id)!)
+    expect(after.has(deleted.id)).toBe(false)
+    expect(after.has(added.id)).toBe(true)
+  })
+
+  it('drops connection-local live overlays on reopen and retains persistent bases', async () => {
+    const path = await temporaryPath()
+    const shared = header('shared', 10)
+    TestPersistence.reset([{ meta: shared, events: messageEvents('persisted needle') }])
+    const first = new Context()
+    await first.plugin(SessionStore)
+    const persistence = await first.plugin(TestPersistence)
+    const live = first.sessions.create(shared.id, { seed: messageEvents('live needle'), meta: { createdAt: 10 } })
+    const search = await first.plugin(SessionQuerySqlite, { path })
+    await expect(first.sessionQuery.searchEvents({ sessionId: live.id, query: 'live' })).resolves.toMatchObject({ items: [{}] })
+    await search.dispose()
+    await persistence.dispose()
+
+    const second = new Context()
+    await second.plugin(SessionStore)
+    const persistenceAgain = await second.plugin(TestPersistence)
+    const searchAgain = await second.plugin(SessionQuerySqlite, { path })
+    await expect(second.sessionQuery.searchSessions({ query: 'live' })).resolves.toEqual({ items: [] })
+    await expect(second.sessionQuery.searchSessions({ query: 'persisted' }))
+      .resolves.toMatchObject({ items: [{ header: shared, live: false, persisted: true }] })
+    expect(TestPersistence.inspections.get(shared.id)).toBe(1)
+    await searchAgain.dispose()
+    await persistenceAgain.dispose()
+  })
+
+  it('refreshes after an external mutating load repair without loading from the query path', async () => {
+    const durable = header('repair')
+    TestPersistence.reset([{ meta: durable, events: messageEvents('before repair') }])
+    const ctx = await liveContext()
+    const persistence = await ctx.plugin(TestPersistence)
+    await expect(ctx.sessionQuery.searchSessions({ query: 'before' }))
+      .resolves.toMatchObject({ items: [{ header: durable }] })
+    TestPersistence.loadEffect = (entry) => {
+      entry.events = messageEvents('repaired needle')
+    }
+    await ctx.sessionPersistence.load(durable.id)
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'repaired' }))
+      .resolves.toMatchObject({ items: [{ header: durable }] })
+    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    await ctx.sessionQuery.searchSessions({ query: 'repaired' })
+    expect(TestPersistence.inspections.get(durable.id)).toBe(2)
+    expect(TestPersistence.loads.get(durable.id)).toBe(1)
+    await persistence.dispose()
+  })
+
+  it('recovers on the next search after source and SQLite transaction failures', async () => {
+    TestPersistence.reset([{ meta: header('durable'), events: messageEvents('durable needle') }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    TestPersistence.failure = 'offline'
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+    const signal = new AbortController().signal
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }, { signal }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+    TestPersistence.failure = new Error('still offline')
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }, { signal }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+    TestPersistence.failure = undefined
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' })).resolves.toMatchObject({ items: [{}] })
+
+    const live = ctx.sessions.create(SessionId('live'), { seed: messageEvents('base') })
+    await ctx.sessionQuery.searchEvents({ sessionId: live.id, query: 'base' })
+    const db = (ctx.sessionQuery as unknown as { _db: DatabaseSync })._db
+    db.exec('PRAGMA query_only = ON')
+    live.append('user/message', { content: [{ type: 'text', text: 'retry needle' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: live.id, query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+    db.exec('PRAGMA query_only = OFF')
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: live.id, query: 'needle' }))
+      .resolves.toMatchObject({ items: [{ seq: 1 }] })
+  })
+})
+
+describe('SQLite schema, cancellation, and real persistence integration', () => {
+  it('creates a new database and WAL sidecars owner-only without changing its parent mode', async () => {
+    if (process.platform === 'win32') return
+    const path = await temporaryPath()
+    const directory = dirname(path)
+    await chmod(directory, 0o755)
+
+    const ctx = await liveContext({ path })
+    await ctx.sessionQuery.searchSessions({ query: 'needle' })
+
+    expect((await stat(directory)).mode & 0o777).toBe(0o755)
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect((await stat(`${path}-wal`)).mode & 0o777).toBe(0o600)
+    expect((await stat(`${path}-shm`)).mode & 0o777).toBe(0o600)
+    await (ctx.sessionQuery as SessionQuerySqlite).close()
+  })
+
+  it('creates a persistent rollback journal owner-only', async () => {
+    if (process.platform === 'win32') return
+    const path = await temporaryPath()
+    const ctx = await liveContext({ path, journalMode: 'persist' })
+    await ctx.sessionQuery.searchSessions({ query: 'needle' })
+
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect((await stat(`${path}-journal`)).mode & 0o777).toBe(0o600)
+    await (ctx.sessionQuery as SessionQuerySqlite).close()
+  })
+
+  it('preserves the mode of an existing database file', async () => {
+    if (process.platform === 'win32') return
+    const path = await temporaryPath()
+    await writeFile(path, '', { mode: 0o644 })
+    await chmod(path, 0o644)
+
+    const ctx = await liveContext({ path, journalMode: 'delete' })
+    await ctx.sessionQuery.searchSessions({ query: 'needle' })
+
+    expect((await stat(path)).mode & 0o777).toBe(0o644)
+    await (ctx.sessionQuery as SessionQuerySqlite).close()
+  })
+
+  it('surfaces filesystem failures while pre-creating the database', async () => {
+    const path = `${await temporaryPath()}\0`
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+
+    await expect(ctx.plugin(SessionQuerySqlite, { path })).rejects.toMatchObject({
+      code: 'SESSION_QUERY_INDEX_FAILED',
+      cause: { code: 'ERR_INVALID_ARG_VALUE' },
+    })
+    expect(ctx.sessionQuery).toBeUndefined()
+  })
+
+  it('resets a recognized incompatible schema but refuses unknown or foreign tables', async () => {
+    const stalePath = await temporaryPath('stale.db')
+    const staleOwner = await liveContext({ path: stalePath })
+    await (staleOwner.sessionQuery as SessionQuerySqlite).close()
+    const stale = new DatabaseSync(stalePath)
+    stale.exec('PRAGMA user_version = 999')
+    stale.close()
+    const staleCtx = await liveContext({ path: stalePath })
+    staleCtx.sessions.create(SessionId('live'), { seed: messageEvents('needle') })
+    await staleCtx.sessionQuery.searchSessions({ query: 'needle' })
+    await (staleCtx.sessionQuery as SessionQuerySqlite).close()
+    const rebuilt = new DatabaseSync(stalePath)
+    expect((rebuilt.prepare('PRAGMA user_version').get() as { user_version: number }).user_version)
+      .toBe(SESSION_QUERY_SQLITE_SCHEMA_VERSION)
+    rebuilt.close()
+
+    const augmentedPath = await temporaryPath('augmented.db')
+    const augmentedOwner = await liveContext({ path: augmentedPath })
+    await (augmentedOwner.sessionQuery as SessionQuerySqlite).close()
+    const augmented = new DatabaseSync(augmentedPath)
+    augmented.exec('CREATE TABLE unrelated(value TEXT)')
+    augmented.exec("INSERT INTO unrelated VALUES ('safe')")
+    augmented.exec('PRAGMA user_version = 999')
+    augmented.close()
+    const augmentedCtx = new Context()
+    await augmentedCtx.plugin(SessionStore)
+    await expect(augmentedCtx.plugin(SessionQuerySqlite, { path: augmentedPath }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+    expect(augmentedCtx.sessionQuery).toBeUndefined()
+    const stillAugmented = new DatabaseSync(augmentedPath)
+    expect(stillAugmented.prepare('SELECT value FROM unrelated').get()).toEqual({ value: 'safe' })
+    expect(stillAugmented.prepare('PRAGMA user_version').get()).toEqual({ user_version: 999 })
+    stillAugmented.close()
+
+    const currentAugmentedPath = await temporaryPath('current-augmented.db')
+    const currentAugmentedOwner = await liveContext({ path: currentAugmentedPath })
+    await (currentAugmentedOwner.sessionQuery as SessionQuerySqlite).close()
+    const currentAugmented = new DatabaseSync(currentAugmentedPath)
+    currentAugmented.exec('CREATE TABLE unrelated(value TEXT)')
+    currentAugmented.exec("INSERT INTO unrelated VALUES ('safe')")
+    currentAugmented.close()
+    const currentAugmentedCtx = new Context()
+    await currentAugmentedCtx.plugin(SessionStore)
+    await expect(currentAugmentedCtx.plugin(SessionQuerySqlite, {
+      path: currentAugmentedPath,
+      journalMode: 'delete',
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+    expect(currentAugmentedCtx.sessionQuery).toBeUndefined()
+    const stillCurrentAugmented = new DatabaseSync(currentAugmentedPath)
+    expect(stillCurrentAugmented.prepare('SELECT value FROM unrelated').get()).toEqual({ value: 'safe' })
+    expect(stillCurrentAugmented.prepare('PRAGMA user_version').get())
+      .toEqual({ user_version: SESSION_QUERY_SQLITE_SCHEMA_VERSION })
+    expect(stillCurrentAugmented.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'wal' })
+    stillCurrentAugmented.close()
+
+    const foreignPath = await temporaryPath('foreign.db')
+    const foreign = new DatabaseSync(foreignPath)
+    foreign.exec('PRAGMA journal_mode = WAL')
+    foreign.exec('CREATE TABLE canonical(value TEXT)')
+    foreign.exec("INSERT INTO canonical VALUES ('safe')")
+    foreign.close()
+    const foreignCtx = new Context()
+    await foreignCtx.plugin(SessionStore)
+    await expect(foreignCtx.plugin(SessionQuerySqlite, { path: foreignPath, journalMode: 'delete' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+    expect(foreignCtx.sessionQuery).toBeUndefined()
+    const stillForeign = new DatabaseSync(foreignPath)
+    expect(stillForeign.prepare('SELECT value FROM canonical').get()).toEqual({ value: 'safe' })
+    expect(stillForeign.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'wal' })
+    stillForeign.close()
+
+    const wildcardPath = await temporaryPath('sqlite-wildcard.db')
+    const wildcard = new DatabaseSync(wildcardPath)
+    wildcard.exec('PRAGMA journal_mode = WAL')
+    wildcard.exec('CREATE TABLE sqliteX(value TEXT)')
+    wildcard.exec("INSERT INTO sqliteX VALUES ('safe')")
+    wildcard.close()
+    const wildcardCtx = new Context()
+    await wildcardCtx.plugin(SessionStore)
+    await expect(wildcardCtx.plugin(SessionQuerySqlite, {
+      path: wildcardPath,
+      journalMode: 'delete',
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+    expect(wildcardCtx.sessionQuery).toBeUndefined()
+    const stillWildcard = new DatabaseSync(wildcardPath)
+    expect(stillWildcard.prepare('SELECT value FROM sqliteX').get()).toEqual({ value: 'safe' })
+    expect(stillWildcard.prepare('PRAGMA application_id').get()).toEqual({ application_id: 0 })
+    expect(stillWildcard.prepare('PRAGMA user_version').get()).toEqual({ user_version: 0 })
+    expect(stillWildcard.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'wal' })
+    stillWildcard.close()
+
+    const otherAppPath = await temporaryPath('other-app.db')
+    const otherApp = new DatabaseSync(otherAppPath)
+    otherApp.exec('PRAGMA application_id = 123')
+    otherApp.close()
+    const otherAppCtx = new Context()
+    await otherAppCtx.plugin(SessionStore)
+    await expect(otherAppCtx.plugin(SessionQuerySqlite, { path: otherAppPath }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+    expect(otherAppCtx.sessionQuery).toBeUndefined()
+  })
+
+  it('fails plugin initialization without an unhandled rejection or partial service', async () => {
+    const path = await temporaryPath('never-queried.db')
+    const foreign = new DatabaseSync(path)
+    foreign.exec('CREATE TABLE canonical(value TEXT)')
+    foreign.close()
+    const unhandled: unknown[] = []
+    const onUnhandled = (reason: unknown) => { unhandled.push(reason) }
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      const ctx = new Context()
+      await ctx.plugin(SessionStore)
+      await expect(ctx.plugin(SessionQuerySqlite, { path }))
+        .rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+      await new Promise<void>((resolve) => { setImmediate(resolve) })
+      expect(unhandled).toEqual([])
+      expect(ctx.sessionQuery).toBeUndefined()
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
+
+  it('cancels both queued and in-flight source waits without committing them', async () => {
+    TestPersistence.reset()
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+
+    const boundaryController = new AbortController()
+    const boundary = ctx.sessionQuery.searchSessions({ query: 'needle' }, { signal: boundaryController.signal })
+    queueMicrotask(() => { boundaryController.abort() })
+    await expect(boundary).rejects.toThrow(expectCode('SESSION_QUERY_ABORTED'))
+
+    const readyController = new AbortController()
+    readyController.abort()
+    const internals = ctx.sessionQuery as unknown as {
+      _ensureReady(signal: AbortSignal): Promise<void>
+    }
+    await expect(internals._ensureReady(readyController.signal))
+      .rejects.toThrow(expectCode('SESSION_QUERY_ABORTED'))
+
+    let releaseBlocking!: () => void
+    TestPersistence.listGate = new Promise<void>((resolve) => { releaseBlocking = resolve })
+    let markBlockingStarted!: () => void
+    const blockingStarted = new Promise<void>((resolve) => { markBlockingStarted = resolve })
+    TestPersistence.listStarted = () => {
+      TestPersistence.listStarted = undefined
+      markBlockingStarted()
+    }
+    const blocking = ctx.sessionQuery.searchSessions({ query: 'needle' })
+    await blockingStarted
+
+    const queuedController = new AbortController()
+    const queued = ctx.sessionQuery.searchSessions({ query: 'needle' }, { signal: queuedController.signal })
+    queuedController.abort()
+    await expect(queued).rejects.toThrow(expectCode('SESSION_QUERY_ABORTED'))
+
+    releaseBlocking()
+    await expect(blocking).resolves.toEqual({ items: [] })
+
+    TestPersistence.set({
+      meta: header('uncommitted'),
+      events: messageEvents('durable needle'),
+    })
+    let releaseActive!: () => void
+    TestPersistence.listGate = new Promise<void>((resolve) => { releaseActive = resolve })
+    let markActiveStarted!: () => void
+    const activeStarted = new Promise<void>((resolve) => { markActiveStarted = resolve })
+    TestPersistence.listStarted = () => {
+      TestPersistence.listStarted = undefined
+      markActiveStarted()
+    }
+    const activeController = new AbortController()
+    const active = ctx.sessionQuery.searchSessions({ query: 'needle' }, { signal: activeController.signal })
+    await activeStarted
+    activeController.abort()
+    await expect(active).rejects.toThrow(expectCode('SESSION_QUERY_ABORTED'))
+    releaseActive()
+
+    const db = (ctx.sessionQuery as unknown as { _db: DatabaseSync })._db
+    expect(db.prepare('SELECT COUNT(*) AS count FROM persisted_sessions').get()).toEqual({ count: 0 })
+    await expect(ctx.sessionQuery.searchSessions({ query: 'needle' }))
+      .resolves.toMatchObject({ items: [{ header: { id: SessionId('uncommitted') } }] })
+  })
+
+  it('rejects queued and future work when close waits for an accepted operation', async () => {
+    TestPersistence.reset()
+    let release!: () => void
+    TestPersistence.listGate = new Promise<void>((resolve) => { release = resolve })
+    let markStarted!: () => void
+    const started = new Promise<void>((resolve) => { markStarted = resolve })
+    TestPersistence.listStarted = () => {
+      TestPersistence.listStarted = undefined
+      markStarted()
+    }
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    const search = ctx.sessionQuery as SessionQuerySqlite
+    const accepted = search.searchSessions({ query: 'needle' })
+    await started
+    const queued = search.searchSessions({ query: 'needle' })
+    const closing = search.close()
+    const repeatedClose = search.close()
+    expect(repeatedClose).toBe(closing)
+    release()
+
+    await expect(accepted).resolves.toEqual({ items: [] })
+    await expect(queued).rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+    await Promise.all([closing, repeatedClose])
+    await expect(search.searchSessions({ query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INDEX_FAILED'))
+    expect(search.close()).toBe(closing)
+  })
+
+  it('awaits optional-persistence child-fiber quiescence on disposal', async () => {
+    TestPersistence.reset()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const search = await ctx.plugin(SessionQuerySqlite, { path: ':memory:' })
+    const persistence = await ctx.plugin(TestPersistence)
+    const optional = (ctx.sessionQuery as unknown as {
+      _optionalPersistenceFiber: Fiber
+    })._optionalPersistenceFiber
+    let release!: () => void
+    const cleanup = new Promise<void>((resolve) => { release = resolve })
+    optional.ctx.effect(() => () => cleanup)
+
+    let settled = false
+    const disposing = search.dispose().then(() => { settled = true })
+    await Promise.resolve()
+    expect(settled).toBe(false)
+    release()
+    await disposing
+    await persistence.dispose()
+  })
+
+  it('combines the real SQLite persistence backend with the real search service keylessly', async () => {
+    const persistencePath = await temporaryPath('canonical.db')
+    const searchPath = await temporaryPath('derived.db')
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const persistence = await ctx.plugin(SessionPersistenceSqlite, { path: persistencePath })
+    const search = await ctx.plugin(SessionQuerySqlite, { path: searchPath })
+    const meta = header('real', 10, { cwd: '/work' })
+    await ctx.sessionPersistence.create(meta)
+    await ctx.sessionPersistence.append(meta.id, messageEvents('real SQLite needle'))
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'SQLite needle' }))
+      .resolves.toMatchObject({ items: [{ header: meta, persisted: true, live: false }] })
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: meta.id, query: 'SQLite needle' }))
+      .resolves.toMatchObject({ items: [{ sessionId: meta.id, seq: 0 }] })
+    await expect(ctx.sessionQuery.searchEvents({ sessionId: SessionId('absent'), query: 'needle' }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
+    await search.dispose()
+    await expect(ctx.sessionPersistence.load(meta.id)).resolves.toMatchObject({ meta, events: [{ seq: 0 }] })
+    await persistence.dispose()
+  })
+
+  it('reconciles colliding local revisions when a derived index reopens against another SQLite store', async () => {
+    const persistencePathA = await temporaryPath('canonical-a.db')
+    const persistencePathB = await temporaryPath('canonical-b.db')
+    const searchPath = await temporaryPath('derived-collision.db')
+    const shared = header('same-id', 10)
+
+    const first = new Context()
+    await first.plugin(SessionStore)
+    const persistenceA = await first.plugin(SessionPersistenceSqlite, { path: persistencePathA })
+    await first.sessionPersistence.create(shared)
+    await first.sessionPersistence.append(shared.id, messageEvents('alpha source'))
+    const inspectA = vi.spyOn(first.sessionPersistence, 'inspect')
+    const searchA = await first.plugin(SessionQuerySqlite, { path: searchPath })
+    await expect(first.sessionQuery.searchSessions({ query: 'alpha' }))
+      .resolves.toMatchObject({ items: [{ header: shared }] })
+    expect(inspectA).toHaveBeenCalledTimes(1)
+    await searchA.dispose()
+    await persistenceA.dispose()
+
+    const reopened = new Context()
+    await reopened.plugin(SessionStore)
+    const persistenceAAgain = await reopened.plugin(SessionPersistenceSqlite, { path: persistencePathA })
+    const reopenedInspect = vi.spyOn(reopened.sessionPersistence, 'inspect')
+    const searchAAgain = await reopened.plugin(SessionQuerySqlite, { path: searchPath })
+    await expect(reopened.sessionQuery.searchSessions({ query: 'alpha' }))
+      .resolves.toMatchObject({ items: [{ header: shared }] })
+    expect(reopenedInspect).not.toHaveBeenCalled()
+    await searchAAgain.dispose()
+    await persistenceAAgain.dispose()
+
+    const second = new Context()
+    await second.plugin(SessionStore)
+    const persistenceB = await second.plugin(SessionPersistenceSqlite, { path: persistencePathB })
+    await second.sessionPersistence.create(shared)
+    await second.sessionPersistence.append(shared.id, messageEvents('bravo source'))
+    const inspectB = vi.spyOn(second.sessionPersistence, 'inspect')
+    const searchB = await second.plugin(SessionQuerySqlite, { path: searchPath })
+    await expect(second.sessionQuery.searchSessions({ query: 'bravo' }))
+      .resolves.toMatchObject({ items: [{ header: shared }] })
+    await expect(second.sessionQuery.searchSessions({ query: 'alpha' })).resolves.toEqual({ items: [] })
+    expect(inspectB).toHaveBeenCalledTimes(1)
+    await searchB.dispose()
+    await persistenceB.dispose()
+  })
+})
diff --git a/packages/session-query/session-query-sqlite/tsconfig.json b/packages/session-query/session-query-sqlite/tsconfig.json
new file mode 100644
index 0000000000..1f09565c4a
--- /dev/null
+++ b/packages/session-query/session-query-sqlite/tsconfig.json
@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../session-query"
+    }
+  ]
+}
diff --git a/packages/session-query/session-query/README.md b/packages/session-query/session-query/README.md
index 710419c6d8..019eced081 100644
--- a/packages/session-query/session-query/README.md
+++ b/packages/session-query/session-query/README.md
@@ -1,10 +1,13 @@
 # @deepseek-ai/dsh-session-query
 
-Exact session-history retrieval and relationship tracing through `ctx.sessionQuery`. The service presents live `ctx.sessions` and an optional, dynamically mounted `ctx.sessionPersistence` as one logical corpus. Matching ids produce one record: live events win, while `live` and `persisted` report both source availabilities. Conflicting immutable headers fail with `SESSION_QUERY_SOURCE_CONFLICT`.
+`SessionQueryService` is the combined abstract `ctx.sessionQuery` contract. It implements exact session-history retrieval, relationship tracing, and provider-independent filtering over live `ctx.sessions` plus optional dynamically mounted `ctx.sessionPersistence`; concrete backends implement its two full-text methods. Matching ids produce one record: live events win, while `live` and `persisted` report both source availabilities. Conflicting immutable headers fail with `SESSION_QUERY_SOURCE_CONFLICT`.
 
 ## Reads
 
 - `listSessions()` reads current persistence metadata, merges live records with live precedence, and returns cloned records in deterministic newest-first order.
+- `readSession(sessionId)` returns one complete detached raw log after the same core replay validation used by resume; it never enters the session into the live store.
+- `filterSessions(filters)` applies provider-independent session metadata and availability predicates to that same cloned logical corpus.
+- `filterEvents(sessionId, filters)` extracts first-party semantic documents and applies provider-independent metadata and literal-text predicates in ascending seq order.
 - `readTitle(sessionId)` loads one live-preferred or persisted log and folds its latest `session/title` event into a `SessionTitleSnapshot`; it returns `undefined` when the known session has no title.
 - `listEvents(sessionId)` loads the live-preferred raw log and classifies each event as `current`, `shadowed`, or `log-only` with the shared `dsh-session` surface fold.
 - `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.
@@ -14,9 +17,21 @@ Exact session-history retrieval and relationship tracing through `ctx.sessionQue
 
 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 title, event read, or trace 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. `listSessions()` remains lightweight and does not load logs or index titles.
 
-`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`.
+## Filtering and extraction
 
-`SessionQueryError.code` is a closed union: `SESSION_QUERY_EVENT_NOT_FOUND`, `SESSION_QUERY_INVALID_CONFIG`, `SESSION_QUERY_INVALID_LINEAGE`, `SESSION_QUERY_INVALID_SURFACE`, `SESSION_QUERY_INVALID_WINDOW`, `SESSION_QUERY_PERSISTENCE_FAILED`, `SESSION_QUERY_SESSION_NOT_FOUND`, and `SESSION_QUERY_SOURCE_CONFLICT`.
+`SessionResultFilter` covers id, nullable cwd, created-at range, nullable parent, and source availability. `SessionEventResultFilter` covers seq/time ranges, event type, surface, and semantic text. Filter arrays are ANDed; values within one list clause are ORed. Empty list values match nothing, ranges are inclusive, and malformed ranges or closed-union values fail with `SESSION_QUERY_INVALID_FILTER`.
+
+The text clause is deliberately independent of FTS providers: caller text is escaped into a Unicode, case-insensitive regular expression, and each whitespace run matches one or more whitespace characters. It is a literal semantic-text scan, not a full-text query. `extractSessionEventText()` and `buildSessionEventSearchDocuments()` define the shared first-party document projection; structural boundaries, stream chunks, request headers, and unknown declaration-merged variants produce no document.
+
+## Full-text methods
+
+`SessionQueryService.searchSessions(request, exec?)` groups the logical corpus by strongest matching event; `searchEvents(request, exec?)` searches one logical session. These are the service's only abstract methods. Both return pages whose continuation is an owned branded `SessionSearchCursor`, accept optional cancellation, and expose snippets without provider-specific numeric scores. Search requests accept only metadata event filters, because literal-text filtering is the scan path described above.
+
+The package has no provider coordinator, fallback implementation, or standalone concrete plugin. A concrete service backend inherits the implemented reads, filters, and traces while owning full-text observation, reconciliation, ranking, cursor generations, and query execution; the first implementation is [`@deepseek-ai/dsh-session-query-sqlite`](../session-query-sqlite/README.md).
+
+`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`.
 
 ## Configuration
 
@@ -35,4 +50,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 search or extraction** — filters, extraction registry, search-provider protocol, index synchronization, and a model-facing tool are absent. The [tracing decision](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) owns relationship semantics; content-bearing full-text-search results and their chainable filters belong beside their first implementation in the proposed [SQLite package](../../../.agents/notes/proposed/feature/2026-07-10-sqlite-session-query-provider.md).
+- **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).
diff --git a/packages/session-query/session-query/package.json b/packages/session-query/session-query/package.json
index a9dd78a614..daf4d4e680 100644
--- a/packages/session-query/session-query/package.json
+++ b/packages/session-query/session-query/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-session-query",
-  "description": "Live-preferred exact session-history retrieval and tracing service (ctx.sessionQuery)",
+  "description": "Combined session query service contract with concrete reads, traces, and filters",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -27,6 +27,7 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
@@ -39,10 +40,8 @@
       "optional": true
     }
   },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/session-query/session-query/src/config.ts b/packages/session-query/session-query/src/config.ts
index 4a15366c2c..5b7ddffd90 100644
--- a/packages/session-query/session-query/src/config.ts
+++ b/packages/session-query/session-query/src/config.ts
@@ -1,25 +1,32 @@
-/** Public configuration and typed failures for session-query. */
+/** Public configuration and typed failures for the combined session-query service. */
 
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 
 /** Default maximum `before`/`after` raw-event window. */
 export const SESSION_QUERY_READ_WINDOW_MAX = 50
 
-/** Configuration for exact session-query reads and traces. */
+/** Backend-independent configuration inherited by every session-query implementation. */
 export interface Config {
   /** Maximum accepted raw read context on either side. Defaults to 50. */
   readWindowMax?: number
 }
 
-/** Stable machine-routable failure taxonomy for exact session reads and traces. */
+/** Stable machine-routable failure taxonomy for session reads, traces, and search. */
 export type SessionQueryErrorCode =
+  | 'SESSION_QUERY_ABORTED'
   | 'SESSION_QUERY_EVENT_NOT_FOUND'
+  | 'SESSION_QUERY_INDEX_FAILED'
   | 'SESSION_QUERY_INVALID_CONFIG'
+  | 'SESSION_QUERY_INVALID_CURSOR'
+  | 'SESSION_QUERY_INVALID_FILTER'
+  | 'SESSION_QUERY_INVALID_LIMIT'
+  | 'SESSION_QUERY_INVALID_QUERY'
   | 'SESSION_QUERY_INVALID_LINEAGE'
   | 'SESSION_QUERY_INVALID_SURFACE'
   | 'SESSION_QUERY_INVALID_WINDOW'
   | 'SESSION_QUERY_PERSISTENCE_FAILED'
   | 'SESSION_QUERY_SESSION_NOT_FOUND'
+  | 'SESSION_QUERY_STALE_CURSOR'
   | 'SESSION_QUERY_SOURCE_CONFLICT'
 
 /** Typed session-query failure whose `code` is one closed taxonomy member. */
diff --git a/packages/session-query/session-query/src/corpus.ts b/packages/session-query/session-query/src/corpus.ts
index ebc3d92577..0e1753d5ce 100644
--- a/packages/session-query/session-query/src/corpus.ts
+++ b/packages/session-query/session-query/src/corpus.ts
@@ -1,10 +1,11 @@
 /** Live/persisted logical-corpus resolution for session-query. */
 
-import type { Context } from 'cordis'
+import type { Context, Fiber } from 'cordis'
 import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
 import type { SessionRecord } from './types.ts'
 import { SessionQueryError } from './config.ts'
+import { assertSessionHeadersCompatible } from './sources.ts'
 
 /** Detached source selected for one exact read. */
 export interface LogicalSession {
@@ -17,18 +18,19 @@ export interface LogicalSession {
 /** Resolves a live-preferred corpus against the persistence service mounted now. */
 export class SessionCorpus {
   private _persistence: SessionPersistence | undefined
+  private readonly _optionalPersistenceFiber: Fiber
 
   constructor(private readonly _ctx: Context) {
+    this._optionalPersistenceFiber = _ctx.inject(['sessionPersistence'], (childCtx: Context) => {
+      const service = childCtx.sessionPersistence
+      this._persistence = service
+      childCtx.effect(() => () => {
+        /* v8 ignore next -- a stale optional-service disposer cannot clear a replacement */
+        if (this._persistence === service) this._persistence = undefined
+      }, 'sessionQuery.persistenceBinding')
+    })
     _ctx.effect(() => {
-      const fiber = _ctx.inject(['sessionPersistence'], (childCtx: Context) => {
-        const service = childCtx.sessionPersistence
-        this._persistence = service
-        childCtx.effect(() => () => {
-          /* v8 ignore next -- a stale optional-service disposer cannot clear a replacement */
-          if (this._persistence === service) this._persistence = undefined
-        }, 'sessionQuery.persistenceBinding')
-      })
-      return () => void fiber.dispose()
+      return () => this._optionalPersistenceFiber.dispose()
     }, 'sessionQuery.optionalPersistence')
   }
 
@@ -45,7 +47,7 @@ export class SessionCorpus {
     }
     for (const session of this._ctx.sessions.list()) {
       const durable = records.get(session.id)
-      if (durable !== undefined) assertCompatibleHeaders(session.header, durable.header)
+      if (durable !== undefined) assertSessionHeadersCompatible(session.header, durable.header)
       records.set(session.id, {
         header: structuredClone(session.header),
         live: true,
@@ -70,17 +72,19 @@ export class SessionCorpus {
     if (persistence === undefined) throw notFound(sessionId)
     const listed = (await listPersisted(persistence)).find(header => header.id === sessionId)
     if (listed === undefined) throw notFound(sessionId)
-    let loaded: Awaited<ReturnType<SessionPersistence['load']>>
+    let loaded: Awaited<ReturnType<SessionPersistence['inspect']>>
     try {
-      loaded = await persistence.load(sessionId)
+      loaded = await persistence.inspect(sessionId)
     } catch (error: unknown) {
       throw new SessionQueryError(
-        `failed to load session "${sessionId}": ${errorMessage(error)}`,
+        `failed to inspect session "${sessionId}": ${errorMessage(error)}`,
         'SESSION_QUERY_PERSISTENCE_FAILED',
         { cause: error },
       )
     }
-    assertCompatibleHeaders(loaded.meta, listed)
+    const attached = this._ctx.sessions.get(sessionId)
+    if (attached !== undefined) return snapshotLive(attached)
+    assertSessionHeadersCompatible(loaded.meta, listed)
     return {
       header: structuredClone(loaded.meta),
       events: loaded.events.map(event => structuredClone(event)),
@@ -107,22 +111,6 @@ function snapshotLive(session: Session): LogicalSession {
   }
 }
 
-function assertCompatibleHeaders(a: SessionHeader, b: SessionHeader): void {
-  if (
-    a.version !== b.version
-    || a.id !== b.id
-    || a.createdAt !== b.createdAt
-    || a.cwd !== b.cwd
-    || a.parentSession !== b.parentSession
-    || a.seedLength !== b.seedLength
-  ) {
-    throw new SessionQueryError(
-      `live and persisted headers conflict for session "${a.id}"`,
-      'SESSION_QUERY_SOURCE_CONFLICT',
-    )
-  }
-}
-
 function compareSessions(a: SessionRecord, b: SessionRecord): number {
   return b.header.createdAt - a.header.createdAt || a.header.id.localeCompare(b.header.id)
 }
diff --git a/packages/session-query/session-query/src/cursor.ts b/packages/session-query/session-query/src/cursor.ts
new file mode 100644
index 0000000000..8ee2a6660d
--- /dev/null
+++ b/packages/session-query/session-query/src/cursor.ts
@@ -0,0 +1,15 @@
+/** Opaque cursor identity for session-search pagination. */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Provider-owned opaque continuation token returned by session search. */
+export type SessionSearchCursor = Branded<'SessionSearchCursor'>
+
+/**
+ * Brand an encoded provider cursor for the public search contract.
+ * @param value - opaque encoded cursor value.
+ * @returns the same runtime string with session-search cursor identity.
+ */
+export function SessionSearchCursor(value: string): SessionSearchCursor {
+  return value as SessionSearchCursor
+}
diff --git a/packages/session-query/session-query/src/documents.ts b/packages/session-query/session-query/src/documents.ts
new file mode 100644
index 0000000000..7b22a2c26d
--- /dev/null
+++ b/packages/session-query/session-query/src/documents.ts
@@ -0,0 +1,74 @@
+/** Shared event metadata and semantic-document projection. */
+
+import { foldSurface } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEventRecord, SessionEventSearchDocument, SessionEventSurface } from './types.ts'
+import { SessionQueryError } from './config.ts'
+import { extractSessionEventText } from './extraction.ts'
+
+/**
+ * Project a raw log into lightweight surface-aware event records.
+ * @param sessionId - session that owns the log.
+ * @param events - complete contiguous raw event log.
+ * @returns one record per event in ascending seq order.
+ */
+export function buildSessionEventRecords(
+  sessionId: SessionId,
+  events: readonly SessionEvent[],
+): SessionEventRecord[] {
+  const surfaceBySeq = classifySurface(events)
+  return events.map(event => ({
+    sessionId,
+    seq: event.seq,
+    type: event.type,
+    time: event.time,
+    surface: surfaceBySeq.get(event.seq) ?? 'log-only',
+  }))
+}
+
+/**
+ * Build first-party semantic documents for one complete raw event log.
+ * @param sessionId - session that owns the log.
+ * @param events - complete contiguous raw event log.
+ * @returns searchable documents in ascending seq order; structural events are omitted.
+ */
+export function buildSessionEventSearchDocuments(
+  sessionId: SessionId,
+  events: readonly SessionEvent[],
+): SessionEventSearchDocument[] {
+  const surfaceBySeq = classifySurface(events)
+  const documents: SessionEventSearchDocument[] = []
+  for (const event of events) {
+    const text = extractSessionEventText(event)
+    if (text.length === 0) continue
+    documents.push({
+      sessionId,
+      seq: event.seq,
+      type: event.type,
+      time: event.time,
+      surface: surfaceBySeq.get(event.seq) ?? 'log-only',
+      text,
+    })
+  }
+  return documents
+}
+
+function classifySurface(events: readonly SessionEvent[]): Map<number, SessionEventSurface> {
+  let folded: ReturnType<typeof foldSurface>
+  try {
+    folded = foldSurface(events)
+  } catch (error: unknown) {
+    throw new SessionQueryError(
+      /* v8 ignore next -- foldSurface throws Error instances */
+      `invalid session surface: ${error instanceof Error ? error.message : 'unknown error'}`,
+      'SESSION_QUERY_INVALID_SURFACE',
+      { cause: error },
+    )
+  }
+  const result = new Map<number, SessionEventSurface>()
+  for (const seq of folded.nodes) result.set(seq, 'current')
+  for (const replacement of folded.replacements) {
+    for (const seq of replacement.shadowedSeqs) result.set(seq, 'shadowed')
+  }
+  return result
+}
diff --git a/packages/session-query/session-query/src/extraction.ts b/packages/session-query/session-query/src/extraction.ts
new file mode 100644
index 0000000000..4cbe850352
--- /dev/null
+++ b/packages/session-query/session-query/src/extraction.ts
@@ -0,0 +1,93 @@
+/** First-party semantic text extraction for session-query consumers. */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/**
+ * Extract searchable semantic text from one first-party session event.
+ *
+ * Structural boundaries, raw stream chunks, request envelopes, and unknown
+ * declaration-merged events contribute no text.
+ * @param event - event to inspect.
+ * @returns newline-joined semantic text, or an empty string when non-searchable.
+ */
+export function extractSessionEventText(event: SessionEvent): string {
+  switch (event.type) {
+    case 'user/message':
+    case 'assistant/message':
+    case 'steering/message':
+      return contentText(event.data.content)
+    case 'prompt/blocked':
+      return joinText([contentText(event.data.content), event.data.reason])
+    case 'tool/call':
+      return joinText([event.data.name, event.data.arguments])
+    case 'tool/result':
+      return joinText([
+        contentText(event.data.content),
+        event.data.error?.name ?? '',
+        event.data.error?.code ?? '',
+      ])
+    case 'todo/write':
+      return joinText(event.data.todos.flatMap(todo => [todo.status, todo.content]))
+    case 'turn/end':
+      return turnEndText(event.data.reason)
+    case 'turn/start':
+    case 'step/start':
+    case 'step/end':
+    case 'assistant/chunk':
+    case 'request/header':
+      return ''
+    // SessionEventMap is merge-extensible. Unknown events remain
+    // non-searchable until a concrete first-party consumer defines semantics.
+    default:
+      return ''
+  }
+}
+
+function turnEndText(reason: SessionEvent<'turn/end'>['data']['reason']): string {
+  switch (reason.kind) {
+    case 'error':
+      return 'failure' in reason
+        ? joinText(['error', reason.failure.message, reason.failure.code])
+        : joinText(['error', reason.message, reason.code ?? ''])
+    case 'aborted':
+      return 'aborted'
+    case 'rejected':
+      return joinText(['rejected', reason.reason])
+    case 'disposed':
+    case 'max-tokens':
+    case 'interrupted':
+      return reason.kind
+    case 'completed':
+      return ''
+    // TurnEndReasonMap is merge-extensible. Unknown outcomes stay out until
+    // their owner defines which detail is semantic rather than structural.
+    default:
+      return ''
+  }
+}
+
+type SessionContentBlock = SessionEvent<'user/message'>['data']['content'][number]
+
+function contentText(content: readonly SessionContentBlock[]): string {
+  return joinText(content.flatMap(blockText))
+}
+
+function blockText(block: SessionContentBlock): string[] {
+  switch (block.type) {
+    case 'text':
+    case 'reasoning':
+      return [block.text]
+    case 'tool-call':
+      return [block.name, block.arguments]
+    case 'tool-result':
+      return block.content.flatMap(blockText)
+    // ContentBlockMap is merge-extensible. Unknown blocks do not become
+    // searchable merely because their payload happens to contain strings.
+    default:
+      return []
+  }
+}
+
+function joinText(parts: readonly string[]): string {
+  return parts.map(part => part.trim()).filter(Boolean).join('\n')
+}
diff --git a/packages/session-query/session-query/src/filters.ts b/packages/session-query/session-query/src/filters.ts
new file mode 100644
index 0000000000..91ae640615
--- /dev/null
+++ b/packages/session-query/session-query/src/filters.ts
@@ -0,0 +1,243 @@
+/** Pure provider-independent predicates for logical sessions and event text. */
+
+import type {
+  SessionEventResultFilter,
+  SessionEventSearchDocument,
+  SessionRecord,
+  SessionResultFilter,
+  SessionResultRange,
+} from './types.ts'
+import { SessionQueryError } from './config.ts'
+
+/**
+ * Apply ANDed logical-session filters while preserving input order.
+ * @param records - detached logical-session records to inspect.
+ * @param filters - clauses whose list values are ORed within each clause.
+ * @returns records accepted by every clause.
+ */
+export function filterSessionResults<T extends SessionRecord>(
+  records: readonly T[],
+  filters: readonly SessionResultFilter[] = [],
+): T[] {
+  const predicates = filters.map(sessionPredicate)
+  return records.filter(record => predicates.every(predicate => predicate(record)))
+}
+
+/**
+ * Apply ANDed event filters to extracted semantic documents.
+ * @param documents - semantic documents produced by {@link buildSessionEventSearchDocuments}.
+ * @param filters - metadata and literal-text predicates.
+ * @returns documents accepted by every clause, in input order.
+ */
+export function filterSessionEventDocuments<T extends SessionEventSearchDocument>(
+  documents: readonly T[],
+  filters: readonly SessionEventResultFilter[] = [],
+): T[] {
+  const predicates = filters.map(eventPredicate)
+  return documents.filter(document => predicates.every(predicate => predicate(document)))
+}
+
+/**
+ * Copy and validate logical-session filters before an asynchronous boundary.
+ * @param filters - caller-owned clauses to materialize.
+ * @returns detached validated clauses.
+ */
+export function materializeSessionResultFilters(
+  filters: readonly SessionResultFilter[],
+): SessionResultFilter[] {
+  assertArray(filters)
+  return filters.map((filter) => {
+    switch (filter.kind) {
+      case 'id':
+        return { kind: filter.kind, values: copyStrings(filter.kind, filter.values) }
+      case 'cwd':
+        return { kind: filter.kind, values: copyNullableStrings(filter.kind, filter.values) }
+      case 'created-at':
+        return copyRange(filter.kind, filter)
+      case 'parent':
+        return { kind: filter.kind, values: copyNullableStrings(filter.kind, filter.values) }
+      case 'availability': {
+        const values = copyStrings(filter.kind, filter.values)
+        assertAllowedValues(filter.kind, values, ['live', 'persisted'])
+        return { kind: filter.kind, values }
+      }
+      default:
+        return unknownFilter(filter)
+    }
+  })
+}
+
+/**
+ * Copy and validate event filters before an asynchronous boundary.
+ * @param filters - caller-owned clauses to materialize.
+ * @returns detached validated clauses.
+ */
+export function materializeSessionEventResultFilters(
+  filters: readonly SessionEventResultFilter[],
+): SessionEventResultFilter[] {
+  assertArray(filters)
+  return filters.map((filter) => {
+    switch (filter.kind) {
+      case 'seq':
+      case 'time':
+        return copyRange(filter.kind, filter)
+      case 'type':
+        return { kind: filter.kind, values: copyStrings(filter.kind, filter.values) }
+      case 'surface': {
+        const values = copyStrings(filter.kind, filter.values)
+        assertAllowedValues(filter.kind, values, ['current', 'shadowed', 'log-only'])
+        return { kind: filter.kind, values }
+      }
+      case 'text':
+        if (typeof filter.text !== 'string') throw invalidFilter('text filter text must be a string')
+        return { kind: filter.kind, text: filter.text }
+      default:
+        return unknownFilter(filter)
+    }
+  })
+}
+
+/**
+ * Compile a literal case-insensitive, whitespace-flexible semantic-text match.
+ * @param text - caller-provided literal text.
+ * @returns Unicode-aware regular expression safe from regex injection.
+ */
+export function compileSessionTextFilter(text: string): RegExp {
+  const trimmed = text.trim()
+  if (trimmed.length === 0) {
+    throw new SessionQueryError(
+      'session text filter must contain non-whitespace text',
+      'SESSION_QUERY_INVALID_FILTER',
+    )
+  }
+  const pattern = trimmed
+    .split(/\s+/u)
+    .map(part => part.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&'))
+    .join('\\s+')
+  return new RegExp(pattern, 'iu')
+}
+
+function sessionPredicate(filter: SessionResultFilter): (record: SessionRecord) => boolean {
+  switch (filter.kind) {
+    case 'id':
+      return record => filter.values.includes(record.header.id)
+    case 'cwd':
+      return record => filter.values.includes(record.header.cwd ?? null)
+    case 'created-at': {
+      const range = validateRange(filter.kind, filter)
+      return record => matchesRange(record.header.createdAt, range)
+    }
+    case 'parent':
+      return record => filter.values.includes(record.header.parentSession ?? null)
+    case 'availability':
+      assertAllowedValues(filter.kind, filter.values, ['live', 'persisted'])
+      return record => filter.values.some(value => value === 'live' ? record.live : record.persisted)
+    default:
+      return unknownFilter(filter)
+  }
+}
+
+function eventPredicate(filter: SessionEventResultFilter): (document: SessionEventSearchDocument) => boolean {
+  switch (filter.kind) {
+    case 'seq': {
+      const range = validateRange(filter.kind, filter)
+      return document => matchesRange(document.seq, range)
+    }
+    case 'time': {
+      const range = validateRange(filter.kind, filter)
+      return document => matchesRange(document.time, range)
+    }
+    case 'type':
+      return document => filter.values.includes(document.type)
+    case 'surface':
+      assertAllowedValues(filter.kind, filter.values, ['current', 'shadowed', 'log-only'])
+      return document => filter.values.includes(document.surface)
+    case 'text': {
+      const pattern = compileSessionTextFilter(filter.text)
+      return document => pattern.test(document.text)
+    }
+    default:
+      return unknownFilter(filter)
+  }
+}
+
+function copyStrings<T extends string>(name: string, values: readonly T[]): T[] {
+  if (!isRuntimeArray(values) || values.some(value => typeof value !== 'string')) {
+    throw invalidFilter(`${name} filter values must be an array of strings`)
+  }
+  return [...values]
+}
+
+function assertArray(value: unknown): void {
+  if (!Array.isArray(value)) throw invalidFilter('filters must be an array')
+}
+
+function copyNullableStrings<T extends string>(name: string, values: readonly (T | null)[]): Array<T | null> {
+  if (!isRuntimeArray(values) || values.some(value => value !== null && typeof value !== 'string')) {
+    throw invalidFilter(`${name} filter values must be an array of strings or null`)
+  }
+  return [...values]
+}
+
+function copyRange<K extends 'created-at' | 'seq' | 'time'>(
+  kind: K,
+  range: SessionResultRange,
+): { kind: K } & SessionResultRange {
+  const copy = {
+    kind,
+    ...range.from === undefined ? {} : { from: range.from },
+    ...range.to === undefined ? {} : { to: range.to },
+  }
+  validateRange(kind, copy)
+  return copy
+}
+
+function unknownFilter(filter: never): never {
+  const kind = (filter as { kind?: unknown }).kind
+  throw invalidFilter(`unknown filter kind ${typeof kind === 'string' ? `"${kind}"` : '(missing)'}`)
+}
+
+function assertAllowedValues(
+  name: string,
+  values: readonly string[],
+  allowed: readonly string[],
+): void {
+  for (const value of values) {
+    if (!allowed.includes(value)) {
+      throw new SessionQueryError(
+        `session ${name} filter contains unknown value "${value}"`,
+        'SESSION_QUERY_INVALID_FILTER',
+      )
+    }
+  }
+}
+
+function validateRange(name: string, range: SessionResultRange): SessionResultRange {
+  if (range.from !== undefined && !Number.isFinite(range.from)) {
+    throw invalidRange(name, 'from must be finite')
+  }
+  if (range.to !== undefined && !Number.isFinite(range.to)) {
+    throw invalidRange(name, 'to must be finite')
+  }
+  if (range.from !== undefined && range.to !== undefined && range.from > range.to) {
+    throw invalidRange(name, 'from must be less than or equal to to')
+  }
+  return range
+}
+
+function matchesRange(value: number, range: SessionResultRange): boolean {
+  return (range.from === undefined || value >= range.from)
+    && (range.to === undefined || value <= range.to)
+}
+
+function invalidRange(name: string, detail: string): SessionQueryError {
+  return invalidFilter(`${name} filter ${detail}`)
+}
+
+function invalidFilter(detail: string): SessionQueryError {
+  return new SessionQueryError(`session ${detail}`, 'SESSION_QUERY_INVALID_FILTER')
+}
+
+function isRuntimeArray(value: unknown): boolean {
+  return Array.isArray(value)
+}
diff --git a/packages/session-query/session-query/src/index.ts b/packages/session-query/session-query/src/index.ts
index 665e2f8577..826802e2b4 100644
--- a/packages/session-query/session-query/src/index.ts
+++ b/packages/session-query/session-query/src/index.ts
@@ -1,22 +1,31 @@
 /**
- * Exact session-history reads and traces over live and optionally persisted logs.
+ * Combined session-history reads, traces, filters, and full-text search seam.
  *
  * @module @deepseek-ai/dsh-session-query
  */
 
 import { Context, Service } from 'cordis'
-import z from 'schemastery'
-import type { SessionId } from '@deepseek-ai/dsh-session'
+import { Session, type SessionId } from '@deepseek-ai/dsh-session'
 import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
 import type { SessionTitleSnapshot } from '@deepseek-ai/dsh-session-title'
 import type {
+  SessionEventResultFilter,
   SessionEventReadRequest,
   SessionEventRecord,
+  SessionEventSearchHit,
+  SessionEventSearchDocument,
+  SessionEventSearchRequest,
   SessionEventTrace,
   SessionEventTraceRequest,
   SessionEventWindow,
   SessionLineageTrace,
+  SessionLogSnapshot,
   SessionRecord,
+  SessionResultFilter,
+  SessionSearchExecContext,
+  SessionSearchHit,
+  SessionSearchPage,
+  SessionSearchRequest,
   SessionSurfaceSnapshot,
 } from './types.ts'
 import {
@@ -25,11 +34,29 @@ import {
   type Config,
 } from './config.ts'
 import { SessionCorpus } from './corpus.ts'
+import { buildSessionEventSearchDocuments } from './documents.ts'
+import {
+  filterSessionEventDocuments,
+  filterSessionResults,
+  materializeSessionEventResultFilters,
+  materializeSessionResultFilters,
+} from './filters.ts'
 import * as tracing from './tracing.ts'
 
 export type * from './types.ts'
+export { SessionSearchCursor } from './cursor.ts'
 export type { Config, SessionQueryErrorCode } from './config.ts'
 export { SESSION_QUERY_READ_WINDOW_MAX, SessionQueryError } from './config.ts'
+export { extractSessionEventText } from './extraction.ts'
+export { buildSessionEventRecords, buildSessionEventSearchDocuments } from './documents.ts'
+export {
+  compileSessionTextFilter,
+  filterSessionEventDocuments,
+  filterSessionResults,
+  materializeSessionEventResultFilters,
+  materializeSessionResultFilters,
+} from './filters.ts'
+export { assertSessionHeadersCompatible } from './sources.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -37,12 +64,15 @@ declare module 'cordis' {
   }
 }
 
-/** Live-preferred logical-corpus exact-read and relationship-tracing service. */
-export class SessionQueryService extends Service {
+/**
+ * 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.
+ */
+export abstract class SessionQueryService extends Service {
   static inject = ['sessions']
-  static Config: z<Config> = z.object({
-    readWindowMax: z.number().step(1).min(0).default(SESSION_QUERY_READ_WINDOW_MAX),
-  })
 
   private readonly _readWindowMax: number
   private readonly _corpus: SessionCorpus
@@ -59,6 +89,28 @@ export class SessionQueryService extends Service {
     this._corpus = new SessionCorpus(ctx)
   }
 
+  /**
+   * 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 in deterministic relevance order.
+   */
+  abstract searchEvents(
+    request: SessionEventSearchRequest,
+    exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionEventSearchHit>>
+
   /**
    * List the complete logical corpus using live-preferred records.
    * @returns deterministic newest-first cloned session records.
@@ -67,6 +119,31 @@ export class SessionQueryService extends Service {
     return this._corpus.listSessions()
   }
 
+  /**
+   * 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> {
+    const loaded = await this._corpus.load(sessionId)
+    new Session(sessionId, loaded.events, loaded.header)
+    return {
+      session: structuredClone(loaded.header),
+      events: loaded.events.map(event => structuredClone(event)),
+    }
+  }
+
+  /**
+   * Filter the complete logical corpus with provider-independent predicates.
+   * @param filters - ANDed session metadata and availability clauses.
+   * @returns matching cloned records in deterministic newest-first order.
+   */
+  async filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]> {
+    const ownedFilters = materializeSessionResultFilters(filters)
+    return this._filterSessions(ownedFilters)
+  }
+
   /**
    * Fold the latest log-backed title from one live-preferred logical session.
    * @param sessionId - live or persisted session id to read.
@@ -87,6 +164,33 @@ export class SessionQueryService extends Service {
     return tracing.eventRecords(sessionId, loaded.events)
   }
 
+  /**
+   * 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[]> {
+    const ownedFilters = materializeSessionEventResultFilters(filters)
+    return this._filterEvents(sessionId, ownedFilters)
+  }
+
+  private async _filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]> {
+    return filterSessionResults(await this._corpus.listSessions(), filters)
+  }
+
+  private async _filterEvents(
+    sessionId: SessionId,
+    filters: readonly SessionEventResultFilter[],
+  ): Promise<SessionEventSearchDocument[]> {
+    const loaded = await this._corpus.load(sessionId)
+    const documents = buildSessionEventSearchDocuments(sessionId, loaded.events)
+    return filterSessionEventDocuments(documents, filters)
+  }
+
   /**
    * Read one session's complete current model surface from one corpus observation.
    * @param sessionId - live-preferred session id to read.
@@ -132,16 +236,27 @@ export class SessionQueryService extends Service {
   async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow> {
     const before = this._readWindow('before', request.before)
     const after = this._readWindow('after', request.after)
-    const loaded = await this._corpus.load(request.sessionId)
-    const target = loaded.events[request.seq]
-    if (target === undefined || target.seq !== request.seq) {
+    const sessionId = request.sessionId
+    const seq = request.seq
+    return this._readEvent(sessionId, seq, before, after)
+  }
+
+  private async _readEvent(
+    sessionId: SessionId,
+    seq: number,
+    before: number,
+    after: number,
+  ): Promise<SessionEventWindow> {
+    const loaded = await this._corpus.load(sessionId)
+    const target = loaded.events[seq]
+    if (target === undefined || target.seq !== seq) {
       throw new SessionQueryError(
-        `session "${request.sessionId}" has no event at seq ${request.seq}`,
+        `session "${sessionId}" has no event at seq ${seq}`,
         'SESSION_QUERY_EVENT_NOT_FOUND',
       )
     }
-    const startSeq = Math.max(0, request.seq - before)
-    const endSeq = Math.min(loaded.events.length - 1, request.seq + after)
+    const startSeq = Math.max(0, seq - before)
+    const endSeq = Math.min(loaded.events.length - 1, seq + after)
     return {
       session: loaded.header,
       target,
diff --git a/packages/session-query/session-query/src/sources.ts b/packages/session-query/session-query/src/sources.ts
new file mode 100644
index 0000000000..f1bb64275f
--- /dev/null
+++ b/packages/session-query/session-query/src/sources.ts
@@ -0,0 +1,26 @@
+/** Shared immutable-header checks for logical session source observers. */
+
+import type { SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionQueryError } from './config.ts'
+
+/**
+ * Reject incompatible observations of one logical session source.
+ * @param a - first live, listed, or loaded header observation.
+ * @param b - second header observation expected to identify the same source.
+ */
+export function assertSessionHeadersCompatible(a: SessionHeader, b: SessionHeader): void {
+  if (
+    a.version !== b.version
+    || a.id !== b.id
+    || a.createdAt !== b.createdAt
+    || a.cwd !== b.cwd
+    || a.parentSession !== b.parentSession
+    || a.seedLength !== b.seedLength
+    || (a.delegationDepth ?? 0) !== (b.delegationDepth ?? 0)
+  ) {
+    throw new SessionQueryError(
+      `session source headers conflict for session "${a.id}"`,
+      'SESSION_QUERY_SOURCE_CONFLICT',
+    )
+  }
+}
diff --git a/packages/session-query/session-query/src/types.ts b/packages/session-query/session-query/src/types.ts
index 25c4a7131b..0f89de8156 100644
--- a/packages/session-query/session-query/src/types.ts
+++ b/packages/session-query/session-query/src/types.ts
@@ -5,7 +5,16 @@
  * @module @deepseek-ai/dsh-session-query/types
  */
 
-import type { SessionEvent, SessionEventType, SessionHeader, SessionId, SurfaceEvent } from '@deepseek-ai/dsh-session'
+import type {
+  SessionEvent,
+  SessionEventType,
+  SessionHeader,
+  SessionId,
+  SurfaceEvent,
+} from '@deepseek-ai/dsh-session'
+import type { SessionSearchCursor } from './cursor.ts'
+
+export type { SessionSearchCursor } from './cursor.ts'
 
 /** Whether an event is current model context, replaced context, or raw-log-only. */
 export type SessionEventSurface = 'current' | 'shadowed' | 'log-only'
@@ -30,6 +39,14 @@ export interface SessionSurfaceSnapshot {
   events: SurfaceEvent[]
 }
 
+/** One validated detached observation of a logical session's complete raw log. */
+export interface SessionLogSnapshot {
+  /** Cloned session header selected from the same observation as `events`. */
+  session: SessionHeader
+  /** Cloned contiguous raw events after persistence repair and replay validation. */
+  events: SessionEvent[]
+}
+
 /** Lightweight metadata for one event within a logical session. */
 export interface SessionEventRecord {
   /** Session that owns the event. */
@@ -124,3 +141,99 @@ export interface SessionEventWindow {
   /** Last seq included in `events`. */
   endSeq: number
 }
+
+/** Inclusive numeric interval used by time and sequence filters. */
+export interface SessionResultRange {
+  /** Inclusive lower bound. */
+  from?: number
+  /** Inclusive upper bound. */
+  to?: number
+}
+
+/** Source availability predicates understood by logical-session filters. */
+export type SessionAvailability = 'live' | 'persisted'
+
+/**
+ * One logical-session predicate. A filter array is ANDed; `values` within a
+ * clause are ORed.
+ */
+export type SessionResultFilter =
+  | { kind: 'id'; values: readonly SessionId[] }
+  | { kind: 'cwd'; values: readonly (string | null)[] }
+  | ({ kind: 'created-at' } & SessionResultRange)
+  | { kind: 'parent'; values: readonly (SessionId | null)[] }
+  | { kind: 'availability'; values: readonly SessionAvailability[] }
+
+/**
+ * One event predicate. A filter array is ANDed; list-valued clauses are ORed.
+ * Text is a literal, case-insensitive, whitespace-flexible semantic-text scan.
+ */
+export type SessionEventResultFilter =
+  | ({ kind: 'seq' } & SessionResultRange)
+  | ({ kind: 'time' } & SessionResultRange)
+  | { kind: 'type'; values: readonly SessionEventType[] }
+  | { kind: 'surface'; values: readonly SessionEventSurface[] }
+  | { kind: 'text'; text: string }
+
+/** Event predicates a full-text provider can apply before relevance ranking. */
+export type SessionEventMetadataFilter = Exclude<SessionEventResultFilter, { kind: 'text' }>
+
+/** Searchable semantic document derived from one session event. */
+export interface SessionEventSearchDocument extends SessionEventRecord {
+  /** First-party semantic text used by scan filters and full-text indexes. */
+  text: string
+}
+
+/** One cursor-paginated result page. */
+export interface SessionSearchPage<T> {
+  /** Results for this page in contract-defined order. */
+  items: readonly T[]
+  /** Opaque continuation cursor, absent on the final page. */
+  nextCursor?: SessionSearchCursor
+}
+
+/** Controls shared by cross-session and within-session search calls. */
+export interface SessionSearchExecContext {
+  /** Abort caller waiting and interrupt provider work where supported. */
+  signal?: AbortSignal
+}
+
+/** Cross-session full-text search request. */
+export interface SessionSearchRequest {
+  /** Full-text query interpreted as data, never executable FTS syntax. */
+  query: string
+  /** Logical-session predicates applied before event ranking. */
+  sessionFilters?: readonly SessionResultFilter[]
+  /** Event predicates applied before event ranking. */
+  eventFilters?: readonly SessionEventMetadataFilter[]
+  /** Maximum sessions in this page. */
+  limit?: number
+  /** Opaque cursor returned for the identical normalized request. */
+  cursor?: SessionSearchCursor
+}
+
+/** Within-session full-text search request. */
+export interface SessionEventSearchRequest {
+  /** Session whose live-preferred logical log is searched. */
+  sessionId: SessionId
+  /** Full-text query interpreted as data, never executable FTS syntax. */
+  query: string
+  /** Event predicates applied before ranking. */
+  filters?: readonly SessionEventMetadataFilter[]
+  /** Maximum events in this page. */
+  limit?: number
+  /** Opaque cursor returned for the identical normalized request. */
+  cursor?: SessionSearchCursor
+}
+
+/** One event full-text search hit with a bounded plain-text excerpt. */
+export interface SessionEventSearchHit extends SessionEventRecord {
+  /** Plain text excerpt selected around the match. */
+  snippet: string
+}
+
+/** One grouped cross-session hit, ranked by its strongest matching event. */
+export interface SessionSearchHit extends SessionRecord {
+  /** Strongest matching event for this session. */
+  bestMatch: SessionEventSearchHit
+}
diff --git a/packages/session-query/session-query/tests/search-helpers.spec.ts b/packages/session-query/session-query/tests/search-helpers.spec.ts
new file mode 100644
index 0000000000..fef9e25ad0
--- /dev/null
+++ b/packages/session-query/session-query/tests/search-helpers.spec.ts
@@ -0,0 +1,220 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import {
+  buildSessionEventRecords,
+  buildSessionEventSearchDocuments,
+  compileSessionTextFilter,
+  extractSessionEventText,
+  filterSessionEventDocuments,
+  filterSessionResults,
+  materializeSessionEventResultFilters,
+  materializeSessionResultFilters,
+  type SessionQueryErrorCode,
+} from '@deepseek-ai/dsh-session-query'
+import { TestSessionQueryService } from './test-service.ts'
+
+const id = SessionId('session')
+
+function header(value: string, extra: Partial<SessionHeader> = {}): SessionHeader {
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(value), createdAt: 10, ...extra }
+}
+
+function expectCode(code: SessionQueryErrorCode): Error {
+  return expect.objectContaining({ code }) as Error
+}
+
+describe('session-query semantic extraction', () => {
+  it('extracts first-party message, tool, todo, and failure detail', () => {
+    const callId = CallId('call')
+    const messageContent: SessionEvent<'user/message'>['data']['content'] = [
+      { type: 'text', text: ' visible ' },
+      { type: 'reasoning', text: 'thought' },
+      { type: 'tool-call', id: callId, name: 'read', arguments: '{"path":"a"}' },
+      {
+        type: 'tool-result',
+        toolCallId: callId,
+        content: [{ type: 'text', text: 'nested' }],
+        isError: false,
+      },
+      { type: 'future-content', payload: 'hidden' } as never,
+    ]
+    const events: SessionEvent[] = [
+      { type: 'user/message', seq: 0, time: 1, data: { content: messageContent, source: { kind: 'user' } }, surfaceOp: 'append' },
+      { type: 'assistant/message', seq: 1, time: 2, data: { turn: 1, step: 1, content: messageContent, provenance: { provider: 'mock', model: 'mock' } }, surfaceOp: 'append' },
+      { type: 'user/message', seq: 2, time: 3, data: { content: messageContent, source: { kind: 'plugin', plugin: 'test' } }, surfaceOp: 'append' },
+      { type: 'steering/message', seq: 3, time: 4, data: { turn: 1, content: messageContent, source: { kind: 'user' } }, surfaceOp: 'append' },
+      { type: 'prompt/blocked', seq: 4, time: 5, data: { content: [{ type: 'text', text: 'unsafe' }], source: { kind: 'user' }, reason: 'policy' } },
+      { type: 'tool/call', seq: 5, time: 6, data: { turn: 1, step: 1, callId, name: 'bash', arguments: '{"cmd":"pwd"}' } },
+      { type: 'tool/result', seq: 6, time: 7, data: { turn: 1, step: 1, callId, content: [{ type: 'text', text: 'failed' }], isError: true, error: { name: 'Oops', code: 'E_OOPS' } }, surfaceOp: 'append' },
+      { type: 'tool/result', seq: 7, time: 8, data: { turn: 1, step: 1, callId, content: [], isError: false }, surfaceOp: 'append' },
+      { type: 'todo/write', seq: 8, time: 9, data: { todos: [{ status: 'in_progress', content: 'ship search' }] } },
+    ]
+
+    for (const event of events.slice(0, 4)) {
+      expect(extractSessionEventText(event)).toBe('visible\nthought\nread\n{"path":"a"}\nnested')
+    }
+    expect(extractSessionEventText(events[4]!)).toBe('unsafe\npolicy')
+    expect(extractSessionEventText(events[5]!)).toBe('bash\n{"cmd":"pwd"}')
+    expect(extractSessionEventText(events[6]!)).toBe('failed\nOops\nE_OOPS')
+    expect(extractSessionEventText(events[7]!)).toBe('')
+    expect(extractSessionEventText(events[8]!)).toBe('in_progress\nship search')
+  })
+
+  it('extracts meaningful turn outcomes and skips structural or unknown events', () => {
+    const reasons: Array<[SessionEvent<'turn/end'>['data']['reason'], string]> = [
+      [{ kind: 'error', step: 2, message: 'boom', code: 'E' }, 'error\nboom\nE'],
+      [{ kind: 'error', step: 2, message: 'boom' }, 'error\nboom'],
+      [{ kind: 'error', step: 2, failure: { message: 'provider boom', code: 'SERVER' } }, 'error\nprovider boom\nSERVER'],
+      [{ kind: 'aborted' }, 'aborted'],
+      [{ kind: 'rejected', reason: 'denied' }, 'rejected\ndenied'],
+      [{ kind: 'disposed' }, 'disposed'],
+      [{ kind: 'max-tokens' }, 'max-tokens'],
+      [{ kind: 'interrupted' }, 'interrupted'],
+      [{ kind: 'completed' }, ''],
+      [{ kind: 'future-status' } as never, ''],
+    ]
+    for (const [reason, text] of reasons) {
+      expect(extractSessionEventText({ type: 'turn/end', seq: 0, time: 1, data: { turn: 1, reason } })).toBe(text)
+    }
+    const structural: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
+      { type: 'step/end', seq: 2, time: 1, data: { turn: 1, step: 1 } },
+      { type: 'assistant/chunk', seq: 3, time: 1, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } },
+      { type: 'request/header', seq: 4, time: 1, data: { header: { config: { provider: 'test', model: 'test' } }, reason: 'initial' } },
+      { type: 'future/event', seq: 5, time: 1, data: { text: 'hidden' } } as never,
+    ]
+    expect(structural.map(extractSessionEventText)).toEqual(['', '', '', '', '', ''])
+  })
+})
+
+describe('session-query document and filter helpers', () => {
+  const events: SessionEvent[] = [
+    { type: 'user/message', seq: 0, time: 10, data: { content: [{ type: 'text', text: 'Hello\n(AI)+' }], source: { kind: 'user' } }, surfaceOp: 'append' },
+    { type: 'assistant/chunk', seq: 1, time: 11, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } },
+    { type: 'assistant/message', seq: 2, time: 12, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'replacement' }], provenance: { provider: 'mock', model: 'mock' } }, surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] },
+    { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'interrupted' } } },
+  ]
+
+  it('classifies every event and omits non-semantic documents', () => {
+    expect(buildSessionEventRecords(id, events).map(record => record.surface))
+      .toEqual(['shadowed', 'log-only', 'current', 'log-only'])
+    const documents = buildSessionEventSearchDocuments(id, events)
+    expect(documents.map(document => [document.seq, document.text, document.surface])).toEqual([
+      [0, 'Hello\n(AI)+', 'shadowed'],
+      [2, 'replacement', 'current'],
+      [3, 'interrupted', 'log-only'],
+    ])
+  })
+
+  it('applies every session clause with OR values and validates closed values', () => {
+    const parent = SessionId('parent')
+    const records = [
+      { header: header('a', { cwd: '/a', parentSession: parent }), live: true, persisted: false, marker: 1 },
+      { header: header('b', { createdAt: 20 }), live: false, persisted: true, marker: 2 },
+    ]
+    expect(filterSessionResults(records, [
+      { kind: 'id', values: [SessionId('a'), SessionId('x')] },
+      { kind: 'cwd', values: ['/a', null] },
+      { kind: 'created-at', from: 5, to: 15 },
+      { kind: 'parent', values: [parent, null] },
+      { kind: 'availability', values: ['live'] },
+    ])).toEqual([records[0]])
+    expect(filterSessionResults(records, [{ kind: 'cwd', values: [null] }])).toEqual([records[1]])
+    expect(filterSessionResults(records, [{ kind: 'parent', values: [null] }])).toEqual([records[1]])
+    expect(filterSessionResults(records, [{ kind: 'availability', values: ['persisted'] }])).toEqual([records[1]])
+    expect(() => filterSessionResults(records, [{ kind: 'availability', values: ['remote' as never] }]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('applies event metadata and safe literal text clauses', () => {
+    const documents = buildSessionEventSearchDocuments(id, events).map((document, marker) => ({ ...document, marker }))
+    expect(filterSessionEventDocuments(documents, [
+      { kind: 'seq', from: 0, to: 1 },
+      { kind: 'time', from: 9, to: 11 },
+      { kind: 'type', values: ['user/message', 'tool/result'] },
+      { kind: 'surface', values: ['shadowed'] },
+      { kind: 'text', text: 'hello   (ai)+' },
+    ])).toEqual([documents[0]])
+    expect(compileSessionTextFilter('CAFÉ').test('café')).toBe(true)
+    expect(filterSessionEventDocuments(documents)).toEqual(documents)
+    expect(filterSessionEventDocuments(documents, [{ kind: 'surface', values: [] }])).toEqual([])
+    expect(() => filterSessionEventDocuments(documents, [{ kind: 'surface', values: ['future' as never] }]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => compileSessionTextFilter(' \n ')).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('rejects malformed range filters and malformed surfaces', () => {
+    const documents = buildSessionEventSearchDocuments(id, events)
+    for (const filter of [
+      { kind: 'seq', from: Number.NaN },
+      { kind: 'seq', to: Number.POSITIVE_INFINITY },
+      { kind: 'time', from: 2, to: 1 },
+    ] as const) {
+      expect(() => filterSessionEventDocuments(documents, [filter]))
+        .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    }
+    expect(() => filterSessionResults([], [{ kind: 'created-at', from: Number.NaN }]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => filterSessionResults([{ header: header('x'), live: true, persisted: false }], [
+      { kind: 'created-at', from: Number.NaN },
+    ])).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    const malformed: SessionEvent[] = [{
+      type: 'assistant/message',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, step: 1, content: [{ type: 'text', text: 'bad' }], provenance: { provider: 'mock', model: 'mock' } },
+      surfaceOp: { op: 'replace', start: 9, end: 9 },
+    }]
+    expect(() => buildSessionEventRecords(id, malformed)).toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
+  })
+
+  it('owns filters and rejects malformed runtime filter shapes deterministically', () => {
+    expect(materializeSessionResultFilters([{ kind: 'created-at', to: 2 }]))
+      .toEqual([{ kind: 'created-at', to: 2 }])
+    expect(() => materializeSessionResultFilters('not-an-array' as never))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{ kind: 'id', values: 'bad' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{ kind: 'id', values: [1] } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{ kind: 'cwd', values: 'bad' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{ kind: 'parent', values: [1] } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{} as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionEventResultFilters([{ kind: 'text', text: 1 } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionEventResultFilters([{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => filterSessionResults([], [{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => filterSessionEventDocuments([], [{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('exposes the scan path on the combined query service', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(TestSessionQueryService)
+    const session = ctx.sessions.create(id)
+    session.append('user/message', { content: [{ type: 'text', text: 'Alpha\n beta' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    session.append('user/message', { content: [{ type: 'text', text: 'other' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    await expect(ctx.sessionQuery.filterEvents(id, [{ kind: 'text', text: 'alpha beta' }]))
+      .resolves.toMatchObject([{ seq: 0, text: 'Alpha\n beta' }])
+  })
+})
+
+it('registers exact and abstract search behavior under one ctx key', async () => {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  const fiber = await ctx.plugin(TestSessionQueryService)
+  await expect(ctx.sessionQuery.searchSessions({ query: 'AI' })).resolves.toEqual({ items: [] })
+  await expect(ctx.sessionQuery.searchEvents({ sessionId: id, query: 'AI' })).resolves.toEqual({ items: [] })
+  await fiber.dispose()
+  expect(ctx.sessionQuery).toBeUndefined()
+})
diff --git a/packages/session-query/session-query/tests/session-query.spec.ts b/packages/session-query/session-query/tests/session-query.spec.ts
index 682c717d9d..a69c3bcb93 100644
--- a/packages/session-query/session-query/tests/session-query.spec.ts
+++ b/packages/session-query/session-query/tests/session-query.spec.ts
@@ -1,12 +1,14 @@
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context, type Fiber } from 'cordis'
 import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
-import SessionPersistence from '@deepseek-ai/dsh-session-persistence'
+import SessionPersistence, { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
 import SessionQueryService, {
+  type SessionEventSurface,
   type SessionQueryErrorCode,
 } from '@deepseek-ai/dsh-session-query'
 import { SessionTitleProviderId } from '@deepseek-ai/dsh-session-title'
+import { TestSessionQueryService } from './test-service.ts'
 
 function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}): SessionHeader {
   return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, ...extra }
@@ -25,13 +27,15 @@ function eventLog(text = 'hello'): SessionEvent[] {
 class TestPersistence extends SessionPersistence {
   static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
   static listFailure: unknown
-  static loadFailure: unknown
+  static inspectFailure: unknown
+  static inspectEffect: (() => void) | undefined
   static afterList: (() => void) | undefined
 
   static reset(entries: readonly { meta: SessionHeader; events: SessionEvent[] }[] = []): void {
     this.entries = new Map(entries.map(entry => [entry.meta.id, structuredClone(entry)]))
     this.listFailure = undefined
-    this.loadFailure = undefined
+    this.inspectFailure = undefined
+    this.inspectEffect = undefined
     this.afterList = undefined
   }
 
@@ -52,10 +56,17 @@ class TestPersistence extends SessionPersistence {
   }
 
   load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    if (TestPersistence.loadFailure !== undefined) return rejectUnknown(TestPersistence.loadFailure)
+    return this.inspect(id)
+  }
+
+  inspect(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    if (TestPersistence.inspectFailure !== undefined) return rejectUnknown(TestPersistence.inspectFailure)
     const entry = TestPersistence.entries.get(id)
     if (entry === undefined) return Promise.reject(new Error('missing test session'))
-    return Promise.resolve(structuredClone(entry))
+    const result = structuredClone(entry)
+    TestPersistence.inspectEffect?.()
+    TestPersistence.inspectEffect = undefined
+    return Promise.resolve(result)
   }
 
   list(): Promise<SessionHeader[]> {
@@ -64,12 +75,20 @@ class TestPersistence extends SessionPersistence {
     TestPersistence.afterList?.()
     return Promise.resolve(headers)
   }
+
+
+  async listSnapshots() {
+    return [...TestPersistence.entries.values()].map(entry => ({
+      header: structuredClone(entry.meta),
+      revision: SessionPersistenceRevision(`events:${entry.events.length}`),
+    }))
+  }
 }
 
-async function liveContext(config: ConstructorParameters<typeof SessionQueryService>[1] = {}): Promise<Context> {
+async function liveContext(config: ConstructorParameters<typeof TestSessionQueryService>[1] = {}): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SessionQueryService, config)
+  await ctx.plugin(TestSessionQueryService, config)
   return ctx
 }
 
@@ -86,6 +105,41 @@ function rejectUnknown<T>(reason: unknown): Promise<T> {
 }
 
 describe('session-query exact reads', () => {
+  it('returns a detached replay-valid full log and rejects a corrupt persisted seed', async () => {
+    const valid = header('valid-log', 2)
+    const corrupt = header('corrupt-log', 1)
+    const validEvents = eventLog('valid')
+    const corruptEvents = [{ ...eventLog('bad')[0]!, seq: 1 }]
+    TestPersistence.reset([
+      { meta: valid, events: validEvents },
+      { meta: corrupt, events: corruptEvents },
+    ])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+
+    const snapshot = await ctx.sessionQuery.readSession(valid.id)
+    expect(snapshot).toEqual({ session: valid, events: validEvents })
+    Object.assign(snapshot.events[0]!, { time: 999 })
+    expect(TestPersistence.entries.get(valid.id)?.events[0]?.time).toBe(10)
+    await expect(ctx.sessionQuery.readSession(corrupt.id)).rejects.toThrow('seed event at index 0 has seq 1')
+  })
+
+  it('prefers a live owner that attaches while its persisted prefix is inspected', async () => {
+    const shared = header('attach-during-inspect', 2)
+    TestPersistence.reset([{ meta: shared, events: eventLog('persisted') }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    TestPersistence.inspectEffect = () => {
+      ctx.sessions.create(shared.id, {
+        seed: eventLog('live'),
+        meta: { createdAt: shared.createdAt },
+      })
+    }
+
+    await expect(ctx.sessionQuery.filterEvents(shared.id, []))
+      .resolves.toMatchObject([{ sessionId: shared.id, text: 'live' }])
+  })
+
   it('reads the latest title from one live-preferred or persisted log without widening listSessions', async () => {
     const persistedHeader = header('persisted-title', 2)
     const sharedHeader = header('shared-title', 3)
@@ -151,6 +205,38 @@ describe('session-query exact reads', () => {
     expect(older.header.createdAt).toBe(1)
   })
 
+  it('filters sessions symmetrically and owns mutable filter values immediately', async () => {
+    const durable = header('durable-filter', 1)
+    TestPersistence.reset([{ meta: durable, events: eventLog('durable') }])
+    const ctx = await liveContext()
+    const live = ctx.sessions.create(SessionId('live-filter'), { meta: { createdAt: 2 } })
+    live.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'live' }], source: { kind: 'user' } },
+      { surfaceOp: 'append' },
+    )
+    const persistence = await ctx.plugin(TestPersistence)
+
+    const ids = [durable.id]
+    const filtered = ctx.sessionQuery.filterSessions([{ kind: 'id', values: ids }])
+    ids[0] = live.id
+    await expect(filtered).resolves.toEqual([{
+      header: durable,
+      live: false,
+      persisted: true,
+    }])
+
+    const surfaces: SessionEventSurface[] = ['current']
+    const events = ctx.sessionQuery.filterEvents(live.id, [{ kind: 'surface', values: surfaces }])
+    surfaces[0] = 'shadowed'
+    await expect(events).resolves.toMatchObject([{ sessionId: live.id, surface: 'current', text: 'live' }])
+    await expect(ctx.sessionQuery.filterSessions([{ kind: 'future' } as never]))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.filterEvents(live.id, [{ kind: 'future' } as never]))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await persistence.dispose()
+  })
+
   it('classifies current, shadowed, and raw-log-only events through foldSurface', async () => {
     const ctx = await liveContext()
     const session = ctx.sessions.create(SessionId('surface'))
@@ -301,6 +387,8 @@ describe('session-query exact reads', () => {
     const sharedEntry = TestPersistence.entries.get(shared.id)!
     sharedEntry.meta = { ...sharedEntry.meta, cwd: '/conflict' }
     await expect(ctx.sessionQuery.listSessions()).rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
+    sharedEntry.meta = { ...sharedEntry.meta, cwd: '/same', delegationDepth: 1 }
+    await expect(ctx.sessionQuery.listSessions()).rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
     await persistence.dispose()
     await expect(ctx.sessionQuery.listSessions()).resolves.toEqual([
       { header: shared, live: true, persisted: false },
@@ -319,7 +407,7 @@ describe('session-query exact reads', () => {
     )
     await ctx.plugin(TestPersistence)
     TestPersistence.listFailure = new Error('list unavailable')
-    TestPersistence.loadFailure = new Error('load unavailable')
+    TestPersistence.inspectFailure = new Error('inspect unavailable')
 
     await expect(ctx.sessionQuery.listEvents(live.id)).resolves.toHaveLength(2)
     await expect(ctx.sessionQuery.readEvent({ sessionId: live.id, seq: 1 })).resolves.toMatchObject({ target: { seq: 1 } })
@@ -337,10 +425,10 @@ describe('session-query exact reads', () => {
     await expect(ctx.sessionQuery.listEvents(SessionId('absent')))
       .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
 
-    TestPersistence.loadFailure = 'raw failure'
+    TestPersistence.inspectFailure = 'raw failure'
     await expect(ctx.sessionQuery.listEvents(durable.id))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
-    TestPersistence.loadFailure = undefined
+    TestPersistence.inspectFailure = undefined
     const durableEntry = TestPersistence.entries.get(durable.id)!
     durableEntry.meta = { ...durableEntry.meta, cwd: '/changed-after-list' }
     TestPersistence.afterList = () => {
@@ -370,19 +458,41 @@ describe('session-query exact reads', () => {
 
     const direct = new Context()
     await direct.plugin(SessionStore)
-    expect(new SessionQueryService(direct)).toBeInstanceOf(SessionQueryService)
+    expect(new TestSessionQueryService(direct)).toBeInstanceOf(SessionQueryService)
     const invalid = new Context()
     await invalid.plugin(SessionStore)
-    expect(() => new SessionQueryService(invalid, { readWindowMax: -1 }))
+    expect(() => new TestSessionQueryService(invalid, { readWindowMax: -1 }))
       .toThrow(expectCode('SESSION_QUERY_INVALID_CONFIG'))
   })
 
   it('leaves the optional persistence dependency optional', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
-    const fiber = await ctx.plugin(SessionQueryService)
-    expect(ctx.sessionQuery).toBeInstanceOf(SessionQueryService)
+    const fiber = await ctx.plugin(TestSessionQueryService)
+    expect(ctx.sessionQuery).toBeInstanceOf(TestSessionQueryService)
     await fiber.dispose()
     expect(ctx.sessionQuery).toBeUndefined()
   })
+
+  it('awaits optional-persistence child-fiber quiescence on disposal', async () => {
+    TestPersistence.reset()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const query = await ctx.plugin(TestSessionQueryService)
+    const persistence = await ctx.plugin(TestPersistence)
+    const optional = (ctx.sessionQuery as unknown as {
+      _corpus: { _optionalPersistenceFiber: Fiber }
+    })._corpus._optionalPersistenceFiber
+    let release!: () => void
+    const cleanup = new Promise<void>((resolve) => { release = resolve })
+    optional.ctx.effect(() => () => cleanup)
+
+    let settled = false
+    const disposing = query.dispose().then(() => { settled = true })
+    await Promise.resolve()
+    expect(settled).toBe(false)
+    release()
+    await disposing
+    await persistence.dispose()
+  })
 })
diff --git a/packages/session-query/session-query/tests/test-service.ts b/packages/session-query/session-query/tests/test-service.ts
new file mode 100644
index 0000000000..e37b0f71ff
--- /dev/null
+++ b/packages/session-query/session-query/tests/test-service.ts
@@ -0,0 +1,26 @@
+import SessionQueryService from '@deepseek-ai/dsh-session-query'
+import type {
+  SessionEventSearchHit,
+  SessionEventSearchRequest,
+  SessionSearchExecContext,
+  SessionSearchHit,
+  SessionSearchPage,
+  SessionSearchRequest,
+} from '@deepseek-ai/dsh-session-query'
+
+/** Test-only concrete query service for backend-independent behavior. */
+export class TestSessionQueryService extends SessionQueryService {
+  override searchSessions(
+    _request: SessionSearchRequest,
+    _exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionSearchHit>> {
+    return Promise.resolve({ items: [] })
+  }
+
+  override searchEvents(
+    _request: SessionEventSearchRequest,
+    _exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionEventSearchHit>> {
+    return Promise.resolve({ items: [] })
+  }
+}
diff --git a/packages/session-query/session-query/tests/tracing.spec.ts b/packages/session-query/session-query/tests/tracing.spec.ts
index ee8b1d833f..b23292bc3d 100644
--- a/packages/session-query/session-query/tests/tracing.spec.ts
+++ b/packages/session-query/session-query/tests/tracing.spec.ts
@@ -3,7 +3,8 @@ import { Context } from 'cordis'
 import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
 import SessionPersistence from '@deepseek-ai/dsh-session-persistence'
-import SessionQueryService, { type SessionQueryErrorCode } from '@deepseek-ai/dsh-session-query'
+import { type SessionQueryErrorCode } from '@deepseek-ai/dsh-session-query'
+import { TestSessionQueryService } from './test-service.ts'
 
 type MutableSessionHeader = { -readonly [K in keyof SessionHeader]: SessionHeader[K] }
 
@@ -30,17 +31,17 @@ function appendEvent(seq: number, sources?: number[]): SessionEvent {
 class TracePersistence extends SessionPersistence {
   static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
   static listCalls = 0
-  static loadCalls = 0
+  static inspectCalls = 0
   static listFailure: Error | undefined
-  static loadFailure: Error | undefined
+  static inspectFailure: Error | undefined
   static afterList: (() => void) | undefined
 
   static reset(entries: readonly { meta: SessionHeader; events: SessionEvent[] }[] = []): void {
     this.entries = new Map(entries.map(entry => [entry.meta.id, structuredClone(entry)]))
     this.listCalls = 0
-    this.loadCalls = 0
+    this.inspectCalls = 0
     this.listFailure = undefined
-    this.loadFailure = undefined
+    this.inspectFailure = undefined
     this.afterList = undefined
   }
 
@@ -61,8 +62,12 @@ class TracePersistence extends SessionPersistence {
   }
 
   load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    TracePersistence.loadCalls += 1
-    if (TracePersistence.loadFailure !== undefined) return Promise.reject(TracePersistence.loadFailure)
+    return this.inspect(id)
+  }
+
+  inspect(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    TracePersistence.inspectCalls += 1
+    if (TracePersistence.inspectFailure !== undefined) return Promise.reject(TracePersistence.inspectFailure)
     const entry = TracePersistence.entries.get(id)
     if (entry === undefined) return Promise.reject(new Error('missing test session'))
     return Promise.resolve(structuredClone(entry))
@@ -75,12 +80,16 @@ class TracePersistence extends SessionPersistence {
     TracePersistence.afterList?.()
     return Promise.resolve(result)
   }
+
+  listSnapshots(): Promise<never[]> {
+    return Promise.resolve([])
+  }
 }
 
 async function queryContext(): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SessionQueryService)
+  await ctx.plugin(TestSessionQueryService)
   return ctx
 }
 
@@ -107,7 +116,7 @@ function appendTraceEvents(session: Session): void {
     { surfaceOp: { op: 'replace', start: 3, end: 3 }, sourceEventSeqs: [3, 2] },
   )
   session.append(
-    'context/message',
+    'user/message',
     { content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'test' } },
     { surfaceOp: 'append' },
   )
@@ -204,7 +213,7 @@ describe('session lineage tracing', () => {
       complete: true,
     })
     expect(TracePersistence.listCalls).toBe(1)
-    expect(TracePersistence.loadCalls).toBe(0)
+    expect(TracePersistence.inspectCalls).toBe(0)
 
     TracePersistence.listFailure = new Error('unavailable')
     await expect(ctx.sessionQuery.traceSession(durable.id))
@@ -296,7 +305,7 @@ describe('session event tracing', () => {
     expect(repeated.derivedEventSeqs).toEqual([8])
   })
 
-  it('loads persisted logs once, prefers live logs, and preserves failures and conflicts', async () => {
+  it('inspects persisted logs once, prefers live logs, and preserves failures and conflicts', async () => {
     const durable = header('shared', 1, { cwd: '/same' })
     TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
     const ctx = await queryContext()
@@ -304,20 +313,20 @@ describe('session event tracing', () => {
 
     await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
       .resolves.toMatchObject({ target: { type: 'user/message', surface: 'current' } })
-    expect([TracePersistence.listCalls, TracePersistence.loadCalls]).toEqual([1, 1])
+    expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1])
 
     const live = ctx.sessions.create(durable.id, { meta: { createdAt: 1, cwd: '/same' } })
     live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     live.append(
-      'context/message',
+      'user/message',
       { content: [{ type: 'text', text: 'live' }], source: { kind: 'plugin', plugin: 'test' } },
       { surfaceOp: 'append' },
     )
     TracePersistence.listFailure = new Error('list unavailable')
-    TracePersistence.loadFailure = new Error('load unavailable')
+    TracePersistence.inspectFailure = new Error('inspect unavailable')
     await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 1 }))
-      .resolves.toMatchObject({ target: { type: 'context/message' } })
-    expect([TracePersistence.listCalls, TracePersistence.loadCalls]).toEqual([1, 1])
+      .resolves.toMatchObject({ target: { type: 'user/message' } })
+    expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1])
 
     TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
     const failedCtx = await queryContext()
@@ -326,10 +335,10 @@ describe('session event tracing', () => {
     await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
     TracePersistence.listFailure = undefined
-    TracePersistence.loadFailure = new Error('load unavailable')
+    TracePersistence.inspectFailure = new Error('inspect unavailable')
     await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
-    TracePersistence.loadFailure = undefined
+    TracePersistence.inspectFailure = undefined
     TracePersistence.afterList = () => {
       mutableHeader(TracePersistence.entries.get(durable.id)!.meta).cwd = '/changed'
     }
diff --git a/packages/session-query/session-query/tsconfig.json b/packages/session-query/session-query/tsconfig.json
index 532017d1d0..0f17353fee 100644
--- a/packages/session-query/session-query/tsconfig.json
+++ b/packages/session-query/session-query/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../../vendor/schemastery"
+      "path": "../../util/brand"
     },
     {
       "path": "../../llm/llm"
diff --git a/packages/session-title/session-title-llm/README.md b/packages/session-title/session-title-llm/README.md
index 49ac5bc8aa..74f4950a48 100644
--- a/packages/session-title/session-title-llm/README.md
+++ b/packages/session-title/session-title-llm/README.md
@@ -8,7 +8,7 @@ This package is a library, not a Cordis plugin. The provider plugins call `regis
 
 `provider` and `model` overrides are optional but must be supplied together as non-empty strings. Without that pair, the helper uses the exact provider/model route captured from the current session's logged `request/header`; an explicit refresh before any route exists therefore needs overrides. The helper measures the final JSON-framed user prompt, including seq fields, wrappers, and JSON escaping, against `maxInputBytes` before logging or dispatch instead of truncating it. Timeout and caller cancellation are rechecked while consuming the stream and after it completes, so a late successful result cannot be accepted even if an interceptor or adapter ignores abort. Malformed or empty output, tool calls, and non-stop finish reasons also reject; the session-title service decides whether that rejection is an automatic warning or an explicit caller failure.
 
-After route and input validation, the helper appends a log-only `session/title-llm-request` event before model dispatch. It contains the title-provider id, exact source seqs, route, system prompt, message list, and output-token cap used by the call. The append shares the title capability's per-session settlement queue, so a superseding request cannot collide with an earlier fallback, request record, or accepted-title flush. The dispatched envelope is deep-frozen to keep interceptors aligned with that record but deliberately lacks dsh-agent-loop's process-local request identity, so loop-only reconstruction observers do not compare it with the conversation header. A later model failure leaves that request record intact; validation failures that never become dispatchable requests do not create one. The event stays outside derived model history.
+After route and input validation, the helper appends a log-only `session/title-llm-request` event before model dispatch. It contains the title-provider id, exact source seqs, route, system prompt, message list, and output-token cap used by the call. The append shares the title capability's per-session settlement queue, so a superseding request cannot collide with an earlier fallback, request record, or accepted-title flush. The dispatched envelope is deep-frozen, carries `purpose: 'session-title'`, and deliberately lacks dsh-agent-loop's process-local request identity. Interceptors stay aligned with the record while loop-only reconstruction observers do not compare it with the conversation header. The DeepSeek adapter maps that purpose to thinking-disabled so the small output budget is reserved for visible title text; other adapters own their purpose-specific behavior. A later model failure leaves the request record intact; validation failures that never become dispatchable requests do not create one. The event stays outside derived model history.
 
 ## Configuration
 
@@ -33,7 +33,7 @@ The title model receives a fixed system instruction to return one concise unador
 
 #### Token effect
 
-The auxiliary request consumes tokens according to selected input size and `maxOutputTokens`. It is separate from the main agent request and does not add title text or framing to agent history.
+The auxiliary request consumes tokens according to selected input size and `maxOutputTokens`. It is separate from the main agent request and does not add title text or framing to agent history. DeepSeek title calls disable thinking; the main conversation retains its configured thinking mode.
 
 #### KV Cache effect
 
diff --git a/packages/session-title/session-title-llm/src/index.ts b/packages/session-title/session-title-llm/src/index.ts
index b17c3e278f..672292bbf6 100644
--- a/packages/session-title/session-title-llm/src/index.ts
+++ b/packages/session-title/session-title-llm/src/index.ts
@@ -261,6 +261,7 @@ export async function generateSessionTitleWithLlm(
     system,
     maxTokens: config.maxOutputTokens,
     sessionId: request.session.id,
+    purpose: 'session-title',
     signal: callDeadline.signal,
   })
   await appendSessionTitleOutOfBand(ctx, request.session, 'session/title-llm-request', {
diff --git a/packages/session-title/session-title-llm/tests/llm.spec.ts b/packages/session-title/session-title-llm/tests/llm.spec.ts
index 2e417883ac..885cc54e1f 100644
--- a/packages/session-title/session-title-llm/tests/llm.spec.ts
+++ b/packages/session-title/session-title-llm/tests/llm.spec.ts
@@ -156,6 +156,7 @@ describe('generateSessionTitleWithLlm', () => {
       model: 'current-model',
       maxTokens: 32,
       sessionId: providerRequest.session.id,
+      purpose: 'session-title',
     })
     expect(options.system).toContain('5 words')
     expect(options.system).toContain('10 CJK characters')
diff --git a/packages/skill/tool-skill/README.md b/packages/skill/tool-skill/README.md
index 89a6e843ab..578c6e7300 100644
--- a/packages/skill/tool-skill/README.md
+++ b/packages/skill/tool-skill/README.md
@@ -16,7 +16,7 @@ The plugin contributes one user-role `<system-reminder>` catalog through `agent/
 |---|---|---|
 | `name` | string (required) | Exact kebab-case skill name from the available skills listing. |
 
-Execution uses the calling agent's `session.header.cwd` so workspace-sensitive providers resolve the winning skill. A successful call returns one text result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`.
+Execution uses the calling agent's `session.header.cwd` so workspace-sensitive providers resolve the winning skill. A successful call returns canonical `{ name, provider, resourceBase?, content }`, excluding catalog ranking and provider-internal machinery; its Native renderer produces one text result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`.
 
 Resource guidance resolves only paths or URLs explicitly referenced by the instructions against `resourceBase`; scripts, references, and assets load on demand, and the result does not enumerate a skill directory. Local providers may supply a directory, while remote or embedded providers may supply a URL or opaque loading guidance.
 
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index 50c4b0db74..f5fbd1dff5 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -42,6 +42,46 @@ export function apply(ctx: Context, config: Config = {}): void {
     parameters: {
       name: { type: 'string', required: true, description: 'The exact skill name from the available skills list.' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          name: { type: 'string', required: true },
+          provider: { type: 'string', required: true },
+          resourceBase: {
+            oneOf: [
+              {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  kind: { type: 'string', required: true, const: 'directory' },
+                  path: { type: 'string', required: true },
+                },
+              },
+              {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  kind: { type: 'string', required: true, const: 'url' },
+                  url: { type: 'string', required: true },
+                },
+              },
+              {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  kind: { type: 'string', required: true, const: 'opaque' },
+                  description: { type: 'string', required: true },
+                },
+              },
+            ],
+          },
+          content: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderSkillContent(value) }],
+    },
     async execute(args, exec) {
       if (!isSkillName(args.name)) {
         throw new Error(`invalid skill name "${args.name}"`)
@@ -53,7 +93,14 @@ export function apply(ctx: Context, config: Config = {}): void {
       if (skill.disableModelInvocation === true) {
         throw new Error(`skill "${args.name}" is not available for model invocation`)
       }
-      return [{ type: 'text', text: renderSkillContent(skill) }]
+      return {
+        name: skill.name,
+        provider: skill.provider,
+        ...skill.resourceBase !== undefined ? {
+          resourceBase: { ...skill.resourceBase },
+        } : {},
+        content: skill.content,
+      }
     },
     presentCall(args) {
       return { card: 'generic', title: `Load skill ${args.name}`, kind: 'read', rawInput: args.name }
@@ -77,7 +124,7 @@ export function apply(ctx: Context, config: Config = {}): void {
   })
 }
 
-function renderSkillContent(skill: SkillDefinition): string {
+function renderSkillContent(skill: Pick<SkillDefinition, 'name' | 'provider' | 'resourceBase' | 'content'>): string {
   const resourceHint = renderResourceHint(skill)
   return [
     `<skill_content name="${escapeAttr(skill.name)}">`,
@@ -92,7 +139,7 @@ function renderSkillContent(skill: SkillDefinition): string {
   ].join('\n')
 }
 
-function renderResourceHint(skill: SkillDefinition): string[] {
+function renderResourceHint(skill: Pick<SkillDefinition, 'provider' | 'resourceBase'>): string[] {
   const base = skill.resourceBase
   if (base === undefined) {
     return [
@@ -116,8 +163,10 @@ function renderResourceHint(skill: SkillDefinition): string[] {
         `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 */
   }
 }
 
diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts
index 90d891c20e..7fef1cbf22 100644
--- a/packages/skill/tool-skill/tests/tool-skill.spec.ts
+++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts
@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import { CallId, type Message } from '@deepseek-ai/dsh-llm'
 import { createScope, type Scope } from '@deepseek-ai/dsh-scope'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import SkillService from '@deepseek-ai/dsh-skill'
 import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
@@ -187,7 +187,7 @@ describe('dsh-tool-skill', () => {
     const ctx = await setup(home)
     ctx.skills.register({ name: 'listed-skill', description: 'Listed', source: 'runtime', content: 'body' })
     const { agent, scope } = await mintAgentScope(ctx, '/workspace')
-    scope.ctx.tools.register(defineTool({
+    scope.ctx.tools.register(defineContentToolFixture({
       name: 'skill',
       description: 'A scoped tool with unrelated semantics.',
       parameters: {},
@@ -229,6 +229,13 @@ describe('dsh-tool-skill', () => {
     })
 
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected skill success')
+    expect(result.value).toEqual({
+      name: 'project-skill',
+      provider: 'local',
+      resourceBase: { kind: 'directory', path: join(project, '.dsh/skills/project-skill') },
+      content: 'Project instructions.',
+    })
     const block = result.content[0]
     expect(block?.type).toBe('text')
     if (block?.type !== 'text') throw new Error('expected text skill result')
@@ -286,7 +293,7 @@ describe('dsh-tool-skill', () => {
     expect(provider.content[0].text).toContain('<skill_resources>\nResources for this skill are managed by provider "runtime".\nLoad referenced resources only as needed.\n</skill_resources>')
   })
 
-  it('fails loud on an unknown resource base kind', async () => {
+  it('rejects an unknown resource-base kind at the canonical output boundary', async () => {
     const home = await tempDir('tool-resource-assert-never')
     const ctx = await setup(home)
     ctx.skills.register({
@@ -301,9 +308,10 @@ describe('dsh-tool-skill', () => {
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c5'), name: 'skill', arguments: { name: 'rogue-resource-skill' } })
 
     expect(result.isError).toBe(true)
+    expect(result.error?.info?.code).toBe('INVALID_TOOL_OUTPUT')
     const block = result.content[0]
     if (block?.type !== 'text') throw new Error('expected text tool result')
-    expect(block.text).toContain('unreachable variant')
+    expect(block.text).toContain('value.resourceBase')
   })
 
   it('returns isError for unknown, invalid, and model-disabled skills', async () => {
diff --git a/packages/spill/spill-policy/README.md b/packages/spill/spill-policy/README.md
index 936f254d6a..cf46ccafd6 100644
--- a/packages/spill/spill-policy/README.md
+++ b/packages/spill/spill-policy/README.md
@@ -13,7 +13,7 @@ This plugin registers **no service** and owns no storage or preview mechanics: p
 ## Behavior
 
 1. Let the tool run (delegates via `next()`, so it bounds whatever a downstream hook accepted).
-2. Skip `read` (avoids a `read → spill → read again` loop) and any non-`accept` decision (a `block`'s corrective feedback passes through).
+2. Skip nested executions (`exec.parent` is present), accepted value replacements (the registry must revalidate and rerender them), `read` (avoids a `read → spill → read again` loop), and any non-`accept` decision (a `block`'s corrective feedback passes through).
 3. Flatten the accepted content only when it is **plain text** (all `text` blocks); a result with any non-text block is left untouched.
 4. If its UTF-8 size is `≤ maxInlineBytes`, leave it unchanged.
 5. Otherwise save the full text and replace the result with a preview + this notice, sized so the whole replacement (preview + blank line + notice) stays within `maxInlineBytes` — the notice's byte cost is reserved out of the budget, so the preview shrinks to fit and the model-facing result never exceeds the cap:
@@ -26,11 +26,11 @@ This plugin registers **no service** and owns no storage or preview mechanics: p
 
    When the notice alone fills the budget (a tiny cap or a long locator) the preview is empty and only the notice is returned. If even that notice-only replacement would exceed `maxInlineBytes`, the policy keeps the inline result — it never emits a replacement over the cap (and a within-cap replacement is always smaller than the original, so this also means spilling never adds bytes).
 
-**Best-effort:** no session owner, no `ctx.spillStore` backend, or a `saveText` rejection ⇒ the policy logs a warning and returns the original result. A spill failure never turns a successful call into an `isError` or hides the inline result.
+**Best-effort:** no session owner, no `ctx.spillStore` backend, or a `saveText` rejection ⇒ the policy logs a warning and returns the original result. A spill failure never turns a successful call into an `isError` or hides the inline result. A successful replacement changes only `content`; the canonical programmatic value is preserved.
 
 ## Scope
 
-The policy sees only the FINAL formatted tool result — not a tool's internal resource. If a provider already truncated (e.g. `web-fetch-local.maxBodyChars`), the spill artifact holds the full formatted result the tool returned, not the full original source. Provider/resource caps stay mandatory and separate. Tool-owned early spill (bash streams, subagent rollouts) is future work — see the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md).
+The policy sees only the FINAL formatted surface result—not a tool's internal resource or canonical value. If a provider already truncated (e.g. `web-fetch-local.maxBodyChars`), the spill artifact holds the full formatted result the tool returned, not the full original source. Provider/resource caps stay mandatory and separate. `glob`/`grep` own item-level surface spill because their complete acquired values still exist before rendering; bash streams own acquisition-time spill. The generic policy prepends its waterfall listener, then delegates, so ordinary tool-owned asynchronous projections complete before generic byte bounding regardless of plugin load order. See the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md).
 
 ## Model Experience
 
@@ -38,7 +38,7 @@ The policy sees only the FINAL formatted tool result — not a tool's internal r
 
 #### What the model sees
 
-Results at or below `maxInlineBytes`, `read` results, blocked decisions, and results containing non-text blocks are unchanged. An oversized plain-text result becomes a bounded head/tail preview followed by `(Omitted <bytes> bytes. Full formatted result stored at: <locator>. <retrievalHint>)`; storage or ownership failures leave the original result visible.
+Results at or below `maxInlineBytes`, nested results, `read` results, blocked decisions, and results containing non-text blocks are unchanged. An oversized plain-text surface result becomes a bounded head/tail preview followed by `(Omitted <bytes> bytes. Full formatted result stored at: <locator>. <retrievalHint>)`; storage or ownership failures leave the original result visible.
 
 #### Token effect
 
diff --git a/packages/spill/spill-policy/package.json b/packages/spill/spill-policy/package.json
index dac7d4311d..e8e9fb4631 100644
--- a/packages/spill/spill-policy/package.json
+++ b/packages/spill/spill-policy/package.json
@@ -40,6 +40,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-retention": "workspace:^",
diff --git a/packages/spill/spill-policy/src/index.ts b/packages/spill/spill-policy/src/index.ts
index b7ac4a31fc..26c501257c 100644
--- a/packages/spill/spill-policy/src/index.ts
+++ b/packages/spill/spill-policy/src/index.ts
@@ -16,15 +16,21 @@
  * - Plain-text results only: a result carrying any non-text block is left
  *   untouched (the policy knows only the final formatted text, not tool
  *   internals).
+ * - Nested composite calls are skipped; only their outer surface result may
+ *   become model-facing and spillable.
+ * - Accepted value replacements pass through for registry revalidation and
+ *   rendering; this presentation policy cannot also replace content in the
+ *   same mutually exclusive decision.
  * - `read` is skipped to avoid a `read → spill → read again` loop.
  * - Best-effort: no session owner, no `ctx.spillStore` backend, or a save
  *   failure ⇒ log and return the original result. A spill failure must NEVER
  *   turn a successful tool call into an `isError` or hide the inline result.
  *
- * It COMPOSES with other post-execute listeners: it delegates via `next()` and
- * bounds the resulting `accept` content, so a hook that replaced the content
- * still has its replacement bounded, and a `block` decision passes through
- * unchanged.
+ * It COMPOSES with other post-execute listeners: its prepended listener
+ * delegates via `next()` and bounds the resulting content projection, so
+ * tool-owned asynchronous projection runs before generic bounding, a hook that
+ * replaced content still has its replacement bounded, and value replacements
+ * and `block` decisions pass through unchanged.
  *
  * @module @deepseek-ai/dsh-spill-policy
  */
@@ -109,7 +115,8 @@ export function apply(ctx: Context, config: Config): void {
     // accepted plain-text results, never corrective feedback.
     const decision = await next()
     // Skip `read` to avoid a read → spill → read again loop.
-    if (decision.kind !== 'accept' || exec.name === 'read') return decision
+    if (decision.kind !== 'accept' || Object.hasOwn(decision, 'value')
+      || exec.parent !== undefined || exec.name === 'read') return decision
 
     const content = decision.content ?? result.content
     const text = flattenPlainText(content)
@@ -170,5 +177,5 @@ export function apply(ctx: Context, config: Config): void {
     }
     const replaced: ContentBlock[] = [{ type: 'text', text: replacedText }]
     return { kind: 'accept', content: replaced, ...decision.additionalContexts ? { additionalContexts: decision.additionalContexts } : {} }
-  })
+  }, { prepend: true })
 }
diff --git a/packages/spill/spill-policy/tests/spill-policy.spec.ts b/packages/spill/spill-policy/tests/spill-policy.spec.ts
index 3342150580..364c4c49ae 100644
--- a/packages/spill/spill-policy/tests/spill-policy.spec.ts
+++ b/packages/spill/spill-policy/tests/spill-policy.spec.ts
@@ -15,11 +15,12 @@ import { CallId } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import type { PostToolDecision, ToolExecution, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
 import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
 import * as SpillPolicy from '@deepseek-ai/dsh-spill-policy'
+import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker'
 
 const testToolSignal = new AbortController().signal
 
@@ -41,7 +42,7 @@ class StubStore extends SpillStore {
 
 /** A tool returning `text` verbatim (name configurable so we can register `read`). */
 function textTool(name: string, text: string) {
-  return defineTool({
+  return defineContentToolFixture({
     name,
     description: name,
     parameters: {},
@@ -60,7 +61,11 @@ function exec(name: string, session = 's1'): ToolExecution {
  * Build a context with tools + the policy, and optionally a spill backend.
  * Returns the context and the backend handle (undefined when `withSpill` false).
  */
-async function setup(config: SpillPolicy.Config, withSpill = true): Promise<{ ctx: Context; spill?: StubStore; fiber: Awaited<ReturnType<Context['plugin']>> }> {
+async function setup(
+  config: SpillPolicy.Config,
+  withSpill = true,
+  beforePolicy?: (ctx: Context) => void,
+): Promise<{ ctx: Context; spill?: StubStore; fiber: Awaited<ReturnType<Context['plugin']>> }> {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
@@ -69,6 +74,7 @@ async function setup(config: SpillPolicy.Config, withSpill = true): Promise<{ ct
     await ctx.plugin(StubStore)
     spill = ctx.spillStore as StubStore
   }
+  beforePolicy?.(ctx)
   const fiber = await ctx.plugin(SpillPolicy, config)
   return { ctx, fiber, ...spill ? { spill } : {} }
 }
@@ -162,7 +168,7 @@ describe('oversized plain-text replacement', () => {
 
   it('leaves a result with a non-text block unchanged', async () => {
     const { ctx, spill } = await setup({ maxInlineBytes: 5 })
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'mixed',
       description: 'mixed',
       parameters: {},
@@ -176,6 +182,43 @@ describe('oversized plain-text replacement', () => {
   })
 })
 
+describe('outer Code Mode failure capture', () => {
+  it('spills the bounded output-limit diagnostic through the ordinary outer-result policy', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry, { mode: 'code' })
+    await ctx.plugin(StubStore)
+    await ctx.plugin(SpillPolicy, { maxInlineBytes: 200 })
+    await ctx.plugin(WorkerCodeRuntime, { maxOutputBytes: 500 })
+    const events: unknown[] = []
+    const agent = {
+      session: {
+        header: { id: SessionId('code-spill'), cwd: '/workspace' },
+        append: (_type: string, data: unknown) => { events.push(data) },
+      },
+    }
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('code-output-limit'),
+      name: 'run_code',
+      arguments: {
+        code: 'console.log("HEAD-" + "x".repeat(300)); console.log("TAIL-" + "y".repeat(300)); return "unreachable";',
+      },
+      agent: agent as never,
+    })
+
+    expect(result.isError).toBe(true)
+    const saved = (ctx.spillStore as StubStore).saves
+    expect(saved).toHaveLength(1)
+    expect(saved[0]?.source.toolName).toBe('run_code')
+    expect(saved[0]?.content).toContain('code run failed (output-limit)')
+    expect(saved[0]?.content).toContain('HEAD-')
+    expect(textOf(result.content)).toContain('Full formatted result stored at: /spill/run_code.txt')
+    expect(events).toEqual([])
+  })
+})
+
 describe('read skip', () => {
   it('never spills the read tool result (avoids a read → spill → read loop)', async () => {
     const { ctx, spill } = await setup({ maxInlineBytes: 10 })
@@ -186,6 +229,21 @@ describe('read skip', () => {
   })
 })
 
+describe('nested-call skip', () => {
+  it('leaves nested composite results complete and spillable only through their outer call', async () => {
+    const { ctx, spill } = await setup({ maxInlineBytes: 10 })
+    const body = 'x'.repeat(1000)
+    ctx.tools.register(textTool('nested', body))
+    const nested = {
+      ...exec('nested'),
+      parent: Symbol('outer') as ToolExecutionToken,
+    }
+    const result = await ctx.tools.execute(nested)
+    expect(textOf(result.content)).toBe(body)
+    expect(spill?.saves).toHaveLength(0)
+  })
+})
+
 describe('best-effort fallback', () => {
   it('keeps the original result when saveText fails', async () => {
     const { ctx, spill } = await setup({ maxInlineBytes: 10 })
@@ -219,6 +277,26 @@ describe('best-effort fallback', () => {
 })
 
 describe('composition', () => {
+  it('wraps an earlier tool-owned projection before applying the generic cap', async () => {
+    let downstreamDecision: PostToolDecision | undefined
+    const { ctx, spill } = await setup({ maxInlineBytes: 200 }, true, (target) => {
+      target.on('tools/post-execute', async (_exec, _result, next): Promise<PostToolDecision> => {
+        downstreamDecision = await next()
+        return {
+          kind: 'accept',
+          content: [{ type: 'text', text: `first page\n\nFull canonical result stored at /spill/search-results.txt.\n${'z'.repeat(500)}` }],
+        }
+      })
+    })
+    ctx.tools.register(textTool('search', 'initial capped page'))
+
+    const result = await ctx.tools.execute(exec('search'))
+
+    expect(downstreamDecision).toEqual({ kind: 'accept' })
+    expect(spill?.saves[0]?.content).toContain('Full canonical result stored at /spill/search-results.txt.')
+    expect(textOf(result.content)).toContain('Full formatted result stored at')
+  })
+
   it('bounds content a downstream post-execute listener replaced', async () => {
     const { ctx, spill } = await setup({ maxInlineBytes: 200 })
     // A later-registered listener replaces the (small) tool result with a big one;
@@ -241,6 +319,21 @@ describe('composition', () => {
     expect(textOf(result.content)).toContain('Full formatted result stored at')
     expect(result.additionalContexts).toEqual([context])
   })
+
+  it('passes a downstream value replacement through for registry rendering', async () => {
+    const { ctx, spill } = await setup({ maxInlineBytes: 10 })
+    const replacement = [{ type: 'text' as const, text: 'z'.repeat(500) }]
+    ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, value: replacement }))
+    ctx.tools.register(textTool('small', 'tiny'))
+
+    const result = await ctx.tools.execute(exec('small'))
+
+    expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected replacement success')
+    expect(result.value).toEqual(replacement)
+    expect(textOf(result.content)).toBe('z'.repeat(500))
+    expect(spill?.saves).toHaveLength(0)
+  })
 })
 
 describe('cap invariant', () => {
diff --git a/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts b/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts
index 6f091c2bf6..6882d324fc 100644
--- a/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts
+++ b/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts
@@ -64,7 +64,7 @@ describe('multi-subagent coexistence (spawn + fork on one context)', () => {
     ])
 
     // Parent does one real turn first, so the fork has a completed turn to seed.
-    parent.send([{ type: 'text', text: 'parent q1' }])
+    parent.followup([{ type: 'text', text: 'parent q1' }])
     await parent.whenIdle()
     const parentPrefixLen = parent.session.events.length
 
@@ -93,7 +93,7 @@ describe('multi-subagent coexistence (spawn + fork on one context)', () => {
     await forkRun.dispose()
 
     // The parent is unaffected and keeps working after both delegations.
-    parent.send([{ type: 'text', text: 'parent q2' }])
+    parent.followup([{ type: 'text', text: 'parent q2' }])
     await parent.whenIdle()
     const lastParentMessage = parent.session.events.findLast(e => e.type === 'assistant/message')
     expect(lastParentMessage?.type === 'assistant/message' && text(lastParentMessage.data.content)).toBe('parent turn two')
diff --git a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
index 046c6ee8fe..cf5848e625 100644
--- a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
+++ b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
@@ -89,9 +89,9 @@ describe('dsh-subagent-fork', () => {
 
   it('seeds every completed parent turn through the last turn/end', async () => {
     const { ctx, parent } = await setup([textResponse('first'), textResponse('second'), textResponse('child')])
-    parent.send([{ type: 'text', text: 'q1' }])
+    parent.followup([{ type: 'text', text: 'q1' }])
     await parent.whenIdle()
-    parent.send([{ type: 'text', text: 'q2' }])
+    parent.followup([{ type: 'text', text: 'q2' }])
     await parent.whenIdle()
     const parentPrefixLen = parent.session.events.length
 
@@ -108,7 +108,7 @@ describe('dsh-subagent-fork', () => {
     // 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.send([{ type: 'text', text: 'parent question' }])
+    parent.followup([{ type: 'text', text: 'parent question' }])
     await parent.whenIdle()
     const parentPrefixLen = parent.session.events.length
 
@@ -137,10 +137,10 @@ describe('dsh-subagent-fork', () => {
     // open (a hanging model call), and fork while it's in flight. The seed must stop after the
     // balanced first turn; including the open turn would fail invariant replay during start.
     const { ctx, parent } = await setup([textResponse('done'), 'hang', textResponse('child')])
-    parent.send([{ type: 'text', text: 'q1' }])
+    parent.followup([{ type: 'text', text: 'q1' }])
     await parent.whenIdle()
     // Start a second turn that hangs (open turn/start + open step, never ends).
-    parent.send([{ type: 'text', text: 'q2' }])
+    parent.followup([{ type: 'text', text: 'q2' }])
     await new Promise(r => setTimeout(r, 20)) // let the hanging turn open
 
     // Forking now must NOT throw (the open second turn is excluded from the seed).
@@ -164,7 +164,7 @@ describe('dsh-subagent-fork', () => {
       textResponse('parent turn'),
       toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 9 }),
     ])
-    parent.send([{ type: 'text', text: 'warm up' }])
+    parent.followup([{ type: 'text', text: 'warm up' }])
     await parent.whenIdle()
     const run = await start(ctx, 'fork', {
       prompt: [{ type: 'text', text: 'report structured' }],
@@ -183,7 +183,7 @@ describe('dsh-subagent-fork', () => {
     // `readResult` must scan only child-owned events after the seed. The child emits no assistant
     // message, so scanning the whole log would incorrectly return the parent's distinctive text.
     const { ctx, parent } = await setup([textResponse('parent stale'), emptyStop])
-    parent.send([{ type: 'text', text: 'parent question' }])
+    parent.followup([{ type: 'text', text: 'parent question' }])
     await parent.whenIdle()
 
     const run = await start(ctx, 'fork', { prompt: [{ type: 'text', text: 'child question' }], parent })
diff --git a/packages/subagent/subagent-inprocess/README.md b/packages/subagent/subagent-inprocess/README.md
index e24df08af5..48c72e9cf0 100644
--- a/packages/subagent/subagent-inprocess/README.md
+++ b/packages/subagent/subagent-inprocess/README.md
@@ -11,7 +11,7 @@ The driver follows this sequence:
 1. Validate the parent depth and optional absolute `maxDepth`, then derive child depth as parent depth plus one and persist it in the child session header.
 2. Call `parent.ctx.agents.create` directly, passing the required request signal into the factory's creation transaction.
 3. During that transaction's unpublished setup window, install the requested persona, tool restriction, and structured-output runtime.
-4. Publish the child, retain the returned `AgentHandle`, and drive one task with `child.send(prompt)` followed by `child.whenIdle()`.
+4. Publish the child, retain the returned `AgentHandle`, and drive one task with `child.followup(prompt)` followed by `child.whenIdle()`.
 5. Read the child's own last assistant message and latest message-triggered turn reason, excluding any fork seed and later plugin-owned zero-step turns.
 
 The child gets the parent's working-directory/session lineage and inherits the parent model unless `request.agentOptions` overrides it. It gets a fresh flat registration scope: parent ownership does not import parent tool restrictions or establish an authority subset.
@@ -60,7 +60,7 @@ Independent of the parent request cache. The child's later history is append-onl
 
 #### What the model sees
 
-A structured run adds the structured-output instruction below. It also adds a child-scoped `structured_output` definition with exact description `Report your final structured result. Call this exactly once, when your answer is complete; the arguments must match this tool's parameter schema exactly.` and the requested schema. This runtime-only definition is outside the generated shipped [tool package map](../../../docs/tool-catalog.md#tool-package-map). Success returns `Structured output recorded.`; a later call becomes ``Error: structured output already recorded: the run is complete, so `<tool>` is not executed``.
+A structured run adds the structured-output instruction below. It also adds a child-scoped `structured_output` definition with exact description `Report your final structured result. Call this exactly once, when your answer is complete; the arguments must match this tool's parameter schema exactly.` and the requested schema. This runtime-only definition is outside the generated shipped [tool package map](../../../docs/tool-catalog.md#tool-package-map). Its canonical acknowledgement is `{ recorded: true }`, rendered as `Structured output recorded.`; a later call becomes ``Error: structured output already recorded: the run is complete, so `<tool>` is not executed``.
 
 ##### Structured-output instruction
 
diff --git a/packages/subagent/subagent-inprocess/src/index.ts b/packages/subagent/subagent-inprocess/src/index.ts
index e83b397bb5..71bc7e42a6 100644
--- a/packages/subagent/subagent-inprocess/src/index.ts
+++ b/packages/subagent/subagent-inprocess/src/index.ts
@@ -141,7 +141,7 @@ export async function startInProcessRun(
 
   const result: Promise<SubagentResult> = (async () => {
     try {
-      child.send(request.prompt)
+      child.followup(request.prompt)
       await child.whenIdle()
       return readResult(
         child,
diff --git a/packages/subagent/subagent-inprocess/src/structured.ts b/packages/subagent/subagent-inprocess/src/structured.ts
index 811d754094..522d36e2d9 100644
--- a/packages/subagent/subagent-inprocess/src/structured.ts
+++ b/packages/subagent/subagent-inprocess/src/structured.ts
@@ -12,9 +12,9 @@
 
 import type { Context } from 'cordis'
 import type { ContinuationStop } from '@deepseek-ai/dsh-agent'
-import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { ToolSchema } from '@deepseek-ai/dsh-llm'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
-import { ToolArgsError, validateStructuredValue, type StructuredOutputSchema } from '@deepseek-ai/dsh-tools'
+import { ToolArgsError, validateJsonSchemaValue, type ObjectJsonSchema } from '@deepseek-ai/dsh-tools'
 
 /** The model-facing tool name a structured child must call to finish. */
 export const STRUCTURED_OUTPUT_TOOL = 'structured_output'
@@ -44,10 +44,10 @@ export interface StructuredAttachment {
  * its creation window. Child disposal removes every registration.
  * @param childCtx - the child agent's scope context (`setup`'s argument).
  * @param schema - the trusted, already-asserted schema subset to enforce (see
- *   `assertSupportedOutputSchema` in dsh-tools).
+ *   `assertObjectJsonSchema` in dsh-tools).
  * @returns the attachment handle (read `captured()` after the child settles).
  */
-export function attachStructuredRuntime(childCtx: Context, schema: StructuredOutputSchema): StructuredAttachment {
+export function attachStructuredRuntime(childCtx: Context, schema: ObjectJsonSchema): StructuredAttachment {
   /**
    * Validated values staged by the capture tool body, awaiting THEIR OWN
    * authoritative `tools/result` notification. The execution object's identity
@@ -74,8 +74,17 @@ export function attachStructuredRuntime(childCtx: Context, schema: StructuredOut
 
   childCtx.tools.register({
     ...schemaEntry,
-    execute(args: unknown, exec: ToolExecution): Promise<ContentBlock[]> {
-      const violations = validateStructuredValue(schema, args)
+    output: {
+      schema: {
+        type: 'object',
+        properties: { recorded: { type: 'boolean', const: true } },
+        required: ['recorded'],
+        additionalProperties: false,
+      },
+      render: () => [{ type: 'text', text: 'Structured output recorded.' }],
+    },
+    execute(args: unknown, exec: ToolExecution): Promise<{ recorded: true }> {
+      const violations = validateJsonSchemaValue(schema, args)
       // ToolArgsError → isError result with INVALID_ARGS: the model retries
       // within the same turn, exactly like a schema-validated defineTool call.
       if (violations.length > 0) throw new ToolArgsError(violations)
@@ -83,7 +92,7 @@ export function attachStructuredRuntime(childCtx: Context, schema: StructuredOut
       // waterfalls may still turn the success into an error. ToolRegistry has
       // already frozen model-bound arguments at the actual input boundary.
       staged.set(exec, { value: args })
-      return Promise.resolve([{ type: 'text', text: 'Structured output recorded.' }])
+      return Promise.resolve({ recorded: true })
     },
   })
 
diff --git a/packages/subagent/subagent-inprocess/tests/structured.spec.ts b/packages/subagent/subagent-inprocess/tests/structured.spec.ts
index 6cacc6f0c8..bb4cf32544 100644
--- a/packages/subagent/subagent-inprocess/tests/structured.spec.ts
+++ b/packages/subagent/subagent-inprocess/tests/structured.spec.ts
@@ -10,8 +10,8 @@ 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 SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
-import type { Config as ToolConfig, StructuredOutputSchema } from '@deepseek-ai/dsh-tools'
-import { RUN_CODE_NAME } from '@deepseek-ai/dsh-tools'
+import type { Config as ToolConfig, ObjectJsonSchema } from '@deepseek-ai/dsh-tools'
+import { defineContentToolFixture, RUN_CODE_NAME } from '@deepseek-ai/dsh-tools'
 import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import { startInProcessRun } from '../src/index.ts'
 import {
@@ -39,7 +39,7 @@ interface SetupOptions {
   codeRun?: (request: CodeRunRequestLike) => Promise<{ logs: never[]; value?: unknown }>
 }
 
-const SCHEMA: StructuredOutputSchema = {
+const SCHEMA: ObjectJsonSchema = {
   type: 'object',
   properties: { answer: { type: 'number' }, note: { type: 'string' } },
   required: ['answer'],
@@ -97,10 +97,15 @@ describe('in-process structured output', () => {
     const { ctx, parent } = await setup([
       toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 42, note: 'done' }),
     ])
+    let acknowledgement: unknown
+    ctx.on('tools/result', (exec, toolResult) => {
+      if (exec.name === STRUCTURED_OUTPUT_TOOL && !toolResult.isError) acknowledgement = toolResult.value
+    })
     const run = await ctx.subagents.start('spawn', structuredRequest(parent))
     const result = await run.result
     expect(result.stopReason).toBe('completed')
     expect(result.structured).toEqual({ answer: 42, note: 'done' })
+    expect(acknowledgement).toEqual({ recorded: true })
     await run.dispose()
   })
 
@@ -131,15 +136,15 @@ describe('in-process structured output', () => {
     ] as Script[number]
     const { ctx, parent } = await setup([response])
     let sideEffectRan = false
-    ctx.tools.register({
+    ctx.tools.register(defineContentToolFixture({
       name: 'side_effect',
       description: 'probe',
-      parameters: { type: 'object', properties: {} },
+      parameters: {},
       execute(): Promise<ContentBlock[]> {
         sideEffectRan = true
         return Promise.resolve([{ type: 'text', text: 'ran' }])
       },
-    })
+    }))
     const run = await ctx.subagents.start('spawn', structuredRequest(parent))
     const result = await run.result
     expect(result.stopReason).toBe('completed')
@@ -159,15 +164,15 @@ describe('in-process structured output', () => {
     ] as Script[number]
     const { ctx, parent } = await setup([response])
     let sideEffectRan = false
-    ctx.tools.register({
+    ctx.tools.register(defineContentToolFixture({
       name: 'side_effect',
       description: 'probe',
-      parameters: { type: 'object', properties: {} },
+      parameters: {},
       execute(): Promise<ContentBlock[]> {
         sideEffectRan = true
         return Promise.resolve([{ type: 'text', text: 'ran' }])
       },
-    })
+    }))
     const run = await ctx.subagents.start('spawn', structuredRequest(parent))
     // Registered after the child and prepended: this listener returns allow
     // after every downstream pre-execute decision. The service-owned guard
@@ -196,15 +201,15 @@ describe('in-process structured output', () => {
     ] as Script[number]
     const { ctx, parent } = await setup([response])
     let sideEffectRan = false
-    ctx.tools.register({
+    ctx.tools.register(defineContentToolFixture({
       name: 'side_effect',
       description: 'probe',
-      parameters: { type: 'object', properties: {} },
+      parameters: {},
       execute(): Promise<ContentBlock[]> {
         sideEffectRan = true
         return Promise.resolve([{ type: 'text', text: 'ran' }])
       },
-    })
+    }))
     const run = await ctx.subagents.start('spawn', structuredRequest(parent))
     const result = await run.result
     // The call ran BEFORE captured was set: the deny gate only guards the
@@ -332,17 +337,17 @@ describe('in-process structured output', () => {
   it('rejects a schema outside the subset loud, before any child exists', async () => {
     const { ctx, parent } = await setup([])
     await expect(ctx.subagents.start('spawn', structuredRequest(parent, {
-      outputSchema: { type: 'object', oneOf: [] } as unknown as StructuredOutputSchema,
-    }))).rejects.toThrow(/unsupported output schema/)
+      outputSchema: { type: 'object', oneOf: [] } as unknown as ObjectJsonSchema,
+    }))).rejects.toThrow(/unsupported JSON schema/)
     expect(ctx.agents.get(SessionId('parent'))).toBeDefined()
   })
 
-  it('a schema carrying non-JSON values fails as OutputSchemaError at the validation boundary', async () => {
+  it('a schema carrying non-JSON values fails as JsonSchemaError at the validation boundary', async () => {
     const { ctx, parent } = await setup([])
     // Semantic assertion runs before provider startup.
     await expect(ctx.subagents.start('spawn', structuredRequest(parent, {
-      outputSchema: { type: 'object', default: () => {} } as unknown as StructuredOutputSchema,
-    }))).rejects.toThrow(/unsupported output schema.*annotation must be JSON data/)
+      outputSchema: { type: 'object', default: () => {} } as unknown as ObjectJsonSchema,
+    }))).rejects.toThrow(/unsupported JSON schema.*annotation must be lossless JSON data/)
   })
 
   it('a post-execute BLOCK on the capture call denies the capture: log and result agree on failure', async () => {
@@ -450,8 +455,10 @@ describe('in-process structured output', () => {
     expect(result.structured).toEqual({ answer: 12 })
     const request = adapter.requests[0]!
     expect(toolNames(request)).toEqual([RUN_CODE_NAME])
-    expect(request.system).toContain('declare const tools:')
-    expect(request.system).toContain('structured_output(args:')
+    expect(request.system).toContain('interface ToolArgsMap')
+    expect(request.system).toContain('interface ToolOutputMap')
+    expect(request.system).toContain('recorded: true;')
+    expect(request.system).toContain('Promise<ToolOutputMap[K]>')
     expect(request.system).toContain(STRUCTURED_OUTPUT_INSTRUCTION)
     await run.dispose()
   })
@@ -515,7 +522,7 @@ describe('in-process structured output', () => {
       textResponse('parent answer'),
       toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 1 }),
     ])
-    parent.send([{ type: 'text', text: 'hello' }])
+    parent.followup([{ type: 'text', text: 'hello' }])
     await parent.whenIdle()
     expect(adapter.requests[0]!.system ?? '').not.toContain(STRUCTURED_OUTPUT_INSTRUCTION)
     const run = await ctx.subagents.start('spawn', structuredRequest(parent))
@@ -531,7 +538,7 @@ describe('in-process structured output', () => {
   describe('scoped registration (each child owns its capture tool)', () => {
     it('a plain agent never sees the tool: nothing is registered globally at all', async () => {
       const { ctx, parent, adapter } = await setup([textResponse('parent answer')])
-      parent.send([{ type: 'text', text: 'hello' }])
+      parent.followup([{ type: 'text', text: 'hello' }])
       await parent.whenIdle()
       // Scoped registration: the global view has no capture tool, ever.
       expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeUndefined()
@@ -545,7 +552,7 @@ describe('in-process structured output', () => {
         // Child turn: must see it, with the run's schema.
         toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 42 }),
       ])
-      parent.send([{ type: 'text', text: 'hello' }])
+      parent.followup([{ type: 'text', text: 'hello' }])
       await parent.whenIdle()
       expect(toolNames(adapter.requests[0]!)).not.toContain(STRUCTURED_OUTPUT_TOOL)
 
@@ -559,7 +566,7 @@ describe('in-process structured output', () => {
     })
 
     it('two concurrent structured children each see their OWN schema', async () => {
-      const otherSchema: StructuredOutputSchema = {
+      const otherSchema: ObjectJsonSchema = {
         type: 'object',
         properties: { verdict: { type: 'string', enum: ['real', 'bogus'] } },
         required: ['verdict'],
@@ -601,12 +608,12 @@ describe('in-process structured output', () => {
       ])
       // A global tool sorts lexicographically after structured_output, while a
       // global section above the 190 band follows the capture instruction.
-      ctx.tools.register({
+      ctx.tools.register(defineContentToolFixture({
         name: 'zz_probe',
         description: 'probe',
-        parameters: { type: 'object', properties: {} },
+        parameters: {},
         execute: () => Promise.resolve([{ type: 'text', text: 'x' }]),
-      })
+      }))
       ctx.systemPrompt.section({ name: 'after-band', order: 200, text: 'AFTER-BAND' })
       const run = await ctx.subagents.start('spawn', structuredRequest(parent))
       await run.result
@@ -623,7 +630,7 @@ describe('in-process structured output', () => {
 
     it('a non-structured agent request keeps tools ABSENT when it had none (no tools: [] materialized)', async () => {
       const { parent, adapter } = await setup([textResponse('plain')])
-      parent.send([{ type: 'text', text: 'q' }])
+      parent.followup([{ type: 'text', text: 'q' }])
       await parent.whenIdle()
       const request = adapter.requests[0]!
       expect(request.tools).toBeUndefined()
@@ -659,7 +666,7 @@ describe('in-process structured output', () => {
       agent: parent,
     })
     expect(result.isError).toBe(true)
-    expect(result.error?.code).toBe('UNKNOWN_TOOL')
+    expect(result.error?.info?.code).toBe('UNKNOWN_TOOL')
   })
 
   it('a structured_output call with NO calling agent at all is UNKNOWN_TOOL', async () => {
@@ -671,7 +678,7 @@ describe('in-process structured output', () => {
       arguments: { answer: 1 },
     })
     expect(result.isError).toBe(true)
-    expect(result.error?.code).toBe('UNKNOWN_TOOL')
+    expect(result.error?.info?.code).toBe('UNKNOWN_TOOL')
   })
 
   it('a failed execution stage is discarded and never promoted by a later call', async () => {
diff --git a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts
index 1cfb809601..ce91480ea8 100644
--- a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts
+++ b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts
@@ -68,7 +68,7 @@ describe('startInProcessRun', () => {
         turn,
         trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'late-metadata' } },
       })
-      session.append('context/message', {
+      session.append('user/message', {
         content: [{ type: 'text', text: 'late metadata' }],
         source: { kind: 'plugin', plugin: 'late-metadata' },
       }, { surfaceOp: 'append' })
@@ -87,7 +87,7 @@ describe('startInProcessRun', () => {
 
   it('seeds a forked child but reads only the child-owned output', async () => {
     const { ctx, parent } = await setup([textResponse('parent answer'), textResponse('child answer')])
-    parent.send([{ type: 'text', text: 'parent question' }])
+    parent.followup([{ type: 'text', text: 'parent question' }])
     await parent.whenIdle()
     const seed = parent.session.events.slice()
     const run = await startInProcessRun(request(parent), { seed })
diff --git a/packages/subagent/subagent-spawn/tests/spawn.e2e.ts b/packages/subagent/subagent-spawn/tests/spawn.e2e.ts
index 89efb2b815..8fbecdc976 100644
--- a/packages/subagent/subagent-spawn/tests/spawn.e2e.ts
+++ b/packages/subagent/subagent-spawn/tests/spawn.e2e.ts
@@ -31,7 +31,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('spawn backend with-key smoke', (
     ctx = await spawnHarness(workdir)
     const parent = ctx.agentLoop.create(SessionId('e2e-parent'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
-    parent.send([{ type: 'text', text:
+    parent.followup([{ type: 'text', text:
       'Use the subagent tool to delegate this exact task: "Use the bash tool to write the text '
       + 'SUBAGENT_WAS_HERE into a file named proof.txt in the current directory." '
       + 'After the subagent finishes, tell me it is done.' }])
diff --git a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
index 7ba0551f34..c83eca75ab 100644
--- a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
+++ b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
@@ -13,6 +13,7 @@ import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-sub
 import { MockAdapter, maxTokensResponse, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import * as spawn from '../src/index.ts'
 import { STRUCTURED_OUTPUT_TOOL } from '@deepseek-ai/dsh-subagent-inprocess'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 
 type Script = ConstructorParameters<typeof MockAdapter>[0]
 
@@ -94,7 +95,7 @@ describe('dsh-subagent-spawn', () => {
   it('a fresh child does NOT inherit the parent conversation (its log starts empty before the prompt)', async () => {
     // Drive the parent through one real turn so it has history, THEN spawn.
     const { ctx, parent } = await setup([textResponse('parent turn'), textResponse('child sees nothing')])
-    parent.send([{ type: 'text', text: 'parent prompt' }])
+    parent.followup([{ type: 'text', text: 'parent prompt' }])
     await parent.whenIdle()
     const parentEventCount = parent.session.events.length
     expect(parentEventCount).toBeGreaterThan(0)
@@ -187,10 +188,10 @@ describe('dsh-subagent-spawn', () => {
     expect(published).toEqual([])
   })
 
-  it('a cancel from agent/queued maps a no-turn child log to aborted', async () => {
+  it('a cancel from agent/inbox/enqueue maps a no-turn child log to aborted', async () => {
     const { ctx, parent } = await setup([])
     const controller = new AbortController()
-    ctx.on('agent/queued', () => { controller.abort('queued-window') })
+    ctx.on('agent/inbox/enqueue', () => { controller.abort('queued-window') })
     const run = await start(ctx, 'spawn', { prompt: [{ type: 'text', text: 'p' }], parent, signal: controller.signal })
     const result = await run.result
     expect(result).toMatchObject({ stopReason: 'aborted', output: [] })
@@ -371,7 +372,7 @@ describe('dsh-subagent-spawn', () => {
         textResponse('parent answer'),
         textResponse('child answer'),
       ])
-      parent.send([{ type: 'text', text: 'hi' }])
+      parent.followup([{ type: 'text', text: 'hi' }])
       await parent.whenIdle()
 
       const run = await start(ctx, 'spawn', {
@@ -393,10 +394,10 @@ describe('dsh-subagent-spawn', () => {
         toolCallResponse('c1', 'forbidden_tool', {}),
         textResponse('done'),
       ])
-      ctx.tools.register({
+      ctx.tools.register(defineContentToolFixture({
         name: 'forbidden_tool', description: 'global', parameters: {},
         execute: () => Promise.resolve([{ type: 'text', text: 'ran' }]),
-      })
+      }))
       const run = await start(ctx, 'spawn', {
         prompt: [{ type: 'text', text: 'do X' }],
         parent,
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 00655f1f51..95e9300b0b 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -32,7 +32,7 @@ import { randomUUID } from 'node:crypto'
 import { Context, Service } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
-import { assertSupportedOutputSchema } from '@deepseek-ai/dsh-tools'
+import { assertObjectJsonSchema } from '@deepseek-ai/dsh-tools'
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -242,7 +242,7 @@ export class SubagentService extends Service {
     }
     this.assertCapabilities(provider, request)
     assertSubagentMaxDepth(request.maxDepth)
-    if (request.outputSchema !== undefined) assertSupportedOutputSchema(request.outputSchema)
+    if (request.outputSchema !== undefined) assertObjectJsonSchema(request.outputSchema)
 
     const parent = request.parent
     const run = await provider.start(request)
diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts
index 7031bd0ad3..7d6df34ffd 100644
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -10,7 +10,7 @@ import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionId } from '@deepseek-ai/dsh-session'
-import type { StructuredOutputSchema, ToolRestriction } from '@deepseek-ai/dsh-tools'
+import type { ObjectJsonSchema, ToolRestriction } from '@deepseek-ai/dsh-tools'
 
 /** Identifies one accepted subagent run across its lifecycle event pair. */
 export type SubagentRunId = Branded<'SubagentRunId'>
@@ -73,11 +73,11 @@ export interface SubagentStartRequest {
   /** Per-child agent options (model and plugin-defined extension fields). */
   readonly agentOptions?: AgentOptions
   /**
-   * Object-rooted JSON Schema within `assertSupportedOutputSchema`'s enforced subset. Start rejects
+   * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
    * unsupported schemas or providers without the capability. Data must be plain host-realm JSON;
    * a successful child returns the matching value as {@link SubagentResult.structured}.
    */
-  readonly outputSchema?: StructuredOutputSchema
+  readonly outputSchema?: ObjectJsonSchema
   /**
    * Optional absolute delegation-depth cap for the child being started: its
    * computed depth must be less than or equal to this non-negative safe
diff --git a/packages/subagent/tool-subagent/README.md b/packages/subagent/tool-subagent/README.md
index e2af5ac552..08e143f94d 100644
--- a/packages/subagent/tool-subagent/README.md
+++ b/packages/subagent/tool-subagent/README.md
@@ -6,9 +6,9 @@ The model-facing delegation tool over one configured `ctx.subagents` provider. C
 
 Each plugin instance binds one `provider` to one `toolName`; the model receives no provider selector. Load another distinctly named instance to expose another transport. The tool registers only while its provider exists, avoiding sibling load-order and provider-reload dependencies. Its description follows `provider.inheritsParentContext`: fresh children require standalone prompts, while forked children already see completed parent turns.
 
-A foreground call passes the execution signal through startup and execution, awaits `run.result`, and always awaits `run.dispose()` before returning. Only `completed` returns final text; abort, refusal, token limit, and other failures become errored tool results without partial output.
+A foreground call passes the execution signal through startup and execution, awaits `run.result`, and always awaits `run.dispose()` before returning. Only `completed` returns the canonical `{ kind: 'foreground', runId, output: JsonValue[] }`, rendered as the same final text; abort, refusal, token limit, and other failures become errored tool results without partial output.
 
-With `run_in_background: true`, the tool registers the parent-owned task before starting the provider. A task-owned signal covers pending startup and the child after the starting call returns. `task_kill` and owner disposal abort it. Settlement awaits startup rollback or child disposal, then maps completed final text, abort to `killed`, and other failures to `failed`. The task has no incremental read; generic task tools own later status, collection, cancellation, and notices. See the [background subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md).
+With `run_in_background: true`, the tool registers the parent-owned task before starting the provider and returns canonical `{ kind: 'background', taskId }`, rendered as `started background subagent task <id>`. A task-owned signal covers pending startup and the child after the starting call returns. `task_kill` and owner disposal abort it. Settlement awaits startup rollback or child disposal, then maps completed final text, abort to `killed`, and other failures to `failed`. The task has no incremental read; generic task tools own later status, collection, cancellation, and notices. See the [background subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md).
 
 `toolFilter` changes the child's global tool layer but is not a parent-derived authority ceiling. See the [agent-scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
 
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index a84041d290..4eb29d0c6e 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -12,6 +12,7 @@ import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { assertSubagentMaxDepth } from '@deepseek-ai/dsh-subagent'
 import type { SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
 import type { TaskOutcome } from '@deepseek-ai/dsh-tasks'
@@ -95,6 +96,16 @@ function outputText(blocks: ContentBlock[]): string {
     .join('')
 }
 
+/** Render text blocks from the canonical JSON block array without trusting arbitrary values. */
+function outputValueText(values: JsonValue[]): string {
+  return values
+    .filter((value): value is { type: 'text'; text: string } =>
+      typeof value === 'object' && value !== null && !Array.isArray(value)
+      && value.type === 'text' && typeof value.text === 'string')
+    .map(value => value.text)
+    .join('')
+}
+
 /** A non-`completed` stop reason means the child did not finish cleanly. */
 function stopReasonError(result: SubagentResult): string | undefined {
   switch (result.stopReason) {
@@ -268,7 +279,36 @@ export function apply(ctx: Context, config: Config): void {
           },
         } : {},
       },
-      async execute(args, exec): Promise<ContentBlock[]> {
+      output: {
+        schema: {
+          oneOf: [
+            {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                kind: { type: 'string', required: true, const: 'background' },
+                taskId: { type: 'string', required: true },
+              },
+            },
+            {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                kind: { type: 'string', required: true, const: 'foreground' },
+                runId: { type: 'string', required: true },
+                output: { type: 'array', required: true, items: { type: 'json' } },
+              },
+            },
+          ],
+        },
+        render: (_args, value) => [{
+          type: 'text',
+          text: value.kind === 'background'
+            ? `started background subagent task ${value.taskId}`
+            : outputValueText(value.output),
+        }],
+      },
+      async execute(args, exec) {
         const parent = exec.agent
         if (!parent) {
           // Non-agent callers provide no parent for delegation ownership.
@@ -305,7 +345,7 @@ export function apply(ctx: Context, config: Config): void {
               }
             },
           })
-          return [{ type: 'text', text: `started background subagent task ${id}` }]
+          return { kind: 'background' as const, taskId: id }
         }
 
         const request = startRequest(
@@ -324,7 +364,13 @@ export function apply(ctx: Context, config: Config): void {
             // The registry converts this throw to isError; partial output is not success.
             throw new Error(error)
           }
-          return [{ type: 'text', text: outputText(result.output) }]
+          return {
+            kind: 'foreground' as const,
+            runId: run.id,
+            // Content blocks already cross durable JSON boundaries elsewhere;
+            // the registry performs the authoritative lossless snapshot here.
+            output: result.output as unknown as JsonValue[],
+          }
         } finally {
           // Dispose before returning so no child session outlives the call.
           await run.dispose()
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 8dda16f6df..8468216d49 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -65,6 +65,12 @@ describe('dsh-tool-subagent', () => {
     const ctx = await setup({ provider: 'mock' }, { reply: 'child says hi' })
     const result = await callSubagent(ctx, { description: 'do a thing', prompt: 'go research X' })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected subagent success')
+    expect(result.value).toEqual({
+      kind: 'foreground',
+      runId: 'scripted-subagent:mock:parent-1',
+      output: [{ type: 'text', text: 'child says hi' }],
+    })
     expect(text(result)).toBe('child says hi')
   })
 
@@ -445,7 +451,10 @@ describe('dsh-tool-subagent', () => {
     const result = await callSubagent(ctx, { description: 'd', prompt: 'p' }, { signal: controller.signal })
     expect(sawAborted).not.toHaveBeenCalled()
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(result.error).toEqual({
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    })
   })
 
   it('tools depend on the service: no `subagent` tool without ctx.subagents', async () => {
@@ -643,6 +652,8 @@ describe('dsh-tool-subagent background mode', () => {
 
     const start = await callSubagent(ctx, { description: 'deep research', prompt: 'dig in', run_in_background: true }, { agent: parent })
     expect(start.isError).toBe(false)
+    if (start.isError) throw new Error('expected background subagent success')
+    expect(start.value).toEqual({ kind: 'background', taskId: 'subagent-1' })
     expect(text(start)).toBe('started background subagent task subagent-1')
 
     const collected = await ctx.tools.execute({
@@ -679,7 +690,10 @@ describe('dsh-tool-subagent background mode', () => {
     controller.abort()
     const result = await callSubagent(ctx, { description: 'd', prompt: 'p', run_in_background: true }, { agent: parent, signal: controller.signal })
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(result.error).toEqual({
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    })
     expect(text(result)).toBe('Error: tool call aborted before dispatch')
   })
 
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 05a4974c19..8fea461545 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -6,7 +6,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 the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; cwd-rooted separators selected as canonical `/` or host-native; `session_info_update.updatedAt` → `{{updatedAt}}`; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `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/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **Normalizers** — pure functions turning the two captured surfaces into stable text: `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; `session_info_update.updatedAt` → `{{updatedAt}}`; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `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/implemented/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, the per-header-class pin (`system-prompt.expected.md` plus `tool-schemas.expected.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Refresh expands packed timing envelopes before aligning existing volatile event times, so switching between packed and unpacked layouts cannot shift later records; fresh chunk-fragment arrays remain authoritative. 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.
 
 A consuming `*.snapshot.ts` is the scenario table plus one factory call:
diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts
index 2821969457..5f6154d321 100644
--- a/packages/support/acp-snapshot/src/harness.ts
+++ b/packages/support/acp-snapshot/src/harness.ts
@@ -17,7 +17,7 @@
  */
 
 import { cp, mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
+import { existsSync, realpathSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { tmpdir } from 'node:os'
 import { basename, dirname, join, delimiter } from 'node:path'
@@ -141,6 +141,8 @@ export interface RunResult {
   sessionId?: string
   /** The generated cwd the session ran in (the bash workspace). */
   cwd: string
+  /** Filesystem-resolved spellings of {@link cwd} that child processes may report. */
+  cwdAliases: string[]
   /**
    * Every persisted session log harvested after the run, ordered primary-first:
    * the top-level (parent) session — the one with no `parentSession` — then each
@@ -222,6 +224,7 @@ export function snapshotSpillRoot(
  */
 export async function runScenario(input: InputScript, opts: RunOptions): Promise<RunResult> {
   const cwd = await mkdtemp(join(opts.workspaceParent ?? tmpdir(), 'acp-snap-cwd-'))
+  const cwdAliases = [...new Set([realpathSync(cwd), realpathSync.native(cwd)])]
   const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-snap-sessions-'))
   // Fixed path length: spill-policy budgets the preview against the REAL path
   // before stdout normalization, so tmpdir() length differences churn expected outputs.
@@ -329,6 +332,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
       rawStdout: launched.rawStdout(),
       stderr: launched.stderr(),
       cwd,
+      cwdAliases,
       ...sessionId !== undefined ? { sessionId } : {},
       sessionLogs,
     }
diff --git a/packages/support/acp-snapshot/src/normalize.ts b/packages/support/acp-snapshot/src/normalize.ts
index b32c5c0574..577dddceb6 100644
--- a/packages/support/acp-snapshot/src/normalize.ts
+++ b/packages/support/acp-snapshot/src/normalize.ts
@@ -46,6 +46,8 @@ export interface NormalizeContext {
   sessionIds: string[]
   /** The generated cwd the run used — replaced with `{{cwd}}`. */
   cwd: string
+  /** Other filesystem spellings of the same cwd (for example Windows short and long paths). */
+  cwdAliases?: readonly string[]
 }
 
 /** How cwd-rooted path separators are represented after the cwd is tokenized. */
@@ -60,9 +62,13 @@ export interface NormalizeOptions {
 /** Replace cwd, session ids, and any stray UUID with stable tokens in a string. */
 function scrubString(value: string, ctx: NormalizeContext, cwdPathMode: CwdPathMode): string {
   let out = value
-  // cwd first (longest, most specific), then explicit session ids, then any
-  // residual UUID (covers ids that appear in places we didn't enumerate).
-  out = out.split(ctx.cwd).join(CWD)
+  // Filesystem APIs can report one directory with several spellings. Replace
+  // every known spelling longest-first so a shorter alias cannot corrupt a
+  // longer one before it is tokenized.
+  const cwdSpellings = [...new Set([ctx.cwd, ...ctx.cwdAliases ?? []])]
+    .filter(spelling => spelling.length > 0)
+    .sort((left, right) => right.length - left.length)
+  for (const spelling of cwdSpellings) out = out.split(spelling).join(CWD)
   out = out.split(`/private${CWD}`).join(CWD)
   if (cwdPathMode === 'canonical') {
     // Restrict separator conversion to paths rooted at the cwd token. A global
diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts
index 51e958a106..7f0190bb2c 100644
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -629,6 +629,7 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
             ...result.sessionLogs.map(l => l.id),
           ],
           cwd: result.cwd,
+          cwdAliases: result.cwdAliases,
         }
 
         // Record writes live model fixtures; keyless refresh writes every comparable replayed
diff --git a/packages/support/acp-snapshot/tests/normalize.spec.ts b/packages/support/acp-snapshot/tests/normalize.spec.ts
index bdd85491d2..e9a1983c76 100644
--- a/packages/support/acp-snapshot/tests/normalize.spec.ts
+++ b/packages/support/acp-snapshot/tests/normalize.spec.ts
@@ -44,6 +44,24 @@ describe('normalizeStdout', () => {
     expect(out).not.toContain(ctx.sessionIds[0] as string)
   })
 
+  it('scrubs every filesystem spelling of the cwd longest-first', () => {
+    const longCwd = String.raw`C:\Users\runneradmin\AppData\Local\Temp\acp-snapshot`
+    const aliasedCtx: NormalizeContext = {
+      sessionIds: [],
+      cwd: String.raw`C:\Users\RUNNER~1\AppData\Local\Temp\acp-snapshot`,
+      cwdAliases: [
+        longCwd,
+        String.raw`C:\Users\runneradmin\AppData\Local\Temp\acp`,
+      ],
+    }
+    const raw = JSON.stringify({
+      cwd: longCwd,
+      path: `${longCwd}\\nested\\proof.txt`,
+    })
+    const frame = JSON.parse(normalizeStdout(raw, aliasedCtx)) as { cwd: string; path: string }
+    expect(frame).toEqual({ cwd: '{{cwd}}', path: '{{cwd}}/nested/proof.txt' })
+  })
+
   it('canonicalizes only cwd-rooted path separators', () => {
     const windowsCtx: NormalizeContext = {
       sessionIds: [],
diff --git a/packages/support/invariants/README.md b/packages/support/invariants/README.md
index e4866212b6..2dd0cde142 100644
--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -34,7 +34,7 @@ The current executable companions protect these relationships:
 
 | Companion | Checks |
 |---|---|
-| `dsh-session`, `dsh-agent`, `dsh-scope`, `dsh-agent-loop` | Session enclosure and call/result trace, agent-status transitions, scoped subjects, and model-request reconstruction. |
+| `dsh-session`, `dsh-agent`, `dsh-scope`, `dsh-agent-loop` | Session enclosure and call/result trace, agent-status transitions, inbox FIFO conservation, scoped subjects, and model-request reconstruction. |
 | `dsh-llm`, `dsh-llm-retry`, `dsh-tools`, `dsh-system-prompt` | Stream grammar, durable retry position and bounds, tool-pipeline stages and frozen results, and authoritative prompt-assembly data. |
 | `dsh-compact`, `dsh-hook-protocol`, `dsh-sandbox-policy` | Durable compaction and hook pairing, compaction metadata, and sandbox-mode vocabulary. |
 | `dsh-fs`, `dsh-subagent`, `dsh-workflow` | Filesystem event identity, provider/child pairing, and workflow/agent lifecycle identity. |
diff --git a/packages/support/loader-smoke/src/index.ts b/packages/support/loader-smoke/src/index.ts
index 717e0c6a12..61ad3b9d16 100644
--- a/packages/support/loader-smoke/src/index.ts
+++ b/packages/support/loader-smoke/src/index.ts
@@ -59,8 +59,6 @@ export interface ExampleLaunchOptions {
   readonly mode?: ExampleMode
   /** Absolute repo tsconfig whose `paths` map resolves unbuilt workspace imports. Required in `src` mode, ignored in `lib`. */
   readonly tsconfigPath?: string
-  /** Prepend `--expose-internals` (the Cordis Loader's bare-plugin resolver needs it for some bins); defaults to `false`. */
-  readonly exposeInternals?: boolean
   /** Extra environment entries the mode-specific ones layer over; the caller then merges the result over `process.env`. */
   readonly env?: NodeJS.ProcessEnv
 }
@@ -90,9 +88,9 @@ function toLibBin(srcBin: string): string {
 /**
  * Resolve how to spawn an example bin in the selected mode.
  *
- * `src` yields `node [--expose-internals] --import <tsx> <srcBin> <configArgs>` with `TSX_TSCONFIG_PATH`
- * set so the tsconfig `paths` map resolves workspace imports to source. `lib` yields
- * `node [--expose-internals] <libBin> <configArgs>` under plain Node with no tsx and no paths map, so
+ * `src` yields `node --import <tsx> <srcBin> <configArgs>` with `TSX_TSCONFIG_PATH` set so the
+ * tsconfig `paths` map resolves workspace imports to source. `lib` yields
+ * `node <libBin> <configArgs>` under plain Node with no tsx and no paths map, so
  * bare package plugins resolve through real package `exports` into built `lib/`; relative example-local
  * TypeScript plugins remain source files loaded through Node's built-in type stripping. Bare resolution
  * requires the config to live below a workspace that declares its `cordis.yml` package dependencies.
@@ -103,7 +101,6 @@ function toLibBin(srcBin: string): string {
 export function resolveExampleLaunch(options: ExampleLaunchOptions): ExampleLaunch {
   const mode = options.mode ?? resolveExampleMode()
   const configArgs = options.configArgs ?? []
-  const flags = options.exposeInternals === true ? ['--expose-internals'] : []
   const env: NodeJS.ProcessEnv = { ...options.env }
 
   if (mode === 'src') {
@@ -112,10 +109,10 @@ export function resolveExampleLaunch(options: ExampleLaunchOptions): ExampleLaun
     }
     const tsxLoader = import.meta.resolve('tsx')
     env.TSX_TSCONFIG_PATH = options.tsconfigPath
-    return { command: process.execPath, args: [...flags, '--import', tsxLoader, options.srcBin, ...configArgs], env }
+    return { command: process.execPath, args: ['--import', tsxLoader, options.srcBin, ...configArgs], env }
   }
 
-  return { command: process.execPath, args: [...flags, options.libBin ?? toLibBin(options.srcBin), ...configArgs], env }
+  return { command: process.execPath, args: [options.libBin ?? toLibBin(options.srcBin), ...configArgs], env }
 }
 
 /** Inputs that vary between real-Loader example smokes. */
@@ -172,7 +169,6 @@ export async function runLoaderSmoke(options: LoaderSmokeOptions): Promise<Loade
       configArgs: options.binArgs ?? [options.configPath],
       ...options.mode !== undefined ? { mode: options.mode } : {},
       tsconfigPath: options.tsconfigPath,
-      exposeInternals: true,
       env: { DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents'), ...options.env },
     })
     const result = await new Promise<LoaderSmokeResult>((resolve, reject) => {
diff --git a/packages/support/loader-smoke/tests/example-launch.spec.ts b/packages/support/loader-smoke/tests/example-launch.spec.ts
index 77a0791516..8033645d53 100644
--- a/packages/support/loader-smoke/tests/example-launch.spec.ts
+++ b/packages/support/loader-smoke/tests/example-launch.spec.ts
@@ -50,7 +50,6 @@ describe('resolveExampleLaunch', () => {
     expect(args).toContain('--import')
     expect(args).toContain(SRC_BIN)
     expect(args[args.length - 1]).toBe('./cordis.yml')
-    expect(args).not.toContain('--expose-internals')
     expect(env.TSX_TSCONFIG_PATH).toBe(TSCONFIG)
   })
 
@@ -78,11 +77,6 @@ describe('resolveExampleLaunch', () => {
     expect(args).toContain(fixture)
   })
 
-  it('prepends --expose-internals when requested', () => {
-    const { args } = resolveExampleLaunch({ srcBin: SRC_BIN, mode: 'lib', exposeInternals: true })
-    expect(args[0]).toBe('--expose-internals')
-  })
-
   it('lib mode: rewrites only the last /src/ segment', () => {
     const { args } = resolveExampleLaunch({
       srcBin: '/repo/src/packages/examples/acp-demo/src/bin.ts',
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 37d342e0fe..1d9ce2b249 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -4,7 +4,7 @@ The process-local background task registry (`ctx.tasks`). It gives long-running
 
 ## Service API
 
-- `start(spec): TaskId` validates the control surface, spec, and exact live owner before calling the producer's `run()` once. A starter throw leaves nothing registered; successful return commits without another failable step.
+- `start(spec): TaskId` validates the control surface, spec, exact live owner, and optional positive `outputLimitBytes` before calling the producer's `run()` once. A starter throw leaves nothing registered; successful return commits without another failable step.
 - `get(id, caller?)` and `list(caller?)` return non-consuming snapshots. Listing includes only caller-owned and unowned tasks.
 - `read(id, caller?)` consumes the single cursor for stream tasks and reads terminal output idempotently for final-output tasks.
 - `kill(id, caller?, reason?)` invokes producer cancellation before changing status. A cancellation throw leaves the task running; success changes it to `stopping` and marks terminal delivery reported.
@@ -14,6 +14,8 @@ The process-local background task registry (`ctx.tasks`). It gives long-running
 
 Owned access compares the task's `SessionId` with the caller's. Ids such as `bash-1` are predictable, so this fence is the boundary. Unowned tasks are open to callers and last until service disposal.
 
+`outputLimitBytes` is producer-owned model-presentation policy carried unchanged into snapshots. A control surface applies it after adding status or notice metadata; the registry does not rewrite producer output or invent a default for producers that omit it.
+
 ## Lifecycle
 
 Tasks belong to their owner and backend, not the producer tool fiber, so producer and surface reloads do not stop them. The first task for an owner attaches one awaited effect to the exact `Agent` scope. Owner disposal cancels that object's tasks, awaits producer quiescence, and removes their snapshots; reused agent or session ids cannot redirect an old cleanup.
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 457f5473a3..16f0807656 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -42,6 +42,7 @@ interface TrackedTask {
   id: TaskId
   kind: TaskKind
   label: string
+  outputLimitBytes: number | undefined
   /** Exact lifecycle owner; session-id authorization is derived from it. */
   owner: Agent | undefined
   cancel: (reason?: string) => void
@@ -104,6 +105,10 @@ export class TaskService extends Service {
     }
     if (spec.kind.length === 0) throw new Error('invalid task kind: expected a non-empty string')
     if (spec.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
+    if (spec.outputLimitBytes !== undefined
+      && (!Number.isSafeInteger(spec.outputLimitBytes) || spec.outputLimitBytes <= 0)) {
+      throw new Error(`invalid outputLimitBytes: expected a positive safe integer, got ${JSON.stringify(spec.outputLimitBytes)}`)
+    }
     if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner)
 
     const hooks = spec.run()
@@ -117,6 +122,7 @@ export class TaskService extends Service {
       id,
       kind: spec.kind,
       label: spec.label,
+      outputLimitBytes: spec.outputLimitBytes,
       owner: spec.owner,
       cancel: hooks.cancel.bind(hooks),
       readOutput: hooks.readOutput?.bind(hooks),
@@ -329,6 +335,7 @@ export class TaskService extends Service {
       id: task.id,
       kind: task.kind,
       label: task.label,
+      ...task.outputLimitBytes !== undefined ? { outputLimitBytes: task.outputLimitBytes } : {},
       ...ownerSession !== undefined ? { ownerSession } : {},
       status: task.status,
       ...task.detail !== undefined ? { detail: task.detail } : {},
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index 96316260ec..d722f3fce6 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -61,6 +61,11 @@ export interface TaskStart {
   kind: TaskKind
   /** One-line model-facing label (the command; the delegation description). */
   label: string
+  /**
+   * Optional UTF-8 byte cap for each complete model-facing completion notice or
+   * output read, including control-surface status metadata.
+   */
+  outputLimitBytes?: number
   /**
    * Owning live agent. Access is fenced by its session id, and agent disposal
    * cancels and awaits the task. The instance must be the one currently
@@ -109,6 +114,8 @@ export interface TaskSnapshot {
   kind: TaskKind
   /** The producer-supplied one-line label. */
   label: string
+  /** Producer-owned cap for complete model-facing notices and output reads. */
+  outputLimitBytes?: number
   /**
    * Owner session id used for authorization and correlation; absent for
    * unowned tasks. Completion listeners receive the exact {@link Agent}
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index 0d3eae8338..015f1c4f2b 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import TaskService, { TaskId } from '@deepseek-ai/dsh-tasks'
 import type { TaskHooks, TaskKind, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
@@ -23,9 +23,11 @@ function stubAgent(ctx: Context, rawId: string): Agent {
     session: new Session(id),
     status: 'idle' as const,
     ctx: scopeFiber.ctx,
-    send() {},
-    steer() {},
-    inject() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
+    inject: () => AgentMessageId('stub'),
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle() { return Promise.resolve() },
   }
@@ -44,13 +46,19 @@ function producer(overrides: Partial<Omit<TaskStart, 'run'> & TaskHooks> = {}) {
   let settle!: (outcome: TaskOutcome) => void
   let reject!: (error: unknown) => void
   const cancels: (string | undefined)[] = []
-  const { kind = 'bash', label = 'sleep 60', owner, ...hookOverrides } = overrides
+  const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, ...hookOverrides } = overrides
   const hooks: TaskHooks = {
     cancel(reason) { cancels.push(reason) },
     done: new Promise<TaskOutcome>((res, rej) => { settle = res; reject = rej }),
     ...hookOverrides,
   }
-  const spec: TaskStart = { kind, label, ...owner !== undefined ? { owner } : {}, run: () => hooks }
+  const spec: TaskStart = {
+    kind,
+    label,
+    ...owner !== undefined ? { owner } : {},
+    ...outputLimitBytes !== undefined ? { outputLimitBytes } : {},
+    run: () => hooks,
+  }
   return { spec, settle, reject, cancels }
 }
 
@@ -85,10 +93,11 @@ describe('TaskService.start', () => {
       .toThrow('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
   })
 
-  it('rejects an empty kind and an empty label', async () => {
+  it('rejects an empty kind, empty label, and invalid output limit', async () => {
     const ctx = await harness()
     expect(() => ctx.tasks.start(producer({ kind: '' as TaskKind }).spec)).toThrow('invalid task kind')
     expect(() => ctx.tasks.start(producer({ label: '' }).spec)).toThrow('invalid task label')
+    expect(() => ctx.tasks.start(producer({ outputLimitBytes: 0 }).spec)).toThrow('outputLimitBytes')
   })
 
   it('issues kind-prefixed ids from per-kind counters', async () => {
@@ -118,6 +127,16 @@ describe('TaskService reads and settlement', () => {
     expect(read.snapshot.finishedAt).toBeTypeOf('number')
   })
 
+  it('projects a producer-owned model output limit into reads and snapshots', async () => {
+    const ctx = await harness()
+    const p = producer({ outputLimitBytes: 64, readOutput: () => 'delta' })
+    const id = ctx.tasks.start(p.spec)
+    expect(ctx.tasks.read(id)).toMatchObject({
+      text: 'delta', snapshot: { outputLimitBytes: 64 },
+    })
+    expect(ctx.tasks.get(id)).toMatchObject({ outputLimitBytes: 64 })
+  })
+
   it('final-output kinds read empty while live, the outcome output idempotently once settled', async () => {
     const ctx = await harness()
     const p = producer({ kind: 'subagent', label: 'research task' })
diff --git a/packages/tasks/tool-tasks/README.md b/packages/tasks/tool-tasks/README.md
index 7e1ab82971..a103640cd5 100644
--- a/packages/tasks/tool-tasks/README.md
+++ b/packages/tasks/tool-tasks/README.md
@@ -10,9 +10,13 @@ The model-facing control surface for `ctx.tasks`: three kind-independent tools,
 
 All three use generic ACP cards: `read` for output and list, `execute` for kill.
 
+Their canonical values are `{ text, task }`, `PublicTaskSnapshot[]`, and `{ outcome: 'cancellation-requested' | 'already-finished', task }`. A public snapshot carries id, kind, label, status/detail, and start/finish times; it deliberately omits `ownerSession` and the internal `reported` notice bit. Native renderers preserve the status and acknowledgement text above.
+
+When a producer supplies `outputLimitBytes`, `task_output`, terminal `task_kill`, and completion notices cap the complete Native UTF-8 result after adding status or notice text. Reads retain the output tail and control suffix when they fit; a bounded completion notice instead reserves `background task <id>` and the `task_output` collection instruction before spending remaining bytes on its variable kind, label, status, detail, and truncation marker. A prepended pre-execute listener captures the caller-visible task before policy, and each task-control definition's final-content callback applies its producer cap to single-text denials, short-circuits, normalized tool or pipeline failures, replacements, and blocks; structured multi-block policy results retain their shape. An existing producer truncation marker is reused rather than duplicated. Producers that omit the field retain the existing unbounded control-surface behavior.
+
 ## Completion notices
 
-An unreported completion injects `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` into the exact owner's session. Injection is durable context for the next request, not a wake-up. A kill or terminal read/wait marks delivery reported and suppresses the redundant notice; owner-disposal races are contained.
+An unreported completion injects `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` into the exact owner's session. When bounded, the stable id prefix and collection command outrank variable label/detail so the notice remains actionable at PTY's supported 64-byte minimum. Injection is durable context for the next request, not a wake-up. A kill or terminal read/wait marks delivery reported and suppresses the redundant notice; owner-disposal races are contained.
 
 ## Config
 
@@ -67,7 +71,7 @@ Reads return output or `(no new output)` followed by `[status: <status>]` and op
 
 #### Token effect
 
-Results and notices remain in parent history until compaction. Stream reads do not repeat consumed output.
+Results and notices remain in parent history until compaction. Stream reads do not repeat consumed output; a producer-supplied `outputLimitBytes` bounds each complete read or notice.
 
 #### KV Cache effect
 
diff --git a/packages/tasks/tool-tasks/package.json b/packages/tasks/tool-tasks/package.json
index fc1f96417d..2e03fb26a2 100644
--- a/packages/tasks/tool-tasks/package.json
+++ b/packages/tasks/tool-tasks/package.json
@@ -26,21 +26,23 @@
     "src"
   ],
   "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-retention": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-retention": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
diff --git a/packages/tasks/tool-tasks/src/index.ts b/packages/tasks/tool-tasks/src/index.ts
index 2d556cada9..ad8e9af674 100644
--- a/packages/tasks/tool-tasks/src/index.ts
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -8,8 +8,10 @@
 
 import type { Context } from 'cordis'
 import z from 'schemastery'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { TextRetainer } from '@deepseek-ai/dsh-retention'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { GenericCallView } from '@deepseek-ai/dsh-tools'
+import type { GenericCallView, ToolDefinition, ToolExecution } from '@deepseek-ai/dsh-tools'
 import { TaskId } from '@deepseek-ai/dsh-tasks'
 import type { TaskSnapshot } from '@deepseek-ai/dsh-tasks'
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -30,18 +32,135 @@ export const Config: z<Config> = z.object({
   maxWaitTimeoutMs: z.number().min(1).default(600_000),
 })
 
+/** Task state safe for model-authored programs; ownership/bookkeeping fields are omitted. */
+export interface PublicTaskSnapshot {
+  id: string
+  kind: string
+  label: string
+  status: TaskSnapshot['status']
+  detail?: string
+  startedAt: number
+  finishedAt?: number
+}
+
+/** Shared schema for task-control outputs. */
+const PUBLIC_TASK_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    id: { type: 'string', required: true },
+    kind: { type: 'string', required: true },
+    label: { type: 'string', required: true },
+    status: {
+      type: 'string',
+      required: true,
+      enum: ['running', 'stopping', 'completed', 'killed', 'failed'],
+    },
+    detail: { type: 'string' },
+    startedAt: { type: 'integer', required: true },
+    finishedAt: { type: 'integer' },
+  },
+} as const
+
+/** Remove task ownership and notification bookkeeping from a registry snapshot. */
+function publicTask(snapshot: TaskSnapshot): PublicTaskSnapshot {
+  return {
+    id: snapshot.id,
+    kind: snapshot.kind,
+    label: snapshot.label,
+    status: snapshot.status,
+    ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {},
+    startedAt: snapshot.startedAt,
+    ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {},
+  }
+}
+
 /**
  * Render generic status with optional producer detail.
  * @param snapshot - task state to render.
  * @returns a bracketed status line.
  */
-export function statusLine(snapshot: TaskSnapshot): string {
+export function statusLine(snapshot: Pick<TaskSnapshot, 'status' | 'detail'>): string {
   return snapshot.detail !== undefined
     ? `[status: ${snapshot.status}, ${snapshot.detail}]`
     : `[status: ${snapshot.status}]`
 }
 
-/** Validate the non-empty constraint that SchemaSpec cannot express. */
+const encoder = new TextEncoder()
+
+function retainTail(text: string, maxBytes: number): string {
+  const retainer = new TextRetainer({ kind: 'tail', maxBytes })
+  retainer.push(text)
+  return retainer.finish().text
+}
+
+function retainHead(text: string, maxBytes: number): string {
+  const retainer = new TextRetainer({ kind: 'head', maxBytes })
+  retainer.push(text)
+  return retainer.finish().text
+}
+
+function fitWithSuffix(
+  content: string,
+  suffix: string,
+  maxBytes: number | undefined,
+  omitted: string,
+): string {
+  const complete = `${content}${suffix}`
+  if (maxBytes === undefined || encoder.encode(complete).byteLength <= maxBytes) return complete
+  const fixed = `${content.endsWith(omitted.trimStart()) ? '' : omitted}${suffix}`
+  const fixedBytes = encoder.encode(fixed).byteLength
+  if (fixedBytes >= maxBytes) return retainTail(fixed, maxBytes)
+  return `${retainTail(content, maxBytes - fixedBytes)}${fixed}`
+}
+
+function fitCompletionNotice(snapshot: TaskSnapshot): string {
+  const prefix = `background task ${snapshot.id}`
+  const detail = ` (${snapshot.kind}: ${snapshot.label}) finished ${statusLine(snapshot)}`
+  const action = '\nDone; task_output.'
+  const complete = `${prefix}${detail}. Read its output with task_output.`
+  const maxBytes = snapshot.outputLimitBytes
+  if (maxBytes === undefined || encoder.encode(complete).byteLength <= maxBytes) return complete
+  const omitted = '\n[notice truncated]'
+  const fixed = `${prefix}${omitted}${action}`
+  const fixedBytes = encoder.encode(fixed).byteLength
+  if (fixedBytes <= maxBytes) {
+    return fixedBytes === maxBytes
+      ? fixed
+      : `${prefix}${retainHead(detail, maxBytes - fixedBytes)}${omitted}${action}`
+  }
+  const compact = `${prefix}${action}`
+  const compactBytes = encoder.encode(compact).byteLength
+  if (compactBytes <= maxBytes) return compact
+  const actionBytes = encoder.encode(action).byteLength
+  if (actionBytes >= maxBytes) return retainTail(action, maxBytes)
+  return `${retainHead(prefix, maxBytes - actionBytes)}${action}`
+}
+
+function rawSingleText(content: readonly ContentBlock[]): string | undefined {
+  if (content.length !== 1) return undefined
+  const block = content[0]
+  if (block?.type !== 'text') return undefined
+  return block.text
+}
+
+function boundSingleText(content: readonly ContentBlock[], maxBytes: number): ContentBlock[] | undefined {
+  const text = rawSingleText(content)
+  if (text === undefined) return undefined
+  return [{
+    type: 'text',
+    text: fitWithSuffix(text, '', maxBytes, '\n[result truncated]'),
+  }]
+}
+
+function visibleOutputLimit(ctx: Context, exec: ToolExecution): number | undefined {
+  if (exec.name !== 'task_output' && exec.name !== 'task_kill') return undefined
+  const taskId = (exec.arguments as { task_id?: unknown } | null | undefined)?.task_id
+  if (typeof taskId !== 'string' || taskId.length === 0) return undefined
+  return ctx.tasks.list(exec.agent).find(snapshot => snapshot.id === taskId)?.outputLimitBytes
+}
+
+/** Validate the non-empty constraint that ParameterSchemaSpec cannot express. */
 function validateTaskId(value: string): TaskId {
   if (value.length === 0) {
     throw new Error(`invalid task_id: expected a non-empty string, got ${JSON.stringify(value)}`)
@@ -61,6 +180,33 @@ export function apply(ctx: Context, config: Config): void {
     throw new Error(`tool-tasks: waitTimeoutMs (${waitDefault}) exceeds maxWaitTimeoutMs (${waitCap})`)
   }
 
+  const outputLimits = new WeakMap<ToolExecution, number>()
+  ctx.on('tools/pre-execute', (exec, next) => {
+    const maxBytes = visibleOutputLimit(ctx, exec)
+    if (maxBytes !== undefined) outputLimits.set(exec, maxBytes)
+    return next()
+  }, { prepend: true })
+  const finalizeTaskContent: NonNullable<ToolDefinition['finalizeContent']> = (exec, result) => {
+    const maxBytes = outputLimits.get(exec) ?? visibleOutputLimit(ctx, exec)
+    outputLimits.delete(exec)
+    if (maxBytes === undefined) return undefined
+    if (exec.name === 'task_output' && !result.isError) {
+      // This definition owns and schema-validates the canonical value. Preserve
+      // its output/status split only while policy left the default rendering intact.
+      const value = result.value as unknown as { text: string; task: PublicTaskSnapshot }
+      const body = value.text.length > 0 ? value.text : '(no new output)'
+      const content = body.endsWith('\n') ? body.slice(0, -1) : body
+      const suffix = `\n${statusLine(value.task)}`
+      if (rawSingleText(result.content) === `${content}${suffix}`) {
+        return [{
+          type: 'text',
+          text: fitWithSuffix(content, suffix, maxBytes, '\n[output truncated]'),
+        }]
+      }
+    }
+    return boundSingleText(result.content, maxBytes)
+  }
+
   // Producers may start work only while a control surface is attached.
   ctx.tasks.attachSurface('tool-tasks')
 
@@ -76,7 +222,10 @@ export function apply(ctx: Context, config: Config): void {
     if (snapshot.reported || owner === undefined) return
     try {
       owner.inject(
-        [{ type: 'text', text: `background task ${snapshot.id} (${snapshot.kind}: ${snapshot.label}) finished ${statusLine(snapshot)}. Read its output with task_output.` }],
+        [{
+          type: 'text',
+          text: fitCompletionNotice(snapshot),
+        }],
         { source: { kind: 'plugin', plugin: 'tool-tasks' } },
       )
     } catch (error: unknown) {
@@ -98,6 +247,22 @@ export function apply(ctx: Context, config: Config): void {
       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.' },
     },
+    finalizeContent: finalizeTaskContent,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          text: { type: 'string', required: true },
+          task: { ...PUBLIC_TASK_SCHEMA, required: true },
+        },
+      },
+      render: (_args, value) => {
+        const body = value.text.length > 0 ? value.text : '(no new output)'
+        const separator = body.endsWith('\n') ? '' : '\n'
+        return [{ type: 'text', text: `${body}${separator}${statusLine(value.task)}` }]
+      },
+    },
     async execute(args, exec) {
       const id = validateTaskId(args.task_id)
       if (args.wait === true) {
@@ -105,9 +270,7 @@ export function apply(ctx: Context, config: Config): void {
         await ctx.tasks.wait(id, timeout, exec.agent, exec.signal)
       }
       const read = ctx.tasks.read(id, exec.agent)
-      const body = read.text.length > 0 ? read.text : '(no new output)'
-      const separator = body.endsWith('\n') ? '' : '\n'
-      return [{ type: 'text', text: `${body}${separator}${statusLine(read.snapshot)}` }]
+      return { text: read.text, task: publicTask(read.snapshot) }
     },
     presentCall: args => presentTaskCall(`Read output from background task ${args.task_id}`, 'read', args.task_id),
   }))
@@ -116,12 +279,18 @@ export function apply(ctx: Context, config: Config): void {
     name: 'task_list',
     description: 'List your background tasks (running and finished) with their ids, kinds, and statuses.',
     parameters: {},
+    output: {
+      schema: { type: 'array', items: PUBLIC_TASK_SCHEMA },
+      render: (_args, tasks) => [{
+        type: 'text',
+        text: tasks.length === 0
+          ? '(no background tasks)'
+          : tasks.map(t => `${t.id} [${t.kind}] ${t.status} — ${t.label}`).join('\n'),
+      }],
+    },
     execute(_args, exec) {
       const tasks = ctx.tasks.list(exec.agent)
-      const text = tasks.length === 0
-        ? '(no background tasks)'
-        : tasks.map(t => `${t.id} [${t.kind}] ${t.status} — ${t.label}`).join('\n')
-      return Promise.resolve([{ type: 'text', text }])
+      return Promise.resolve(tasks.map(publicTask))
     },
     presentCall: () => presentTaskCall('List background tasks', 'read'),
   }))
@@ -133,15 +302,36 @@ export function apply(ctx: Context, config: Config): void {
       task_id: { type: 'string', required: true, 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.' },
     },
+    finalizeContent: finalizeTaskContent,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          outcome: {
+            type: 'string',
+            required: true,
+            enum: ['cancellation-requested', 'already-finished'],
+          },
+          task: { ...PUBLIC_TASK_SCHEMA, required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.outcome === 'already-finished'
+          ? `task ${value.task.id} had already finished ${statusLine(value.task)}`
+          : `requested cancellation of task ${value.task.id}`,
+      }],
+    },
     execute(args, exec) {
       const id = validateTaskId(args.task_id)
       const result = ctx.tasks.kill(id, exec.agent, args.reason)
-      if (result === 'already-finished') {
-        // A snapshot describes terminal state without consuming pending output.
-        const snapshot = ctx.tasks.get(id, exec.agent)
-        return Promise.resolve([{ type: 'text', text: `task ${id} had already finished ${statusLine(snapshot)}` }])
-      }
-      return Promise.resolve([{ type: 'text', text: `requested cancellation of task ${id}` }])
+      // A snapshot describes current state without consuming pending output.
+      const snapshot = publicTask(ctx.tasks.get(id, exec.agent))
+      return Promise.resolve({
+        outcome: result === 'already-finished' ? 'already-finished' as const : 'cancellation-requested' as const,
+        task: snapshot,
+      })
     },
     presentCall: args => presentTaskCall(`Kill background task ${args.task_id}`, 'execute', args.task_id),
   }))
diff --git a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
index 4c09845eae..c41f498472 100644
--- a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
+++ b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
@@ -6,7 +6,7 @@ import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import TaskService, { TaskId } from '@deepseek-ai/dsh-tasks'
 import type { TaskHooks, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import { statusLine } from '@deepseek-ai/dsh-tool-tasks'
@@ -52,13 +52,19 @@ function detachAgent(agent: Agent): void {
 function producer(overrides: Partial<Omit<TaskStart, 'run'> & TaskHooks> = {}) {
   let settle!: (outcome: TaskOutcome) => void
   const cancels: (string | undefined)[] = []
-  const { kind = 'bash', label = 'sleep 60', owner, ...hookOverrides } = overrides
+  const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, ...hookOverrides } = overrides
   const hooks: TaskHooks = {
     cancel(reason) { cancels.push(reason) },
     done: new Promise<TaskOutcome>((res) => { settle = res }),
     ...hookOverrides,
   }
-  const spec: TaskStart = { kind, label, ...owner !== undefined ? { owner } : {}, run: () => hooks }
+  const spec: TaskStart = {
+    kind,
+    label,
+    ...owner !== undefined ? { owner } : {},
+    ...outputLimitBytes !== undefined ? { outputLimitBytes } : {},
+    run: () => hooks,
+  }
   return { spec, settle, cancels }
 }
 
@@ -116,7 +122,16 @@ describe('task_output', () => {
     ctx.tasks.start(producer({ readOutput: () => chunks.shift() ?? '' }).spec)
 
     // A body already ending in a newline gets no doubled separator.
-    expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' }))).toBe('line one\n[status: running]')
+    const first = await call(ctx, 'task_output', { task_id: 'bash-1' })
+    if (first.isError) throw new Error('expected task_output success')
+    const firstValue = first.value as { text: string; task: Record<string, unknown> }
+    expect(firstValue).toMatchObject({
+      text: 'line one\n',
+      task: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'running' },
+    })
+    expect(firstValue.task).not.toHaveProperty('ownerSession')
+    expect(firstValue.task).not.toHaveProperty('reported')
+    expect(text(first)).toBe('line one\n[status: running]')
     expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' }))).toBe('(no new output)\n[status: running]')
   })
 
@@ -131,6 +146,118 @@ describe('task_output', () => {
     expect(text(await call(ctx, 'task_output', { task_id: 'subagent-1' }))).toBe('the answer\n[status: completed, completed]')
   })
 
+  it('applies a producer limit to the complete body and status result', async () => {
+    const { ctx } = await setup()
+    ctx.tasks.start(producer({
+      outputLimitBytes: 48,
+      readOutput: () => '界'.repeat(100),
+    }).spec)
+
+    const output = text(await call(ctx, 'task_output', { task_id: 'bash-1' }))
+    expect(Buffer.byteLength(output)).toBeLessThanOrEqual(48)
+    expect(output).toContain('[status: running]')
+  })
+
+  it('preserves empty and newline-terminated output under a producer limit', async () => {
+    const { ctx } = await setup()
+    const chunks = ['', 'line\n']
+    ctx.tasks.start(producer({
+      outputLimitBytes: 64,
+      readOutput: () => chunks.shift() ?? '',
+    }).spec)
+
+    expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' })))
+      .toBe('(no new output)\n[status: running]')
+    expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' })))
+      .toBe('line\n[status: running]')
+  })
+
+  it('bounds post-policy output without restoring the canonical status rendering', async () => {
+    const { ctx } = await setup()
+    ctx.tasks.start(producer({
+      outputLimitBytes: 64,
+      readOutput: () => 'canonical output',
+    }).spec)
+    ctx.on('tools/post-execute', (exec, _result, next) => {
+      if (exec.name !== 'task_output') return next()
+      return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: 'p'.repeat(1_000) }] })
+    })
+
+    const result = await call(ctx, 'task_output', { task_id: 'bash-1' })
+    expect(Buffer.byteLength(text(result))).toBeLessThanOrEqual(64)
+    expect(text(result)).toContain('[result truncated]')
+    expect(text(result)).not.toContain('[status: running]')
+  })
+
+  it('applies a producer limit to a normalized read failure', async () => {
+    const { ctx } = await setup()
+    ctx.tasks.start(producer({
+      outputLimitBytes: 64,
+      readOutput: () => { throw new Error('read failed: '.repeat(100)) },
+    }).spec)
+
+    const result = await call(ctx, 'task_output', { task_id: 'bash-1' })
+    expect(result.isError).toBe(true)
+    expect(Buffer.byteLength(text(result))).toBeLessThanOrEqual(64)
+    expect(text(result)).toContain('[result truncated]')
+  })
+
+  it('bounds pre-, around-, and post-execute policy outcomes and failures', async () => {
+    const { ctx } = await setup()
+    for (let index = 0; index < 5; index += 1) {
+      ctx.tasks.start(producer({ outputLimitBytes: 64 }).spec)
+    }
+    ctx.on('tools/pre-execute', async (exec, next) => {
+      const taskId = (exec.arguments as { task_id?: unknown }).task_id
+      if (taskId === 'bash-1') return { kind: 'deny', reason: 'd'.repeat(1_000) }
+      if (taskId === 'bash-3') throw new Error(`pre failed: ${'p'.repeat(1_000)}`)
+      return next()
+    })
+    ctx.on('tools/execute', async (exec, next) => {
+      const taskId = (exec.arguments as { task_id?: unknown }).task_id
+      if (taskId === 'bash-2') {
+        return {
+          content: [],
+          isError: false,
+          value: {
+            text: 'a'.repeat(1_000),
+            task: {
+              id: 'bash-2', kind: 'bash', label: 'sleep 60', status: 'running', startedAt: 0,
+            },
+          },
+        }
+      }
+      if (taskId === 'bash-4') throw new Error(`around failed: ${'e'.repeat(1_000)}`)
+      return next()
+    })
+    ctx.on('tools/post-execute', async (exec, _result, next) => {
+      const taskId = (exec.arguments as { task_id?: unknown }).task_id
+      if (taskId === 'bash-5') throw new Error(`post failed: ${'o'.repeat(1_000)}`)
+      return next()
+    })
+
+    const denied = await call(ctx, 'task_output', { task_id: 'bash-1' })
+    expect(denied.isError).toBe(true)
+    expect(Buffer.byteLength(text(denied))).toBeLessThanOrEqual(64)
+    expect(text(denied)).toContain('[result truncated]')
+
+    const shortCircuited = await call(ctx, 'task_output', { task_id: 'bash-2' })
+    expect(shortCircuited.isError).toBe(false)
+    expect(Buffer.byteLength(text(shortCircuited))).toBeLessThanOrEqual(64)
+    expect(text(shortCircuited)).toContain('[output truncated]')
+
+    const failures = [
+      await call(ctx, 'task_output', { task_id: 'bash-3' }),
+      await call(ctx, 'task_output', { task_id: 'bash-4' }),
+      await call(ctx, 'task_output', { task_id: 'bash-5' }),
+    ]
+    for (const failure of failures) {
+      expect(failure.isError).toBe(true)
+      expect(Buffer.byteLength(text(failure))).toBeLessThanOrEqual(64)
+      expect(text(failure)).toContain('[result truncated]')
+    }
+  })
+
   it('wait: true blocks until settlement and reports the terminal state', async () => {
     const { ctx } = await setup()
     const p = producer({ kind: 'subagent', label: 'research' })
@@ -173,7 +300,17 @@ describe('task_list', () => {
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
 
-    expect(text(await call(ctx, 'task_list', {}, alice))).toBe([
+    const listed = await call(ctx, 'task_list', {}, alice)
+    if (listed.isError) throw new Error('expected task_list success')
+    const listedValue = listed.value as Array<Record<string, unknown>>
+    expect(listedValue).toHaveLength(3)
+    expect(listedValue[0]).toMatchObject({ id: 'bash-1', kind: 'bash', label: 'pnpm test', status: 'running' })
+    expect(listedValue[2]).toMatchObject({ id: 'bash-2', kind: 'bash', label: 'build', status: 'completed', detail: 'exit code: 0' })
+    for (const task of listedValue) {
+      expect(task).not.toHaveProperty('ownerSession')
+      expect(task).not.toHaveProperty('reported')
+    }
+    expect(text(listed)).toBe([
       'bash-1 [bash] running — pnpm test',
       'subagent-1 [subagent] running — open research',
       'bash-2 [bash] completed — build',
@@ -191,10 +328,85 @@ describe('task_kill', () => {
     ctx.tasks.start(p.spec)
 
     const result = await call(ctx, 'task_kill', { task_id: 'bash-1', reason: 'superseded' })
+    if (result.isError) throw new Error('expected task_kill success')
+    const killValue = result.value as { outcome: string; task: Record<string, unknown> }
+    expect(killValue).toMatchObject({
+      outcome: 'cancellation-requested',
+      task: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'stopping' },
+    })
+    expect(killValue.task).not.toHaveProperty('ownerSession')
+    expect(killValue.task).not.toHaveProperty('reported')
     expect(text(result)).toBe('requested cancellation of task bash-1')
     expect(p.cancels).toEqual(['superseded'])
   })
 
+  it('applies the producer output limit to a cancellation acknowledgement', async () => {
+    const { ctx } = await setup()
+    const p = producer({ outputLimitBytes: 8 })
+    ctx.tasks.start(p.spec)
+
+    const result = await call(ctx, 'task_kill', { task_id: 'bash-1' })
+    expect(Buffer.byteLength(text(result))).toBeLessThanOrEqual(8)
+    expect(p.cancels).toEqual([undefined])
+  })
+
+  it('applies the producer output limit to a normalized cancellation failure', async () => {
+    const { ctx } = await setup()
+    ctx.tasks.start(producer({
+      outputLimitBytes: 64,
+      cancel: () => { throw new Error('cancel failed: '.repeat(100)) },
+    }).spec)
+
+    const result = await call(ctx, 'task_kill', { task_id: 'bash-1' })
+    expect(result.isError).toBe(true)
+    expect(Buffer.byteLength(text(result))).toBeLessThanOrEqual(64)
+    expect(text(result)).toContain('[result truncated]')
+    expect(ctx.tasks.get(TaskId('bash-1'))).toMatchObject({ status: 'running', reported: false })
+  })
+
+  it('bounds single-text post policy while preserving structured policy results', async () => {
+    const { ctx } = await setup()
+    ctx.on('tools/post-execute', (exec, _result, next) => {
+      if (exec.name !== 'task_kill') return next()
+      const reason = (exec.arguments as { reason?: unknown }).reason
+      if (reason === 'replace') {
+        return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: 'r'.repeat(1_000) }] })
+      }
+      if (reason === 'block') {
+        return Promise.resolve({ kind: 'block', feedback: [{ type: 'text', text: 'b'.repeat(1_000) }] })
+      }
+      if (reason === 'multi') {
+        return Promise.resolve({
+          kind: 'block',
+          feedback: [{ type: 'text', text: 'first' }, { type: 'text', text: 'second' }],
+        })
+      }
+      if (reason === 'reasoning') {
+        return Promise.resolve({ kind: 'block', feedback: [{ type: 'reasoning', text: 'policy detail' }] })
+      }
+      return next()
+    })
+    for (let index = 0; index < 4; index += 1) {
+      ctx.tasks.start(producer({ outputLimitBytes: 64 }).spec)
+    }
+
+    const replaced = await call(ctx, 'task_kill', { task_id: 'bash-1', reason: 'replace' })
+    expect(replaced.isError).toBe(false)
+    expect(Buffer.byteLength(text(replaced))).toBeLessThanOrEqual(64)
+    expect(text(replaced)).toContain('[result truncated]')
+
+    const blocked = await call(ctx, 'task_kill', { task_id: 'bash-2', reason: 'block' })
+    expect(blocked.isError).toBe(true)
+    expect(Buffer.byteLength(text(blocked))).toBeLessThanOrEqual(64)
+    expect(text(blocked)).toContain('[result truncated]')
+
+    const multi = await call(ctx, 'task_kill', { task_id: 'bash-3', reason: 'multi' })
+    expect(multi.content).toEqual([{ type: 'text', text: 'first' }, { type: 'text', text: 'second' }])
+
+    const reasoning = await call(ctx, 'task_kill', { task_id: 'bash-4', reason: 'reasoning' })
+    expect(reasoning.content).toEqual([{ type: 'reasoning', text: 'policy detail' }])
+  })
+
   it('reports an already-finished task without consuming its pending delta', async () => {
     const { ctx } = await setup()
     let delta = 'unread tail'
@@ -203,8 +415,13 @@ describe('task_kill', () => {
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
 
-    expect(text(await call(ctx, 'task_kill', { task_id: 'bash-1' })))
-      .toBe('task bash-1 had already finished [status: completed, exit code: 0]')
+    const killed = await call(ctx, 'task_kill', { task_id: 'bash-1' })
+    if (killed.isError) throw new Error('expected task_kill success')
+    expect(killed.value).toMatchObject({
+      outcome: 'already-finished',
+      task: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'completed', detail: 'exit code: 0' },
+    })
+    expect(text(killed)).toBe('task bash-1 had already finished [status: completed, exit code: 0]')
     // The kill described the task via a non-consuming snapshot: the delta is intact.
     expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' }))).toBe('unread tail\n[status: completed, exit code: 0]')
   })
@@ -244,6 +461,90 @@ describe('completion notices', () => {
     )
   })
 
+  it('preserves task ids and collection guidance in bounded completion notices', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = fakeAgent(ctx, 'sess-1', inject)
+    const first = producer({
+      owner,
+      kind: 'subagent',
+      label: 'x'.repeat(1_000),
+      outputLimitBytes: 64,
+    })
+    ctx.tasks.start(first.spec)
+    first.settle({ status: 'completed', detail: 'd'.repeat(1_000) })
+    await tick()
+
+    expect(inject).toHaveBeenNthCalledWith(
+      1,
+      [{ type: 'text', text: 'background task subagent-1\n[notice truncated]\nDone; task_output.' }],
+      { source: { kind: 'plugin', plugin: 'tool-tasks' } },
+    )
+
+    const second = producer({
+      owner,
+      kind: 'subagent',
+      label: 'x'.repeat(1_000),
+      outputLimitBytes: 80,
+    })
+    ctx.tasks.start(second.spec)
+    second.settle({ status: 'completed', detail: 'd'.repeat(1_000) })
+    await tick()
+
+    const content = inject.mock.calls[1]?.[0] as Array<{ type: string; text?: string }> | undefined
+    const notice = content?.[0]?.text ?? ''
+    expect(Buffer.byteLength(notice)).toBeLessThanOrEqual(80)
+    expect(notice).toContain('background task subagent-2 (subagent: xxxx')
+    expect(notice).toContain('[notice truncated]\nDone; task_output.')
+  })
+
+  it('keeps the complete PTY task id and collection action at the minimum PTY limit', async () => {
+    const { ctx } = await setup()
+    for (let index = 0; index < 99; index += 1) {
+      const prior = producer({ kind: 'pty-send' })
+      ctx.tasks.start(prior.spec)
+      prior.settle({ status: 'completed' })
+    }
+    const inject = vi.fn()
+    const owner = fakeAgent(ctx, 'sess-1', inject)
+    const target = producer({
+      owner,
+      kind: 'pty-send',
+      label: 'x'.repeat(1_000),
+      outputLimitBytes: 64,
+    })
+    ctx.tasks.start(target.spec)
+
+    target.settle({ status: 'completed', detail: 'd'.repeat(1_000) })
+    await tick()
+
+    const content = inject.mock.calls[0]?.[0] as Array<{ type: string; text?: string }> | undefined
+    const notice = content?.[0]?.text ?? ''
+    expect(Buffer.byteLength(notice)).toBeLessThanOrEqual(64)
+    expect(notice).toBe('background task pty-send-100\nDone; task_output.')
+  })
+
+  it('reserves the collection-action tail when a producer supplies a smaller budget', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = fakeAgent(ctx, 'sess-1', inject)
+    const tiny = producer({ owner, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 8 })
+    const short = producer({ owner, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 32 })
+    ctx.tasks.start(tiny.spec)
+    ctx.tasks.start(short.spec)
+
+    tiny.settle({ status: 'completed' })
+    short.settle({ status: 'completed' })
+    await tick()
+
+    const tinyNotice = (inject.mock.calls[0]?.[0] as Array<{ text?: string }> | undefined)?.[0]?.text ?? ''
+    const shortNotice = (inject.mock.calls[1]?.[0] as Array<{ text?: string }> | undefined)?.[0]?.text ?? ''
+    expect(Buffer.byteLength(tinyNotice)).toBeLessThanOrEqual(8)
+    expect(tinyNotice).toBe('_output.')
+    expect(Buffer.byteLength(shortNotice)).toBeLessThanOrEqual(32)
+    expect(shortNotice).toBe('background ta\nDone; task_output.')
+  })
+
   it('suppresses the notice for a task the model already killed', async () => {
     const { ctx } = await setup()
     const inject = vi.fn()
diff --git a/packages/tasks/tool-tasks/tsconfig.json b/packages/tasks/tool-tasks/tsconfig.json
index feab4f3be8..cff642796c 100644
--- a/packages/tasks/tool-tasks/tsconfig.json
+++ b/packages/tasks/tool-tasks/tsconfig.json
@@ -17,6 +17,9 @@
     {
       "path": "../../../vendor/schemastery"
     },
+    {
+      "path": "../../util/retention"
+    },
     {
       "path": "../../core/agent"
     },
diff --git a/packages/timeout/timeout-policy/README.md b/packages/timeout/timeout-policy/README.md
index 60b590a7f8..aea741d1fe 100644
--- a/packages/timeout/timeout-policy/README.md
+++ b/packages/timeout/timeout-policy/README.md
@@ -19,7 +19,7 @@ For a tool that **declares a `timeoutMs`** the listener:
 
 1. Reads the budget from the tool's own declaration in the registry (`ctx.tools.get(exec.name)?.timeoutMs`) and arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')` — one signal fusing the caller's abort with this plugin's timer (`@deepseek-ai/dsh-timeout`).
 2. Swaps that derived signal onto `exec` for the downstream dispatch, then restores the caller's own signal afterward (cordis `next()` ignores passed arguments, so the wrapper mutates the shared `exec` in place; restoring keeps `tools/post-execute` seeing the caller's signal).
-3. After dispatch, if `timeoutOf(d.signal, 'TOOL_TIMEOUT')` matches — this plugin's own timer fired — replaces the result with a structured `TOOL_TIMEOUT` tool result: `{ isError: true, error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }, content: 'Error: tool call timed out after <ms>ms' }`.
+3. After dispatch, if `timeoutOf(d.signal, 'TOOL_TIMEOUT')` matches — this plugin's own timer fired — replaces the result with a structured `TOOL_TIMEOUT` tool result: `{ isError: true, error: { message, info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' } }, content: 'Error: tool call timed out after <ms>ms' }`.
 
 A tool that **declares no budget** delegates untouched (no deadline).
 
diff --git a/packages/timeout/timeout-policy/src/index.ts b/packages/timeout/timeout-policy/src/index.ts
index e9fe3a46af..61470ea6af 100644
--- a/packages/timeout/timeout-policy/src/index.ts
+++ b/packages/timeout/timeout-policy/src/index.ts
@@ -33,10 +33,11 @@ export const inject = ['tools']
  * @returns the `isError` {@link ToolExecutionResult} with a `TOOL_TIMEOUT` error.
  */
 function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
+  const message = `tool call timed out after ${timeoutMs}ms`
   return {
-    content: [{ type: 'text', text: `Error: tool call timed out after ${timeoutMs}ms` }],
+    content: [{ type: 'text', text: `Error: ${message}` }],
     isError: true,
-    error: { name: 'ToolTimeoutError', code: TOOL_TIMEOUT },
+    error: { message, info: { name: 'ToolTimeoutError', code: TOOL_TIMEOUT } },
   }
 }
 
diff --git a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts
index 77974cd4a0..c2d55d044c 100644
--- a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts
+++ b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts
@@ -11,7 +11,7 @@ import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool, TOOL_ABORTED, type ToolExecutionInput, type PostToolDecision } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture, TOOL_ABORTED, type ToolExecutionInput, type PostToolDecision } from '@deepseek-ai/dsh-tools'
 import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
 import { TOOL_TIMEOUT } from '@deepseek-ai/dsh-timeout-policy'
 
@@ -27,7 +27,7 @@ async function setup() {
 }
 
 /** A cooperative tool that settles ONLY when its exec.signal aborts (returns text). */
-const cooperativeTool = defineTool({
+const cooperativeTool = defineContentToolFixture({
   name: 'slow', description: 'stops when aborted', parameters: {}, timeoutMs: 100,
   execute(_args, exec): Promise<{ type: 'text'; text: string }[]> {
     const done = [{ type: 'text' as const, text: 'stopped cooperatively' }]
@@ -37,7 +37,7 @@ const cooperativeTool = defineTool({
 })
 
 /** A cooperative tool that THROWS its own upstream-abort error when aborted (web-provider shape). */
-const abortThrowingTool = defineTool({
+const abortThrowingTool = defineContentToolFixture({
   name: 'aborter', description: 'throws WEB_ABORTED when aborted', parameters: {}, timeoutMs: 100,
   execute(_args, exec): Promise<never> {
     if (exec.signal.aborted) return Promise.reject(new HarnessError('web fetch aborted', 'WEB_ABORTED'))
@@ -49,7 +49,7 @@ describe('timeout-policy delegation (unconfigured / fast)', () => {
   it('delegates a tool with NO declared budget unchanged and does not touch exec.signal', async () => {
     const ctx = await setup()
     let seenSignal: AbortSignal | undefined
-    ctx.tools.register(defineTool({ name: 'probe', description: 'd', parameters: {},
+    ctx.tools.register(defineContentToolFixture({ name: 'probe', description: 'd', parameters: {},
       async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }))
     const upstream = new AbortController().signal
     const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream })
@@ -59,16 +59,20 @@ describe('timeout-policy delegation (unconfigured / fast)', () => {
 
   it('a tool with a budget that returns fast keeps its own result (no timeout)', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 10_000,
+    ctx.tools.register(defineContentToolFixture({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 10_000,
       async execute() { return [{ type: 'text' as const, text: 'ok' }] } }))
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'fast', arguments: {} })
-    expect(result).toEqual({ content: [{ type: 'text', text: 'ok' }], isError: false })
+    expect(result).toEqual({
+      content: [{ type: 'text', text: 'ok' }],
+      isError: false,
+      value: [{ type: 'text', text: 'ok' }],
+    })
   })
 
   it('a budgeted tool receives the DERIVED deadline signal (not the caller signal) during dispatch', async () => {
     const ctx = await setup()
     let seenSignal: AbortSignal | undefined
-    ctx.tools.register(defineTool({ name: 'probe', description: 'd', parameters: {}, timeoutMs: 10_000,
+    ctx.tools.register(defineContentToolFixture({ name: 'probe', description: 'd', parameters: {}, timeoutMs: 10_000,
       async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }))
     const upstream = new AbortController().signal
     await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream })
@@ -80,7 +84,7 @@ describe('timeout-policy delegation (unconfigured / fast)', () => {
 describe('timeout-policy signal restoration', () => {
   it('restores the caller signal for post-execute after wrapping', async () => {
     const ctx = await setup()
-    ctx.tools.register(defineTool({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 10_000,
+    ctx.tools.register(defineContentToolFixture({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 10_000,
       async execute() { return [{ type: 'text' as const, text: 'ok' }] } }))
     let postSignal: AbortSignal | undefined | 'unset' = 'unset'
     ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => { postSignal = exec.signal; return next() })
@@ -103,7 +107,10 @@ describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => {
     expect(result).toEqual({
       content: [{ type: 'text', text: 'Error: tool call timed out after 100ms' }],
       isError: true,
-      error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+      error: {
+        message: 'tool call timed out after 100ms',
+        info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+      },
     })
   })
 
@@ -114,14 +121,17 @@ describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => {
     await vi.advanceTimersByTimeAsync(150)
     const result = await pending
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' })
+    expect(result.error).toEqual({
+      message: 'tool call timed out after 100ms',
+      info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+    })
     expect(result.content[0]).toMatchObject({ text: 'Error: tool call timed out after 100ms' })
   })
 
   it('preserves registry ABORTED when the caller aborts first (upstream cancel, not our timeout)', async () => {
     const ctx = await setup()
     const entered = Promise.withResolvers<undefined>()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'slow', description: 'stops when aborted', parameters: {}, timeoutMs: 100,
       execute(_args, exec) {
         entered.resolve(undefined)
@@ -139,7 +149,10 @@ describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => {
     await vi.advanceTimersByTimeAsync(0)
     const result = await pending
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'AbortError', code: TOOL_ABORTED })
+    expect(result.error).toEqual({
+      message: 'tool call aborted',
+      info: { name: 'AbortError', code: TOOL_ABORTED },
+    })
     expect(result.content[0]).toMatchObject({ text: 'Error: tool call aborted' })
   })
 
@@ -147,7 +160,7 @@ describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => {
     const ctx = await setup()
     const sawAbort = Promise.withResolvers<undefined>()
     const releaseCleanup = Promise.withResolvers<undefined>()
-    ctx.tools.register(defineTool({
+    ctx.tools.register(defineContentToolFixture({
       name: 'slow-cleanup', description: 'settles after abort cleanup', parameters: {}, timeoutMs: 100,
       async execute(_args, exec) {
         if (!exec.signal.aborted) {
@@ -172,7 +185,10 @@ describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => {
 
     await expect(pending).resolves.toMatchObject({
       isError: true,
-      error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+      error: {
+        message: 'tool call timed out after 100ms',
+        info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+      },
     })
   })
 })
@@ -189,7 +205,7 @@ describe('timeout-policy disposal (HMR safety)', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     let seenSignal: AbortSignal | undefined
-    ctx.tools.register(defineTool({ name: 'probe', description: 'd', parameters: {}, timeoutMs: 10_000,
+    ctx.tools.register(defineContentToolFixture({ name: 'probe', description: 'd', parameters: {}, timeoutMs: 10_000,
       async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }))
     const fiber = await ctx.plugin(timeoutPolicy)
     const upstream = new AbortController().signal
@@ -216,7 +232,7 @@ describe('dsh-timeout-policy real-load-path guard', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
-    ctx.tools.register(defineTool({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 5_000,
+    ctx.tools.register(defineContentToolFixture({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 5_000,
       async execute() { return [{ type: 'text' as const, text: 'ok' }] } }))
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(timeoutPolicy) as Parameters<Context['plugin']>[0]
diff --git a/packages/todo/tool-todo/README.md b/packages/todo/tool-todo/README.md
index 2ccdd7699e..febb2c9ce0 100644
--- a/packages/todo/tool-todo/README.md
+++ b/packages/todo/tool-todo/README.md
@@ -18,7 +18,7 @@ Beyond the schema's type/required/enum checks, `execute` rejects an empty or dup
 
 ## Rendering
 
-The tool writes only the session event; it does not render. UIs subscribe to `session/event` and render the `todo/write` data themselves: the [TUI app](../../examples/tui-demo) shows a persistent plan, and the [ACP bridge](../../ui/acp) maps the list to a `plan` sessionUpdate (synthesizing the `priority` ACP requires).
+The canonical result is `{ todos, counts: { pending, inProgress, completed } }`; its Native renderer returns the compact update acknowledgement. The tool also writes the full `todo/write` session event. UIs subscribe to `session/event` and render that durable list themselves: the [TUI app](../../examples/tui-demo) shows a persistent plan, and the [ACP bridge](../../ui/acp) maps the list to a `plan` sessionUpdate (synthesizing the `priority` ACP requires).
 
 ## Export shape
 
diff --git a/packages/todo/tool-todo/src/index.ts b/packages/todo/tool-todo/src/index.ts
index 039d2085f7..1da9914ac9 100644
--- a/packages/todo/tool-todo/src/index.ts
+++ b/packages/todo/tool-todo/src/index.ts
@@ -6,7 +6,6 @@
  */
 
 import type { Context } from 'cordis'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { TodoItem } from '@deepseek-ai/dsh-session'
 
@@ -28,7 +27,7 @@ const DESCRIPTION =
   + '(not started), `in_progress` (being worked on now), `completed` (finished).'
 
 /**
- * Validate the value constraints the SchemaSpec can't express and build the canonical {@link
+ * Validate the value constraints the ParameterSchemaSpec can't express and build the canonical {@link
  * TodoItem}[]: trimmed non-empty unique content and at most one in-progress item. The registry
  * has already enforced the status enum; the cast below records that guarantee.
  */
@@ -67,6 +66,7 @@ export function apply(ctx: Context): void {
         description: 'The COMPLETE task list, replacing any previous list.',
         items: {
           type: 'object',
+          additionalProperties: true,
           properties: {
             content: { type: 'string', required: true, description: 'What the task is — a short imperative line.' },
             status: {
@@ -79,7 +79,41 @@ export function apply(ctx: Context): void {
         },
       },
     },
-    execute(args, exec): Promise<ContentBlock[]> {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          todos: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                content: { type: 'string', required: true },
+                status: { type: 'string', required: true, enum: [...STATUSES] },
+              },
+            },
+          },
+          counts: {
+            type: 'object',
+            additionalProperties: false,
+            required: true,
+            properties: {
+              pending: { type: 'integer', required: true },
+              inProgress: { type: 'integer', required: true },
+              completed: { type: 'integer', required: true },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `Updated todo list: ${value.counts.pending} pending, ${value.counts.inProgress} in progress, ${value.counts.completed} completed.`,
+      }],
+    },
+    execute(args, exec) {
       const todos = toTodoList(args.todos)
       if (!exec.agent) {
         // The list is per-agent-session state; a non-agent caller (no owning
@@ -88,10 +122,14 @@ export function apply(ctx: Context): void {
       }
       exec.agent.session.append('todo/write', { todos })
       const count = (status: TodoItem['status']): number => todos.filter(t => t.status === status).length
-      return Promise.resolve([{
-        type: 'text',
-        text: `Updated todo list: ${count('pending')} pending, ${count('in_progress')} in progress, ${count('completed')} completed.`,
-      }])
+      return Promise.resolve({
+        todos: todos.map(todo => ({ content: todo.content, status: todo.status })),
+        counts: {
+          pending: count('pending'),
+          inProgress: count('in_progress'),
+          completed: count('completed'),
+        },
+      })
     },
     presentCall: args => ({ card: 'generic', title: 'Update todo list', kind: 'other', rawInput: args.todos }),
   }))
diff --git a/packages/todo/tool-todo/tests/integration.spec.ts b/packages/todo/tool-todo/tests/integration.spec.ts
index 869c1183f2..fe09af9730 100644
--- a/packages/todo/tool-todo/tests/integration.spec.ts
+++ b/packages/todo/tool-todo/tests/integration.spec.ts
@@ -59,7 +59,7 @@ describe('todo_write tool through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-todo'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'plan a two-step task' }])
+    agent.followup([{ type: 'text', text: 'plan a two-step task' }])
     await waitForIdle(ctx, agent)
 
     const log = agent.session.events
@@ -87,7 +87,7 @@ describe('todo_write tool through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-todo-2'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'plan then update' }])
+    agent.followup([{ type: 'text', text: 'plan then update' }])
     await waitForIdle(ctx, agent)
 
     const todoEvents = agent.session.events.filter(e => e.type === 'todo/write')
diff --git a/packages/todo/tool-todo/tests/tool-todo.spec.ts b/packages/todo/tool-todo/tests/tool-todo.spec.ts
index 47cfc27390..79758cb3ea 100644
--- a/packages/todo/tool-todo/tests/tool-todo.spec.ts
+++ b/packages/todo/tool-todo/tests/tool-todo.spec.ts
@@ -73,6 +73,11 @@ describe('dsh-tool-todo', () => {
     ]
     const result = await callTodo(ctx, { todos }, { agent })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected todo_write success')
+    expect(result.value).toEqual({
+      todos,
+      counts: { pending: 1, inProgress: 1, completed: 0 },
+    })
     expect(text(result)).toContain('1 pending, 1 in progress, 0 completed')
 
     const event = agent.session.events.findLast(e => e.type === 'todo/write')!
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 9c7a1f554c..f8e4704f20 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -10,11 +10,11 @@ Integrations that expose the agent to an external editor or client. These are **
 | `permission/` | User-facing permission presets (`workspace-write`/`danger-full-access`): one product-level select bundling the sandbox-mode and approval-policy knobs, written through to their session events | `ctx.permission` |
 | `user-interaction/` | Abstract human question/answer seam used by UI-backed confirmation tools | `ctx.userInteraction` |
 | `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) |
-| `tui/` | Interactive pi-tui terminal channel; renders session titles/events and tool intents, and answers `ctx.userInteraction` | (drives `ctx.agents`) |
+| `tui/` | Interactive pi-tui terminal channel; renders session titles/events and tool intents, answers `ctx.userInteraction`, and hosts effect-owned plugin overlays | `ctx.tui` (drives `ctx.agents`) |
 | `jsonrpc/` | Stdio JSON-RPC server for out-of-process SDK clients | (drives `ctx.agents`) |
 | `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |
 
-A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The `jsonrpc` plugin is the SDK-client sibling of the `acp` bridge (a JSON-RPC server over `ctx.agents` for out-of-process SDK clients rather than editors). [`tui`](tui/README.md) is the interactive terminal front door; non-interactive tasks use the headless `cli-demo` app instead of a UI channel. [`commands`](commands/README.md) is the human-only discovery and dispatch plane shared by TUI and ACP; command input and output do not become model messages.
+A UI integration is a client-driver plugin, not a loop change: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The `jsonrpc` plugin is the SDK-client sibling of the `acp` bridge (a JSON-RPC server over `ctx.agents` for out-of-process SDK clients rather than editors). [`tui`](tui/README.md) is the interactive terminal front door and supplies the terminal-local `ctx.tui` extension service; non-interactive tasks use the headless `cli-demo` app instead of a UI channel. [`commands`](commands/README.md) is the human-only discovery and dispatch plane shared by TUI and ACP; command input and output do not become model messages.
 
 `user-approval`, `user-interaction`, and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. `user-approval` owns the one-shot `ctx.approval` decision mechanism and its policy tier; answerers remain with their UI channel owners. `user-interaction` remains provider-neutral (`ctx.userInteraction`), while `tool-ask-user` is its model-facing consumer and the app/bridge packages provide concrete providers.
 
diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md
index 3a8576df74..f135e42553 100644
--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -29,7 +29,7 @@ The `initialize` handshake reports a fixed server identity (`agentInfo: { name:
 | `session/new` | `ctx.agents.create({ sessionId, meta:{cwd} })` | creates a new session/agent; N concurrent sessions are allowed, keyed by id; advertises the effective command snapshot; `cwd` must be absolute (it becomes the session's workspace — see Per-session cwd); non-empty `additionalDirectories` and `mcpServers` rejected |
 | `session/load` | `ctx.agents.resume(...)` | reserves the id, verifies the persisted cwd, resumes, replays user, assistant, tool, and title events, and re-advertises commands |
 | `session/list` | `ctx.sessionQuery` | returns live-preferred newest-first sessions with absolute cwd and optional folded title; supports exact normalized cwd filtering, returns no cursor, and rejects supplied cursors |
-| `session/prompt` | `ctx.commands.execute()` or `agent.send()` | a flattened prompt beginning with `/` stays in the direct command plane; ordinary prompts support ACP `text` and `resource_link`; `dsh-session:` links and inline mentions are snapshotted through optional `ctx.sessionReferences` before enqueue; unsupported content, unavailable reference capability, failed snapshots, and empty prompts are rejected; one request is in flight per session and settles on the owning turn's end, with an error turn rejecting the RPC |
+| `session/prompt` | `ctx.commands.execute()` or `agent.followup()` | a flattened prompt beginning with `/` stays in the direct command plane; ordinary prompts support ACP `text` and `resource_link`; `dsh-session:` links and inline mentions are snapshotted through optional `ctx.sessionReferences` before enqueue; unsupported content, unavailable reference capability, failed snapshots, and empty prompts are rejected; one request is in flight per session and settles on the owning turn's end, with an error turn rejecting the RPC |
 | `session/cancel` | command `AbortSignal` or `agent.cancel()` | aborts the exact direct command, or applies the queue-aware agent cancel and settles its prompt `cancelled`; one session never cancels another |
 | `session/update` | `session/event` | streams user replay, assistant text/reasoning, retry/failure attempt markers, tool render intents, and `session_info_update` title revisions |
 | `elicitation/create` | `ctx.userInteraction.ask()` | maps `ask_user_question` questions to ACP form elicitations; option descriptions are shown in enum titles, `multi_select` uses ACP array enums, optionless requests use a required `custom` field, and a non-empty custom answer overrides any selected choice |
diff --git a/packages/ui/acp/acp-feature-support.md b/packages/ui/acp/acp-feature-support.md
index 55d44613c5..3292ee17c4 100644
--- a/packages/ui/acp/acp-feature-support.md
+++ b/packages/ui/acp/acp-feature-support.md
@@ -23,7 +23,7 @@ The bridge implements the **core prompt-turn loop** for N concurrent sessions: i
 | `session/load` | S | ✅ | ✅ | ✅ | Maps to `agents.resume` + full event-log replay; validates persisted `cwd` before constructing the agent. |
 | `session/resume` | S | ❌ | ✅ | ✅ | Reconnect WITHOUT replay; gated by `sessionCapabilities.resume`. Not advertised. |
 | `session/close` | S | ❌ | ✅ | ✅ | No `session/close` handler — the SDK dispatch returns `method_not_found`. The bridge tears sessions down on client disconnect / Cordis disposal (cross-cutting, see [§8](#8-cross-cutting)), but that is not the on-demand per-session method. |
-| `session/prompt` | S | ✅ | ✅ | ✅ | A flattened prompt beginning with `/` dispatches through `ctx.commands` without a model request; ordinary input maps to `agent.send`. One request is in flight per session. |
+| `session/prompt` | S | ✅ | ✅ | ✅ | A flattened prompt beginning with `/` dispatches through `ctx.commands` without a model request; ordinary input maps to `agent.followup`. One request is in flight per session. |
 | `session/cancel` | S | ✅ | ✅ | ✅ | Aborts the exact direct command, or applies queue-aware `agent.cancel` and settles its prompt `cancelled`, scoped to one session. |
 | `session/set_mode` | S | ✅ | ✅ | ✅ | Composed opportunistically: with `@deepseek-ai/dsh-plan-mode` mounted, `session/new`/`session/load` advertise the fixed `default` / `plan` projection and `session/set_mode` records the boolean pending intent (optimistic `current_mode_update`; logged `plan/mode` lands at the turn boundary). Without the plugin: no `modes` advertised, `set_mode` rejected (see [§6 Modes](#6-session-modes--config-options--models)). |
 | `session/set_config_option` | S | ✅ | ✅ | ✅ | A provider/model select is present for a complete registered target; one `permission` select is added when `ctx.permission` is composed. Every response carries the complete refreshed state. |
diff --git a/packages/ui/acp/src/index.ts b/packages/ui/acp/src/index.ts
index 7e0b15ff9c..dcc32f1c6f 100644
--- a/packages/ui/acp/src/index.ts
+++ b/packages/ui/acp/src/index.ts
@@ -60,7 +60,7 @@ import {
 } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-commands'
 import { encodeSessionReferenceUri } from '@deepseek-ai/dsh-session-reference'
-import { displayPromptContent, SessionId } from '@deepseek-ai/dsh-session'
+import { displayPromptContent, SessionId, type JsonValue } from '@deepseek-ai/dsh-session'
 // Side-effect type import: resolves `ctx.get('permission')` to the service.
 import type {} from '@deepseek-ai/dsh-permission'
 import type { SessionEvent, TodoItem, TurnEndReason } from '@deepseek-ai/dsh-session'
@@ -1056,7 +1056,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
         }
         const { text } = referencedPrompt
         let preparedContent: ContentBlock[] = [{ type: 'text', text }]
-        let preparedContexts: NonNullable<Parameters<Agent['send']>[1]>['contexts'] = []
+        let preparedContexts: NonNullable<Parameters<Agent['followup']>[1]>['contexts'] = []
         if (referencedPrompt.references.length > 0) {
           const sessionReferences = ctx.get('sessionReferences')
           if (sessionReferences === undefined) {
@@ -1081,14 +1081,14 @@ export function apply(ctx: Context, config: AcpConfig): void {
           }
           assertOpen()
         }
-        // Install the in-flight slot BEFORE send() (send does not synchronously
+        // Install the in-flight slot BEFORE followup() (followup does not synchronously
         // flip status to running; the session/event listener records the turn
         // number and settle/rejects it). Capture the log length now as the
         // A turn that ends in error rejects this promise (the codec never
         // produces an error stop reason).
         const stopReason = await new Promise<StopReason>((resolve, reject) => {
           rec.inflight = { resolve, reject, turn: undefined }
-          rec.agent.send(preparedContent, { contexts: preparedContexts })
+          rec.agent.followup(preparedContent, { contexts: preparedContexts })
         })
         return { stopReason }
       },
@@ -1333,8 +1333,8 @@ function validateMcpServers(params: { mcpServers?: unknown[] }): void {
  * generic fallback (title = tool name, raw args as input) when no registry is
  * available (e.g. pure translator tests).
  *
- * Other event types (turn/step boundaries, context/message, …) produce
- * no client update.
+ * Other event types (turn/step boundaries, injected-context user messages, …)
+ * produce no client update.
  * @param sessionId - the ACP session id stamped on every emitted notification.
  * @param event - the harness session event to translate.
  * @param notify - sink for each produced `session/update` notification; called
@@ -1374,6 +1374,9 @@ export function streamSessionEventUpdate(
     }
     case 'user/message': {
       if (!includeUserMessages) return
+      // Only a direct human prompt replays as a user message; injected context
+      // (plugin/goal source) is not the user's turn and produces no update.
+      if (event.data.source.kind !== 'user') return
       // Replay the user's prompt so a loaded session shows both sides of each
       // turn. Live prompt turns suppress this path to avoid duplicating what
       // the client just sent.
@@ -1420,7 +1423,7 @@ export function streamSessionEventUpdate(
       notify({ sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } } })
       return
     }
-    // non-error turn/step boundaries, context/message, steering,
+    // non-error turn/step boundaries, injected-context user messages, steering,
     // assistant/message — no direct ACP client update.
     default:
       return
@@ -1499,7 +1502,7 @@ export class ToolPresenter {
    * @param meta - the result's machine-readable meta, forwarded when present.
    * @returns a normalized tool-owned view or raw-content fallback.
    */
-  result(callId: CallId, content: ContentBlock[], isError: boolean, meta?: unknown): ToolResultView {
+  result(callId: CallId, content: ContentBlock[], isError: boolean, meta?: JsonValue): ToolResultView {
     const call = this.pending.get(callId)
     this.pending.delete(callId)
     // No remembered call (unknown/late callId) → nothing to present from; raw content.
diff --git a/packages/ui/acp/tests/bridge.spec.ts b/packages/ui/acp/tests/bridge.spec.ts
index 1e15910ce7..6e24acce24 100644
--- a/packages/ui/acp/tests/bridge.spec.ts
+++ b/packages/ui/acp/tests/bridge.spec.ts
@@ -383,7 +383,7 @@ describe('acp bridge', () => {
         },
       }],
     })
-    expect(target.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(target.events.some(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toBe(false)
     const request = JSON.stringify(harness.adapter.requests[0]?.messages)
     expect(request).toContain('untrusted, read-only snapshot')
     expect(request).toContain('source background')
diff --git a/packages/ui/acp/tests/dispose.spec.ts b/packages/ui/acp/tests/dispose.spec.ts
index 8baf076d58..bcfb177b16 100644
--- a/packages/ui/acp/tests/dispose.spec.ts
+++ b/packages/ui/acp/tests/dispose.spec.ts
@@ -264,7 +264,7 @@ describe('acp bridge — disposal & HMR safety', () => {
     const handle = await harness.ctx.agents.create({
       sessionId: SessionId('guard-a'), agentOptions: { provider: 'mock', model: 'mock' },
     })
-    handle.agent.send([{ type: 'text', text: 'go' }])
+    handle.agent.followup([{ type: 'text', text: 'go' }])
     await handle.agent.whenIdle()
     expect(harness.ctx.sessions.get(SessionId('guard-a'))).toBeDefined()
 
@@ -288,7 +288,7 @@ describe('acp bridge — disposal & HMR safety', () => {
     // Drive a turn that hangs in the model stream, so the loop is mid-turn when
     // disposed — its exit runs a final session/flush we can gate to hold the
     // teardown observably in-flight.
-    handle.agent.send([{ type: 'text', text: 'go' }])
+    handle.agent.followup([{ type: 'text', text: 'go' }])
     await new Promise(r => setTimeout(r, 30))
     expect(handle.agent.status).toBe('running')
     let releaseFlush!: () => void
diff --git a/packages/ui/acp/tests/edges.spec.ts b/packages/ui/acp/tests/edges.spec.ts
index fdbaf241e6..ac85fbd7e0 100644
--- a/packages/ui/acp/tests/edges.spec.ts
+++ b/packages/ui/acp/tests/edges.spec.ts
@@ -30,7 +30,7 @@ describe('acp bridge — demux & config edges', () => {
     const before = harness.updates.length
 
     const { agent: foreign } = await harness.ctx.agents.create({ sessionId: SessionId('foreign-session'), agentOptions: { provider: 'mock', model: 'mock' } })
-    foreign.send([{ type: 'text', text: 'hi' }])
+    foreign.followup([{ type: 'text', text: 'hi' }])
     await foreign.whenIdle()
     await new Promise(r => setTimeout(r, 10))
 
diff --git a/packages/ui/acp/tests/harness.ts b/packages/ui/acp/tests/harness.ts
index 40e1f45b34..fa7700c5f3 100644
--- a/packages/ui/acp/tests/harness.ts
+++ b/packages/ui/acp/tests/harness.ts
@@ -37,6 +37,20 @@ import * as ToolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as AcpPlugin from '../src/index.ts'
 import { type AcpConfig } from '../src/index.ts'
 
+class TestSessionQueryService extends SessionQueryService {
+  override searchSessions(
+    ..._args: Parameters<SessionQueryService['searchSessions']>
+  ): ReturnType<SessionQueryService['searchSessions']> {
+    return Promise.resolve({ items: [] })
+  }
+
+  override searchEvents(
+    ..._args: Parameters<SessionQueryService['searchEvents']>
+  ): ReturnType<SessionQueryService['searchEvents']> {
+    return Promise.resolve({ items: [] })
+  }
+}
+
 /** A scripted mock adapter (mirrors the agent-loop test adapter). */
 class MockAdapter extends LlmAdapter {
   requests: GenerateOptions[] = []
@@ -221,7 +235,7 @@ export async function makeBridgeHarness(options: {
   await ctx.plugin(CommandService)
   await ctx.plugin(AgentLoop, { agents: [] })
   await ctx.plugin(SessionPersistenceJsonl, { root: options.storageDir })
-  await ctx.plugin(SessionQueryService)
+  await ctx.plugin(TestSessionQueryService)
   if (options.withSessionReferences) {
     await ctx.plugin(SessionReferenceService)
   }
diff --git a/packages/ui/acp/tests/stream-update.spec.ts b/packages/ui/acp/tests/stream-update.spec.ts
index 89cf69f4f2..2585968b7e 100644
--- a/packages/ui/acp/tests/stream-update.spec.ts
+++ b/packages/ui/acp/tests/stream-update.spec.ts
@@ -12,6 +12,11 @@ import FsLocal from '@deepseek-ai/dsh-fs-local'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import { streamSessionEventUpdate, agentOptions, todosToPlan, ToolPresenter } from '../src/index.ts'
 
+const UNUSED_TOOL_OUTPUT: ToolDefinition['output'] = {
+  schema: { type: 'null' },
+  render: () => [],
+}
+
 /** Collect the updates a single event produces (no presenter → generic fallback). */
 function updatesFor(event: SessionEvent): SessionNotification['update'][] {
   const out: SessionNotification['update'][] = []
@@ -279,6 +284,7 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
     name: 'bash',
     description: 'run a command',
     parameters: {},
+    output: UNUSED_TOOL_OUTPUT,
     execute: async () => [],
     presentCall: (args: unknown) => {
       const a = args as { command: string; description: string }
@@ -336,7 +342,7 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
   })
 
   it('a tool with no presentCall/presentResult gets the generic fallback (title = name)', () => {
-    const plain: ToolDefinition = { name: 'plain', description: 'p', parameters: {}, execute: async () => [] }
+    const plain: ToolDefinition = { name: 'plain', description: 'p', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [] }
     const presenter = new ToolPresenter(registryOf(plain))
     const [update] = updatesWith(presenter, evt('tool/call', {
       turn: 1, step: 1, callId: CallId('c1'), name: 'plain', arguments: '{"a":1}',
@@ -352,6 +358,7 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
       name: 'mini',
       description: 'm',
       parameters: {},
+      output: UNUSED_TOOL_OUTPUT,
       execute: async () => [],
       presentCall: () => ({ card: 'generic', title: 'Doing a thing' }),
       presentResult: () => ({ card: 'generic', title: 'Did the thing' }),
@@ -398,6 +405,7 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
       name: 'boom',
       description: 'b',
       parameters: {},
+      output: UNUSED_TOOL_OUTPUT,
       execute: async () => [],
       presentCall: () => { throw new Error('call boom') },
       presentResult: () => { throw new Error('result boom') },
@@ -427,6 +435,7 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
       name: 'boom',
       description: 'b',
       parameters: {},
+      output: UNUSED_TOOL_OUTPUT,
       execute: async () => [],
       presentCall: () => { throw new Error('call boom') },
       presentResult: () => { throw new Error('result boom') },
@@ -450,6 +459,7 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
       name: 'rogue',
       description: 'r',
       parameters: {},
+      output: UNUSED_TOOL_OUTPUT,
       execute: async () => [],
       // A card value outside the union — forced with a cast (no valid input reaches this).
       presentCall: () => ({ card: 'chart', title: 'nope' }) as unknown as ReturnType<NonNullable<ToolDefinition['presentCall']>>,
@@ -468,6 +478,7 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
       name: 'rogue',
       description: 'r',
       parameters: {},
+      output: UNUSED_TOOL_OUTPUT,
       execute: async () => [],
       presentCall: () => ({ card: 'generic', title: 'r' }),
       presentResult: () => ({ card: 'chart' }) as unknown as ReturnType<NonNullable<ToolDefinition['presentResult']>>,
@@ -530,6 +541,7 @@ describe('terminal-card mapping (capability-gated)', () => {
     name: 'bash',
     description: 'run a command',
     parameters: {},
+    output: UNUSED_TOOL_OUTPUT,
     execute: async () => [],
     presentCall: (args: unknown) => {
       const command = (args as { command: string }).command
@@ -691,6 +703,7 @@ describe('terminal-card mapping (capability-gated)', () => {
       name: 'bash',
       description: 'run a command',
       parameters: {},
+      output: UNUSED_TOOL_OUTPUT,
       execute: async () => [],
       presentCall: (args: unknown) => ({ card: 'terminal', title: (args as { command: string }).command }),
     }
@@ -713,6 +726,7 @@ describe('diff-card mapping', () => {
     name: 'writer',
     description: 'writes a file',
     parameters: {},
+    output: UNUSED_TOOL_OUTPUT,
     execute: async () => [],
     presentCall: () => view as ReturnType<NonNullable<ToolDefinition['presentCall']>>,
   })
@@ -848,6 +862,7 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo
       name: 'writer',
       description: 'writes a file',
       parameters: {},
+      output: UNUSED_TOOL_OUTPUT,
       execute: async () => [],
       presentCall: () => ({ card: 'diff', title: 'Write x', diffs: [{ path: 'x', oldText: null, newText: 'y' }] }),
       presentResult: () => ({ card: 'diff', diffs: [] }),
diff --git a/packages/ui/acp/tests/turns.spec.ts b/packages/ui/acp/tests/turns.spec.ts
index 4ca6775d06..b3dcc22a55 100644
--- a/packages/ui/acp/tests/turns.spec.ts
+++ b/packages/ui/acp/tests/turns.spec.ts
@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import {
   errorResponse,
@@ -63,7 +63,7 @@ describe('acp bridge — turn outcomes', () => {
       storageDir,
       script: [toolCallResponse('c1', 'bash', { command: 'echo hi' }), textResponse('done')],
     })
-    harness.ctx.tools.register(defineTool({
+    harness.ctx.tools.register(defineContentToolFixture({
       name: 'bash',
       description: 'run a command',
       parameters: { command: { type: 'string' } },
@@ -204,7 +204,7 @@ describe('acp bridge — turn outcomes', () => {
       storageDir,
       script: [toolCallResponse('c1', 'kaboom', { x: 1 }), textResponse('done')],
     })
-    harness.ctx.tools.register(defineTool({
+    harness.ctx.tools.register(defineContentToolFixture({
       name: 'kaboom',
       description: 'explodes when presented',
       parameters: { x: { type: 'number' } },
@@ -227,7 +227,7 @@ describe('acp bridge — turn outcomes', () => {
       storageDir,
       script: [toolCallResponse('c1', 'bash', { command: 'boom' }), textResponse('ok')],
     })
-    harness.ctx.tools.register(defineTool({
+    harness.ctx.tools.register(defineContentToolFixture({
       name: 'bash',
       description: 'run a command',
       parameters: { command: { type: 'string' } },
@@ -285,10 +285,10 @@ describe('acp bridge — turn outcomes', () => {
     const sessionId = await newSession(harness)
     const agent = harness.ctx.agents.get(SessionId(sessionId))!
     // On the queued prompt, synchronously inject a one-shot context turn (idle
-    // inject writes turn/start{injection} → context/message → turn/end). Fire
+    // inject writes turn/start{injection} → user/message → turn/end). Fire
     // once so it lands between install and the prompt turn.
     let injected = false
-    harness.ctx.on('agent/queued', (subject) => {
+    harness.ctx.on('agent/inbox/enqueue', (subject) => {
       if (subject === agent && !injected) {
         injected = true
         agent.inject([{ type: 'text', text: 'ctx note' }], { source: { kind: 'plugin', plugin: 'test' } })
diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md
index 68f885608f..da44317c94 100644
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -9,13 +9,14 @@ Shared boot glue for the app bins ([`dsh-tui-demo`](../../examples/tui-demo/READ
 | `installFailLoud(binName, proc?)` | Turn a post-`boot()` unhandled Loader rejection into one labelled stderr line + `exit(1)`; returns the uninstaller (for tests) |
 | `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber (a plugin module that failed to import) |
 | `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 |
-| `boot(binName, absoluteConfigPath, patches?)` | Mount the Loader, mount the statically imported include plugin as the `cordis:include` builtin (so the config may live outside `node_modules` reach), include the config by absolute `file://` URL with the optional overlay patches, await the whole tree, assert entries loaded, return the root context |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, run optional host preparation before plugins mount (e.g. `ctx.provide(RESUME_SESSION_ID_KEY, id)`), then mount the Loader/include tree, await it, assert entries loaded, and return the root context |
+| `RESUME_SESSION_ID_KEY` | Context key a bin sets through `boot`'s `prepare` hook to hand a resume session id to the booted config; the config reads it as the bare identifier `resumeSessionId` in a `!!js` expression, so resuming needs no environment variable |
 | `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 its own source checkout; 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 |
 
 Two failure classes the guards handle: `loader.await()` swallows init rejections (`Promise.allSettled`) — Node still exits non-zero on the resulting unhandled rejection, and `installFailLoud` replaces the noisy dump with one labelled line and a guaranteed `exit(1)`; a failed plugin IMPORT is only logged by the Loader (the process would otherwise exit 0 on a usable config typo), leaving a fiber-less entry that `assertEntriesLoaded` turns into a `boot()` rejection.
 
-Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve through the cordis Loader's internal module loader when Node runs with `--expose-internals` or the optional `node-addon-require-builtin` fallback is installed; without either, consumers must install plugins where plain Node import resolution can find them. Relative specifiers resolve against the config directory with no flag. The bins' subprocess smokes exercise the internal-loader path, while this package's unit suite drives `boot()` in-process against configs with relative specifiers.
+Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve through the Cordis Loader's internal module loader. Repository bins install Loader's optional `node-addon-require-builtin` peer; external callers must supply it or install plugins where plain Node import resolution can find them. Relative specifiers resolve against the config directory without the native helper. The bins' subprocess smokes exercise the internal-loader path, while this package's unit suite drives `boot()` in-process against configs with relative specifiers.
 
 This package carries no loader hooks and no dev-mode surface: the `dsh-scripts` launcher ([`sdk/scripts`](../../sdk/scripts/README.md), with the shared project model in [`sdk/helper`](../../sdk/helper/README.md)) owns process startup, tsx registration, and local-plugin source resolution, and consumes these helpers for the boot sequence itself.
 
@@ -38,7 +39,7 @@ No direct invalidation from `boot()`; a consumer that calls `addHarnessSourceSec
 
 ## Known Limitations and Deferred Work
 
-- **Bare package specifiers depend on Loader internals** — production bins need `node --expose-internals` or the Loader's optional native fallback; an in-process caller without either must use resolvable relative/file specifiers or tsx path mapping.
+- **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 tsx path mapping.
 - **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.
 - **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/src/index.ts b/packages/ui/app-boot/src/index.ts
index faeb5a0e0a..00e316ebe8 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -156,6 +156,18 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
   }
 }
 
+/**
+/**
+ * Context key a bin sets through {@link boot}'s `prepare` hook to hand a resume
+ * session id to the booted config: `ctx.provide(RESUME_SESSION_ID_KEY, id)`
+ * makes `id` readable as the bare identifier `resumeSessionId` in a config
+ * `!!js` expression. The value is the bin's already-parsed id (or `undefined`),
+ * so resuming a session needs no environment variable. A bin that never
+ * provides it leaves the identifier undeclared, so configs read it defensively
+ * (`typeof resumeSessionId === 'string' ? resumeSessionId : undefined`).
+ */
+export const RESUME_SESSION_ID_KEY = 'resumeSessionId'
+
 /**
  * Boot the Loader against `absoluteConfigPath` and return only after the whole
  * tree settles. Entry names load through the Loader's internal module loader
@@ -165,20 +177,24 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
  * `cordis:include` builtin, loading through the ambient module pipeline
  * (vite/tsx/plain ESM) while the included tree's own specifiers stay
  * config-relative. A missing fiber rejects here; a later init rejection is
- * handled by {@link installFailLoud}. Built bins need `--expose-internals` or
- * the Loader's native fallback for bare plugin specifiers; relative specifiers
- * do not.
+ * handled by {@link installFailLoud}. Built bins need the Loader's native
+ * helper for bare plugin specifiers; relative specifiers do not.
  * @param binName - the diagnostic prefix for load-failure errors.
  * @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.
+ * @param prepare - optional host setup run against the root context before any Loader entry mounts.
  * @returns the root context once every entry has started.
  */
 export async function boot(
-  binName: string, absoluteConfigPath: string, patches?: PatchOptions[],
+  binName: string,
+  absoluteConfigPath: string,
+  patches?: PatchOptions[],
+  prepare?: (ctx: Context) => Promise<void> | void,
 ): Promise<Context> {
   const ctx = new Context()
+  await prepare?.(ctx)
   ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
   await ctx.plugin(Loader)
   ctx.loader.builtins.include = Include
diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/ui/app-boot/tests/app-boot.spec.ts
index d9934cb8bb..db425c301a 100644
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -171,6 +171,19 @@ describe('boot', () => {
     }
   })
 
+  it('runs host preparation before the Loader tree mounts', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
+    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n')
+    const prepared: Context[] = []
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'), undefined, (hostCtx) => { prepared.push(hostCtx) })
+    try {
+      expect(prepared).toEqual([ctx])
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
   it('rejects (never exits 0 half-empty) when a config names a plugin that cannot be imported', async () => {
     const dir = tmp()
     writeFileSync(join(dir, 'cordis.yml'), '- id: ghost\n  name: ./missing.mjs\n')
diff --git a/packages/ui/app-boot/tests/config-reload.spec.ts b/packages/ui/app-boot/tests/config-reload.spec.ts
new file mode 100644
index 0000000000..05ebe80b58
--- /dev/null
+++ b/packages/ui/app-boot/tests/config-reload.spec.ts
@@ -0,0 +1,128 @@
+/**
+ * Config hot-reload resilience of the booted include tree. `dsh-app-boot`
+ * installs a fail-loud unhandled-rejection handler, so a `refresh()` that
+ * rethrows a config-file parse error would kill a live app on one bad
+ * `cordis.yml` edit (the HMR watcher awaits `refresh()` in an async event
+ * callback nobody else catches). These tests pin the vendored
+ * `@cordisjs/plugin-include` contract that boot relies on: an invalid file
+ * keeps the last good tree, and a valid re-read re-applies overlay patches
+ * exactly like the initial load.
+ */
+
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { Context } from 'cordis'
+import type { Include } from '@cordisjs/plugin-include'
+import { boot } from '../src/index.ts'
+
+const NAME = 'dsh-test-bin'
+
+const NOOP_PLUGIN = 'export const name = "noop"\nexport function apply() {}\n'
+
+interface TreeFixture {
+  ctx: Context
+  dir: string
+  include: Include
+}
+
+async function bootTree(configBody: string): Promise<TreeFixture> {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-config-reload-'))
+  writeFileSync(join(dir, 'noop.mjs'), NOOP_PLUGIN)
+  writeFileSync(join(dir, 'cordis.yml'), configBody)
+  const ctx = await boot(NAME, join(dir, 'cordis.yml'))
+  const entry = [...ctx.loader.entries()].find(candidate => candidate.subtree !== undefined)
+  if (entry?.subtree === undefined) throw new Error('booted tree has no include entry')
+  return { ctx, dir, include: entry.subtree as Include }
+}
+
+function entryConfig(ctx: Context, id: string): unknown {
+  return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
+}
+
+describe('include refresh with an invalid file', () => {
+  it('keeps the last good tree instead of throwing, then applies the next valid edit', async () => {
+    const { ctx, dir, include } = await bootTree('- id: noop\n  name: ./noop.mjs\n  config:\n    value: 1\n')
+    try {
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 1 })
+
+      writeFileSync(join(dir, 'cordis.yml'), 'invalid: [unclosed\n')
+      await expect(include.refresh()).resolves.toBeUndefined()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 1 })
+
+      // An empty file parses to `undefined` without a YAML error; it must be
+      // treated exactly like a parse failure, not crash the entry walk.
+      writeFileSync(join(dir, 'cordis.yml'), '')
+      await expect(include.refresh()).resolves.toBeUndefined()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 1 })
+
+      writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: 2\n')
+      await include.refresh()
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 2 })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
+describe('include refresh with overlay patches', () => {
+  it('re-applies entry patches and inserted entries on every re-read (parity with initial load)', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-config-reload-overlay-'))
+    writeFileSync(join(dir, 'noop.mjs'), NOOP_PLUGIN)
+    writeFileSync(join(dir, 'base.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
+    writeFileSync(join(dir, 'cordis.yml'), [
+      '- id: base',
+      "  name: 'cordis:include'",
+      '  config:',
+      '    path: ./base.yml',
+      '    patches:',
+      '      - id: noop',
+      '        name: ./noop.mjs',
+      '        config:',
+      '          value: patched',
+      '      - insert:',
+      '          - id: extra',
+      '            name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'))
+    try {
+      const entry = [...ctx.loader.entries()].find(candidate => candidate.options.id === 'base')
+      if (entry?.subtree === undefined) throw new Error('overlay tree has no base include entry')
+      const include = entry.subtree as Include
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched' })
+      expect(entryConfig(ctx, 'extra')).toBeUndefined()
+      expect([...ctx.loader.entries()].some(candidate => candidate.options.id === 'extra')).toBe(true)
+
+      writeFileSync(join(dir, 'base.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: edited\n')
+      await include.refresh()
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched' })
+      expect([...ctx.loader.entries()].some(candidate => candidate.options.id === 'extra')).toBe(true)
+
+      // Hot-update of the include entry's own config (the `internal/update`
+      // path): the new patches must apply now AND stick for later re-reads —
+      // the listener vetoes the fiber restart, so it must persist the new
+      // config itself or the next refresh() re-applies the old overlay.
+      await entry.update({ config: { path: './base.yml', patches: [{ id: 'noop', name: './noop.mjs', config: { value: 'patched-v2' } }] } })
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched-v2' })
+      expect([...ctx.loader.entries()].some(candidate => candidate.options.id === 'extra')).toBe(false)
+
+      writeFileSync(join(dir, 'base.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: edited-2\n')
+      await include.refresh()
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched-v2' })
+
+      // Removing every patch must revert to the file's own values: patching
+      // may not bake earlier patch results into the cached parse.
+      await entry.update({ config: { path: './base.yml', patches: [] } })
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'edited-2' })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
diff --git a/packages/ui/jsonrpc/src/server.ts b/packages/ui/jsonrpc/src/server.ts
index 65ca3ed52c..5200a2de13 100644
--- a/packages/ui/jsonrpc/src/server.ts
+++ b/packages/ui/jsonrpc/src/server.ts
@@ -152,7 +152,7 @@ export class HarnessSdkServer {
     rec.activePrompt = true
     try {
       rec.lastTurnEnd = undefined
-      rec.handle.agent.send(params.contentBlocks)
+      rec.handle.agent.followup(params.contentBlocks)
       await rec.handle.agent.whenIdle()
       const status = this.finishedStatus(rec.lastTurnEnd)
       this.transport.notify('session.finished', {
diff --git a/packages/ui/jsonrpc/tests/server.spec.ts b/packages/ui/jsonrpc/tests/server.spec.ts
index 40dbc81acd..91d3503263 100644
--- a/packages/ui/jsonrpc/tests/server.spec.ts
+++ b/packages/ui/jsonrpc/tests/server.spec.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'
+import { AgentMessageId, type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'
 
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
@@ -152,7 +152,7 @@ describe('HarnessSdkServer', () => {
         meta: { cwd: storageDir },
         agentOptions: { provider: 'deepseek', model: 'dsagent-model' },
       })
-      orphanHandle.agent.send([{ type: 'text', text: 'outside the sdk session map' }])
+      orphanHandle.agent.followup([{ type: 'text', text: 'outside the sdk session map' }])
       await orphanHandle.agent.whenIdle()
       await orphanHandle.dispose()
       expect(llmServer.requests).toHaveLength(3)
@@ -170,16 +170,16 @@ describe('HarnessSdkServer', () => {
     const mainWhenIdle = vi.fn<() => Promise<void>>()
       .mockReturnValueOnce(firstMainIdle)
       .mockResolvedValue(undefined)
-    const mainSend = vi.fn()
-    const mainAgent = {
-      send: mainSend,
+    const mainFollowup = vi.fn<Agent['followup']>().mockReturnValue(AgentMessageId('main-followup'))
+    const mainAgent = ({
+      followup: mainFollowup,
       whenIdle: mainWhenIdle,
-    } as unknown as Agent
-    const otherSend = vi.fn()
-    const otherAgent = {
-      send: otherSend,
+    } satisfies Pick<Agent, 'followup' | 'whenIdle'>) as unknown as Agent
+    const otherFollowup = vi.fn<Agent['followup']>().mockReturnValue(AgentMessageId('other-followup'))
+    const otherAgent = ({
+      followup: otherFollowup,
       whenIdle: vi.fn(() => Promise.resolve()),
-    } as unknown as Agent
+    } satisfies Pick<Agent, 'followup' | 'whenIdle'>) as unknown as Agent
     const mainHandle = { agent: mainAgent, dispose: vi.fn(() => Promise.resolve()) }
     const otherHandle = { agent: otherAgent, dispose: vi.fn(() => Promise.resolve()) }
     const create = vi.fn(async (options: { sessionId: SessionId }) =>
@@ -196,7 +196,7 @@ describe('HarnessSdkServer', () => {
     })
 
     const first = prompt('main', 'first')
-    await vi.waitFor(() => { expect(mainSend).toHaveBeenCalledOnce() })
+    await vi.waitFor(() => { expect(mainFollowup).toHaveBeenCalledOnce() })
 
     await expect(prompt('main', 'overlap')).rejects.toThrow('session already has an active prompt: main')
     await expect(prompt('other', 'independent')).resolves.toEqual({ accepted: true })
@@ -208,8 +208,8 @@ describe('HarnessSdkServer', () => {
     await expect(prompt('main', 'failing')).rejects.toThrow('turn wait failed')
     await expect(prompt('main', 'after failure')).resolves.toEqual({ accepted: true })
 
-    expect(mainSend).toHaveBeenCalledTimes(4)
-    expect(otherSend).toHaveBeenCalledOnce()
+    expect(mainFollowup).toHaveBeenCalledTimes(4)
+    expect(otherFollowup).toHaveBeenCalledOnce()
     await server.shutdown()
     expect(mainHandle.dispose).toHaveBeenCalledOnce()
     expect(otherHandle.dispose).toHaveBeenCalledOnce()
@@ -225,9 +225,9 @@ describe('HarnessSdkServer', () => {
       shutdown(): Promise<Record<string, never>>
     }
     const session = ctx.sessions.create(SessionId('message-outcome'))
-    const agent = {
+    const agent = ({
       session,
-      send(content: { type: 'text'; text: string }[]) {
+      followup(content: { type: 'text'; text: string }[]) {
         session.append('turn/start', {
           turn: 1,
           trigger: { kind: 'message', source: { kind: 'user' } },
@@ -241,14 +241,15 @@ describe('HarnessSdkServer', () => {
           turn: 2,
           trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'late-metadata' } },
         })
-        session.append('context/message', {
+        session.append('user/message', {
           content: [{ type: 'text', text: 'late metadata' }],
           source: { kind: 'plugin', plugin: 'late-metadata' },
         }, { surfaceOp: 'append' })
         session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
+        return AgentMessageId('message-outcome')
       },
       whenIdle: () => Promise.resolve(),
-    } as unknown as Agent
+    } satisfies Pick<Agent, 'session' | 'followup' | 'whenIdle'>) as unknown as Agent
     server.sessions.set('message-outcome', {
       handle: { agent, dispose: () => Promise.resolve() },
       lastTurnEnd: undefined,
diff --git a/packages/ui/tool-ask-user/README.md b/packages/ui/tool-ask-user/README.md
index 96d5a43856..ff67395800 100644
--- a/packages/ui/tool-ask-user/README.md
+++ b/packages/ui/tool-ask-user/README.md
@@ -13,7 +13,7 @@ Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the mo
 - `options` — optional choices with `label` and `description`. If recommending a choice, put it first and append `(Recommended)` to that label.
 - `multi_select` — whether that question may return more than one selected option.
 
-The tool calls `ctx.userInteraction.ask()` and returns JSON text shaped as `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`. `selected` contains option labels; `custom` is present only for a free-form answer and overrides selected choices.
+The tool calls `ctx.userInteraction.ask()` and returns canonical `{ answers: [{ id, selected, custom? }] }`. `selected` contains option labels; `custom` is present only for a free-form answer and overrides selected choices. The Native renderer preserves the compact JSON text shape `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`.
 
 ## Role
 
@@ -52,4 +52,4 @@ 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.
-- **Answers return as JSON text** — the seam's structured `AskUserQuestionAnswer` is serialized into the tool result rather than carried as typed content blocks.
+- **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/src/index.ts b/packages/ui/tool-ask-user/src/index.ts
index 773d17bcf6..f908bdad4d 100644
--- a/packages/ui/tool-ask-user/src/index.ts
+++ b/packages/ui/tool-ask-user/src/index.ts
@@ -27,6 +27,7 @@ export function apply(ctx: Context): void {
         description: 'Questions to ask the user before continuing.',
         items: {
           type: 'object',
+          additionalProperties: true,
           properties: {
             id: { type: 'string', required: true, description: 'Stable id for this question; echoed in the answer.' },
             question: { type: 'string', required: true, description: 'The specific question to ask the user.' },
@@ -39,6 +40,7 @@ export function apply(ctx: Context): void {
               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', required: true, description: 'Short user-facing option label.' },
                   description: { type: 'string', description: 'One sentence explaining the tradeoff or impact.' },
@@ -53,6 +55,28 @@ export function apply(ctx: Context): void {
         },
       },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          answers: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                id: { type: 'string', required: true },
+                selected: { type: 'array', required: true, items: { type: 'string' } },
+                custom: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
     async execute(args, exec) {
       const result = await ctx.userInteraction.ask({
         questions: args.questions.map(question => ({
@@ -65,7 +89,13 @@ export function apply(ctx: Context): void {
         ...exec.agent !== undefined ? { agent: exec.agent } : {},
         signal: exec.signal,
       })
-      return [{ type: 'text', text: JSON.stringify(result) }]
+      return {
+        answers: result.answers.map(answer => ({
+          id: answer.id,
+          selected: [...answer.selected],
+          ...answer.custom !== undefined ? { custom: answer.custom } : {},
+        })),
+      }
     },
   }))
 }
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 0f03322dcd..395986aed1 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
@@ -164,6 +164,14 @@ describe('ask_user_question tool', () => {
       },
     })
 
+    expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected ask_user_question success')
+    expect(result.value).toEqual({
+      answers: [
+        { id: 'targets', selected: ['tests', 'docs'] },
+        { id: 'notes', selected: [], custom: 'ship today' },
+      ],
+    })
     expect(result.content).toEqual([{
       type: 'text',
       text: '{"answers":[{"id":"targets","selected":["tests","docs"]},{"id":"notes","selected":[],"custom":"ship today"}]}',
@@ -226,7 +234,7 @@ describe('ask_user_question tool', () => {
 
     expect(result).toMatchObject({
       isError: true,
-      error: { name: 'UserInteractionError', code: 'NO_PROVIDER' },
+      error: { info: { name: 'UserInteractionError', code: 'NO_PROVIDER' } },
     })
   })
 
@@ -242,7 +250,7 @@ describe('ask_user_question tool', () => {
 
     expect(result).toMatchObject({
       isError: true,
-      error: { name: 'UserInteractionError', code: 'EMPTY_QUESTIONS' },
+      error: { info: { name: 'UserInteractionError', code: 'EMPTY_QUESTIONS' } },
     })
   })
 
diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md
index 28d45f50d6..616544779f 100644
--- a/packages/ui/tui/README.md
+++ b/packages/ui/tui/README.md
@@ -2,21 +2,25 @@
 
 The interactive terminal front door for DeepSeek Harness agents, built on [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui). It requires stdin and stdout TTYs; scripts and Loader pipes should use the one-shot [`@deepseek-ai/dsh-cli-demo`](../../examples/cli-demo/README.md) app instead.
 
-The implemented [TUI feature Agent Note](../../../.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md) owns the front-door decision; the [terminal-state snapshot Agent Note](../../../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns its verification strategy.
+The implemented [TUI feature Agent Note](../../../.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md) owns the front-door decision; the [file-reference autocomplete Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-tui-file-reference-autocomplete.md) owns path-only `@file` behavior; the [terminal-state snapshot Agent Note](../../../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns its verification strategy.
 
 Interactive terminals on macOS, Linux, and Windows are supported. Windows uses pi-tui's native console VT-input handling, and the [Windows support Agent Note](../../../.agents/notes/implemented/feature/2026-07-20-windows-tui-support.md) owns the platform decision and ConPTY process verification.
 
 This package owns interactive terminal presentation and input only. It injects `agents`, [`commands`](../commands/README.md), `llm`, `systemPrompt`, `tokenMeter`, `tools`, and `userInteraction`, optionally reads a `skills` service (present only when one is mounted), then drives an agent created or resumed by app or developer code. Agent lifecycle, persistence, and the model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries.
 
+After terminal startup succeeds, the package provides the terminal-local `ctx.tui` extension service. A plugin that injects it can call `openOverlay()` with a component factory and constrained layout options; the host exposes the viewport, semantic theme, display-text escaping, redraw, close, and a lifetime signal, but not the pi-tui tree, terminal, focus controller, or overlay handle. Plugin overlays, the model selector, and user questions share one FIFO modal queue. Each request is an effect of the calling plugin fiber, so unload removes queued work or closes visible work before cleanup settles; terminal shutdown unloads dependents before stopping pi-tui. Overlay state is not logged or replayed. Component code is trusted and may render ANSI styling, but must pass untrusted text through `host.display()`. The [interactive-extension Agent Note](../../../.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md) owns the boundary and rejected alternatives.
+
 The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the latest `todo/write` plan above the editor, and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. The latest logged session title becomes the header subtitle, with `welcome` before a title exists, and the terminal window title becomes `<session title> — <configured title>`. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view compares token-meter pressure with `ctx.llm.resolveModelContext()` for the current route, displays `context unknown` when the adapter has no capacity metadata, and also shows tool-card mode and the current model with reasoning state; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. Surface replacement events rebuild the transcript so compacted history does not reappear.
 
 An embedding may provide `TuiRuntime.formatCwd` when its logical workspace label differs from the session's host directory. The override changes only the footer label; tools continue to use the session `cwd`.
 
 Before model output, session events, tool presenters, questions, configuration, or diagnostics reach pi-tui's ANSI-aware renderers or the terminal title, the TUI renders C0 and C1 controls other than line feeds as visible `\xNN` text. Those sources cannot add terminal control sequences; the TUI and pi-tui retain ownership of terminal rendering and styling.
 
-When optional `ctx.sessionReferences` is mounted, the existing `@` file menu also offers metadata-only session candidates, inserts `@[label](dsh-session:<payload>)`, and prepares the selected snapshots before dispatch. Preparation disables duplicate submission and restores the editor input on failure. The TUI chooses `agent.steer()` or `agent.send()` from the status after that asynchronous preparation, so idle sends still dispatch `agent/prompt-submit` while in-turn steering joins at a checkpoint without that hook.
+Typing `@` at a token boundary searches files and directories under the session working directory. A bare fuzzy query uses a reusable bounded workspace index; a query containing `/` lists that directory directly, and selecting a folder keeps completion open for descent. Whitespace-bearing paths are inserted as `@"path with spaces"`. Selecting a file inserts only its path and a trailing space: the TUI does not read it, attach hidden context, or replace it with a reference object. When a model-facing `read` tool is registered, the TUI adds one fixed system-prompt instruction telling the model to read an explicit path when its contents are needed.
 
-While the agent is running, ordinary editor submissions call `agent.steer()`; otherwise they call `agent.send()`. A slash at the start of the submitted line enters `ctx.commands` instead: known commands execute directly, unknown commands produce a warning, and neither path automatically reaches the model. A command producer may explicitly schedule agent work; [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces) uses that contract for `/plan [message]`. The TUI registers `/help`, `/model`, `/clear`, `/reasoning`, `/tools`, `/redraw`, `/reload`, `/resume`, `/status`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically, as do `/skill:` completions. A status line above the editor reports the turn phase the TUI derives from session events — waiting for the first token, thinking, responding, or executing tools — with the elapsed time in that phase and the running step total, refreshed each second, and ends with the `Enter sends steering, Esc cancels` hint; while steering messages wait to reach the model it inserts a `N queued ·` badge before the hint that clears as each drains. Ctrl+C or Escape cancels a running turn. Tool cards collapse long bodies into a configurable head/tail preview; Ctrl+O toggles every card between its preview and full output. Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle.
+When optional `ctx.sessionReferences` is mounted, the same `@` menu also offers metadata-only session candidates, inserts `@[label](dsh-session:<payload>)`, and prepares the selected snapshots before dispatch. Session references remain structured because the model has no filesystem-like tool for retrieving session snapshots later. Preparation disables duplicate submission and restores the editor input on failure. The TUI chooses `agent.steer()` or `agent.followup()` from the status after that asynchronous preparation, so idle follow-ups still dispatch `agent/prompt-submit` while in-turn steering joins at a checkpoint without that hook.
+
+While the agent is running, ordinary editor submissions call `agent.steer()`; otherwise they call `agent.followup()`. A slash at the start of the submitted line enters `ctx.commands` instead: known commands execute directly, unknown commands produce a warning, and neither path automatically reaches the model. A command producer may explicitly schedule agent work; [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces) uses that contract for `/plan [message]`. The TUI registers `/help`, `/model`, `/clear`, `/reasoning`, `/tools`, `/redraw`, `/reload`, `/resume`, `/status`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically, as do `/skill:` completions. A status line above the editor reports the turn phase the TUI derives from session events — waiting for the first token, thinking, responding, or executing tools — with the elapsed time in that phase and the running step total, refreshed each second, and ends with the `Enter sends steering, Esc cancels` hint; while steering messages wait to reach the model it inserts a `N queued ·` badge before the hint that clears as each drains. Ctrl+C or Escape cancels a running turn. Tool cards collapse long bodies into a configurable head/tail preview; Ctrl+O toggles every card between its preview and full output. Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle.
 
 `/model` opens the advisory `ctx.llm` catalog as a keyboard selector: Up/Down moves, Enter selects, and Escape closes it. `/model <model>` still selects an unambiguous model id directly, while `/model <provider>/<model>` selects an exact target. The configured target or latest logged request header initializes the selector, and an unlisted current model remains visible because catalogs are advisory. Selection is local to this TUI session. Prompt assembly snapshots the target for one step, replaces `{{provider}}` and `{{model}}`, and applies the same pair through `agent/request`; a switch during assembly therefore starts with a later step. The request header durably records targets that reach the model, while an unused selection remains process-local.
 
@@ -26,7 +30,9 @@ The footer sums the session's reported usage as `↑<uncached input> ↓<output>
 
 `/status` adds a point-in-time diagnostics card to the transcript and remains available while the agent runs. It reports the session id, title, working directory, selected provider/model, reasoning-block visibility, agent state, event/turn/step/tool-call counts, exact input/output/cache token buckets, KV-cache hit rate, token-meter context use and capacity, creation time, and latest event time. Missing titles, models, cache input, or context capacity are labeled instead of inferred. The card is terminal-only and does not duplicate the compact footer.
 
-When `resumeCommand` is set and a `sessionPersistence` backend is mounted, exiting prints the resume command for the current session (once it has been persisted, so an abandoned session yields no hint), and `/resume` lists this workspace's persisted sessions newest-first, each with its resume command and a marker on the current one. `{session}` in the template expands to the session id; the TUI only prints commands to copy and never resumes in place.
+`/resume` opens a full-viewport keyboard selector over the current workspace instead of a centered dialog. Its focused search field starts immediately after the search glyph and emits pi-tui's cursor marker, so terminal IME composition remains anchored inside the field. Candidates are sorted by last logged activity and searchable by log-backed title or session id; each row reports current/live/persisted state, last turn outcome, recent provider/model, and durable goal phase when present. Up/Down and Page Up/Page Down navigate, Enter resumes, Escape clears a non-empty search before a second Escape cancels, and Ctrl+C cancels directly. The current session, a session already live in this runtime, an unreadable log, a mismatched cwd, or a session whose logged provider has no current adapter remains visible but disabled. Selection repeats those checks and requires the current agent to be idle before flushing the current session. The TUI then stops the terminal UI and calls the optional host-owned `TuiRuntime.handoffResume`; where `process.execve` is available, the shipped `dsh` host disposes the app and replaces its process. Resume restores the same `SessionId`, transcript, title, todos, and durable goal; goal activation remains disarmed and the TUI asks for human confirmation or `/goal resume`.
+
+`resumeCommand` remains the deployment-owned fallback: exiting prints it only after the current session is durable, and a host without in-place handoff shows the selected session's command. `{session}` expands to the session id. TUI code never executes the template or arbitrary shell text.
 
 ## Config
 
@@ -38,14 +44,18 @@ When `resumeCommand` is set and a `sessionPersistence` backend is mounted, exiti
 | `maxToolOutputLines` | `6` | Output lines retained across a collapsed tool card's head/tail preview |
 | `maxQuestionOptions` | `8` | Visible options in a question panel |
 | `maxModelOptions` | `8` | Visible models in the model selector |
+| `maxResumeOptions` | `8` | Visible sessions in the resume selector |
 | `questionDialogWidth` | `200` | Question-panel width in columns, clamped to the terminal |
 | `questionDialogMaxHeight` | `20` | Question-panel maximum rows |
 | `modelDialogWidth` | `72` | Model-selector width in columns |
 | `modelDialogMaxHeight` | `20` | Model-selector maximum rows |
+| `fileSearchMaxResults` | `20` | Maximum file and directory candidates shown for one `@` query |
+| `fileSearchMaxEntries` | `10000` | Maximum paths retained in the bounded workspace index used by bare fuzzy queries |
+| `fileSearchExcludedDirectories` | `['.git', 'node_modules']` | Directory basenames omitted from traversal and direct completion |
 | `showHardwareCursor` | `false` | Show the hardware cursor at pi-tui's IME marker |
 | `color` | `true` | Apply the built-in ANSI palette (see [Color](#color)) |
 | `title` | `DeepSeek Harness` | Product suffix for the terminal window title. |
-| `resumeCommand` | — | Shell command template for the exit hint and `/resume`, with `{session}` expanded to the session id; unset disables both. Needs a `sessionPersistence` backend |
+| `resumeCommand` | — | Shell command template for the exit hint and hosts without in-place handoff, with `{session}` expanded to the session id |
 
 ```yaml
 - id: terminal
@@ -55,9 +65,10 @@ When `resumeCommand` is set and a `sessionPersistence` backend is mounted, exiti
     sessionId: main-session-123
     showReasoning: true
     maxToolOutputLines: 6
+    fileSearchExcludedDirectories: ['.git', 'node_modules', 'dist']
 ```
 
-Startup fails before mounting when either process stream is not a TTY. The composing app must mount the TUI before its config-created agent so the front door can observe `agent-loop/config-start-failed`; a matching exact-session failure is written before fullscreen mode starts and exits with status 1 instead of leaving a blank terminal. Disposal aborts running commands, removes the TUI definitions, stops loaders, rejects pending questions, drains terminal input, restores terminal state, unregisters event listeners and the user-interaction provider, and never exits a replacement process during HMR.
+Startup fails before mounting when either process stream is not a TTY. The composing app must mount the TUI before its config-created agent so the front door can observe `agent-loop/config-start-failed`; a matching exact-session failure is written before fullscreen mode starts and exits with status 1 instead of leaving a blank terminal. Disposal stops extension admission, unloads the `ctx.tui` provider and its dependent plugins, aborts running commands, removes the TUI definitions, stops loaders, rejects pending questions, drains terminal input, restores terminal state, unregisters event listeners and the user-interaction provider, and never exits a replacement process during HMR.
 
 ## Color
 
@@ -69,7 +80,7 @@ The palette uses the standard 16-color ANSI foregrounds and SGR attributes, whic
 
 #### What the model sees
 
-Each non-empty ordinary editor submission becomes one text block, sent with `agent.send()` while the target agent is idle and `agent.steer()` while it is running. A session mention becomes readable `@label` text plus the durable untrusted context defined by [`dsh-session-reference`](../../context/session-reference/README.md); its full JSON is hidden behind a compact reference card. Slash commands and keybindings are TUI-only; command results remain terminal notices. A command producer may schedule a separate agent input, such as the optional message accepted by `/plan [message]`.
+Each non-empty ordinary editor submission becomes one text block, sent with `agent.followup()` while the target agent is idle and `agent.steer()` while it is running. A session mention becomes readable `@label` text plus the durable untrusted context defined by [`dsh-session-reference`](../../context/session-reference/README.md); its full JSON is hidden behind a compact reference card. Slash commands and keybindings are TUI-only; command results remain terminal notices. A command producer may schedule a separate agent input, such as the optional message accepted by `/plan [message]`.
 
 #### Token effect
 
@@ -79,6 +90,26 @@ Submitted text is retained under the agent loop's normal session-history and com
 
 Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
+### File-reference autocomplete
+
+#### What the model sees
+
+A selected file remains ordinary user text such as `@src/index.ts` or `@"docs/design notes.md"`; autocomplete adds no content block, durable context, or special reference payload. When `read` is registered, every request from this TUI agent also contains the following fixed system-prompt section. The model decides whether the task requires the file contents and calls `read` through the normal tool loop when it does; a path alone is not evidence that the file was inspected.
+
+##### Exact system-prompt text
+
+```markdown
+Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.
+```
+
+#### Token effect
+
+Autocomplete itself adds no tokens. The selected path contributes only its ordinary user-text tokens; the fixed instruction contributes system-prompt tokens whenever `read` is available. File contents consume context only after a model-selected `read` call returns them.
+
+#### KV Cache effect
+
+The fixed instruction is part of the stable system-prompt prefix and is reusable across turns. Each selected path is append-only user text; a later `read` result appends the requested contents through the ordinary tool transcript.
+
 ### Session model selection
 
 #### What the model sees
@@ -97,7 +128,7 @@ Changing provider or model enters that target's cache domain; no cache reuse acr
 
 #### What the model sees
 
-A `/skill:<name> [instructions]` submission loads the named skill and delivers one text block: a `<skill name="…">` element wrapping the skill's instructions — preceded, when the provider exposes a resource base, by a line locating the skill's relative resources — followed by any trailing instructions the user typed. Delivery follows the same send-while-idle / steer-while-running rule as ordinary input. The command, not the model, chooses the skill; model-disabled skills are omitted from autocomplete but stay loadable by exact name.
+A `/skill:<name> [instructions]` submission loads the named skill and delivers one text block: a `<skill name="…">` element wrapping the skill's instructions — preceded, when the provider exposes a resource base, by a line locating the skill's relative resources — followed by any trailing instructions the user typed. Delivery follows the same followup-while-idle / steer-while-running rule as ordinary input. The command, not the model, chooses the skill; model-disabled skills are omitted from autocomplete but stay loadable by exact name.
 
 #### Token effect
 
@@ -123,7 +154,10 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
+- **Resume has no cross-process session lock** — the selector rejects sessions known to be live in its own runtime, but another process can resume the same persisted id before or during handoff. Deployments that can run concurrent hosts must coordinate ownership outside the TUI.
 - **One configured session owns the transcript and editor** — questions from other agents can still use the shared overlay provider, but session rendering and prompt input remain bound to `sessionId`.
 - **Tool cards are text terminal presentations** — terminal, diff, and generic cards use tool-owned titles/content, but session content currently has no image block for inline image rendering.
 - **Non-TTY operation is intentionally unsupported** — app bundles that need automation must compose a one-shot or server front door (`dsh-cli-demo`, `dsh-acp`) rather than expecting an internal fallback.
 - **Manual `/skill:` invocation always reloads the full skill body** — the TUI does not detect a skill already present in the conversation, so repeated invocations append its instructions again.
+- **File discovery is host-workspace discovery** — autocomplete reads the TUI process's session `cwd`, while the selected text is later interpreted by the configured `read` tool. Deployments that mount a remote or virtual filesystem must keep those namespaces aligned or provide another completion surface.
+- **File search uses explicit directory exclusions, not ignore files** — `.git` and `node_modules` are excluded by default and deployments may configure more basenames, but `.gitignore` and `.ignore` are not interpreted. Directory symlinks are not traversed.
diff --git a/packages/ui/tui/package.json b/packages/ui/tui/package.json
index 4d668ba697..3242f5a2a3 100644
--- a/packages/ui/tui/package.json
+++ b/packages/ui/tui/package.json
@@ -33,9 +33,11 @@
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-llm-retry": "^0.0.1",
+    "@deepseek-ai/dsh-goal": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-session-reference": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1",
     "@deepseek-ai/dsh-session-title": "^0.0.1",
     "@deepseek-ai/dsh-skill": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -48,6 +50,9 @@
     "@deepseek-ai/dsh-session-persistence": {
       "optional": true
     },
+    "@deepseek-ai/dsh-session-query": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-skill": {
       "optional": true
     }
@@ -60,6 +65,7 @@
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
diff --git a/packages/ui/tui/src/extension.ts b/packages/ui/tui/src/extension.ts
new file mode 100644
index 0000000000..d6cb7bc4e4
--- /dev/null
+++ b/packages/ui/tui/src/extension.ts
@@ -0,0 +1,165 @@
+/**
+ * Public interactive-extension contract for one mounted TUI front door.
+ *
+ * Plugins receive terminal-specific rendering primitives without access to
+ * the live pi-tui tree, focus controller, overlay handles, or terminal
+ * lifecycle. Registrations and open overlays remain owned by the calling
+ * Cordis fiber.
+ * @module @deepseek-ai/dsh-tui/extension
+ */
+
+/** Terminal component shape accepted from a trusted TUI extension. */
+export interface TuiComponent {
+  /**
+   * Render this component for the supplied viewport width.
+   * @param width - Available terminal columns.
+   * @returns terminal lines owned by this component.
+   */
+  render(width: number): string[]
+  /**
+   * Handle one terminal input sequence while this component owns focus.
+   * @param data - Raw terminal input sequence.
+   */
+  handleInput?(data: string): void
+  /** Receive key-release events instead of having them filtered by the host. */
+  wantsKeyRelease?: boolean
+  /** Drop cached rendering derived from theme, size, or component state. */
+  invalidate(): void
+}
+
+/** Optional focus state forwarded by the host to a component. */
+export interface TuiFocusable {
+  /** Whether the component currently owns terminal focus. */
+  focused: boolean
+}
+
+/** Read-only semantic color roles supplied by the mounted TUI. */
+export interface TuiTheme {
+  /** Render ordinary foreground text. */
+  readonly text: (value: string) => string
+  /** Render secondary information. */
+  readonly muted: (value: string) => string
+  /** Render low-emphasis hints. */
+  readonly dim: (value: string) => string
+  /** Render the active accent role. */
+  readonly accent: (value: string) => string
+  /** Render a successful outcome. */
+  readonly success: (value: string) => string
+  /** Render a warning. */
+  readonly warning: (value: string) => string
+  /** Render an error. */
+  readonly error: (value: string) => string
+  /** Apply the host's bold role. */
+  readonly bold: (value: string) => string
+}
+
+/** Current terminal viewport exposed without the mutable Terminal object. */
+export interface TuiViewport {
+  /** Terminal columns. */
+  readonly columns: number
+  /** Terminal rows. */
+  readonly rows: number
+}
+
+/** Supported overlay anchor points. */
+export type TuiOverlayAnchor =
+  | 'center'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'top-center'
+  | 'bottom-center'
+  | 'left-center'
+  | 'right-center'
+
+/** Terminal-edge spacing for an overlay. */
+export interface TuiOverlayMargin {
+  /** Rows reserved above the overlay. */
+  readonly top?: number
+  /** Columns reserved to the right of the overlay. */
+  readonly right?: number
+  /** Rows reserved below the overlay. */
+  readonly bottom?: number
+  /** Columns reserved to the left of the overlay. */
+  readonly left?: number
+}
+
+/** Position and size constraints retained under TUI host ownership. */
+export interface TuiOverlayOptions {
+  /** Width in columns or as a percentage of terminal width. */
+  readonly width?: number | `${number}%`
+  /** Minimum width in columns. */
+  readonly minWidth?: number
+  /** Maximum height in rows or as a percentage of terminal height. */
+  readonly maxHeight?: number | `${number}%`
+  /** Overlay anchor; defaults to the terminal center. */
+  readonly anchor?: TuiOverlayAnchor
+  /** Terminal-edge spacing. */
+  readonly margin?: number | TuiOverlayMargin
+}
+
+/** Capabilities available while an overlay component is queued or visible. */
+export interface TuiOverlayHost {
+  /**
+   * Aborts when the request, caller fiber, overlay session, or TUI closes.
+   * Extension work started for the overlay must cooperate with this signal.
+   */
+  readonly signal: AbortSignal
+  /** Current viewport; a fresh immutable value is returned on every read. */
+  readonly viewport: TuiViewport
+  /** Semantic styles that follow terminal color-scheme changes. */
+  readonly theme: TuiTheme
+  /**
+   * Escape control characters in untrusted display text.
+   * @param value - text crossing into terminal presentation.
+   * @returns a printable representation that cannot emit terminal controls.
+   */
+  display(value: string): string
+  /** Invalidate the component and schedule one contained terminal redraw. */
+  invalidate(): void
+  /** Close this overlay normally; repeated calls are no-ops. */
+  close(): void
+}
+
+/** One effect-owned request to create an interactive overlay. */
+export interface TuiOverlayRequest {
+  /**
+   * Construct the component when this request reaches the front of the modal
+   * queue. A throw closes the session with `reason: "error"`.
+   */
+  readonly create: (host: TuiOverlayHost) => TuiComponent & Partial<TuiFocusable>
+  /** Host-owned position and size constraints. */
+  readonly options?: TuiOverlayOptions
+  /** Optional request cancellation in addition to caller and TUI ownership. */
+  readonly signal?: AbortSignal
+}
+
+/** Stable reason an overlay stopped being queued or visible. */
+export type TuiOverlayCloseReason =
+  | 'closed'
+  | 'aborted'
+  | 'owner-disposed'
+  | 'tui-disposed'
+  | 'error'
+
+/** Settled overlay outcome; component failures retain their original value. */
+export type TuiOverlayOutcome =
+  | { readonly reason: Exclude<TuiOverlayCloseReason, 'error'> }
+  | { readonly reason: 'error'; readonly error: unknown }
+
+/** Live state of an overlay operation. */
+export type TuiOverlayState = 'queued' | 'active' | 'closed'
+
+/** Handle returned to the extension that opened an overlay. */
+export interface TuiOverlaySession {
+  /** Current queue/display state. */
+  readonly state: TuiOverlayState
+  /** Settles exactly once after the overlay leaves the queue or display. */
+  readonly closed: Promise<TuiOverlayOutcome>
+  /**
+   * Close the overlay normally and await its settled outcome.
+   * @returns the same immutable value exposed through {@link closed}.
+   */
+  close(): Promise<TuiOverlayOutcome>
+}
diff --git a/packages/ui/tui/src/file-autocomplete.ts b/packages/ui/tui/src/file-autocomplete.ts
new file mode 100644
index 0000000000..23a3a7c1fa
--- /dev/null
+++ b/packages/ui/tui/src/file-autocomplete.ts
@@ -0,0 +1,346 @@
+/**
+ * Host-workspace discovery for TUI `@file` completion. The index contains
+ * paths only: selected values remain ordinary prompt text and file contents
+ * stay behind the model-facing `read` tool.
+ *
+ * @module @deepseek-ai/dsh-tui/file-autocomplete
+ */
+
+import { lstat, readdir } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+/** Default maximum file and directory candidates rendered for one query. */
+export const DEFAULT_FILE_SEARCH_MAX_RESULTS = 20
+/** Default maximum entries retained in one workspace search index. */
+export const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 10_000
+/** Directory basenames omitted from traversal unless the deployment overrides them. */
+export const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES = ['.git', 'node_modules'] as const
+
+/** Resolved limits and exclusions for one TUI workspace index. */
+export interface FileSearchConfig {
+  /** Maximum ranked candidates returned for one query. */
+  maxResults: number
+  /** Maximum indexed files and directories. */
+  maxEntries: number
+  /** Directory basenames never traversed or offered. */
+  excludedDirectories: readonly string[]
+}
+
+/** One path-only completion candidate inside the session cwd. */
+export interface FileSearchCandidate {
+  /** User-facing path accepted by the normal prompt and filesystem tools. */
+  path: string
+  /** Directories keep completion open; files finish the mention. */
+  kind: 'file' | 'directory'
+}
+
+/** Active `@` token ending at the editor cursor. */
+export interface ActiveAtToken {
+  /** Complete token replaced when the user accepts a completion. */
+  prefix: string
+  /** Path query after `@` or `@"`. */
+  query: string
+  /** Whether the user opened a quoted path. */
+  quoted: boolean
+}
+
+interface IndexedPath extends FileSearchCandidate {}
+
+interface RankedPath {
+  candidate: FileSearchCandidate
+  score: number
+}
+
+interface IndexGeneration {
+  controller: AbortController
+  promise: Promise<IndexedPath[]>
+}
+
+/**
+ * Extract an `@path` or `@"path with spaces` token at the cursor. An `@`
+ * inside another token, such as an email address, is not a completion trigger.
+ * @param line - current editor line.
+ * @param cursorCol - cursor column within that line.
+ * @returns the active token, or `undefined` outside an `@` token.
+ */
+export function activeAtToken(line: string, cursorCol: number): ActiveAtToken | undefined {
+  const beforeCursor = line.slice(0, cursorCol)
+  const quoted = /(?:^|\s)(@"([^"]*))$/u.exec(beforeCursor)
+  if (quoted?.[1] !== undefined && quoted[2] !== undefined) {
+    return { prefix: quoted[1], query: quoted[2], quoted: true }
+  }
+  const plain = /(?:^|\s)(@([^\s]*))$/u.exec(beforeCursor)
+  if (plain?.[1] === undefined || plain[2] === undefined) return undefined
+  return { prefix: plain[1], query: plain[2], quoted: false }
+}
+
+/**
+ * Format a selected path as prompt text. Whitespace uses Pi's quoted
+ * `@"path"` grammar; directories retain a trailing slash so completion can
+ * descend another level.
+ * @param candidate - selected file or directory.
+ * @param preserveQuote - retain an explicitly opened quote even when unnecessary.
+ * @returns the insertion value, or `undefined` for a path the editor grammar cannot represent safely.
+ */
+export function formatFileMention(
+  candidate: FileSearchCandidate,
+  preserveQuote: boolean,
+): string | undefined {
+  const path = candidate.kind === 'directory' ? `${candidate.path}/` : candidate.path
+  if (/[\u0000-\u001f\u007f-\u009f"]/u.test(path)) return undefined
+  const quoted = preserveQuote || /\s/u.test(path)
+  if (!quoted) return `@${path}`
+  return `@"${path}"`
+}
+
+/**
+ * Cancellable, reusable fuzzy index rooted at one agent working directory.
+ * Directory-scoped queries list live state; bare fuzzy queries share one
+ * bounded traversal until the `@` interaction ends or a tool result invalidates it.
+ */
+export class WorkspaceFileSearch {
+  private readonly excludedDirectories: ReadonlySet<string>
+  private generation: IndexGeneration | undefined
+  private disposed = false
+
+  constructor(
+    private readonly root: string,
+    private readonly config: FileSearchConfig,
+  ) {
+    if (!Number.isSafeInteger(config.maxResults) || config.maxResults <= 0) {
+      throw new Error('file search maxResults must be a positive safe integer')
+    }
+    if (!Number.isSafeInteger(config.maxEntries) || config.maxEntries <= 0) {
+      throw new Error('file search maxEntries must be a positive safe integer')
+    }
+    if (config.excludedDirectories.some(name => name.length === 0 || name.includes('/') || name.includes('\\'))) {
+      throw new Error('file search excludedDirectories entries must be non-empty directory basenames')
+    }
+    this.excludedDirectories = new Set(config.excludedDirectories)
+  }
+
+  /**
+   * Return ranked path candidates for the current token.
+   * @param rawQuery - path text following `@` or `@"`.
+   * @param signal - cancels this caller's wait without killing an index shared by a newer query.
+   * @returns at most `maxResults` deterministic candidates.
+   */
+  async list(rawQuery: string, signal: AbortSignal): Promise<FileSearchCandidate[]> {
+    signal.throwIfAborted()
+    if (this.disposed) return []
+    const query = rawQuery.replaceAll('\\', '/')
+    const slash = query.lastIndexOf('/')
+    if (query === '' || slash >= 0) {
+      const directory = slash < 0 ? '' : query.slice(0, slash + 1)
+      const fragment = slash < 0 ? '' : query.slice(slash + 1)
+      return this.listDirectory(directory, fragment, signal)
+    }
+    const indexed = await waitForPromise(this.ensureIndex(), signal)
+    return rankCandidates(
+      indexed.filter(candidate => visibleForGlobalQuery(candidate.path, query)),
+      query,
+      this.config.maxResults,
+    )
+  }
+
+  /** Discard the current index so the next bare query observes a fresh tree. */
+  invalidate(): void {
+    this.generation?.controller.abort(new Error('file search index invalidated'))
+    this.generation = undefined
+  }
+
+  /** Abort traversal and make later queries return no candidates. */
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.invalidate()
+  }
+
+  private ensureIndex(): Promise<IndexedPath[]> {
+    if (this.generation !== undefined) return this.generation.promise
+    const controller = new AbortController()
+    const generation = {
+      controller,
+      promise: Promise.resolve([] as IndexedPath[]),
+    } satisfies IndexGeneration
+    generation.promise = this.scanWorkspace(controller.signal).catch((error: unknown) => {
+      /* v8 ignore next -- every owned abort clears `generation` synchronously; this only protects an unexpected scan failure */
+      if (this.generation === generation) this.generation = undefined
+      throw error
+    })
+    this.generation = generation
+    return generation.promise
+  }
+
+  private async scanWorkspace(signal: AbortSignal): Promise<IndexedPath[]> {
+    const indexed: IndexedPath[] = []
+    const directories: { absolute: string; relative: string }[] = [{ absolute: this.root, relative: '' }]
+    for (let cursor = 0; cursor < directories.length && indexed.length < this.config.maxEntries; cursor += 1) {
+      signal.throwIfAborted()
+      const directory = directories[cursor]
+      /* v8 ignore next 3 -- cursor is bounded by this exact queue's length. */
+      if (directory === undefined) {
+        throw new Error('file search selected a missing directory')
+      }
+      const entries = await readDirectory(directory.absolute, signal)
+      for (const entry of entries) {
+        signal.throwIfAborted()
+        const path = directory.relative === '' ? entry.name : `${directory.relative}/${entry.name}`
+        if (entry.isDirectory()) {
+          if (this.excludedDirectories.has(entry.name)) continue
+          indexed.push({ path, kind: 'directory' })
+          directories.push({ absolute: join(directory.absolute, entry.name), relative: path })
+        } else if (entry.isFile()) {
+          indexed.push({ path, kind: 'file' })
+        }
+        if (indexed.length >= this.config.maxEntries) break
+      }
+    }
+    return indexed
+  }
+
+  private async listDirectory(
+    displayDirectory: string,
+    fragment: string,
+    signal: AbortSignal,
+  ): Promise<FileSearchCandidate[]> {
+    if (displayDirectory.split('/').some(segment => this.excludedDirectories.has(segment))) return []
+    const absolute = await resolveDisplayDirectory(this.root, displayDirectory, signal)
+    if (absolute === undefined) return []
+    const entries = await readDirectory(absolute, signal)
+    const candidates: FileSearchCandidate[] = []
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') && !fragment.startsWith('.')) continue
+      if (entry.isDirectory()) {
+        if (this.excludedDirectories.has(entry.name)) continue
+        candidates.push({ path: `${displayDirectory}${entry.name}`, kind: 'directory' })
+      } else if (entry.isFile()) {
+        candidates.push({ path: `${displayDirectory}${entry.name}`, kind: 'file' })
+      }
+    }
+    return rankCandidates(candidates, fragment, this.config.maxResults)
+  }
+}
+
+async function resolveDisplayDirectory(
+  root: string,
+  displayDirectory: string,
+  signal: AbortSignal,
+): Promise<string | undefined> {
+  const resolvedRoot = resolve(root)
+  const absolute = resolve(resolvedRoot, displayDirectory === '' ? '.' : displayDirectory)
+  const fromRoot = relative(resolvedRoot, absolute)
+  if (fromRoot === '..' || fromRoot.startsWith(`..${sep}`)) return undefined
+  /* v8 ignore next -- only Windows can produce a cross-volume absolute relative path */
+  if (isAbsolute(fromRoot)) return undefined
+  let current = resolvedRoot
+  for (const segment of fromRoot.split(sep).filter(Boolean)) {
+    signal.throwIfAborted()
+    current = join(current, segment)
+    try {
+      const status = await lstat(current)
+      signal.throwIfAborted()
+      if (status.isSymbolicLink() || !status.isDirectory()) return undefined
+    } catch (_error: unknown) {
+      signal.throwIfAborted()
+      return undefined
+    }
+  }
+  return absolute
+}
+
+async function readDirectory(absolute: string, signal: AbortSignal) {
+  signal.throwIfAborted()
+  try {
+    const entries = await readdir(absolute, { withFileTypes: true })
+    signal.throwIfAborted()
+    return entries.sort((left, right) => compareText(left.name, right.name))
+  } catch (_error: unknown) {
+    signal.throwIfAborted()
+    // An unreadable/missing subtree contributes no candidates; other readable
+    // branches remain useful and autocomplete is advisory.
+    return []
+  }
+}
+
+function visibleForGlobalQuery(path: string, query: string): boolean {
+  if (query.startsWith('.') || query.includes('/.')) return true
+  return !path.split('/').some(segment => segment.startsWith('.'))
+}
+
+function rankCandidates(
+  candidates: readonly FileSearchCandidate[],
+  query: string,
+  limit: number,
+): FileSearchCandidate[] {
+  const ranked: RankedPath[] = []
+  for (const candidate of candidates) {
+    const score = scoreCandidate(candidate, query)
+    if (score !== undefined) ranked.push({ candidate, score })
+  }
+  ranked.sort((left, right) =>
+    right.score - left.score
+    || kindRank(left.candidate.kind) - kindRank(right.candidate.kind)
+    || (query === '' ? 0 : left.candidate.path.length - right.candidate.path.length)
+    || compareText(left.candidate.path, right.candidate.path))
+  return ranked.slice(0, limit).map(entry => entry.candidate)
+}
+
+function scoreCandidate(candidate: FileSearchCandidate, query: string): number | undefined {
+  if (query === '') return 0
+  const path = candidate.path.toLowerCase()
+  const name = path.slice(path.lastIndexOf('/') + 1)
+  const needle = query.toLowerCase()
+  const directoryBonus = candidate.kind === 'directory' ? 25 : 0
+  if (name === needle) return 1_000 + directoryBonus
+  if (name.startsWith(needle)) return 900 + directoryBonus
+  if (name.includes(needle)) return 700 + directoryBonus
+  if (path.includes(needle)) return 500 + directoryBonus
+  const subsequence = subsequenceScore(path, needle)
+  return subsequence === undefined ? undefined : 300 + subsequence + directoryBonus
+}
+
+function subsequenceScore(target: string, query: string): number | undefined {
+  let targetIndex = 0
+  let gap = 0
+  for (const character of query) {
+    const found = target.indexOf(character, targetIndex)
+    if (found < 0) return undefined
+    gap += found - targetIndex
+    targetIndex = found + 1
+  }
+  return Math.max(0, 100 - gap)
+}
+
+function kindRank(kind: FileSearchCandidate['kind']): number {
+  return kind === 'directory' ? 0 : 1
+}
+
+function compareText(left: string, right: string): number {
+  /* v8 ignore next -- entries and candidates are unique; host enumeration
+   * order determines which comparison direction sort requests. */
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+function waitForPromise<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  /* v8 ignore next -- `list()` checks this signal immediately before its synchronous call into this helper */
+  if (signal.aborted) return Promise.reject(errorReason(signal.reason, 'file search aborted'))
+  return new Promise<T>((resolvePromise, rejectPromise) => {
+    const onAbort = (): void => { rejectPromise(errorReason(signal.reason, 'file search aborted')) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolvePromise(value)
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', onAbort)
+        rejectPromise(errorReason(error, 'file search index failed'))
+      },
+    )
+  })
+}
+
+function errorReason(reason: unknown, fallback: string): Error {
+  return reason instanceof Error ? reason : new Error(fallback, { cause: reason })
+}
diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts
index 4a16aa87d0..de0ef02f7e 100644
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -31,13 +31,12 @@ import {
   type EditorTheme,
   type Focusable,
   type MarkdownTheme,
-  type OverlayHandle,
   type SelectListTheme,
   type SlashCommand,
   type Terminal,
   type TerminalColorScheme,
 } from '@earendil-works/pi-tui'
-import type { Context } from 'cordis'
+import { Service, type Context, type Fiber } from 'cordis'
 import z from 'schemastery'
 import {
   installAgentLlmTarget,
@@ -61,18 +60,24 @@ import type {} from '@deepseek-ai/dsh-llm-retry'
 import {
   displayPromptContent,
   SessionId,
+  type JsonValue,
   type Session,
   type SessionEvent,
   type SessionHeader,
   type TodoItem,
 } from '@deepseek-ai/dsh-session'
+import { foldGoal, type GoalPhase } from '@deepseek-ai/dsh-goal'
 import {
   formatSessionReferenceMention,
   parseSessionReferenceText,
   type SessionReferenceService,
 } from '@deepseek-ai/dsh-session-reference'
 import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
-// Side-effect type import: declaration-merges the optional `sessionPersistence`
+import type {
+  SessionLogSnapshot,
+  SessionRecord,
+} from '@deepseek-ai/dsh-session-query'
+// Type import also declaration-merges the optional `sessionPersistence`
 // service onto `Context` so `ctx.get('sessionPersistence')` is typed.
 import type {} from '@deepseek-ai/dsh-session-persistence'
 import type { SkillDefinition, SkillResourceBase, SkillService } from '@deepseek-ai/dsh-skill'
@@ -90,11 +95,97 @@ import {
   type AskUserQuestionItem,
   type AskUserQuestionRequest,
 } from '@deepseek-ai/dsh-user-interaction'
+import {
+  TuiExtensionServiceImpl,
+  TuiOverlayManager,
+} from './overlay-manager.ts'
+import type {
+  TuiOverlayRequest,
+  TuiOverlaySession,
+  TuiTheme,
+} from './extension.ts'
+
+export type {
+  TuiComponent,
+  TuiFocusable,
+  TuiOverlayAnchor,
+  TuiOverlayCloseReason,
+  TuiOverlayHost,
+  TuiOverlayMargin,
+  TuiOverlayOptions,
+  TuiOverlayOutcome,
+  TuiOverlayRequest,
+  TuiOverlaySession,
+  TuiOverlayState,
+  TuiTheme,
+  TuiViewport,
+} from './extension.ts'
+
+declare module 'cordis' {
+  interface Context {
+    /** Terminal-only interaction service, available only while a TUI is mounted. */
+    tui: TuiExtensionService
+    /** Optional process host that can replace this TUI with a resumed session. */
+    tuiResumeHost: TuiResumeHost
+  }
+}
+
+/** Process-lifecycle owner used by the shipped CLI for an atomic resume handoff. */
+export interface TuiResumeHost {
+  /**
+   * Dispose the current app and replace it with a runtime for `sessionId`.
+   * Success does not return. A host may reject before it commits teardown;
+   * after commit it owns fatal reporting and process exit.
+   * @param sessionId - validated persisted session selected by the user.
+   */
+  handoff(sessionId: SessionId): Promise<never>
+}
+
+/**
+ * Optional terminal-local interaction service provided by one mounted TUI.
+ *
+ * The concrete provider retains pi-tui, focus, and terminal lifecycle state.
+ * Plugins receive only effect-owned overlay sessions.
+ */
+export abstract class TuiExtensionService extends Service {
+  /** Exact agent driven by this terminal instance. */
+  abstract readonly agent: Agent
+
+  /**
+   * Queue an interactive overlay owned by the calling plugin fiber.
+   *
+   * The TUI displays one overlay at a time in FIFO order. Disposing the caller
+   * removes a queued overlay or closes an active one before plugin teardown
+   * settles. This live presentation is neither logged nor replayed.
+   *
+   * @param request - component factory, layout constraints, and cancellation.
+   * @returns the effect-owned overlay session.
+   * @throws when the TUI has begun shutting down.
+   */
+  abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession
+}
+import {
+  activeAtToken,
+  DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES,
+  DEFAULT_FILE_SEARCH_MAX_ENTRIES,
+  DEFAULT_FILE_SEARCH_MAX_RESULTS,
+  formatFileMention,
+  WorkspaceFileSearch,
+} from './file-autocomplete.ts'
+
+export {
+  DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES,
+  DEFAULT_FILE_SEARCH_MAX_ENTRIES,
+  DEFAULT_FILE_SEARCH_MAX_RESULTS,
+} from './file-autocomplete.ts'
 
 export const name = 'ui-tui'
-export const inject = ['agents', 'commands', 'userInteraction', 'tools', 'llm', 'systemPrompt', 'tokenMeter']
+export const inject = ['agents', 'sessions', 'commands', 'userInteraction', 'tools', 'llm', 'systemPrompt', 'tokenMeter']
 
-/** Presentation settings for the pi-tui terminal mode. */
+/** Model guidance for path-only file references selected through the TUI. */
+export const FILE_REFERENCE_PROMPT = 'Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.'
+
+/** Interaction and presentation settings for the pi-tui terminal mode. */
 export interface TuiConfig {
   /** Render model reasoning blocks. */
   showReasoning?: boolean
@@ -104,6 +195,8 @@ export interface TuiConfig {
   maxQuestionOptions?: number
   /** Maximum models visible at once in the model selector. */
   maxModelOptions?: number
+  /** Maximum sessions visible at once in the resume selector. */
+  maxResumeOptions?: number
   /** User-question panel width in terminal columns, clamped to the terminal. */
   questionDialogWidth?: number
   /** User-question panel maximum height in terminal rows. */
@@ -112,6 +205,12 @@ export interface TuiConfig {
   modelDialogWidth?: number
   /** Model-selector maximum height in terminal rows. */
   modelDialogMaxHeight?: number
+  /** Maximum fuzzy file candidates displayed for one `@` query. */
+  fileSearchMaxResults?: number
+  /** Maximum paths retained in one `@` workspace index. */
+  fileSearchMaxEntries?: number
+  /** Directory basenames excluded from `@` traversal and completion. */
+  fileSearchExcludedDirectories?: string[]
   /** Show the terminal's hardware cursor at the pi editor's IME marker. */
   showHardwareCursor?: boolean
   /** Apply the built-in ANSI color palette. */
@@ -131,31 +230,41 @@ const showReasoningSchema = z.boolean().default(true)
 const maxToolOutputLinesSchema = z.number().step(1).min(1).default(6)
 const maxQuestionOptionsSchema = z.number().step(1).min(1).default(8)
 const maxModelOptionsSchema = z.number().step(1).min(1).default(8)
+const maxResumeOptionsSchema = z.number().step(1).min(1).default(8)
 const questionDialogWidthSchema = z.number().step(1).min(20).default(200)
 const questionDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
 const modelDialogWidthSchema = z.number().step(1).min(20).default(72)
 const modelDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
+const fileSearchMaxResultsSchema = z.number().step(1).min(1).default(DEFAULT_FILE_SEARCH_MAX_RESULTS)
+const fileSearchMaxEntriesSchema = z.number().step(1).min(1).default(DEFAULT_FILE_SEARCH_MAX_ENTRIES)
+const fileSearchExcludedDirectoriesSchema = z.array(z.string()).default([...DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES])
 const showHardwareCursorSchema = z.boolean().default(false)
 const colorSchema = z.boolean().default(true)
 // No default: an unset value auto-detects truecolor from COLORTERM in `apply`.
 const truecolorSchema = z.boolean()
 const titleSchema = z.string().default('DeepSeek Harness')
 
-/** Schemastery schema for presentation settings embedded by app bundles. */
-export const TuiConfigSchema: z<TuiConfig> = z.object({
+const tuiConfigSchemaFields = {
   showReasoning: showReasoningSchema,
   maxToolOutputLines: maxToolOutputLinesSchema,
   maxQuestionOptions: maxQuestionOptionsSchema,
   maxModelOptions: maxModelOptionsSchema,
+  maxResumeOptions: maxResumeOptionsSchema,
   questionDialogWidth: questionDialogWidthSchema,
   questionDialogMaxHeight: questionDialogMaxHeightSchema,
   modelDialogWidth: modelDialogWidthSchema,
   modelDialogMaxHeight: modelDialogMaxHeightSchema,
+  fileSearchMaxResults: fileSearchMaxResultsSchema,
+  fileSearchMaxEntries: fileSearchMaxEntriesSchema,
+  fileSearchExcludedDirectories: fileSearchExcludedDirectoriesSchema,
   showHardwareCursor: showHardwareCursorSchema,
   color: colorSchema,
   truecolor: truecolorSchema,
   title: titleSchema,
-})
+}
+
+/** Schemastery schema for presentation settings embedded by app bundles. */
+export const TuiConfigSchema: z<TuiConfig> = z.object(tuiConfigSchemaFields)
 
 /** Serializable plugin configuration. */
 export interface Config extends TuiConfig {
@@ -164,11 +273,10 @@ export interface Config extends TuiConfig {
   /** Exact shared agent/session identity driven by this terminal. Defaults to `main`. */
   sessionId?: string
   /**
-   * Shell command template shown for resuming this session: printed on exit and
-   * listed by `/resume`, with every `{session}` occurrence replaced by the live
-   * session id. Absent disables both surfaces. Deployments set it only when a
-   * persistence backend makes the session resumable (e.g.
-   * `RESUME_SESSION_ID={session} dsh`).
+   * Shell command fallback printed on exit or after selecting a session when
+   * the host cannot hand off in place. Every `{session}` becomes the selected
+   * id; the TUI never executes this text. Absent disables only the fallback,
+   * not the interactive selector.
    */
   resumeCommand?: string
 }
@@ -177,18 +285,22 @@ export const Config: z<Config> = z.object({
   welcome: z.string(),
   sessionId: z.string().default('main'),
   resumeCommand: z.string(),
-  showReasoning: showReasoningSchema,
-  maxToolOutputLines: maxToolOutputLinesSchema,
-  maxQuestionOptions: maxQuestionOptionsSchema,
-  maxModelOptions: maxModelOptionsSchema,
-  questionDialogWidth: questionDialogWidthSchema,
-  questionDialogMaxHeight: questionDialogMaxHeightSchema,
-  modelDialogWidth: modelDialogWidthSchema,
-  modelDialogMaxHeight: modelDialogMaxHeightSchema,
-  showHardwareCursor: showHardwareCursorSchema,
-  color: colorSchema,
-  truecolor: truecolorSchema,
-  title: titleSchema,
+  showReasoning: tuiConfigSchemaFields.showReasoning,
+  maxToolOutputLines: tuiConfigSchemaFields.maxToolOutputLines,
+  maxQuestionOptions: tuiConfigSchemaFields.maxQuestionOptions,
+  maxModelOptions: tuiConfigSchemaFields.maxModelOptions,
+  maxResumeOptions: tuiConfigSchemaFields.maxResumeOptions,
+  questionDialogWidth: tuiConfigSchemaFields.questionDialogWidth,
+  questionDialogMaxHeight: tuiConfigSchemaFields.questionDialogMaxHeight,
+  modelDialogWidth: tuiConfigSchemaFields.modelDialogWidth,
+  modelDialogMaxHeight: tuiConfigSchemaFields.modelDialogMaxHeight,
+  fileSearchMaxResults: tuiConfigSchemaFields.fileSearchMaxResults,
+  fileSearchMaxEntries: tuiConfigSchemaFields.fileSearchMaxEntries,
+  fileSearchExcludedDirectories: tuiConfigSchemaFields.fileSearchExcludedDirectories,
+  showHardwareCursor: tuiConfigSchemaFields.showHardwareCursor,
+  color: tuiConfigSchemaFields.color,
+  truecolor: tuiConfigSchemaFields.truecolor,
+  title: tuiConfigSchemaFields.title,
 })
 
 /** Fully defaulted TUI presentation settings. */
@@ -197,10 +309,14 @@ export interface ResolvedTuiConfig {
   maxToolOutputLines: number
   maxQuestionOptions: number
   maxModelOptions: number
+  maxResumeOptions: number
   questionDialogWidth: number
   questionDialogMaxHeight: number
   modelDialogWidth: number
   modelDialogMaxHeight: number
+  fileSearchMaxResults: number
+  fileSearchMaxEntries: number
+  fileSearchExcludedDirectories: string[]
   showHardwareCursor: boolean
   color: boolean
   truecolor: boolean
@@ -221,6 +337,8 @@ export interface TuiRuntime {
   formatCwd?: (cwd: string | undefined) => string
   /** Monotonic-enough wall clock for elapsed status rendering. Defaults to `Date.now`. */
   now?(): number
+  /** Host-owned process handoff; absent leaves `resumeCommand` as the fallback. */
+  handoffResume?: TuiResumeHost['handoff']
 }
 
 /**
@@ -235,10 +353,14 @@ export function resolveTuiConfig(config: TuiConfig | undefined): ResolvedTuiConf
     maxToolOutputLines: config?.maxToolOutputLines ?? 6,
     maxQuestionOptions: config?.maxQuestionOptions ?? 8,
     maxModelOptions: config?.maxModelOptions ?? 8,
+    maxResumeOptions: config?.maxResumeOptions ?? 8,
     questionDialogWidth: config?.questionDialogWidth ?? 200,
     questionDialogMaxHeight: config?.questionDialogMaxHeight ?? 20,
     modelDialogWidth: config?.modelDialogWidth ?? 72,
     modelDialogMaxHeight: config?.modelDialogMaxHeight ?? 20,
+    fileSearchMaxResults: config?.fileSearchMaxResults ?? DEFAULT_FILE_SEARCH_MAX_RESULTS,
+    fileSearchMaxEntries: config?.fileSearchMaxEntries ?? DEFAULT_FILE_SEARCH_MAX_ENTRIES,
+    fileSearchExcludedDirectories: [...(config?.fileSearchExcludedDirectories ?? DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES)],
     showHardwareCursor: config?.showHardwareCursor ?? false,
     color: config?.color ?? true,
     truecolor: config?.truecolor ?? false,
@@ -271,6 +393,11 @@ function ansi(open: string, close: string, enabled: boolean): (text: string) =>
 }
 
 const TERMINAL_CONTROL_PATTERN = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/gu
+const TERMINAL_OSC_PATTERN = /(?:\u001B\]|\u009D)(?:(?!\u0007|\u001B\\)[\s\S])*(?:\u0007|\u001B\\|$)/gu
+const TERMINAL_CSI_PATTERN = /(?:\u001B\[|\u009B)[0-?]*[ -/]*[@-~]/gu
+const TERMINAL_ESCAPE_PATTERN = /\u001B[@-_]/gu
+const BRACKETED_PASTE_START = '\u001B[200~'
+const BRACKETED_PASTE_END = '\u001B[201~'
 
 /**
  * Escape external C0/C1 controls before pi-tui adds application-owned ANSI.
@@ -286,6 +413,15 @@ function displayInlineText(text: string): string {
   return displayText(text).replaceAll('\n', '\\x0a')
 }
 
+/** Remove terminal controls from clipboard text before an editable field stores it. */
+function sanitizePastedText(text: string): string {
+  return text
+    .replace(TERMINAL_OSC_PATTERN, '')
+    .replace(TERMINAL_CSI_PATTERN, '')
+    .replace(TERMINAL_ESCAPE_PATTERN, '')
+    .replace(TERMINAL_CONTROL_PATTERN, '')
+}
+
 /**
  * Theme-agnostic palette built from the standard 16-color ANSI set plus SGR
  * attributes, which every terminal remaps to its active color scheme. Body
@@ -745,7 +881,7 @@ function diffLines(diff: FileDiff, palette: Palette): string[] {
 }
 
 class ToolCardComponent implements Component {
-  private result: { content: ContentBlock[]; isError: boolean; meta?: unknown } | undefined
+  private result: { content: ContentBlock[]; isError: boolean; meta?: JsonValue } | undefined
   private expanded = false
   private callView: ToolCallView
   private resultView: ToolResultView | undefined
@@ -1140,6 +1276,248 @@ class ModelDialog implements Component {
   }
 }
 
+interface ResumeRoute {
+  provider: string
+  model: string
+}
+
+interface ResumeCandidate {
+  record: SessionRecord
+  title: string
+  lastActivityAt: number
+  lastTurn: string
+  route?: ResumeRoute
+  goalPhase?: GoalPhase
+  disabledReason?: string
+}
+
+function resumeTurnLabel(snapshot: SessionLogSnapshot): string {
+  const event = snapshot.events.findLast(item => item.type === 'turn/end')
+  if (event === undefined) return 'no completed turn'
+  const reason = event.data.reason
+  switch (reason.kind) {
+    case 'completed': return `turn ${event.data.turn}: completed`
+    case 'aborted': return `turn ${event.data.turn}: cancelled`
+    case 'error': return `turn ${event.data.turn}: error`
+    case 'disposed': return `turn ${event.data.turn}: disposed`
+    case 'max-tokens': return `turn ${event.data.turn}: max tokens`
+    case 'rejected': return `turn ${event.data.turn}: rejected`
+    case 'interrupted': return `turn ${event.data.turn}: interrupted`
+    default: return `turn ${event.data.turn}: unknown result`
+  }
+}
+
+function resumeRoute(snapshot: SessionLogSnapshot): ResumeRoute | undefined {
+  const header = snapshot.events.findLast(item => item.type === 'request/header')
+  if (header?.type === 'request/header') {
+    return { provider: header.data.header.config.provider, model: header.data.header.config.model }
+  }
+  const assistant = snapshot.events.findLast(item => item.type === 'assistant/message')
+  return assistant?.type === 'assistant/message'
+    ? { provider: assistant.data.provenance.provider, model: assistant.data.provenance.model }
+    : undefined
+}
+
+function summarizeResumeCandidate(
+  record: SessionRecord,
+  snapshot: SessionLogSnapshot,
+  currentId: SessionId,
+  cwd: string | undefined,
+  availableProviders: ReadonlySet<string>,
+): ResumeCandidate {
+  const title = foldSessionTitle(snapshot.events)?.title ?? 'Untitled session'
+  const route = resumeRoute(snapshot)
+  const foldedGoal = foldGoal(snapshot.events).goal
+  let disabledReason: string | undefined
+  if (record.header.id === currentId) disabledReason = 'current session'
+  else if (record.live) disabledReason = 'session is already live in this runtime'
+  else if (record.header.cwd !== cwd) disabledReason = 'different workspace'
+  else if (route !== undefined && !availableProviders.has(route.provider)) {
+    disabledReason = `session is complete, but route is currently unavailable (${route.provider}/${route.model})`
+  }
+  return {
+    record,
+    title,
+    lastActivityAt: snapshot.events.at(-1)?.time ?? snapshot.session.createdAt,
+    lastTurn: resumeTurnLabel(snapshot),
+    ...route === undefined ? {} : { route },
+    ...foldedGoal === undefined ? {} : { goalPhase: foldedGoal.phase },
+    ...disabledReason === undefined ? {} : { disabledReason },
+  }
+}
+
+/** Full-viewport keyboard selector over detached, preflighted resume summaries. */
+class ResumePicker implements Component, Focusable {
+  private readonly search = new Input()
+  private pasteBuffer: string | undefined
+  private selectedIndex = 0
+  private error = ''
+  focused = false
+
+  constructor(
+    private readonly candidates: readonly ResumeCandidate[],
+    private readonly maxVisible: number,
+    private readonly workspaceLabel: string,
+    private readonly viewportRows: () => number,
+    private readonly palette: Palette,
+    private readonly done: (candidate: ResumeCandidate) => void,
+    private readonly cancel: () => void,
+  ) {}
+
+  invalidate(): void {
+    this.search.invalidate()
+  }
+
+  private filtered(): ResumeCandidate[] {
+    const query = this.search.getValue().trim().toLocaleLowerCase()
+    if (query === '') return [...this.candidates]
+    return this.candidates.filter(candidate => candidate.title.toLocaleLowerCase().includes(query)
+      || candidate.record.header.id.toLocaleLowerCase().includes(query))
+  }
+
+  private visibleCandidateCount(): number {
+    const candidateBudget = Math.max(1, Math.floor((Math.max(1, this.viewportRows()) - 13) / 4))
+    return Math.min(this.maxVisible, candidateBudget)
+  }
+
+  private handleBracketedPaste(data: string): boolean {
+    const start = data.indexOf(BRACKETED_PASTE_START)
+    if (this.pasteBuffer === undefined && start < 0) return false
+    if (this.pasteBuffer === undefined) {
+      const prefix = data.slice(0, start)
+      if (prefix !== '') this.handleInput(prefix)
+      this.pasteBuffer = data.slice(start + BRACKETED_PASTE_START.length)
+    } else {
+      this.pasteBuffer += data
+    }
+    const end = this.pasteBuffer.indexOf(BRACKETED_PASTE_END)
+    if (end < 0) return true
+    const pasted = sanitizePastedText(this.pasteBuffer.slice(0, end))
+    const remaining = this.pasteBuffer.slice(end + BRACKETED_PASTE_END.length)
+    this.pasteBuffer = undefined
+    const previous = this.search.getValue()
+    this.search.handleInput(`${BRACKETED_PASTE_START}${pasted}${BRACKETED_PASTE_END}`)
+    if (this.search.getValue() !== previous) {
+      this.selectedIndex = 0
+      this.error = ''
+    }
+    if (remaining !== '') this.handleInput(remaining)
+    this.invalidate()
+    return true
+  }
+
+  handleInput(data: string): void {
+    if (this.handleBracketedPaste(data)) return
+    const filtered = this.filtered()
+    if (matchesKey(data, Key.ctrl('c'))) {
+      this.cancel()
+      return
+    }
+    if (matchesKey(data, Key.escape)) {
+      if (this.search.getValue() === '') this.cancel()
+      else {
+        this.search.setValue('')
+        this.selectedIndex = 0
+        this.error = ''
+      }
+    } else if (matchesKey(data, Key.up)) {
+      this.selectedIndex = filtered.length === 0
+        ? 0
+        : (this.selectedIndex + filtered.length - 1) % filtered.length
+    } else if (matchesKey(data, Key.down)) {
+      this.selectedIndex = filtered.length === 0 ? 0 : (this.selectedIndex + 1) % filtered.length
+    } else if (matchesKey(data, Key.pageUp)) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - this.visibleCandidateCount())
+    } else if (matchesKey(data, Key.pageDown)) {
+      this.selectedIndex = Math.min(
+        Math.max(0, filtered.length - 1),
+        this.selectedIndex + this.visibleCandidateCount(),
+      )
+    } else if (matchesKey(data, Key.enter)) {
+      const selected = filtered[this.selectedIndex]
+      if (selected === undefined) this.error = 'No session matches this search.'
+      else if (selected.disabledReason !== undefined) this.error = selected.disabledReason
+      else this.done(selected)
+    } else {
+      const previous = this.search.getValue()
+      this.search.focused = this.focused
+      this.search.handleInput(data)
+      if (this.search.getValue() !== previous) {
+        this.selectedIndex = 0
+        this.error = ''
+      }
+    }
+    this.invalidate()
+  }
+
+  render(width: number): string[] {
+    this.search.focused = this.focused
+    const height = Math.max(1, this.viewportRows())
+    const horizontalPadding = width >= 12 ? 2 : 0
+    const contentWidth = Math.max(1, width - horizontalPadding * 2)
+    const indent = ' '.repeat(horizontalPadding)
+    const filtered = this.filtered()
+    if (this.selectedIndex >= filtered.length) this.selectedIndex = Math.max(0, filtered.length - 1)
+    const selected = filtered[this.selectedIndex]
+    const position = selected === undefined ? 0 : this.selectedIndex + 1
+    const lines: string[] = [
+      '',
+      `${indent}${this.palette.bold(this.palette.accent(`Resume session (${position} of ${filtered.length})`))}`,
+      '',
+    ]
+
+    const searchInnerWidth = Math.max(1, contentWidth - 4)
+    lines.push(`${indent}${this.palette.dim(`╭${'─'.repeat(Math.max(0, contentWidth - 2))}╮`)}`)
+    const searchContent = this.search.render(searchInnerWidth).join('').replace(/^> /u, '⌕ ')
+    const clippedSearch = truncateToWidth(searchContent, searchInnerWidth, '')
+    lines.push(
+      `${indent}${this.palette.dim('│')} ${clippedSearch}${' '.repeat(Math.max(0, searchInnerWidth - visibleWidth(clippedSearch)))} ${this.palette.dim('│')}`,
+      `${indent}${this.palette.dim(`╰${'─'.repeat(Math.max(0, contentWidth - 2))}╯`)}`,
+      '',
+      `${indent}${this.palette.muted(displayText(this.workspaceLabel))}`,
+      '',
+    )
+
+    const visibleCount = this.visibleCandidateCount()
+    const start = Math.max(0, Math.min(
+      this.selectedIndex - Math.floor(visibleCount / 2),
+      filtered.length - visibleCount,
+    ))
+    const end = Math.min(filtered.length, start + visibleCount)
+    const push = (line: string): void => {
+      lines.push(`${indent}${truncateToWidth(line, contentWidth, '…')}`)
+    }
+    for (let index = start; index < end; index += 1) {
+      const candidate = filtered[index] as ResumeCandidate
+      const active = index === this.selectedIndex
+      const status = [
+        candidate.disabledReason === 'current session' ? 'current' : undefined,
+        candidate.record.live ? 'live' : undefined,
+        candidate.record.persisted ? 'persisted' : undefined,
+      ].filter((value): value is string => value !== undefined).join(' · ')
+      const lead = `${active ? '❯' : ' '} ${displayText(candidate.title)}`
+      push(active ? this.palette.bold(this.palette.accent(lead)) : lead)
+      const route = candidate.route === undefined ? 'route unavailable' : `${candidate.route.provider}/${candidate.route.model}`
+      const goal = candidate.goalPhase === undefined ? '' : ` · goal ${candidate.goalPhase}`
+      push(this.palette.muted(`  ${new Date(candidate.lastActivityAt).toISOString()} · ${candidate.lastTurn} · ${route}${goal}`))
+      push(this.palette.dim(`  ${status} · ${displayText(candidate.record.header.id)}`))
+      if (candidate.disabledReason !== undefined) {
+        push(this.palette.warning(`  unavailable: ${displayText(candidate.disabledReason)}`))
+      }
+    }
+    if (filtered.length === 0) push(this.palette.warning('No matching sessions.'))
+    if (this.error !== '') {
+      lines.push('')
+      push(this.palette.error(displayText(this.error)))
+    }
+
+    const footer = `${indent}${this.palette.dim('Type to search  •  ↑/↓ navigate  •  Enter resume  •  Esc clear/cancel')}`
+    while (lines.length < height - 2) lines.push('')
+    lines.push(footer, '')
+    return lines.slice(0, height)
+  }
+}
+
 class QuestionDialog implements Component, Focusable {
   private selectedIndex = 0
   private selected = new Set<number>()
@@ -1290,14 +1668,15 @@ interface PendingQuestion {
   resolve(answer: AskUserQuestionAnswer): void
   reject(error: unknown): void
   onAbort: () => void
-  overlay: OverlayHandle | undefined
+  overlay: TuiOverlaySession | undefined
 }
 
-/** Add session candidates to pi-tui's existing command/file provider. */
-class SessionAutocompleteProvider implements AutocompleteProvider {
+/** Merge path-only file candidates and optional session snapshots with commands. */
+class ReferenceAutocompleteProvider implements AutocompleteProvider {
   constructor(
     private readonly base: CombinedAutocompleteProvider,
-    private readonly sessions: SessionReferenceService,
+    private readonly files: WorkspaceFileSearch,
+    private readonly sessions: SessionReferenceService | undefined,
     private readonly agent: Agent,
   ) {}
 
@@ -1311,17 +1690,33 @@ class SessionAutocompleteProvider implements AutocompleteProvider {
     const currentLine = lines[cursorLine]
     /* v8 ignore next -- Editor always supplies its current state line. */
     if (currentLine === undefined) return basePromise
-    const token = /(?:^|\s)(@[^\s]*)$/u.exec(currentLine.slice(0, cursorCol))?.[1]
-    if (token === undefined) return basePromise
-    let candidates
-    try {
-      candidates = await this.sessions.listCandidates(this.agent, token.slice(1), undefined, options.signal)
-    } catch {
+    const token = activeAtToken(currentLine, cursorCol)
+    if (token === undefined) {
+      this.files.invalidate()
       return basePromise
     }
-    const base = await basePromise
+    const filePromise = this.files.list(token.query, options.signal).catch(() => [])
+    const sessionPromise = this.sessions === undefined || token.quoted
+      ? Promise.resolve([])
+      : this.sessions.listCandidates(this.agent, token.query, undefined, options.signal).catch(() => [])
+    const [base, fileCandidates, sessionCandidates] = await Promise.all([
+      basePromise,
+      filePromise,
+      sessionPromise,
+    ])
     if (options.signal.aborted) return base
-    const items: AutocompleteItem[] = candidates.map((candidate) => {
+    const fileItems: AutocompleteItem[] = fileCandidates.flatMap((candidate) => {
+      const value = formatFileMention(candidate, token.quoted)
+      if (value === undefined) return []
+      const name = candidate.path.slice(candidate.path.lastIndexOf('/') + 1)
+      const directory = candidate.kind === 'directory'
+      return [{
+        value,
+        label: `${directory ? 'Folder' : 'File'} · ${displayInlineText(name)}${directory ? '/' : ''}`,
+        description: displayInlineText(candidate.path),
+      }]
+    })
+    const sessionItems: AutocompleteItem[] = sessionCandidates.map((candidate) => {
       const mentionLabel = displayInlineText(candidate.label)
       const sessionId = displayInlineText(candidate.sessionId)
       const location = candidate.cwd === undefined ? '(no cwd)' : displayInlineText(candidate.cwd)
@@ -1332,8 +1727,9 @@ class SessionAutocompleteProvider implements AutocompleteProvider {
         description,
       }
     })
+    const items = [...fileItems, ...sessionItems]
     if (items.length === 0) return base
-    return { items: [...items, ...(base?.items ?? [])], prefix: token }
+    return { items: [...items, ...(base?.items ?? [])], prefix: token.prefix }
   }
 
   applyCompletion(
@@ -1471,6 +1867,7 @@ export function createTuiChat(
   const agent = ctx.agents.get(sessionId)
   if (agent === undefined) throw new Error(`ui-tui: session "${sessionId}" is not running`)
   const persistence = ctx.get('sessionPersistence')
+  const sessionQuery = ctx.get('sessionQuery')
   const resolved = resolveTuiConfig(config)
   const palette = createPalette(resolved.color)
   const mdTheme = markdownTheme(palette)
@@ -1487,14 +1884,15 @@ export function createTuiChat(
   let toolsExpanded = false
   let streaming: StreamingAssistantComponent | undefined
   let runningStatus: RunningStatus | undefined
-  // Steering messages queued during the running turn (`agent/queued`) that the
-  // loop has not yet drained, shown as a badge on the status line. Each entry is
-  // the queued message's serialized source: a drain (`steering/message`) removes
-  // one MATCHING entry, so loop-authored steering — continuation reasons enter
-  // the inbox without an `agent/queued` event — cannot consume a pending user
-  // message's slot. Cleared on leaving `running`, which also absorbs a
-  // cancellation that discards the queue without logging drains; the status
-  // line exists only while running, so idle carries no badge to keep current.
+  // Steering messages queued during the running turn (`agent/inbox/enqueue`
+  // with `info.steering`) that the loop has not yet drained, shown as a badge on
+  // the status line. Each entry is the queued message's serialized source: a
+  // drain (`steering/message`) removes one MATCHING entry, so a loop-authored
+  // continuation reason (which enqueues and drains under its own source) pushes
+  // and pops its own slot and cannot consume a pending user message's slot.
+  // Cleared on leaving `running`, which also absorbs a cancellation that
+  // discards the queue without logging drains; the status line exists only
+  // while running, so idle carries no badge to keep current.
   const pendingSteering: string[] = []
   let disposed = false
   let shuttingDown: Promise<void> | undefined
@@ -1502,6 +1900,11 @@ export function createTuiChat(
   // rather than declaring an injection that would make the TUI require them.
   const skills = ctx.get('skills')
   const cwd = agent.session.header.cwd ?? process.cwd()
+  const fileSearch = new WorkspaceFileSearch(cwd, {
+    maxResults: resolved.fileSearchMaxResults,
+    maxEntries: resolved.fileSearchMaxEntries,
+    excludedDirectories: resolved.fileSearchExcludedDirectories,
+  })
   const skillAbort = new AbortController()
   const tokens = sessionTokens(agent.session)
   const toolCards = new Map<string, ToolCardComponent>()
@@ -1511,7 +1914,11 @@ export function createTuiChat(
   const commandControllers = new Set<AbortController>()
   const referenceControllers = new Set<AbortController>()
   let activeQuestion: PendingQuestion | undefined
-  let modelOverlay: OverlayHandle | undefined
+  let modelOverlay: TuiOverlaySession | undefined
+  let resumeOverlay: TuiOverlaySession | undefined
+  let resumeInFlight = false
+  let resumeScan = 0
+  let tuiServiceFiber: Fiber | undefined
   const target: AgentLlmTargetRef = { current: initialTarget(agent), assembled: undefined }
   let contextWindow: number | undefined
   let contextResolution: Promise<
@@ -1520,6 +1927,8 @@ export function createTuiChat(
   > | undefined
   let modelCommands = Promise.resolve()
   const now = (): number => runtime.now?.() ?? Date.now()
+  const agentStatus = (): AgentStatus => agent.status
+  const isDisposed = (): boolean => disposed
 
   // A configured subtitle renders as a banner line; when absent, the banner has
   // no subtitle. The banner itself sweeps in on start (see startBannerReveal).
@@ -1569,6 +1978,41 @@ export function createTuiChat(
     requestRender()
   }
 
+  const extensionTheme: TuiTheme = Object.freeze({
+    text: (value: string) => palette.text(value),
+    muted: (value: string) => palette.muted(value),
+    dim: (value: string) => palette.dim(value),
+    accent: (value: string) => palette.accent(value),
+    success: (value: string) => palette.success(value),
+    warning: (value: string) => palette.warning(value),
+    error: (value: string) => palette.error(value),
+    bold: (value: string) => palette.bold(value),
+  })
+  const overlayManager = new TuiOverlayManager({
+    viewport: () => Object.freeze({
+      columns: runtime.terminal.columns,
+      rows: runtime.terminal.rows,
+    }),
+    theme: () => extensionTheme,
+    display: displayText,
+    show: (component, options) => ui.showOverlay(component, options === undefined
+      ? undefined
+      : {
+        ...options,
+        ...typeof options.margin === 'object'
+          ? { margin: { ...options.margin } }
+          : {},
+      }),
+    invalidate: requestRender,
+    reportError: (error) => {
+      const message = errorChain(error)
+      ctx.logger.warn(`ui-tui: overlay failed: ${message}`)
+      /* v8 ignore next -- shutdown removes overlays before the terminal stops */
+      if (disposed) return
+      appendNotice(`TUI overlay failed: ${message}`, 'error')
+    },
+  })
+
   const disposeTargetListeners = installAgentLlmTarget(agent.ctx, target)
 
   const resolveContextWindow = (selected: AgentLlmTarget | undefined): void => {
@@ -1608,29 +2052,29 @@ export function createTuiChat(
       appendNotice(`Current model: ${current}\nNo models are advertised by registered providers.`, 'warning')
       return
     }
-    modelOverlay?.hide()
-    modelOverlay = undefined
-    const close = (): void => {
-      modelOverlay?.hide()
-      modelOverlay = undefined
-      requestRender()
-    }
-    const dialog = new ModelDialog(
-      choices,
-      target.current,
-      resolved.maxModelOptions,
-      palette,
-      (selected) => {
-        close()
-        selectModel(selected)
+    void modelOverlay?.close()
+    const session = overlayManager.open({
+      create: () => new ModelDialog(
+        choices,
+        target.current,
+        resolved.maxModelOptions,
+        palette,
+        (selected) => {
+          void session.close()
+          selectModel(selected)
+        },
+        () => { void session.close() },
+      ),
+      options: {
+        width: resolved.modelDialogWidth,
+        maxHeight: resolved.modelDialogMaxHeight,
+        anchor: 'center',
+        margin: 1,
       },
-      close,
-    )
-    modelOverlay = ui.showOverlay(dialog, {
-      width: resolved.modelDialogWidth,
-      maxHeight: resolved.modelDialogMaxHeight,
-      anchor: 'center',
-      margin: 1,
+    })
+    modelOverlay = session
+    void session.closed.then(() => {
+      if (modelOverlay === session) modelOverlay = undefined
     })
     requestRender()
   }
@@ -1795,6 +2239,29 @@ export function createTuiChat(
   const renderEvent = (event: SessionEvent, options: { addHistory: boolean; renderChunks: boolean }): void => {
     switch (event.type) {
       case 'user/message': {
+        // Injected context (plugin/goal source) renders as a dim context card,
+        // not a human bubble; only a direct human prompt is a user message. The
+        // boolean avoids narrowing `source`, so the label keeps its full union.
+        const source = event.data.source
+        if (source.kind !== 'user') {
+          const references = sessionReferenceCard(event.data.meta)
+          if (references !== undefined) {
+            chat.addChild(new Spacer(1))
+            chat.addChild(new Text(palette.dim(`Referenced sessions · ${references.map(displayText).join(', ')}`), 1, 0))
+            break
+          }
+          const text = displayText(contentText(event.data.content).trim())
+          if (text) {
+            // The tui type view lacks plugin-augmented source kinds (e.g. goal),
+            // so read the display label without narrowing on `kind`.
+            const labelled = source as { kind: string; plugin?: string }
+            const label = labelled.plugin ?? labelled.kind
+            chat.addChild(new Spacer(1))
+            chat.addChild(new Text(palette.dim(`Context · ${displayText(label)}`), 1, 0))
+            chat.addChild(new Text(palette.muted(text), 1, 0))
+          }
+          break
+        }
         const text = displayText(contentText(displayPromptContent(event.data)).trim())
         if (text) {
           chat.addChild(new Spacer(1))
@@ -1819,22 +2286,6 @@ export function createTuiChat(
         }
         break
       }
-      case 'context/message': {
-        const references = sessionReferenceCard(event.data.meta)
-        if (references !== undefined) {
-          chat.addChild(new Spacer(1))
-          chat.addChild(new Text(palette.dim(`Referenced sessions · ${references.map(displayText).join(', ')}`), 1, 0))
-          break
-        }
-        const text = displayText(contentText(event.data.content).trim())
-        if (text) {
-          const source = event.data.source.kind === 'plugin' ? event.data.source.plugin : event.data.source.kind
-          chat.addChild(new Spacer(1))
-          chat.addChild(new Text(palette.dim(`Context · ${displayText(source)}`), 1, 0))
-          chat.addChild(new Text(palette.muted(text), 1, 0))
-        }
-        break
-      }
       case 'prompt/blocked':
         appendNotice(`Prompt blocked: ${event.data.reason}`, 'warning')
         break
@@ -1919,7 +2370,6 @@ export function createTuiChat(
       const isSurface = event.type === 'user/message'
         || event.type === 'assistant/message'
         || event.type === 'tool/result'
-        || event.type === 'context/message'
         || event.type === 'steering/message'
       if (isSurface && !active.has(event.seq)) continue
       if (event.type === 'tool/call' && !activeCalls.has(event.data.callId)) continue
@@ -1933,7 +2383,7 @@ export function createTuiChat(
   }
 
   const rejectQuestion = (pending: PendingQuestion): void => {
-    pending.overlay?.hide()
+    void pending.overlay?.close()
     pending.overlay = undefined
     removeAbortListener(pending)
     pending.reject(new UserInteractionError(
@@ -1956,31 +2406,48 @@ export function createTuiChat(
         startNextQuestion()
         return
       }
-      const dialog = new QuestionDialog(
-        question,
-        pending.index + 1,
-        pending.request.questions.length,
-        pending.request.questions.length - pending.answers.length,
-        resolved.maxQuestionOptions,
-        palette,
-        (selection) => {
-          pending.overlay?.hide()
-          pending.overlay = undefined
-          pending.answers.push({ id: question.id, ...selection })
-          pending.index += 1
-          show()
+      const session = overlayManager.open({
+        ...pending.request.signal === undefined ? {} : { signal: pending.request.signal },
+        create: () => new QuestionDialog(
+          question,
+          pending.index + 1,
+          pending.request.questions.length,
+          pending.request.questions.length - pending.answers.length,
+          resolved.maxQuestionOptions,
+          palette,
+          (selection) => {
+            pending.overlay = undefined
+            void session.close()
+            pending.answers.push({ id: question.id, ...selection })
+            pending.index += 1
+            show()
+          },
+          () => {
+            activeQuestion = undefined
+            rejectQuestion(pending)
+            startNextQuestion()
+          },
+        ),
+        options: {
+          width: resolved.questionDialogWidth,
+          maxHeight: resolved.questionDialogMaxHeight,
+          anchor: 'bottom-left',
+          margin: { bottom: 1 },
         },
-        () => {
-          activeQuestion = undefined
-          rejectQuestion(pending)
-          startNextQuestion()
-        },
-      )
-      pending.overlay = ui.showOverlay(dialog, {
-        width: resolved.questionDialogWidth,
-        maxHeight: resolved.questionDialogMaxHeight,
-        anchor: 'bottom-left',
-        margin: { bottom: 1 },
+      })
+      pending.overlay = session
+      void session.closed.then((result) => {
+        if (pending.overlay !== session) return
+        pending.overlay = undefined
+        /* v8 ignore next 2 -- close, abort, and shutdown settle the owner before this callback */
+        if (result.reason !== 'error') return
+        activeQuestion = undefined
+        removeAbortListener(pending)
+        pending.reject(new UserInteractionError(
+          `ask_user_question TUI failed: ${errorChain(result.error)}`,
+          'ASK_ABORTED',
+        ))
+        startNextQuestion()
       })
       requestRender()
     }
@@ -2032,7 +2499,6 @@ export function createTuiChat(
     }
     return all
       .filter(header => header.cwd === agent.session.header.cwd)
-      .sort((a, b) => b.createdAt - a.createdAt)
   }
 
   /**
@@ -2051,20 +2517,23 @@ export function createTuiChat(
   const shutdown = (exitProcess: boolean): Promise<void> => {
     shuttingDown ??= (async () => {
       disposed = true
+      overlayManager.beginShutdown()
       contextResolution = undefined
       clearStatus()
-      modelOverlay?.hide()
-      modelOverlay = undefined
       for (const controller of commandControllers) controller.abort(new Error('TUI disposed'))
       commandControllers.clear()
       for (const controller of referenceControllers) controller.abort(new Error('TUI disposed'))
       referenceControllers.clear()
+      await tuiServiceFiber?.dispose()
+      tuiServiceFiber = undefined
       if (activeQuestion !== undefined) {
         const pending = activeQuestion
         activeQuestion = undefined
         rejectQuestion(pending)
       }
       for (const pending of questionQueue.splice(0)) rejectQuestion(pending)
+      await overlayManager.dispose()
+      modelOverlay = undefined
       disposeUserInteraction()
       await runtime.terminal.drainInput(100, 20)
       ui.stop()
@@ -2209,15 +2678,19 @@ export function createTuiChat(
         ...ctx.commands.list(agent).map(command => ({
           name: command.name,
           description: command.description,
+          ...(command.input === undefined ? {} : { argumentHint: command.input.hint }),
         })),
         ...skillCommands,
       ],
       agent.session.header.cwd ?? process.cwd(),
     )
     const sessionReferences = ctx.get('sessionReferences')
-    editor.setAutocompleteProvider(sessionReferences === undefined
-      ? base
-      : new SessionAutocompleteProvider(base, sessionReferences, agent))
+    editor.setAutocompleteProvider(new ReferenceAutocompleteProvider(
+      base,
+      fileSearch,
+      sessionReferences,
+      agent,
+    ))
   }
   const disposeCommandChanges = ctx.on('commands/change', refreshCommandAutocomplete)
   refreshCommandAutocomplete()
@@ -2301,6 +2774,16 @@ export function createTuiChat(
       handler: () => { requestExit(); return { kind: 'success' } },
     })
   })
+  const fileReferencePromptFiber = agent.ctx.inject(['systemPrompt'], (promptCtx) => {
+    promptCtx.systemPrompt.section({
+      name: 'ui:tui-file-reference',
+      order: 99,
+      // Tool visibility can change dynamically or by agent scope. Empty
+      // sections are omitted by renderPrompt, so guidance never names a tool
+      // that this agent cannot call.
+      text: () => agent.ctx.tools.get('read', agent) === undefined ? '' : FILE_REFERENCE_PROMPT,
+    })
+  })
 
   const runCommand = (text: string): void => {
     const controller = new AbortController()
@@ -2328,7 +2811,7 @@ export function createTuiChat(
     } else if (agent.status === 'running') {
       agent.steer(content, { contexts })
     } else {
-      agent.send(content, { contexts })
+      agent.followup(content, { contexts })
     }
   }
 
@@ -2408,37 +2891,156 @@ export function createTuiChat(
     })
   }
 
-  /**
-   * List this workspace's resumable sessions, newest first, each with its
-   * resume command and a marker on the current one. Warns when resume is not
-   * configured or no persistence backend is mounted; notes when nothing is
-   * persisted yet. The listing is asynchronous (a persistence scan), so the
-   * transcript updates once it resolves.
-   */
-  const showResume = (): void => {
-    const template = config.resumeCommand
-    if (template === undefined) {
-      appendNotice('Resume is not configured for this app.', 'warning')
-      return
+  /** Build one display candidate without letting a corrupt neighbor abort the selector. */
+  const readResumeCandidate = async (
+    record: SessionRecord,
+    providers: ReadonlySet<string>,
+  ): Promise<ResumeCandidate> => {
+    try {
+      let snapshot: SessionLogSnapshot
+      const live = ctx.sessions.get(record.header.id)
+      if (live !== undefined) {
+        snapshot = {
+          session: structuredClone(live.header),
+          events: live.events.map(event => structuredClone(event)),
+        }
+      } else {
+        /* v8 ignore next -- caller checks the optional service before mapping records */
+        if (sessionQuery === undefined) throw new Error('session query is unavailable')
+        snapshot = await sessionQuery.readSession(record.header.id)
+      }
+      return summarizeResumeCandidate(
+        record,
+        snapshot,
+        agent.session.id,
+        agent.session.header.cwd,
+        providers,
+      )
+    } catch (error: unknown) {
+      return {
+        record,
+        title: 'Unreadable session',
+        lastActivityAt: record.header.createdAt,
+        lastTurn: 'log unavailable',
+        disabledReason: `session cannot be loaded: ${errorChain(error)}`,
+      }
     }
-    if (persistence === undefined) {
-      appendNotice('Resume is not available: no persistence backend is mounted.', 'warning')
-      return
-    }
-    void listWorkspaceSessions().then((sessions) => {
-      if (sessions.length === 0) {
-        appendNotice('No resumable sessions found for this workspace yet.', 'info')
+  }
+
+  /** Re-read every mutable precondition immediately before terminal handoff. */
+  const preflightResume = async (sessionId: SessionId): Promise<ResumeCandidate> => {
+    /* v8 ignore next -- only showResume can call this closure, after proving the optional service exists */
+    if (sessionQuery === undefined) throw new Error('Resume is unavailable: session query is not mounted.')
+    const initialStatus = agentStatus()
+    if (initialStatus !== 'idle') throw new Error(`Resume requires an idle agent (status: ${initialStatus}).`)
+    const record = (await sessionQuery.listSessions()).find(candidate => candidate.header.id === sessionId)
+    if (record === undefined) throw new Error(`Session "${sessionId}" is no longer available.`)
+    const candidate = await readResumeCandidate(
+      record,
+      new Set(ctx.llm.listProviders().map(provider => provider.id)),
+    )
+    if (candidate.disabledReason !== undefined) throw new Error(candidate.disabledReason)
+    const finalStatus = agentStatus()
+    if (finalStatus !== 'idle') throw new Error(`Resume requires an idle agent (status: ${finalStatus}).`)
+    return candidate
+  }
+
+  const handoffResume = async (candidate: ResumeCandidate, overlay: TuiOverlaySession): Promise<void> => {
+    if (resumeInFlight) return
+    resumeInFlight = true
+    let terminalReleased = false
+    try {
+      const checked = await preflightResume(candidate.record.header.id)
+      const hostHandoff = runtime.handoffResume
+      if (hostHandoff === undefined) {
+        const template = config.resumeCommand
+        const fallback = template?.replaceAll('{session}', checked.record.header.id)
+        await overlay.close()
+        resumeOverlay = undefined
+        appendNotice(fallback === undefined
+          ? 'Session is resumable, but this host cannot hand it off in place.'
+          : `This host cannot hand off in place. Exit and run: ${fallback}`, 'warning')
         return
       }
-      chat.addChild(new Spacer(1))
-      chat.addChild(new Text(palette.bold(palette.accent('Resumable sessions')), 1, 0))
-      const lines = sessions.map((header) => {
-        const when = new Date(header.createdAt).toISOString().slice(0, 16).replace('T', ' ')
-        const marker = header.id === agent.session.id ? palette.success(' (current)') : ''
-        return `${palette.muted(when)}${marker}\n  ${displayText(template.replaceAll('{session}', header.id))}`
+      /* v8 ignore next -- shutdown during preflight invalidates an awaited service read or reaches this guard */
+      if (disposed) return
+      await ctx.sessions.flush(agent.session)
+      // Disposal can run while the flush promise is pending; TypeScript does not model that reentry.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (disposed) return
+      if (agent.status !== 'idle') throw new Error(`Resume requires an idle agent (status: ${agent.status}).`)
+      await overlay.close()
+      resumeOverlay = undefined
+      await runtime.terminal.drainInput(100, 20)
+      // Disposal can run while terminal draining is pending; TypeScript does not model that reentry.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (disposed) return
+      ui.stop()
+      terminalReleased = true
+      await hostHandoff(checked.record.header.id)
+      throw new Error('resume host returned without replacing the process')
+    } catch (error: unknown) {
+      if (!disposed) {
+        if (terminalReleased) {
+          ui.start()
+          ui.setFocus(editor)
+          appendNotice(`Resume handoff failed: ${errorChain(error)}`, 'error')
+        } else {
+          await overlay.close()
+          resumeOverlay = undefined
+          appendNotice(`Resume failed: ${errorChain(error)}`, 'error')
+        }
+      }
+    } finally {
+      resumeInFlight = false
+    }
+  }
+
+  /** Open the current-workspace searchable session selector. */
+  const showResume = (): void => {
+    if (agent.status !== 'idle') {
+      appendNotice('Resume requires the current turn to finish or be cancelled first.', 'warning')
+      return
+    }
+    if (sessionQuery === undefined) {
+      appendNotice('Resume is not available: session query is not mounted.', 'warning')
+      return
+    }
+    const scan = ++resumeScan
+    void resumeOverlay?.close()
+    void sessionQuery.listSessions().then(async (records) => {
+      if (isDisposed() || scan !== resumeScan) return
+      const workspace = records.filter(record => record.header.cwd === agent.session.header.cwd)
+      const providers = new Set(ctx.llm.listProviders().map(provider => provider.id))
+      const candidates = await Promise.all(workspace.map(record => readResumeCandidate(record, providers)))
+      candidates.sort((a, b) => b.lastActivityAt - a.lastActivityAt
+        || a.record.header.id.localeCompare(b.record.header.id))
+      if (isDisposed() || scan !== resumeScan) return
+      const session = overlayManager.open({
+        create: host => new ResumePicker(
+          candidates,
+          resolved.maxResumeOptions,
+          runtime.formatCwd?.(agent.session.header.cwd) ?? formatCwd(agent.session.header.cwd),
+          () => host.viewport.rows,
+          palette,
+          (candidate) => { void handoffResume(candidate, session) },
+          () => { void session.close() },
+        ),
+        options: {
+          width: '100%',
+          maxHeight: '100%',
+          anchor: 'top-left',
+          margin: 0,
+        },
+      })
+      resumeOverlay = session
+      void session.closed.then(() => {
+        /* v8 ignore next -- overlay FIFO closes this session before a replacement can become the tracked resume overlay */
+        if (resumeOverlay === session) resumeOverlay = undefined
       })
-      chat.addChild(new Text(lines.join('\n'), 1, 0))
       requestRender()
+    }, (error: unknown) => {
+      if (!disposed && scan === resumeScan) appendNotice(`Resume session scan failed: ${errorChain(error)}`, 'error')
     })
   }
 
@@ -2510,7 +3112,7 @@ export function createTuiChat(
   }
 
   const removeInputListener = ui.addInputListener((data) => {
-    if (activeQuestion !== undefined || modelOverlay !== undefined) return undefined
+    if (overlayManager.hasActiveOverlay()) return undefined
     if (matchesKey(data, Key.ctrl('o'))) {
       toggleTools()
       return { consume: true }
@@ -2548,13 +3150,14 @@ export function createTuiChat(
 
   const disposeSessionEvents = ctx.on('session/event', (session, event) => {
     if (session !== agent.session) return
+    if (event.type === 'tool/result') fileSearch.invalidate()
     recordEventUsage(tokens, event)
     advanceTurnPhase(event)
     if (event.type === 'steering/message') {
       // A queued steering message reached the model as it drained; drop its
-      // entry from the badge. Matching by source keeps loop-authored steering
-      // (e.g. continuation reasons), which logs here without a matching
-      // `agent/queued` increment, from consuming a pending user slot.
+      // entry from the badge. Matching by source keeps a loop-authored
+      // continuation reason popping its own enqueued slot rather than a pending
+      // user message's slot.
       const drained = pendingSteering.indexOf(JSON.stringify(event.data.source))
       if (drained >= 0) {
         pendingSteering.splice(drained, 1)
@@ -2568,7 +3171,7 @@ export function createTuiChat(
     renderEvent(event, { addHistory: false, renderChunks: true })
     requestRender()
   })
-  const disposeQueued = ctx.on('agent/queued', (subject, _content, info) => {
+  const disposeQueued = ctx.on('agent/inbox/enqueue', (subject, info) => {
     if (subject !== agent || !info.steering) return
     pendingSteering.push(JSON.stringify(info.source))
     refreshStatus()
@@ -2596,6 +3199,7 @@ export function createTuiChat(
 
   const detachListeners = (): void => {
     skillAbort.abort()
+    fileSearch.dispose()
     removeInputListener()
     disposeCommandChanges()
     stopBannerReveal()
@@ -2637,16 +3241,27 @@ export function createTuiChat(
   }
 
   rebuildTranscript(true)
+  const restoredGoal = foldGoal(agent.session.events).goal
+  if (restoredGoal !== undefined && restoredGoal.phase !== 'complete') {
+    appendNotice(
+      `Goal restored (${restoredGoal.phase}) with automatic continuation disarmed. `
+      + 'Human confirmation is required; send “继续” or run /goal resume.',
+      'warning',
+    )
+  }
   setStatus(agent.status)
   try {
     ui.start()
   } catch (error: unknown) {
     disposed = true
     detachListeners()
-    void commandFiber.dispose().catch(
+    void Promise.all([
+      commandFiber.dispose(),
+      fileReferencePromptFiber.dispose(),
+    ]).catch(
       /* v8 ignore next 2 -- command registration cleanup is non-throwing; this guards a future disposer regression */
       (cleanupError: unknown) => {
-        ctx.logger.warn(`ui-tui: command cleanup after startup failure failed: ${errorChain(cleanupError)}`)
+        ctx.logger.warn(`ui-tui: scoped cleanup after startup failure failed: ${errorChain(cleanupError)}`)
       },
     )
     clearStatus()
@@ -2654,13 +3269,19 @@ export function createTuiChat(
     ui.stop()
     throw error
   }
+  tuiServiceFiber = ctx.inject([], (serviceCtx) => {
+    new TuiExtensionServiceImpl(serviceCtx, agent, overlayManager)
+  })
   startBannerReveal()
 
   return {
     async dispose(): Promise<void> {
       detachListeners()
       await shutdown(false)
-      await commandFiber.dispose()
+      await Promise.all([
+        commandFiber.dispose(),
+        fileReferencePromptFiber.dispose(),
+      ])
     },
   }
 }
@@ -2715,9 +3336,11 @@ export function apply(ctx: Context, config: Config): void {
   // Truecolor is a terminal capability, so detect it here at the process
   // boundary from COLORTERM; an explicit `truecolor` config value still wins.
   const truecolor = config.truecolor ?? ['truecolor', '24bit'].includes(process.env.COLORTERM ?? '')
+  const resumeHost = ctx.get('tuiResumeHost')
   mountTui(ctx, Object.assign({}, config, { truecolor }), {
     terminal: new ProcessTerminal(),
     exit: code => process.exit(code),
+    ...resumeHost === undefined ? {} : { handoffResume: sessionId => resumeHost.handoff(sessionId) },
   })
 }
 /* v8 ignore stop */
diff --git a/packages/ui/tui/src/overlay-manager.ts b/packages/ui/tui/src/overlay-manager.ts
new file mode 100644
index 0000000000..efe8716777
--- /dev/null
+++ b/packages/ui/tui/src/overlay-manager.ts
@@ -0,0 +1,369 @@
+/**
+ * Private bridge between the public TUI extension contract and pi-tui.
+ *
+ * The manager serializes modal ownership, guards extension callbacks, and
+ * settles every queued or active operation before terminal teardown.
+ * @module @deepseek-ai/dsh-tui/overlay-manager
+ */
+
+import { Service, type Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { TuiExtensionService } from './index.ts'
+import type {
+  Component,
+  Focusable,
+  OverlayHandle,
+} from '@earendil-works/pi-tui'
+import type {
+  TuiComponent,
+  TuiFocusable,
+  TuiOverlayCloseReason,
+  TuiOverlayHost,
+  TuiOverlayOutcome,
+  TuiOverlayOptions,
+  TuiOverlayRequest,
+  TuiOverlaySession,
+  TuiOverlayState,
+  TuiTheme,
+  TuiViewport,
+} from './extension.ts'
+
+/** pi-tui operations retained by the front door instead of exposed to plugins. */
+export interface TuiOverlayDriver {
+  /** Current terminal viewport. */
+  viewport(): TuiViewport
+  /** Current semantic theme facade. */
+  theme(): TuiTheme
+  /** Escape text at the terminal display boundary. */
+  display(value: string): string
+  /** Mount one guarded component and return its private pi-tui handle. */
+  show(component: Component, options: TuiOverlayOptions | undefined): OverlayHandle
+  /** Invalidate the mounted UI and request a render. */
+  invalidate(): void
+  /** Report a contained extension failure. */
+  reportError(error: unknown): void
+}
+
+interface OverlayEntry {
+  readonly request: TuiOverlayRequest
+  readonly controller: AbortController
+  readonly signal: AbortSignal
+  readonly closed: Promise<TuiOverlayOutcome>
+  readonly resolveClosed: (outcome: TuiOverlayOutcome) => void
+  readonly session: TuiOverlaySession
+  state: TuiOverlayState
+  component?: GuardedOverlayComponent
+  handle?: OverlayHandle
+  removeRequestAbort?: () => void
+  outcome?: TuiOverlayOutcome
+  failing?: boolean
+}
+
+/** Turn a close reason into its immutable public outcome. */
+function outcome(reason: Exclude<TuiOverlayCloseReason, 'error'>): TuiOverlayOutcome {
+  return Object.freeze({ reason })
+}
+
+/** Retain only supported layout fields before a queued request returns to its caller. */
+function retainOptions(options: TuiOverlayOptions): TuiOverlayOptions {
+  return Object.freeze({
+    ...options.width === undefined ? {} : { width: options.width },
+    ...options.minWidth === undefined ? {} : { minWidth: options.minWidth },
+    ...options.maxHeight === undefined ? {} : { maxHeight: options.maxHeight },
+    ...options.anchor === undefined ? {} : { anchor: options.anchor },
+    ...options.margin === undefined
+      ? {}
+      : {
+        margin: typeof options.margin === 'object'
+          ? Object.freeze({ ...options.margin })
+          : options.margin,
+      },
+  })
+}
+
+/** Guard plugin component methods while preserving focus and key-release state. */
+class GuardedOverlayComponent implements Component, Focusable {
+  constructor(
+    private readonly component: TuiComponent & Partial<TuiFocusable>,
+    private readonly fail: (error: unknown) => void,
+  ) {}
+
+  get focused(): boolean {
+    try {
+      return this.component.focused ?? false
+    } catch (error) {
+      this.fail(error)
+      return false
+    }
+  }
+
+  set focused(value: boolean) {
+    try {
+      if ('focused' in this.component) this.component.focused = value
+    } catch (error) {
+      this.fail(error)
+    }
+  }
+
+  get wantsKeyRelease(): boolean {
+    try {
+      return this.component.wantsKeyRelease ?? false
+    } catch (error) {
+      this.fail(error)
+      return false
+    }
+  }
+
+  render(width: number): string[] {
+    try {
+      return this.component.render(width)
+    } catch (error) {
+      this.fail(error)
+      return []
+    }
+  }
+
+  handleInput(data: string): void {
+    try {
+      this.component.handleInput?.(data)
+    } catch (error) {
+      this.fail(error)
+    }
+  }
+
+  invalidate(): boolean {
+    try {
+      this.component.invalidate()
+      return true
+    } catch (error) {
+      this.fail(error)
+      return false
+    }
+  }
+}
+
+/** FIFO modal owner for one mounted TUI. */
+export class TuiOverlayManager {
+  private readonly queue: OverlayEntry[] = []
+  private active: OverlayEntry | undefined
+  private accepting = true
+  private disposeTask: Promise<void> | undefined
+
+  constructor(private readonly driver: TuiOverlayDriver) {}
+
+  /**
+   * Whether one extension or built-in overlay currently owns terminal focus.
+   * @returns `true` while an overlay is active.
+   */
+  hasActiveOverlay(): boolean {
+    return this.active !== undefined
+  }
+
+  /** Reject new work while the TUI unloads dependent extension fibers. */
+  beginShutdown(): void {
+    this.accepting = false
+  }
+
+  /**
+   * Queue one overlay without assigning Cordis ownership.
+   * @param request - component factory, constraints, and request signal.
+   * @returns an internal session that can close with an ownership reason.
+   */
+  open(request: TuiOverlayRequest): TuiOverlaySession & {
+    closeWith(reason: Exclude<TuiOverlayCloseReason, 'error'>): Promise<TuiOverlayOutcome>
+  } {
+    if (!this.accepting) throw new Error('TUI is shutting down')
+    const requestSignal = request.signal
+    const retainedRequest: TuiOverlayRequest = Object.freeze({
+      create: request.create,
+      ...request.options === undefined ? {} : { options: retainOptions(request.options) },
+      ...requestSignal === undefined ? {} : { signal: requestSignal },
+    })
+    const controller = new AbortController()
+    const signal = requestSignal === undefined
+      ? controller.signal
+      : AbortSignal.any([requestSignal, controller.signal])
+    const deferred = Promise.withResolvers<TuiOverlayOutcome>()
+    const session: TuiOverlaySession & {
+      closeWith(reason: Exclude<TuiOverlayCloseReason, 'error'>): Promise<TuiOverlayOutcome>
+    } = {
+      get state(): TuiOverlayState {
+        return entry.state
+      },
+      closed: deferred.promise,
+      close: () => this.close(entry, outcome('closed')),
+      closeWith: (reason: Exclude<TuiOverlayCloseReason, 'error'>) =>
+        this.close(entry, outcome(reason)),
+    }
+    const entry: OverlayEntry = {
+      request: retainedRequest,
+      controller,
+      signal,
+      closed: deferred.promise,
+      resolveClosed: deferred.resolve,
+      session,
+      state: 'queued',
+    }
+    if (requestSignal?.aborted === true) {
+      void this.close(entry, outcome('aborted'))
+      return session
+    }
+    if (requestSignal !== undefined) {
+      const onAbort = (): void => { void this.close(entry, outcome('aborted')) }
+      requestSignal.addEventListener('abort', onAbort, { once: true })
+      entry.removeRequestAbort = () => { requestSignal.removeEventListener('abort', onAbort) }
+    }
+    this.queue.push(entry)
+    this.activateNext()
+    return session
+  }
+
+  /** Stop accepting work and settle every active or queued overlay. */
+  dispose(): Promise<void> {
+    if (this.disposeTask !== undefined) return this.disposeTask
+    this.beginShutdown()
+    const entries = [
+      ...this.active === undefined ? [] : [this.active],
+      ...this.queue,
+    ]
+    return this.disposeTask = Promise.all(
+      entries.map(entry => this.close(entry, outcome('tui-disposed'))),
+    ).then(() => {})
+  }
+
+  private activateNext(): void {
+    if (!this.accepting || this.active !== undefined) return
+    const entry = this.queue.shift()
+    if (entry === undefined) return
+    this.active = entry
+    entry.state = 'active'
+    const host = this.host(entry)
+    let component: TuiComponent & Partial<TuiFocusable>
+    try {
+      component = entry.request.create(host)
+    } catch (error) {
+      this.fail(entry, error)
+      return
+    }
+    if (this.active !== entry) return
+    const guarded = new GuardedOverlayComponent(component, (error) => {
+      this.fail(entry, error)
+    })
+    entry.component = guarded
+    try {
+      const handle = this.driver.show(guarded, entry.request.options)
+      if (this.active !== entry) {
+        this.hide(handle)
+        return
+      }
+      entry.handle = handle
+      this.driver.invalidate()
+    } catch (error) {
+      this.fail(entry, error)
+    }
+  }
+
+  private host(entry: OverlayEntry): TuiOverlayHost {
+    const driver = this.driver
+    return Object.freeze({
+      get signal(): AbortSignal {
+        return entry.signal
+      },
+      get viewport(): TuiViewport {
+        return Object.freeze({ ...driver.viewport() })
+      },
+      get theme(): TuiTheme {
+        return driver.theme()
+      },
+      display: (value: string) => this.driver.display(value),
+      invalidate: () => {
+        if (this.active !== entry || entry.component === undefined || entry.failing === true) return
+        if (!entry.component.invalidate() || this.active !== entry) return
+        try {
+          this.driver.invalidate()
+        } catch (error) {
+          this.fail(entry, error)
+        }
+      },
+      close: () => { void this.close(entry, outcome('closed')) },
+    })
+  }
+
+  private fail(entry: OverlayEntry, error: unknown): void {
+    if (entry.state === 'closed' || entry.failing === true) return
+    entry.failing = true
+    this.report(error)
+    queueMicrotask(() => {
+      void this.close(entry, Object.freeze({ reason: 'error', error }))
+    })
+  }
+
+  private report(error: unknown): void {
+    try {
+      this.driver.reportError(error)
+    } catch {
+      // Error reporting is a containment boundary, never a second failure path.
+    }
+  }
+
+  private hide(handle: OverlayHandle): void {
+    try {
+      handle.hide()
+    } catch (error) {
+      this.report(error)
+    }
+  }
+
+  private close(entry: OverlayEntry, result: TuiOverlayOutcome): Promise<TuiOverlayOutcome> {
+    if (entry.outcome !== undefined) return entry.closed
+    entry.outcome = result
+    entry.state = 'closed'
+    entry.removeRequestAbort?.()
+    delete entry.removeRequestAbort
+    if (!entry.controller.signal.aborted) entry.controller.abort(result)
+    const queuedIndex = this.queue.indexOf(entry)
+    if (queuedIndex >= 0) this.queue.splice(queuedIndex, 1)
+    if (this.active === entry) {
+      this.active = undefined
+      if (entry.handle !== undefined) this.hide(entry.handle)
+      delete entry.handle
+    }
+    delete entry.component
+    entry.resolveClosed(result)
+    try {
+      this.driver.invalidate()
+    } catch (error) {
+      this.report(error)
+    }
+    queueMicrotask(() => { this.activateNext() })
+    return entry.closed
+  }
+}
+
+/** Cordis service whose method effects bind to the calling plugin fiber. */
+export class TuiExtensionServiceImpl extends Service implements TuiExtensionService {
+  constructor(
+    ctx: Context,
+    readonly agent: Agent,
+    private readonly overlays: TuiOverlayManager,
+  ) {
+    super(ctx, 'tui')
+  }
+
+  /** @inheritdoc */
+  openOverlay(request: TuiOverlayRequest): TuiOverlaySession {
+    let operation: ReturnType<TuiOverlayManager['open']> | undefined
+    const disposeOwner = this.ctx.effect(
+      () => () => operation?.closeWith('owner-disposed'),
+      'tui.openOverlay()',
+    )
+    try {
+      operation = this.overlays.open(request)
+    } catch (error) {
+      void disposeOwner()
+      throw error
+    }
+    void operation.closed.then(() => { void disposeOwner() })
+    return operation
+  }
+}
diff --git a/packages/ui/tui/tests/extension.spec.ts b/packages/ui/tui/tests/extension.spec.ts
new file mode 100644
index 0000000000..bf11d6c601
--- /dev/null
+++ b/packages/ui/tui/tests/extension.spec.ts
@@ -0,0 +1,587 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type {
+  Component,
+  OverlayHandle,
+} from '@earendil-works/pi-tui'
+import type {
+  TuiComponent,
+  TuiOverlayHost,
+  TuiOverlayOptions,
+  TuiOverlaySession,
+  TuiTheme,
+} from '../src/extension.ts'
+import {
+  TuiExtensionServiceImpl,
+  TuiOverlayManager,
+  type TuiOverlayDriver,
+} from '../src/overlay-manager.ts'
+
+const theme: TuiTheme = Object.freeze({
+  text: (value: string) => `text:${value}`,
+  muted: (value: string) => `muted:${value}`,
+  dim: (value: string) => `dim:${value}`,
+  accent: (value: string) => `accent:${value}`,
+  success: (value: string) => `success:${value}`,
+  warning: (value: string) => `warning:${value}`,
+  error: (value: string) => `error:${value}`,
+  bold: (value: string) => `bold:${value}`,
+})
+
+interface ShownOverlay {
+  component: Component
+  options: TuiOverlayOptions | undefined
+  hidden: boolean
+  focused: boolean
+}
+
+interface DriverFixture {
+  driver: TuiOverlayDriver
+  shown: ShownOverlay[]
+  errors: unknown[]
+  invalidations: number
+  showError?: unknown
+  onShow?: (component: Component) => void
+}
+
+function driverFixture(): DriverFixture {
+  const fixture: DriverFixture = {
+    shown: [],
+    errors: [],
+    invalidations: 0,
+    driver: undefined as never,
+  }
+  fixture.driver = {
+    viewport: () => ({ columns: 96, rows: 32 }),
+    theme: () => theme,
+    display: value => `safe:${value}`,
+    show(component, options) {
+      if (fixture.showError !== undefined) throw fixture.showError
+      const shown: ShownOverlay = {
+        component,
+        options,
+        hidden: false,
+        focused: true,
+      }
+      fixture.shown.push(shown)
+      const handle: OverlayHandle = {
+        hide() {
+          shown.hidden = true
+          shown.focused = false
+        },
+        setHidden(hidden) {
+          shown.hidden = hidden
+        },
+        isHidden: () => shown.hidden,
+        focus() {
+          shown.focused = true
+        },
+        unfocus() {
+          shown.focused = false
+        },
+        isFocused: () => shown.focused,
+      }
+      fixture.onShow?.(component)
+      return handle
+    },
+    invalidate() {
+      fixture.invalidations += 1
+    },
+    reportError(error) {
+      fixture.errors.push(error)
+    },
+  }
+  return fixture
+}
+
+function component(lines = ['overlay']): TuiComponent {
+  return {
+    render: () => lines,
+    invalidate() {},
+  }
+}
+
+async function microtask(): Promise<void> {
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+describe('TuiOverlayManager', () => {
+  it('serializes overlays, exposes the constrained host, and settles normal close once', async () => {
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    let firstHost: TuiOverlayHost | undefined
+    const firstComponent = {
+      focused: false,
+      wantsKeyRelease: true,
+      inputs: [] as string[],
+      invalidated: 0,
+      render: (width: number) => [`first:${String(width)}`],
+      handleInput(data: string) {
+        this.inputs.push(data)
+      },
+      invalidate() {
+        this.invalidated += 1
+      },
+    }
+    const first = manager.open({
+      create(host) {
+        firstHost = host
+        return firstComponent
+      },
+      options: { width: '75%', minWidth: 24, maxHeight: 20, anchor: 'center', margin: { bottom: 1 } },
+    })
+    const secondOptions: TuiOverlayOptions = { width: 40, margin: { bottom: 2 } }
+    const second = manager.open({
+      create: () => component(['second']),
+      options: secondOptions,
+    })
+    ;(secondOptions as { width: number }).width = 80
+    ;(secondOptions.margin as { bottom: number }).bottom = 4
+
+    expect(manager.hasActiveOverlay()).toBe(true)
+    expect(first.state).toBe('active')
+    expect(second.state).toBe('queued')
+    expect(fixture.shown).toHaveLength(1)
+    expect(fixture.shown[0]?.options).toEqual({
+      width: '75%',
+      minWidth: 24,
+      maxHeight: 20,
+      anchor: 'center',
+      margin: { bottom: 1 },
+    })
+    expect(firstHost?.viewport).toEqual({ columns: 96, rows: 32 })
+    expect(Object.isFrozen(firstHost?.viewport)).toBe(true)
+    expect(firstHost?.theme.accent('x')).toBe('accent:x')
+    expect(firstHost?.display('\u001b')).toBe('safe:\u001b')
+    firstHost?.invalidate()
+    expect(firstComponent.invalidated).toBe(1)
+    expect(fixture.shown[0]?.component.render(40)).toEqual(['first:40'])
+    fixture.shown[0]!.component.handleInput?.('x')
+    fixture.shown[0]!.component.invalidate()
+    expect(firstComponent.inputs).toEqual(['x'])
+    expect(firstComponent.invalidated).toBe(2)
+    expect(fixture.shown[0]?.component.wantsKeyRelease).toBe(true)
+    ;(fixture.shown[0]?.component as Component & { focused: boolean }).focused = true
+    expect(firstComponent.focused).toBe(true)
+    expect((fixture.shown[0]?.component as Component & { focused: boolean }).focused).toBe(true)
+
+    const firstOutcome = await first.close()
+    expect(firstOutcome).toEqual({ reason: 'closed' })
+    expect(await first.close()).toBe(firstOutcome)
+    expect(firstHost?.signal.aborted).toBe(true)
+    const beforeClosedInvalidation = fixture.invalidations
+    firstHost?.invalidate()
+    expect(fixture.invalidations).toBe(beforeClosedInvalidation)
+    await microtask()
+
+    expect(first.state).toBe('closed')
+    expect(second.state).toBe('active')
+    expect(fixture.shown[0]?.hidden).toBe(true)
+    expect(fixture.shown[1]?.options).toEqual({ width: 40, margin: { bottom: 2 } })
+    expect(Object.isFrozen(fixture.shown[1]?.options)).toBe(true)
+    expect(Object.isFrozen(fixture.shown[1]?.options?.margin)).toBe(true)
+    expect(fixture.shown[1]?.component.wantsKeyRelease).toBe(false)
+    expect((fixture.shown[1]?.component as Component & { focused: boolean }).focused).toBe(false)
+    ;(fixture.shown[1]?.component as Component & { focused: boolean }).focused = true
+    fixture.shown[1]!.component.handleInput?.('ignored')
+    await second.close()
+    await microtask()
+
+    const numericMargin = manager.open({
+      create: () => component(['numeric margin']),
+      options: { margin: 1 },
+    })
+    expect(fixture.shown[2]?.options).toEqual({ margin: 1 })
+    await numericMargin.close()
+    await microtask()
+
+    const emptyOptions = manager.open({
+      create: () => component(['empty options']),
+      options: {},
+    })
+    expect(fixture.shown[3]?.options).toEqual({})
+    await emptyOptions.close()
+    await microtask()
+
+    expect(manager.hasActiveOverlay()).toBe(false)
+    await manager.dispose()
+    await manager.dispose()
+  })
+
+  it('removes pre-aborted, active, and queued requests without activating cancelled work', async () => {
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    const preAborted = new AbortController()
+    preAborted.abort()
+    const pre = manager.open({
+      signal: preAborted.signal,
+      create: () => component(['never']),
+    })
+    expect(await pre.closed).toEqual({ reason: 'aborted' })
+    expect(fixture.shown).toHaveLength(0)
+
+    const activeAbort = new AbortController()
+    let activeHost: TuiOverlayHost | undefined
+    const active = manager.open({
+      signal: activeAbort.signal,
+      create(host) {
+        activeHost = host
+        return component(['active'])
+      },
+    })
+    const queuedAbort = new AbortController()
+    const queued = manager.open({
+      signal: queuedAbort.signal,
+      create: () => component(['queued']),
+    })
+    queuedAbort.abort()
+    expect(await queued.closed).toEqual({ reason: 'aborted' })
+    expect(queued.state).toBe('closed')
+    activeAbort.abort()
+    expect(await active.closed).toEqual({ reason: 'aborted' })
+    expect(activeHost?.signal.aborted).toBe(true)
+    await microtask()
+    expect(fixture.shown).toHaveLength(1)
+    expect(manager.hasActiveOverlay()).toBe(false)
+  })
+
+  it('does not mount entries closed or aborted during component construction', async () => {
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    const closed = manager.open({
+      create(host) {
+        host.invalidate()
+        host.close()
+        return component(['closed during construction'])
+      },
+    })
+    await expect(closed.closed).resolves.toEqual({ reason: 'closed' })
+
+    const controller = new AbortController()
+    const aborted = manager.open({
+      signal: controller.signal,
+      create() {
+        controller.abort()
+        return component(['aborted during construction'])
+      },
+    })
+    await expect(aborted.closed).resolves.toEqual({ reason: 'aborted' })
+
+    const after = manager.open({ create: () => component(['after construction closes']) })
+    expect(fixture.shown).toHaveLength(1)
+    expect(fixture.shown[0]?.component.render(40)).toEqual(['after construction closes'])
+    await after.close()
+  })
+
+  it('hides a handle returned after reentrant closure during mounting', async () => {
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    fixture.onShow = (shown) => {
+      ;(shown as Component & { focused: boolean }).focused = true
+    }
+    const closed = manager.open({
+      create(host) {
+        return {
+          get focused(): boolean {
+            return false
+          },
+          set focused(_value: boolean) {
+            host.close()
+          },
+          render: () => ['closed during mount'],
+          invalidate() {},
+        }
+      },
+    })
+    await expect(closed.closed).resolves.toEqual({ reason: 'closed' })
+    expect(fixture.shown[0]?.hidden).toBe(true)
+    expect(manager.hasActiveOverlay()).toBe(false)
+
+    delete fixture.onShow
+    const after = manager.open({ create: () => component(['after mount close']) })
+    expect(fixture.shown[1]?.hidden).toBe(false)
+    expect(fixture.shown[1]?.component.render(40)).toEqual(['after mount close'])
+    await after.close()
+  })
+
+  it('stops admission and disposes active and queued overlays with the TUI', async () => {
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    const active = manager.open({ create: () => component(['active']) })
+    const queued = manager.open({ create: () => component(['queued']) })
+    manager.beginShutdown()
+    expect(() => manager.open({ create: () => component() })).toThrow('TUI is shutting down')
+    await manager.dispose()
+    expect(await active.closed).toEqual({ reason: 'tui-disposed' })
+    expect(await queued.closed).toEqual({ reason: 'tui-disposed' })
+    expect(fixture.shown).toHaveLength(1)
+    expect(fixture.shown[0]?.hidden).toBe(true)
+    await manager.dispose()
+  })
+
+  it('contains factory, mount, render, input, and invalidation failures', async () => {
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    const factoryError = new Error('factory failed')
+    const factory = manager.open({
+      create() {
+        throw factoryError
+      },
+    })
+    const afterFactory = manager.open({ create: () => component(['after factory']) })
+    expect(await factory.closed).toEqual({ reason: 'error', error: factoryError })
+    await microtask()
+    expect(afterFactory.state).toBe('active')
+    await afterFactory.close()
+    await microtask()
+
+    const showError = new Error('show failed')
+    fixture.showError = showError
+    const show = manager.open({ create: () => component(['show']) })
+    expect(await show.closed).toEqual({ reason: 'error', error: showError })
+    delete fixture.showError
+    await microtask()
+
+    const renderError = new Error('render failed')
+    const rendering = manager.open({
+      create: () => ({
+        render() {
+          throw renderError
+        },
+        invalidate() {
+          throw new Error('must be suppressed after the first failure')
+        },
+      }),
+    })
+    const renderComponent = fixture.shown.at(-1)!.component
+    expect(renderComponent.render(20)).toEqual([])
+    renderComponent.invalidate()
+    expect(fixture.errors.filter(error => error === renderError)).toHaveLength(1)
+    expect(await rendering.closed).toEqual({ reason: 'error', error: renderError })
+    await microtask()
+
+    const inputError = new Error('input failed')
+    const input = manager.open({
+      create: () => ({
+        render: () => ['input'],
+        handleInput() {
+          throw inputError
+        },
+        invalidate() {},
+      }),
+    })
+    fixture.shown.at(-1)!.component.handleInput?.('x')
+    expect(await input.closed).toEqual({ reason: 'error', error: inputError })
+    await microtask()
+
+    const invalidateError = new Error('invalidate failed')
+    let invalidatingHost: TuiOverlayHost | undefined
+    const invalidating = manager.open({
+      create(host) {
+        invalidatingHost = host
+        return {
+          render: () => ['invalidate'],
+          invalidate() {
+            throw invalidateError
+          },
+        }
+      },
+    })
+    const invalidationsBeforeFailure = fixture.invalidations
+    invalidatingHost?.invalidate()
+    invalidatingHost?.invalidate()
+    expect(fixture.invalidations).toBe(invalidationsBeforeFailure)
+    expect(await invalidating.closed).toEqual({ reason: 'error', error: invalidateError })
+    await microtask()
+
+    const focusError = new Error('focus failed')
+    const focus = manager.open({
+      create: () => ({
+        get focused(): boolean {
+          throw focusError
+        },
+        set focused(_value: boolean) {
+          throw new Error('focus assignment failed')
+        },
+        get wantsKeyRelease(): boolean {
+          throw new Error('key-release query failed')
+        },
+        render: () => ['focus'],
+        invalidate() {},
+      }),
+    })
+    const guarded = fixture.shown.at(-1)!.component as Component & { focused: boolean }
+    expect(guarded.focused).toBe(false)
+    guarded.focused = true
+    expect(guarded.wantsKeyRelease).toBe(false)
+    expect(await focus.closed).toEqual({ reason: 'error', error: focusError })
+    expect(fixture.errors).toEqual([
+      factoryError,
+      showError,
+      renderError,
+      inputError,
+      invalidateError,
+      focusError,
+    ])
+  })
+
+  it('contains host redraw, overlay removal, and error-reporter failures', async () => {
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    let host: TuiOverlayHost | undefined
+    const invalidationError = new Error('redraw failed')
+    let redrawFails = false
+    fixture.driver.invalidate = () => {
+      if (redrawFails) throw invalidationError
+    }
+    fixture.driver.reportError = () => { throw new Error('report failed') }
+    const invalidating = manager.open({
+      create(value) {
+        host = value
+        return component()
+      },
+    })
+    redrawFails = true
+    host?.invalidate()
+    expect(await invalidating.closed).toEqual({ reason: 'error', error: invalidationError })
+    await microtask()
+
+    redrawFails = false
+    fixture.driver.invalidate = () => {}
+    const hideError = new Error('hide failed')
+    fixture.driver.show = () => ({
+      hide() { throw hideError },
+      setHidden() {},
+      isHidden: () => false,
+      focus() {},
+      unfocus() {},
+      isFocused: () => true,
+    })
+    const hiding = manager.open({
+      create(value) {
+        host = value
+        return component()
+      },
+    })
+    host?.close()
+    expect(await hiding.closed).toEqual({ reason: 'closed' })
+  })
+})
+
+describe('TuiExtensionService', () => {
+  it('binds an open overlay to the calling plugin fiber', async () => {
+    const ctx = new Context()
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    const agent = {} as Agent
+    const provider = ctx.plugin((providerCtx) => {
+      new TuiExtensionServiceImpl(providerCtx, agent, manager)
+    })
+    await provider
+    let session: TuiOverlaySession | undefined
+    let host: TuiOverlayHost | undefined
+    const consumer = ctx.inject(['tui'], (consumerCtx) => {
+      expect(consumerCtx.tui.agent).toBe(agent)
+      session = consumerCtx.tui.openOverlay({
+        create(value) {
+          host = value
+          return component(['plugin'])
+        },
+      })
+    })
+    await consumer
+    expect(session?.state).toBe('active')
+
+    await consumer.dispose()
+    expect(await session?.closed).toEqual({ reason: 'owner-disposed' })
+    expect(host?.signal.aborted).toBe(true)
+    await provider.dispose()
+    await manager.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('unloads and reloads dependent plugins with the mounted TUI service', async () => {
+    const ctx = new Context()
+    const agent = {} as Agent
+    const sessions: TuiOverlaySession[] = []
+    let starts = 0
+    const consumer = ctx.inject(['tui'], (consumerCtx) => {
+      starts += 1
+      sessions.push(consumerCtx.tui.openOverlay({ create: () => component([`start:${String(starts)}`]) }))
+    })
+
+    const firstFixture = driverFixture()
+    const firstManager = new TuiOverlayManager(firstFixture.driver)
+    const firstProvider = ctx.plugin((providerCtx) => {
+      new TuiExtensionServiceImpl(providerCtx, agent, firstManager)
+    })
+    await firstProvider
+    await consumer
+    expect(starts).toBe(1)
+    await firstProvider.dispose()
+    expect(await sessions[0]?.closed).toEqual({ reason: 'owner-disposed' })
+
+    const secondFixture = driverFixture()
+    const secondManager = new TuiOverlayManager(secondFixture.driver)
+    const secondProvider = ctx.plugin((providerCtx) => {
+      new TuiExtensionServiceImpl(providerCtx, agent, secondManager)
+    })
+    await secondProvider
+    await vi.waitFor(() => { expect(starts).toBe(2) })
+    await sessions[1]?.close()
+    await consumer.dispose()
+    await secondProvider.dispose()
+    await firstManager.dispose()
+    await secondManager.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects new service work after terminal shutdown begins', async () => {
+    const ctx = new Context()
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    const provider = ctx.plugin((providerCtx) => {
+      new TuiExtensionServiceImpl(providerCtx, {} as Agent, manager)
+    })
+    await provider
+    manager.beginShutdown()
+    const consumer = ctx.inject(['tui'], (consumerCtx) => {
+      expect(() => consumerCtx.tui.openOverlay({ create: () => component() }))
+        .toThrow('TUI is shutting down')
+    })
+    await consumer
+    await consumer.dispose()
+    await provider.dispose()
+    await manager.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('does not admit an overlay when called from an unloading plugin', async () => {
+    const ctx = new Context()
+    const fixture = driverFixture()
+    const manager = new TuiOverlayManager(fixture.driver)
+    const provider = ctx.plugin((providerCtx) => {
+      new TuiExtensionServiceImpl(providerCtx, {} as Agent, manager)
+    })
+    await provider
+    let error: unknown
+    const consumer = ctx.inject(['tui'], (consumerCtx) => {
+      consumerCtx.effect(() => () => {
+        try {
+          consumerCtx.tui.openOverlay({ create: () => component() })
+        } catch (value) {
+          error = value
+        }
+      })
+    })
+    await consumer
+    await consumer.dispose()
+    expect(error).toMatchObject({ code: 'INACTIVE_EFFECT' })
+    expect(fixture.shown).toHaveLength(0)
+    await provider.dispose()
+    await manager.dispose()
+    await ctx.fiber.dispose()
+  })
+})
diff --git a/packages/ui/tui/tests/file-autocomplete.spec.ts b/packages/ui/tui/tests/file-autocomplete.spec.ts
new file mode 100644
index 0000000000..53dd1f4f1a
--- /dev/null
+++ b/packages/ui/tui/tests/file-autocomplete.spec.ts
@@ -0,0 +1,197 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  activeAtToken,
+  formatFileMention,
+  WorkspaceFileSearch,
+} from '../src/file-autocomplete.ts'
+
+const searches: WorkspaceFileSearch[] = []
+const roots: string[] = []
+
+async function workspace(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-file-autocomplete-'))
+  roots.push(root)
+  await mkdir(join(root, 'src'), { recursive: true })
+  await mkdir(join(root, 'docs'), { recursive: true })
+  await mkdir(join(root, '.hidden'), { recursive: true })
+  await mkdir(join(root, 'node_modules', 'ignored-package'), { recursive: true })
+  await writeFile(join(root, 'README.md'), 'readme')
+  await writeFile(join(root, 'src', 'tui.spec.ts'), 'test')
+  await writeFile(join(root, 'src', 'terminal-view.ts'), 'view')
+  await writeFile(join(root, 'docs', 'design notes.md'), 'design')
+  await writeFile(join(root, '.hidden', 'secret.txt'), 'hidden')
+  await writeFile(join(root, 'node_modules', 'ignored-package', 'index.js'), 'ignored')
+  try {
+    await symlink(join(root, 'src', 'tui.spec.ts'), join(root, 'linked-test.ts'))
+  } catch {
+    // Windows may deny symlink creation without Developer Mode; the product
+    // still skips every non-file/non-directory Dirent on platforms that expose one.
+  }
+  return root
+}
+
+function search(root: string, overrides: Partial<ConstructorParameters<typeof WorkspaceFileSearch>[1]> = {}): WorkspaceFileSearch {
+  const instance = new WorkspaceFileSearch(root, {
+    maxResults: overrides.maxResults ?? 20,
+    maxEntries: overrides.maxEntries ?? 10_000,
+    excludedDirectories: overrides.excludedDirectories ?? ['.git', 'node_modules'],
+  })
+  searches.push(instance)
+  return instance
+}
+
+afterEach(async () => {
+  for (const instance of searches.splice(0)) instance.dispose()
+  await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true })))
+})
+
+describe('TUI file autocomplete grammar', () => {
+  it('recognizes boundary and quoted mentions without treating emails as references', () => {
+    expect(activeAtToken('@src/tu', 7)).toEqual({ prefix: '@src/tu', query: 'src/tu', quoted: false })
+    expect(activeAtToken('read @"docs/design n', 20)).toEqual({
+      prefix: '@"docs/design n',
+      query: 'docs/design n',
+      quoted: true,
+    })
+    expect(activeAtToken('mail a@b.test', 13)).toBeUndefined()
+    expect(activeAtToken('done @src/x" next', 17)).toBeUndefined()
+  })
+
+  it('formats files, directories, quotes, and rejects unsafe editor values', () => {
+    expect(formatFileMention({ path: 'src/index.ts', kind: 'file' }, false)).toBe('@src/index.ts')
+    expect(formatFileMention({ path: 'src', kind: 'directory' }, false)).toBe('@src/')
+    expect(formatFileMention({ path: 'docs/design notes.md', kind: 'file' }, false))
+      .toBe('@"docs/design notes.md"')
+    expect(formatFileMention({ path: 'README.md', kind: 'file' }, true)).toBe('@"README.md"')
+    expect(formatFileMention({ path: 'bad\nname', kind: 'file' }, false)).toBeUndefined()
+    expect(formatFileMention({ path: 'bad "name".md', kind: 'file' }, false)).toBeUndefined()
+    expect(formatFileMention({ path: 'bad"name.md', kind: 'file' }, false)).toBeUndefined()
+  })
+})
+
+describe('WorkspaceFileSearch', () => {
+  it('lists live directory levels, descends, quotes spaces, and filters hidden/excluded entries', async () => {
+    const root = await workspace()
+    const files = search(root)
+    const signal = new AbortController().signal
+
+    expect(await files.list('', signal)).toEqual([
+      { path: 'docs', kind: 'directory' },
+      { path: 'src', kind: 'directory' },
+      { path: 'README.md', kind: 'file' },
+    ])
+    expect(await files.list('src/', signal)).toEqual([
+      { path: 'src/terminal-view.ts', kind: 'file' },
+      { path: 'src/tui.spec.ts', kind: 'file' },
+    ])
+    expect(await files.list('src/ts', signal)).toEqual([
+      { path: 'src/tui.spec.ts', kind: 'file' },
+      { path: 'src/terminal-view.ts', kind: 'file' },
+    ])
+    expect(await files.list('docs/design n', signal)).toEqual([
+      { path: 'docs/design notes.md', kind: 'file' },
+    ])
+    expect(await files.list('node_modules/', signal)).toEqual([])
+    expect(await files.list('.hidden/', signal)).toEqual([
+      { path: '.hidden/secret.txt', kind: 'file' },
+    ])
+    const absoluteSrc = `${join(root, 'src').replaceAll('\\', '/')}/`
+    expect(await files.list(`${absoluteSrc}tui`, signal)).toEqual([
+      { path: `${absoluteSrc}tui.spec.ts`, kind: 'file' },
+      { path: `${absoluteSrc}terminal-view.ts`, kind: 'file' },
+    ])
+    expect(await files.list('~/.dsh-file-autocomplete-missing/', signal)).toEqual([])
+    expect(await files.list('../', signal)).toEqual([])
+    expect(await files.list('README.md/', signal)).toEqual([])
+  })
+
+  it('does not traverse directory symlinks during direct completion', async () => {
+    const root = await workspace()
+    const outside = await mkdtemp(join(tmpdir(), 'dsh-file-autocomplete-outside-'))
+    roots.push(outside)
+    await writeFile(join(outside, 'outside-secret.txt'), 'secret')
+    await symlink(
+      outside,
+      join(root, 'escape'),
+      process.platform === 'win32' ? 'junction' : 'dir',
+    )
+    const files = search(root)
+    const signal = new AbortController().signal
+
+    expect(await files.list('escape/', signal)).toEqual([])
+    expect(await files.list('escape/outside', signal)).toEqual([])
+  })
+
+  it('ranks basename and subsequence fuzzy matches across the bounded workspace index', async () => {
+    const root = await workspace()
+    await writeFile(join(root, 'src', 'tspc-helper.ts'), 'helper')
+    const files = search(root, { maxResults: 2 })
+    const signal = new AbortController().signal
+
+    expect(await files.list('tspc', signal)).toEqual([
+      { path: 'src/tspc-helper.ts', kind: 'file' },
+      { path: 'src/tui.spec.ts', kind: 'file' },
+    ])
+    expect(await files.list('README.md', signal)).toEqual([
+      { path: 'README.md', kind: 'file' },
+    ])
+    expect(await files.list('terminal', signal)).toEqual([
+      { path: 'src/terminal-view.ts', kind: 'file' },
+    ])
+    expect(await files.list('secret', signal)).toEqual([])
+    expect(await files.list('.hidden', signal)).toEqual([
+      { path: '.hidden', kind: 'directory' },
+      { path: '.hidden/secret.txt', kind: 'file' },
+    ])
+  })
+
+  it('invalidates cached traversal, enforces the entry cap, and settles disposal', async () => {
+    const root = await workspace()
+    const capped = search(root, { maxEntries: 2 })
+    const signal = new AbortController().signal
+    expect(await capped.list('README', signal)).toEqual([
+      { path: 'README.md', kind: 'file' },
+    ])
+
+    const files = search(root)
+    expect(await files.list('fresh-file', signal)).toEqual([])
+    await writeFile(join(root, 'fresh-file.ts'), 'fresh')
+    expect(await files.list('fresh-file', signal)).toEqual([])
+    files.invalidate()
+    expect(await files.list('fresh-file', signal)).toEqual([
+      { path: 'fresh-file.ts', kind: 'file' },
+    ])
+    files.dispose()
+    expect(await files.list('fresh-file', signal)).toEqual([])
+    files.dispose()
+  })
+
+  it('cancels individual callers, skips missing directories, and validates limits', async () => {
+    const root = await workspace()
+    expect(() => search(root, { maxResults: 0 })).toThrow('maxResults')
+    expect(() => search(root, { maxEntries: 1.5 })).toThrow('maxEntries')
+    expect(() => search(root, { excludedDirectories: ['nested/name'] })).toThrow('basenames')
+
+    const files = search(root)
+    expect(await files.list('missing/', new AbortController().signal)).toEqual([])
+
+    const preAborted = new AbortController()
+    preAborted.abort(new Error('pre-aborted'))
+    await expect(files.list('tui', preAborted.signal)).rejects.toThrow('pre-aborted')
+
+    files.invalidate()
+    const running = new AbortController()
+    const pending = files.list('tui', running.signal)
+    running.abort(new Error('superseded'))
+    await expect(pending).rejects.toThrow('superseded')
+
+    files.invalidate()
+    const nonErrorAbort = new AbortController()
+    const nonErrorPending = files.list('tui', nonErrorAbort.signal)
+    nonErrorAbort.abort('cancelled')
+    await expect(nonErrorPending).rejects.toThrow('file search aborted')
+  })
+})
diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts
index c6da283236..37eee99735 100644
--- a/packages/ui/tui/tests/harness.ts
+++ b/packages/ui/tui/tests/harness.ts
@@ -1,6 +1,7 @@
 import { Context } from 'cordis'
 import type { Terminal } from '@earendil-works/pi-tui'
 import AgentRegistry, {
+  AgentMessageId,
   type Agent,
   type AgentCancelCause,
   type AgentOptions,
@@ -14,6 +15,7 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import { createTuiChat, type Config, type TuiRuntime } from '../src/index.ts'
+import { TestSessionQueryService } from './session-query.ts'
 
 interface FakeAgent extends Agent {
   status: AgentStatus
@@ -48,7 +50,13 @@ export interface TuiHarnessOptions {
     resolveModelContext?: (provider: string, model: string) => Promise<LlmModelContext | undefined>
   }
   /** Provide a fake `sessionPersistence` service so resume surfaces can list sessions. */
-  sessionPersistence?: { list(): Promise<SessionHeader[]> }
+  sessionPersistence?: {
+    list(): Promise<SessionHeader[]>
+    load?(id: ReturnType<typeof SessionId>): Promise<{ meta: SessionHeader; events: Session['events'] }>
+  }
+  handoffResume?: TuiRuntime['handoffResume']
+  /** Set false to exercise the optional session-query degradation path. */
+  mountSessionQuery?: boolean
 }
 
 export interface TuiHarness<TerminalType extends Terminal, Exit extends (code: number) => void> {
@@ -118,7 +126,22 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
   }
   if (ctx.get('systemPrompt') === undefined) await ctx.plugin(SystemPrompt)
   if (options.sessionPersistence !== undefined) {
-    ctx.provide('sessionPersistence', options.sessionPersistence as never)
+    const persistence = options.sessionPersistence
+    ctx.provide('sessionPersistence', {
+      ...persistence,
+      locate: () => undefined,
+      create: () => Promise.resolve(),
+      append: () => Promise.resolve(),
+      load: persistence.load === undefined
+        ? (id: ReturnType<typeof SessionId>) => Promise.reject(new Error(`session "${id}" not found`))
+        : (id: ReturnType<typeof SessionId>) => persistence.load!(id),
+      inspect: persistence.load === undefined
+        ? (id: ReturnType<typeof SessionId>) => Promise.reject(new Error(`session "${id}" not found`))
+        : (id: ReturnType<typeof SessionId>) => persistence.load!(id),
+    } as never)
+  }
+  if (options.mountSessionQuery !== false && ctx.get('sessionQuery') === undefined) {
+    await ctx.plugin(TestSessionQueryService)
   }
   const sessionId = SessionId('main-session')
   const session = ctx.sessions.create(
@@ -149,15 +172,23 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
     steered,
     steeredOptions,
     cancelled,
-    send(content, options) {
+    followup(content, options) {
       sent.push(content)
       sentOptions.push(options)
+      return AgentMessageId('stub')
+    },
+    queue(content, options) {
+      sent.push(content)
+      sentOptions.push(options)
+      return AgentMessageId('stub')
     },
     steer(content, options) {
       steered.push(content)
       steeredOptions.push(options)
+      return AgentMessageId('stub')
     },
-    inject() {},
+    inject: () => AgentMessageId('stub'),
+    send: () => AgentMessageId('stub'),
     cancel(cause = { kind: 'user' }) {
       cancelled.push(cause)
     },
@@ -178,6 +209,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
     // test pins the clock only by passing `now` explicitly.
     ...(options.now === undefined ? {} : { now: options.now }),
     ...(options.formatCwd === undefined ? {} : { formatCwd: options.formatCwd }),
+    ...(options.handoffResume === undefined ? {} : { handoffResume: options.handoffResume }),
   })
   return { ctx, session, agent, terminal, exit, controller }
 }
diff --git a/packages/ui/tui/tests/plugin-shape.spec.ts b/packages/ui/tui/tests/plugin-shape.spec.ts
index 149035099e..c5c497fab9 100644
--- a/packages/ui/tui/tests/plugin-shape.spec.ts
+++ b/packages/ui/tui/tests/plugin-shape.spec.ts
@@ -14,6 +14,7 @@ describe('dsh-tui plugin export shape', () => {
     expect(unwrapped.name).toBe('ui-tui')
     expect(unwrapped.inject).toEqual([
       'agents',
+      'sessions',
       'commands',
       'userInteraction',
       'tools',
diff --git a/packages/ui/tui/tests/session-query.ts b/packages/ui/tui/tests/session-query.ts
new file mode 100644
index 0000000000..d9083ad6d1
--- /dev/null
+++ b/packages/ui/tui/tests/session-query.ts
@@ -0,0 +1,16 @@
+import SessionQueryService from '@deepseek-ai/dsh-session-query'
+
+/** Test-only backend-independent query service. */
+export class TestSessionQueryService extends SessionQueryService {
+  override searchSessions(
+    ..._args: Parameters<SessionQueryService['searchSessions']>
+  ): ReturnType<SessionQueryService['searchSessions']> {
+    return Promise.resolve({ items: [] })
+  }
+
+  override searchEvents(
+    ..._args: Parameters<SessionQueryService['searchEvents']>
+  ): ReturnType<SessionQueryService['searchEvents']> {
+    return Promise.resolve({ items: [] })
+  }
+}
diff --git a/packages/ui/tui/tests/session-reference.snapshot.ts b/packages/ui/tui/tests/session-reference.snapshot.ts
index 4fecad3b86..f0b5e0eb61 100644
--- a/packages/ui/tui/tests/session-reference.snapshot.ts
+++ b/packages/ui/tui/tests/session-reference.snapshot.ts
@@ -11,10 +11,10 @@ import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import CommandService from '@deepseek-ai/dsh-commands'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQueryService from '@deepseek-ai/dsh-session-query'
 import SessionReferenceService, { formatSessionReferenceMention } from '@deepseek-ai/dsh-session-reference'
 import { createTuiChat } from '../src/index.ts'
 import { HeadlessTerminal } from './headless-terminal.ts'
+import { TestSessionQueryService } from './session-query.ts'
 
 const EXPECTED = join(dirname(fileURLToPath(import.meta.url)), 'snapshots/session-reference.expected.txt')
 const REFRESHING = process.env.DSH_SNAPSHOT === 'refresh'
@@ -57,7 +57,7 @@ describe('TUI session-reference snapshot', () => {
     await ctx.plugin(CommandService)
     await ctx.plugin(UserInteractionService)
     await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(SessionQueryService)
+    await ctx.plugin(TestSessionQueryService)
     await ctx.plugin(SessionReferenceService)
 
     const adapter = new SnapshotAdapter()
@@ -128,7 +128,7 @@ describe('TUI session-reference snapshot', () => {
       type: 'text',
       text: '\n\n## My request:\n',
     })
-    expect(target.session.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(target.session.events.some(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toBe(false)
 
     const snapshot = await terminal.snapshot({ includeScrollback: true })
     if (REFRESHING) {
diff --git a/packages/ui/tui/tests/snapshots/file-autocomplete.expected.txt b/packages/ui/tui/tests/snapshots/file-autocomplete.expected.txt
new file mode 100644
index 0000000000..174f21a0f4
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/file-autocomplete.expected.txt
@@ -0,0 +1,24 @@
+terminal 96x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=5 viewportRow=4 bufferRow=4
+viewport
+0| " DEEPSEEK HARNESS"
+  style 1-8 fg=bright-blue bold
+  style 10-16 bold
+1| " Snapshot agent ready."
+  style 1-21 fg=bright-black
+2| " deepseek-v4-flash  •  main-session"
+  style 1-34 dim
+3| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+4| " @tsc                                                                                           "
+  style 5-5 inverse
+5| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+6| " → File · terminal-special-case.t  src/terminal-special-case.ts                                 "
+  style 1-32 fg=bright-blue
+7| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+8-35| <blank>
diff --git a/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt b/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt
index 7711b71636..db54654115 100644
--- a/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt
+++ b/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt
@@ -1,32 +1,51 @@
 terminal 92x32 buffer=normal length=32 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=10 bufferRow=10
+cursor hidden column=6 viewportRow=4 bufferRow=4
 buffer
-0| " DEEPSEEK HARNESS"
-  style 1-8 fg=bright-blue bold
-  style 10-16 bold
-1| " Snapshot agent ready."
-  style 1-21 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
-3| <blank>
-4| " Resumable sessions                                                                         "
-  style 1-18 fg=bright-blue bold
-5| " 2024-01-02 03:04 (current)                                                                 "
-  style 1-16 fg=bright-black
-  style 17-26 fg=green
-6| "   RESUME_SESSION_ID=main-session dsh                                                       "
-7| " 2024-01-01 00:00                                                                           "
-  style 1-16 fg=bright-black
-8| "   RESUME_SESSION_ID=earlier-session dsh                                                    "
-9| "────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-91 dim
-10| "                                                                                            "
-  style 1-1 inverse
-11| "────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-91 dim
-12| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                     0% context  tools:collapsed"
-  style 0-43 dim
-  style 65-91 dim
-13-31| <blank>
+0| "                                                                                            "
+1| "  Resume session (1 of 2)                                                                   "
+  style 2-24 fg=bright-blue bold
+2| "                                                                                            "
+3| "  ╭──────────────────────────────────────────────────────────────────────────────────────╮  "
+  style 2-89 dim
+4| "  │ ⌕                                                                                    │  "
+  style 2-2 dim
+  style 6-6 inverse
+  style 89-89 dim
+5| "  ╰──────────────────────────────────────────────────────────────────────────────────────╯  "
+  style 2-89 dim
+6| "                                                                                            "
+7| "  /workspace/project                                                                        "
+  style 2-19 fg=bright-black
+8| "                                                                                            "
+9| "  ❯ Untitled session                                                                        "
+  style 2-19 fg=bright-blue bold
+10| "    2026-07-23T08:00:00.000Z · no completed turn · route unavailable                        "
+  style 2-67 fg=bright-black
+11| "    current · live · main-session                                                           "
+  style 2-32 dim
+12| "    unavailable: current session                                                            "
+  style 2-31 fg=yellow
+13| "    Resume selector design                                                                  "
+14| "    2024-01-01T00:00:08.000Z · turn 1: completed · deepseek/deepseek-v4-pro                 "
+  style 2-74 fg=bright-black
+15| "    persisted · earlier-session                                                             "
+  style 2-30 dim
+16| "                                                                                            "
+17| "                                                                                            "
+18| "                                                                                            "
+19| "                                                                                            "
+20| "                                                                                            "
+21| "                                                                                            "
+22| "                                                                                            "
+23| "                                                                                            "
+24| "                                                                                            "
+25| "                                                                                            "
+26| "                                                                                            "
+27| "                                                                                            "
+28| "                                                                                            "
+29| "                                                                                            "
+30| "  Type to search  •  ↑/↓ navigate  •  Enter resume  •  Esc clear/cancel                     "
+  style 2-70 dim
+31| "                                                                                            "
diff --git a/packages/ui/tui/tests/tui.snapshot.ts b/packages/ui/tui/tests/tui.snapshot.ts
index 9a2f3b51e1..d837841286 100644
--- a/packages/ui/tui/tests/tui.snapshot.ts
+++ b/packages/ui/tui/tests/tui.snapshot.ts
@@ -1,4 +1,5 @@
-import { mkdir, readdir, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it, vi } from 'vitest'
@@ -6,8 +7,7 @@ import type { Context } from 'cordis'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
 import { CallId, type ContentBlock } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-llm-retry'
-import type { Session } from '@deepseek-ai/dsh-session'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionId, type JsonValue, type Session } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { type ToolDefinition, type ToolResultView } from '@deepseek-ai/dsh-tools'
 import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
@@ -32,6 +32,7 @@ const CHECKPOINTS = [
   'retry-cancelled',
   'retry-exhausted',
   'banner-gradient',
+  'file-autocomplete',
   'code-mode-pending',
   'dynamic-workflow-pending',
   'cordis-tools-pending',
@@ -157,7 +158,7 @@ function appendToolResult(
   session: Session,
   id: string,
   content: ContentBlock[],
-  options: { isError?: boolean; meta?: unknown } = {},
+  options: { isError?: boolean; meta?: JsonValue } = {},
 ): void {
   session.append('tool/result', {
     turn: 1,
@@ -178,6 +179,7 @@ function visualTool(
     name,
     description: `${name} snapshot fixture`,
     parameters: {},
+    output: { schema: { type: 'null' }, render: () => [] },
     execute: () => Promise.resolve([]),
     presentCall: call,
     ...result === undefined ? {} : { presentResult: result },
@@ -337,6 +339,24 @@ describe('TUI terminal-state snapshots', () => {
     await disposeSnapshot(harness)
   })
 
+  it('pins fuzzy file candidates and the active path-only mention', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'dsh-tui-file-snapshot-'))
+    await mkdir(join(cwd, 'src'), { recursive: true })
+    await writeFile(join(cwd, 'src', 'terminal-special-case.ts'), 'export const marker = true\n')
+    await writeFile(join(cwd, 'src', 'terminal-state.ts'), 'export const state = true\n')
+    const harness = await setupSnapshot({ cwd, formatCwd: () => '/workspace/project' })
+    try {
+      harness.terminal.send('@tsc')
+      await vi.waitFor(async () => {
+        expect(await harness.terminal.snapshot()).toContain('File · terminal-special-case.t')
+      })
+      await checkpoint('file-autocomplete', harness.terminal)
+    } finally {
+      await disposeSnapshot(harness)
+      await rm(cwd, { recursive: true, force: true })
+    }
+  })
+
   it('pins Code Mode run_code with its production presenter', async () => {
     const harness = await setupSnapshot({ configureContext: configureAdvancedTools })
     const call = {
@@ -451,7 +471,7 @@ describe('TUI terminal-state snapshots', () => {
         session.append('todo/write', {
           todos: [{ content: `Unsafe todo ${CONTROL_PROBE}`, status: 'in_progress' }],
         })
-        session.append('context/message', {
+        session.append('user/message', {
           content: [{ type: 'text', text: `Unsafe context ${CONTROL_PROBE}` }],
           source: { kind: 'plugin', plugin: `unsafe-${CONTROL_PROBE}` },
         }, { surfaceOp: 'append' })
@@ -567,7 +587,7 @@ describe('TUI terminal-state snapshots', () => {
     await checkpoint('surface-before-compaction', harness.terminal, { includeScrollback: true })
 
     await renderAfter(harness, () => {
-      harness.session.append('context/message', {
+      harness.session.append('user/message', {
         content: [{ type: 'text', text: 'Compacted summary: the prior command completed and its details were retired from the active surface.' }],
         source: { kind: 'plugin', plugin: 'compact' },
       }, {
@@ -626,13 +646,27 @@ describe('TUI terminal-state snapshots', () => {
     await disposeSnapshot(harness)
   })
 
-  it('lists this workspace\'s resumable sessions with their commands', async () => {
+  it('opens the searchable resume selector with log-backed session summaries', async () => {
+    const dateNow = vi.spyOn(Date, 'now').mockReturnValue(Date.parse('2026-07-23T08:00:00.000Z'))
+    const earlier = { version: 0, id: SessionId('earlier-session'), createdAt: Date.parse('2024-01-01T00:00:00Z'), cwd: '/workspace/project' }
     const harness = await setupSnapshot({
       config: { resumeCommand: 'RESUME_SESSION_ID={session} dsh' },
-      sessionPersistence: { list: async () => [
-        { version: 0, id: SessionId('main-session'), createdAt: Date.parse('2024-01-02T03:04:00Z'), cwd: '/workspace/project' },
-        { version: 0, id: SessionId('earlier-session'), createdAt: Date.parse('2024-01-01T00:00:00Z'), cwd: '/workspace/project' },
-      ] },
+      sessionPersistence: {
+        list: async () => [earlier],
+        load: async () => ({
+          meta: earlier,
+          events: [
+            { type: 'turn/start', seq: 0, time: Date.parse('2024-01-01T00:00:01Z'), data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+            { type: 'user/message', seq: 1, time: Date.parse('2024-01-01T00:00:02Z'), data: { content: [{ type: 'text', text: 'restore the selector' }], source: { kind: 'user' } }, surfaceOp: 'append' },
+            { type: 'step/start', seq: 2, time: Date.parse('2024-01-01T00:00:03Z'), data: { turn: 1, step: 1 } },
+            { type: 'request/header', seq: 3, time: Date.parse('2024-01-01T00:00:04Z'), data: { header: { config: { provider: 'deepseek', model: 'deepseek-v4-pro' } }, reason: 'initial' } },
+            { type: 'assistant/message', seq: 4, time: Date.parse('2024-01-01T00:00:05Z'), data: { turn: 1, step: 1, content: [{ type: 'text', text: 'ready' }], provenance: { provider: 'deepseek', model: 'deepseek-v4-pro' } }, surfaceOp: 'append' },
+            { type: 'step/end', seq: 5, time: Date.parse('2024-01-01T00:00:06Z'), data: { turn: 1, step: 1 } },
+            { type: 'turn/end', seq: 6, time: Date.parse('2024-01-01T00:00:07Z'), data: { turn: 1, reason: { kind: 'completed' } } },
+            { type: 'session/title', seq: 7, time: Date.parse('2024-01-01T00:00:08Z'), data: { title: 'Resume selector design', messageSeqs: [1], source: { kind: 'fallback' } } },
+          ],
+        }),
+      },
     }, { columns: 92, rows: 32 })
     harness.terminal.send('/resume')
     harness.terminal.send('\r')
@@ -642,6 +676,7 @@ describe('TUI terminal-state snapshots', () => {
     await harness.terminal.flush()
     await checkpoint('resume-sessions', harness.terminal, { includeScrollback: true })
     await disposeSnapshot(harness)
+    dateNow.mockRestore()
   })
 
   it('pins the detailed session diagnostics card', async () => {
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 22a50c9ccf..0fea8b2750 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -1,26 +1,32 @@
-import { homedir } from 'node:os'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { CombinedAutocompleteProvider, type Terminal } from '@earendil-works/pi-tui'
-import AgentRegistry, { agentEvents, assembleContextFor, type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, assembleContextFor, AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
 import { type LlmCallConfig } from '@deepseek-ai/dsh-llm'
+import { GOAL_CHANGE_VERSION, GoalId, renderGoalChange, type GoalSnapshotChangeMeta } from '@deepseek-ai/dsh-goal'
 import CommandService, { type CommandInvocation } from '@deepseek-ai/dsh-commands'
-import SessionStore, { SessionId, type JsonValue, type SessionHeader } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, type JsonValue, type SessionEvent, type SessionHeader, type TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { SessionRecord } from '@deepseek-ai/dsh-session-query'
 import SkillService, { type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill'
 import type {} from '@deepseek-ai/dsh-session-title'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQueryService from '@deepseek-ai/dsh-session-query'
 import SessionReferenceService, { formatSessionReferenceMention } from '@deepseek-ai/dsh-session-reference'
 import type {} from '@deepseek-ai/dsh-llm-retry'
 import {
   createTuiChat,
+  FILE_REFERENCE_PROMPT,
   mountTui,
   renderSkillInvocation,
   resolveTuiConfig,
+  type TuiOverlayHost,
+  type TuiOverlaySession,
   type TuiRuntime,
 } from '../src/index.ts'
+import { WorkspaceFileSearch } from '../src/file-autocomplete.ts'
 import {
   appendAssistant,
   appendUser,
@@ -28,6 +34,12 @@ import {
   disposeTuiTestHarness,
   type TuiHarnessOptions,
 } from './harness.ts'
+import { TestSessionQueryService } from './session-query.ts'
+
+const UNUSED_TOOL_OUTPUT: ToolDefinition['output'] = {
+  schema: { type: 'null' },
+  render: () => [],
+}
 
 class FakeTerminal implements Terminal {
   columns = 88
@@ -142,10 +154,14 @@ describe('TUI config', () => {
       maxToolOutputLines: 6,
       maxQuestionOptions: 8,
       maxModelOptions: 8,
+      maxResumeOptions: 8,
       questionDialogWidth: 200,
       questionDialogMaxHeight: 20,
       modelDialogWidth: 72,
       modelDialogMaxHeight: 20,
+      fileSearchMaxResults: 20,
+      fileSearchMaxEntries: 10_000,
+      fileSearchExcludedDirectories: ['.git', 'node_modules'],
       showHardwareCursor: false,
       color: true,
       truecolor: false,
@@ -156,10 +172,14 @@ describe('TUI config', () => {
       maxToolOutputLines: 2,
       maxQuestionOptions: 3,
       maxModelOptions: 4,
+      maxResumeOptions: 5,
       questionDialogWidth: 60,
       questionDialogMaxHeight: 14,
       modelDialogWidth: 64,
       modelDialogMaxHeight: 16,
+      fileSearchMaxResults: 7,
+      fileSearchMaxEntries: 123,
+      fileSearchExcludedDirectories: ['.git', 'generated'],
       showHardwareCursor: true,
       color: false,
       truecolor: true,
@@ -169,10 +189,14 @@ describe('TUI config', () => {
       maxToolOutputLines: 2,
       maxQuestionOptions: 3,
       maxModelOptions: 4,
+      maxResumeOptions: 5,
       questionDialogWidth: 60,
       questionDialogMaxHeight: 14,
       modelDialogWidth: 64,
       modelDialogMaxHeight: 16,
+      fileSearchMaxResults: 7,
+      fileSearchMaxEntries: 123,
+      fileSearchExcludedDirectories: ['.git', 'generated'],
       showHardwareCursor: true,
       color: false,
       truecolor: true,
@@ -185,6 +209,21 @@ describe('resume command and /resume', () => {
   const RESUME = 'RESUME_SESSION_ID={session} dsh'
   const header = (id: string, createdAt: number, cwd: string): SessionHeader =>
     ({ version: 0, id: SessionId(id), createdAt, cwd })
+  const resumeEvents = (
+    title: string,
+    provider = 'deepseek',
+    time = 100,
+    reason: TurnEndReason = { kind: 'completed' },
+  ): SessionEvent[] => [
+    { type: 'turn/start', seq: 0, time, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    { type: 'user/message', seq: 1, time: time + 1, data: { content: [{ type: 'text', text: 'resume me' }], source: { kind: 'user' } }, surfaceOp: 'append' },
+    { type: 'step/start', seq: 2, time: time + 2, data: { turn: 1, step: 1 } },
+    { type: 'request/header', seq: 3, time: time + 3, data: { header: { config: { provider, model: 'model-1' } }, reason: 'initial' } },
+    { type: 'assistant/message', seq: 4, time: time + 4, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'done' }], provenance: { provider, model: 'model-1' } }, surfaceOp: 'append' },
+    { type: 'step/end', seq: 5, time: time + 5, data: { turn: 1, step: 1 } },
+    { type: 'turn/end', seq: 6, time: time + 6, data: { turn: 1, reason } },
+    { type: 'session/title', seq: 7, time: time + 7, data: { title, messageSeqs: [1], source: { kind: 'fallback' } } },
+  ]
 
   it('prints the resume command on exit once the session is persisted', async () => {
     const result = await setup({
@@ -224,73 +263,832 @@ describe('resume command and /resume', () => {
     await dispose(result)
   })
 
-  it('lists this workspace\'s sessions newest-first and marks the current one', async () => {
+  it('opens a newest-active-first searchable selector and Esc clears before cancelling', async () => {
+    const older = header('older-session', 500, '/workspace')
+    const newer = header('newer-session', 2000, '/workspace')
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>()
     const result = await setup({
       cwd: '/workspace',
       config: { resumeCommand: RESUME },
+      handoffResume: handoff,
       sessionPersistence: {
-        list: async () => [
-          header('main-session', 1000, '/workspace'),
-          header('older-session', 500, '/workspace'),
-          header('newer-session', 2000, '/workspace'),
-          header('foreign-session', 3000, '/elsewhere'),
-        ],
+        list: async () => [older, newer, header('foreign-session', 3000, '/elsewhere')],
+        load: async id => id === newer.id
+          ? { meta: newer, events: resumeEvents('Newer product work', 'deepseek', 300) }
+          : { meta: older, events: resumeEvents('Older investigation', 'deepseek', 100) },
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    const output = result.terminal.output
+    expect(output).toContain('Resume session')
+    expect(output).toContain('Newer product work')
+    expect(output).toContain('Older investigation')
+    expect(output).toContain('current · live')
+    expect(output.indexOf('Newer product work')).toBeLessThan(output.indexOf('Older investigation'))
+    expect(output).not.toContain('foreign-session')
+    result.terminal.send('Older')
+    await tick()
+    expect(result.terminal.output).toContain('⌕ Older')
+    result.terminal.send('\x1b')
+    await tick()
+    expect(result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session')))
+      .not.toContain('⌕ Older')
+    result.terminal.send('\x1b')
+    await tick()
+    expect(handoff).not.toHaveBeenCalled()
+    await dispose(result)
+  })
+
+  it('handles selector navigation, empty matches, and backspace search edits', async () => {
+    const target = header('keyboard-target', 10, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Keyboard target') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('\x1b[B')
+    result.terminal.send('\x1b[A')
+    result.terminal.send('\t')
+    result.terminal.send('zz')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('No session matches this search')
+    result.terminal.send('\x7f')
+    result.terminal.send('\x7f')
+    await tick()
+    const cleared = result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session'))
+    expect(cleared).toContain('⌕ ')
+    expect(cleared).not.toContain('zz')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('current session')
+    result.terminal.send('\x1b')
+    await dispose(result)
+  })
+
+  it('sanitizes bracketed-paste terminal controls before storing the search query', async () => {
+    const target = header('safe-target', 10, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Safe target') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('\x1b[200~Safe\x1b]0;own')
+    result.terminal.send('ed\x07 target\x1b[31m\x1b[201~')
+    await tick()
+    const rendered = result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session'))
+    expect(rendered).toContain('⌕ Safe target')
+    expect(rendered).not.toContain('owned')
+    expect(rendered).not.toContain('[31m')
+    result.terminal.send('\x1b')
+    result.terminal.send('Safe\x1b[200~\x1b[201~ target')
+    await tick()
+    expect(result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session')))
+      .toContain('⌕ Safe target')
+    await dispose(result)
+  })
+
+  it('pages by the number of candidates that fit the current viewport', async () => {
+    const targets = Array.from({ length: 8 }, (_, index) =>
+      header(`paged-${index}`, 1000 - index, '/workspace'))
+    const result = await setup({
+      cwd: '/workspace',
+      sessionPersistence: {
+        list: async () => targets,
+        load: async id => ({
+          meta: targets.find(target => target.id === id)!,
+          events: resumeEvents(`Paged ${id.slice('paged-'.length)}`, 'deepseek', 1000 - Number(id.slice('paged-'.length)) * 10),
+        }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('\x1b[6~')
+    await tick()
+    const rendered = result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session'))
+    expect(rendered).toContain('❯ Paged 3')
+    result.terminal.send('\x1b[5~')
+    await tick()
+    expect(result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session')))
+      .toContain('❯ Untitled session')
+    result.terminal.resize(10)
+    await tick()
+    expect(result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session')))
+      .toContain('⌕')
+    result.terminal.send('\x03')
+    await dispose(result)
+  })
+
+  it('clips candidate count through the configured visible-session limit', async () => {
+    const targets = [header('limited-a', 10, '/workspace'), header('limited-b', 20, '/workspace')]
+    const result = await setup({
+      cwd: '/workspace',
+      config: { maxResumeOptions: 1 },
+      sessionPersistence: {
+        list: async () => targets,
+        load: async id => ({
+          meta: targets.find(target => target.id === id)!,
+          events: resumeEvents(`Limited ${id}`),
+        }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('(1 of 3)')
+    await dispose(result)
+  })
+
+  it.each([
+    [{ kind: 'aborted' }, 'cancelled'],
+    [{ kind: 'error', step: 1, message: 'failed' }, 'error'],
+    [{ kind: 'disposed' }, 'disposed'],
+    [{ kind: 'max-tokens' }, 'max tokens'],
+    [{ kind: 'rejected', reason: 'policy' }, 'rejected'],
+    [{ kind: 'interrupted' }, 'interrupted'],
+    [{ kind: 'future-result' } as unknown as TurnEndReason, 'unknown result'],
+  ] as const)('renders the last turn result %s', async (reason, label) => {
+    const target = header(`turn-${label}`, 10, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents(`Turn ${label}`, 'deepseek', 100, reason) }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain(`turn 1: ${label}`)
+    await dispose(result)
+  })
+
+  it('refuses while running instead of cancelling or switching', async () => {
+    const result = await setup({ cwd: '/workspace', status: 'running' })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('finish or be cancelled first')
+    expect(result.agent.cancelled).toEqual([])
+    await dispose(result)
+  })
+
+  it('warns when the optional session-query service is absent', async () => {
+    const result = await setup({ cwd: '/workspace', mountSessionQuery: false })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('session query is not mounted')
+    await dispose(result)
+  })
+
+  it('keeps persisted query records readable without a persistence service', async () => {
+    const target = header('query-only-persisted', 10, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.provide('sessionQuery', {
+          listSessions: () => Promise.resolve([{
+            header: target,
+            live: false,
+            persisted: true,
+          }]),
+          readSession: () => Promise.resolve({
+            session: target,
+            events: resumeEvents('Query-only persisted session'),
+          }),
+        } as never)
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('Query-only persisted session')
+    expect(result.terminal.output).toContain('persisted')
+    expect(result.terminal.output).not.toContain('session cannot be loaded')
+    await dispose(result)
+  })
+
+  it('contains a session-query scan failure in the current TUI', async () => {
+    const result = await setup({
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.provide('sessionQuery', {
+          listSessions: () => Promise.reject(new Error('index unavailable')),
+        } as never)
       },
     })
     result.terminal.send('/resume')
     result.terminal.send('\r')
     await tick()
-    const output = result.terminal.output
-    expect(output).toContain('Resumable sessions')
-    expect(output).toContain('RESUME_SESSION_ID=main-session dsh')
-    expect(output).toContain('(current)')
-    expect(output).toContain('RESUME_SESSION_ID=newer-session dsh')
-    expect(output).not.toContain('foreign-session')
-    // Newest-first: the newer session's command precedes the current session's.
-    // Match the full resume command, not the bare id: the banner detail line
-    // echoes the current session id (`main-session`) above the listing.
-    expect(output.indexOf('RESUME_SESSION_ID=newer-session')).toBeLessThan(
-      output.indexOf('RESUME_SESSION_ID=main-session'),
-    )
-    expect(output.indexOf('RESUME_SESSION_ID=main-session')).toBeLessThan(
-      output.indexOf('RESUME_SESSION_ID=older-session'),
-    )
+    expect(result.terminal.output).toContain('Resume session scan failed: index unavailable')
+    expect(result.terminal.stopped).toBe(0)
     await dispose(result)
   })
 
-  it('warns from /resume when resume is not configured', async () => {
-    const result = await setup({ cwd: '/workspace' })
-    result.terminal.send('/resume')
-    result.terminal.send('\r')
-    await tick()
-    expect(result.terminal.output).toContain('Resume is not configured')
-    await dispose(result)
-  })
-
-  it('warns from /resume when no persistence backend is mounted', async () => {
-    const result = await setup({ cwd: '/workspace', config: { resumeCommand: RESUME } })
-    result.terminal.send('/resume')
-    result.terminal.send('\r')
-    await tick()
-    expect(result.terminal.output).toContain('no persistence backend is mounted')
-    await dispose(result)
-  })
-
-  it('notes from /resume when no workspace sessions are persisted yet', async () => {
+  it('supersedes a slower prior selector scan', async () => {
+    const first = Promise.withResolvers<SessionRecord[]>()
+    let calls = 0
     const result = await setup({
-      cwd: '/workspace',
-      config: { resumeCommand: RESUME },
-      sessionPersistence: { list: async () => [header('foreign-session', 10, '/elsewhere')] },
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.provide('sessionQuery', {
+          listSessions: () => ++calls === 1 ? first.promise : Promise.resolve([]),
+        } as never)
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick()
+    first.reject(new Error('superseded scan failed'))
+    await tick()
+    expect(calls).toBe(2)
+    expect(result.terminal.output).toContain('No matching sessions')
+    expect(result.terminal.output).not.toContain('superseded scan failed')
+    result.terminal.send('\x1b[A')
+    result.terminal.send('\x1b[B')
+    await dispose(result)
+  })
+
+  it('drops a selector scan that resolves after TUI disposal', async () => {
+    const listing = Promise.withResolvers<SessionRecord[]>()
+    const result = await setup({
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.provide('sessionQuery', { listSessions: () => listing.promise } as never)
+      },
     })
     result.terminal.send('/resume')
     result.terminal.send('\r')
     await tick()
-    expect(result.terminal.output).toContain('No resumable sessions found')
+    await dispose(result)
+    listing.resolve([])
+    await tick()
+    expect(result.terminal.stopped).toBeGreaterThan(0)
+  })
+
+  it('drops loaded selector summaries when the TUI disposed during log reads', async () => {
+    const target = header('dispose-during-load', 10, '/workspace')
+    const loading = Promise.withResolvers<{ meta: SessionHeader; events: SessionEvent[] }>()
+    const result = await setup({
+      cwd: '/workspace',
+      sessionPersistence: {
+        list: async () => [target],
+        load: () => loading.promise,
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick()
+    await dispose(result)
+    loading.resolve({ meta: target, events: resumeEvents('Disposed load') })
+    await tick()
+    expect(result.terminal.stopped).toBeGreaterThan(0)
+  })
+
+  it('preflights route availability and corrupt sessions without losing the current TUI', async () => {
+    const missing = header('missing-route', 10, '/workspace')
+    const corrupt = header('corrupt', 30, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      config: { resumeCommand: RESUME },
+      sessionPersistence: {
+        list: async () => [missing, corrupt],
+        load: async (id) => {
+          if (id === corrupt.id) throw new Error('checksum mismatch')
+          return {
+            meta: missing,
+            events: resumeEvents('Missing adapter', 'absent-provider'),
+          }
+        },
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('Missing adapter')
+    expect(result.terminal.output).toContain('absent-provider/model-1')
+    expect(result.terminal.output).toContain('Unreadable session')
+    result.terminal.send('Missing adapter')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('route is currently unavailable')
+    expect(result.terminal.stopped).toBe(0)
+    await dispose(result)
+  })
+
+  it('keeps a session already live in this runtime visible but disabled', async () => {
+    const target = header('live-target', 10, '/workspace')
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>()
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: handoff,
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.provide('sessionQuery', {
+          listSessions: () => Promise.resolve([{
+            header: target,
+            live: true,
+            persisted: true,
+          }]),
+          readSession: () => Promise.resolve({
+            session: target,
+            events: resumeEvents('Live target'),
+          }),
+        } as never)
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Live target')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('session is already live in this runtime')
+    expect(handoff).not.toHaveBeenCalled()
+    await dispose(result)
+  })
+
+  it('falls back to assistant provenance and header creation time for sparse logs', async () => {
+    const assistantOnly = header('assistant-route', 20, '/workspace')
+    const empty = header('empty-log', 10, '/workspace')
+    const events = resumeEvents('Assistant route', 'deepseek')
+      .filter(event => event.type !== 'request/header')
+      .map((event, seq) => ({ ...event, seq })) as SessionEvent[]
+    const result = await setup({
+      cwd: '/workspace',
+      sessionPersistence: {
+        list: async () => [assistantOnly, empty],
+        load: async id => id === assistantOnly.id
+          ? { meta: assistantOnly, events }
+          : { meta: empty, events: [] },
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('deepseek/model-1')
+    expect(result.terminal.output).toContain(new Date(empty.createdAt).toISOString())
+    await dispose(result)
+  })
+
+  it('flushes, releases the terminal, and invokes one host handoff for the same SessionId', async () => {
+    const target = header('target-session', 10, '/workspace')
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>(() => Promise.reject(new Error('test host retained process')))
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: handoff,
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Target session') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Target session')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(handoff).toHaveBeenCalledTimes(1)
+    expect(handoff).toHaveBeenCalledWith(target.id)
+    expect(result.terminal.stopped).toBeGreaterThan(0)
+    expect(result.terminal.output).toContain('Resume handoff failed: test host retained process')
+    await dispose(result)
+  })
+
+  it('restores the UI when a host returns instead of replacing the process', async () => {
+    const target = header('returning-host', 10, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: async () => undefined as never,
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Returning host') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Returning host')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('resume host returned without replacing the process')
+    await dispose(result)
+  })
+
+  it('keeps the current TUI when the selected log fails its second preflight load', async () => {
+    const target = header('racing-corruption', 10, '/workspace')
+    let loads = 0
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: vi.fn(),
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => {
+          if (++loads > 1) throw new Error('log changed during selection')
+          return { meta: target, events: resumeEvents('Racing corruption') }
+        },
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Racing corruption')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('Resume failed: session cannot be loaded: failed to inspect session')
+    expect(result.terminal.output).toContain('log changed during selection')
+    expect(result.terminal.stopped).toBe(0)
+    await dispose(result)
+  })
+
+  it('does not flush or hand off when disposal begins during selected-session preflight', async () => {
+    const target = header('dispose-during-preflight', 10, '/workspace')
+    const secondListing = Promise.withResolvers<SessionRecord[]>()
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>()
+    const flush = vi.fn()
+    let listings = 0
+    const record: SessionRecord = { header: target, live: false, persisted: true }
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: handoff,
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.on('session/flush', flush)
+        ctx.provide('sessionQuery', {
+          listSessions: () => ++listings === 1 ? Promise.resolve([record]) : secondListing.promise,
+          readSession: () => Promise.resolve({
+            session: target,
+            events: resumeEvents('Dispose during preflight'),
+          }),
+        } as never)
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick()
+    result.terminal.send('Dispose during preflight')
+    result.terminal.send('\r')
+    await vi.waitFor(() => { expect(listings).toBe(2) })
+    await dispose(result)
+    secondListing.resolve([record])
+    await tick()
+    expect(flush).not.toHaveBeenCalled()
+    expect(handoff).not.toHaveBeenCalled()
+  })
+
+  it('hands off a validated session exposed by a query backend without a persistence service', async () => {
+    const target = header('query-without-persistence', 10, '/workspace')
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>(
+      () => Promise.reject(new Error('test host retained process')),
+    )
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: handoff,
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.provide('sessionQuery', {
+          listSessions: () => Promise.resolve([{
+            header: target,
+            live: false,
+            persisted: true,
+          }]),
+          readSession: () => Promise.resolve({
+            session: target,
+            events: resumeEvents('Query without persistence'),
+          }),
+        } as never)
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Query without persistence')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(handoff).toHaveBeenCalledWith(target.id)
+    expect(result.terminal.output).toContain('Resume handoff failed: test host retained process')
+    await dispose(result)
+  })
+
+  it('does not hand off after disposal begins during the current-session flush', async () => {
+    const target = header('dispose-during-flush', 10, '/workspace')
+    const flushing = Promise.withResolvers<undefined>()
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>()
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: handoff,
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.on('session/flush', () => flushing.promise)
+      },
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Dispose during flush') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Dispose during flush')
+    result.terminal.send('\r')
+    await tick()
+    const disposing = dispose(result)
+    await tick()
+    flushing.resolve(undefined)
+    await disposing
+    expect(handoff).not.toHaveBeenCalled()
+  })
+
+  it('does not hand off after disposal begins while terminal input drains', async () => {
+    const target = header('dispose-during-drain', 10, '/workspace')
+    const draining = Promise.withResolvers<undefined>()
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>()
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: handoff,
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Dispose during drain') }),
+      },
+    })
+    result.terminal.drainInput.mockImplementationOnce(() => draining.promise)
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Dispose during drain')
+    result.terminal.send('\r')
+    await vi.waitFor(() => { expect(result.terminal.drainInput).toHaveBeenCalled() })
+    await dispose(result)
+    draining.resolve(undefined)
+    await tick()
+    expect(handoff).not.toHaveBeenCalled()
+  })
+
+  it('does not restart the terminal when a pending host rejects during disposal', async () => {
+    const target = header('host-rejects-during-disposal', 10, '/workspace')
+    const host = Promise.withResolvers<never>()
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>(() => host.promise)
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: handoff,
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Host disposal') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Host disposal')
+    result.terminal.send('\r')
+    await vi.waitFor(() => { expect(handoff).toHaveBeenCalled() })
+    const startsBeforeDispose = result.terminal.started
+    await dispose(result)
+    host.reject(new Error('host rejected after disposal'))
+    await tick()
+    expect(result.terminal.started).toBe(startsBeforeDispose)
+    expect(result.terminal.output).not.toContain('host rejected after disposal')
+  })
+
+  it('rejects a candidate whose cwd changes between listing and preflight', async () => {
+    const target = header('moving-workspace', 10, '/workspace')
+    let listings = 0
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: vi.fn(),
+      sessionPersistence: {
+        list: async () => [++listings <= 2 ? target : header('moving-workspace', 10, '/elsewhere')],
+        load: async () => ({
+          meta: listings <= 2 ? target : header('moving-workspace', 10, '/elsewhere'),
+          events: resumeEvents('Moving workspace'),
+        }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Moving workspace')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('different workspace')
+    await dispose(result)
+  })
+
+  it('admits only one handoff while the selected preflight is pending', async () => {
+    const target = header('single-handoff', 10, '/workspace')
+    const preflight = Promise.withResolvers<{ meta: SessionHeader; events: SessionEvent[] }>()
+    let loads = 0
+    const result = await setup({
+      cwd: '/workspace',
+      sessionPersistence: {
+        list: async () => [target],
+        load: () => ++loads === 1
+          ? Promise.resolve({ meta: target, events: resumeEvents('Single handoff') })
+          : preflight.promise,
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Single handoff')
+    result.terminal.send('\r')
+    result.terminal.send('\r')
+    await tick()
+    preflight.resolve({ meta: target, events: resumeEvents('Single handoff') })
+    await tick(); await tick()
+    expect(loads).toBe(2)
+    await dispose(result)
+  })
+
+  it('rechecks running state and candidate existence before loading the selected log', async () => {
+    const target = header('preflight-races', 10, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: vi.fn(),
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Preflight races') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.agent.status = 'running'
+    result.terminal.send('Preflight races')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('Resume requires an idle agent (status: running)')
+    result.agent.status = 'idle'
+    await dispose(result)
+
+    let disappearingLists = 0
+    const disappearing = await setup({
+      cwd: '/workspace',
+      handoffResume: vi.fn(),
+      sessionPersistence: {
+        list: async () => ++disappearingLists <= 2 ? [target] : [],
+        load: async () => ({ meta: target, events: resumeEvents('Disappearing target') }),
+      },
+    })
+    disappearing.terminal.send('/resume')
+    disappearing.terminal.send('\r')
+    await tick(); await tick()
+    disappearing.terminal.send('Disappearing target')
+    disappearing.terminal.send('\r')
+    await tick()
+    expect(disappearing.terminal.output).toContain('is no longer available')
+    await dispose(disappearing)
+  })
+
+  it('rechecks idleness after the selected log finishes loading', async () => {
+    const target = header('load-turns-running', 10, '/workspace')
+    let loads = 0
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: vi.fn(),
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => {
+          loads += 1
+          if (loads === 2) result.agent.status = 'running'
+          return { meta: target, events: resumeEvents('Load turns running') }
+        },
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Load turns running')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('Resume requires an idle agent (status: running)')
+    result.agent.status = 'idle'
+    await dispose(result)
+  })
+
+  it('keeps resumeCommand as a displayed fallback when the host cannot hand off', async () => {
+    const target = header('fallback-session', 10, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      config: { resumeCommand: RESUME },
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Fallback target') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Fallback target')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('This host cannot hand off in place. Exit and run:')
+    expect(result.terminal.output).toContain('RESUME_SESSION_ID=fallback-session')
+    expect(result.terminal.stopped).toBe(0)
+    await dispose(result)
+  })
+
+  it('keeps the selector independent from an absent command fallback', async () => {
+    const target = header('no-fallback-session', 10, '/workspace')
+    const result = await setup({
+      cwd: '/workspace',
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('No fallback target') }),
+      },
+    })
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('No fallback target')
+    result.terminal.send('\r')
+    await tick()
+    expect(result.terminal.output).toContain('Session is resumable, but this host cannot hand it off in place')
+    await dispose(result)
+  })
+
+  it('rechecks idleness after the current-session flush', async () => {
+    const target = header('post-flush-running', 10, '/workspace')
+    const control: { setRunning?: () => void } = {}
+    const handoff = vi.fn<NonNullable<TuiRuntime['handoffResume']>>()
+    const result = await setup({
+      cwd: '/workspace',
+      handoffResume: handoff,
+      async configureContext(ctx) {
+        ctx.provide('tools', { get: () => undefined } as never)
+        ctx.on('session/flush', () => { control.setRunning?.() })
+      },
+      sessionPersistence: {
+        list: async () => [target],
+        load: async () => ({ meta: target, events: resumeEvents('Post-flush running') }),
+      },
+    })
+    control.setRunning = () => { result.agent.status = 'running' }
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    result.terminal.send('Post-flush running')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('Resume requires an idle agent (status: running)')
+    expect(handoff).not.toHaveBeenCalled()
+    result.agent.status = 'idle'
     await dispose(result)
   })
 })
 
 describe('pi-tui chat lifecycle and transcript', () => {
+  it('restores durable goal phase without implying automatic continuation', async () => {
+    const change: GoalSnapshotChangeMeta = {
+      kind: 'goal/change',
+      version: GOAL_CHANGE_VERSION,
+      operation: 'create',
+      goal: {
+        id: GoalId('restored-goal'),
+        revision: 1,
+        objective: 'Resume only with human confirmation',
+        phase: 'active',
+        maxGoalRounds: 4,
+      },
+      roundsStarted: 0,
+      createdAt: 10,
+      updatedAt: 10,
+    }
+    const result = await setup({
+      beforeMount(session) {
+        session.append('user/message', {
+          content: renderGoalChange(change),
+          source: { kind: 'goal', goalId: change.goal.id, revision: change.goal.revision, round: 0 },
+          meta: change as unknown as JsonValue,
+        }, { surfaceOp: 'append' })
+      },
+    })
+    expect(result.terminal.output).toContain('Goal restored (active) with automatic continuation disarmed')
+    expect(result.terminal.output).toContain('/goal resume')
+    result.terminal.send('/resume')
+    result.terminal.send('\r')
+    await tick(); await tick()
+    expect(result.terminal.output).toContain('goal active')
+    await dispose(result)
+  })
+
   it('uses the latest log-backed title for the header subtitle and terminal window', async () => {
     const result = await setup({
       // A fixed short cwd keeps the footer's token counters inside the 88-column
@@ -374,8 +1172,11 @@ describe('pi-tui chat lifecycle and transcript', () => {
     result.session.append('user/message', { content: [{ type: 'text', text: '   ' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: 'steering note' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    result.session.append('context/message', { content: [{ type: 'text', text: 'user context' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    result.session.append('context/message', { content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    result.session.append('user/message', { content: [{ type: 'text', text: 'user context' }], source: { kind: 'plugin', plugin: 'ctx' } }, { surfaceOp: 'append' })
+    result.session.append('user/message', { content: [{ type: 'text', text: '' }], source: { kind: 'plugin', plugin: 'ctx' } }, { surfaceOp: 'append' })
+    // A non-plugin injected source (goal) has no `plugin` field, so its context
+    // card label falls back to the source kind.
+    result.session.append('user/message', { content: [{ type: 'text', text: 'goal context' }], source: { kind: 'goal', goalId: 'g1', revision: 1, round: 0 } as never }, { surfaceOp: 'append' })
     result.session.append('prompt/blocked', { content: [{ type: 'text', text: 'blocked' }], source: { kind: 'user' }, reason: 'test policy' })
     appendAssistant(result.session, [])
     result.session.append('step/end', { turn: 1, step: 1 })
@@ -456,6 +1257,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     expect(result.terminal.output).toContain('Enter sends steering, Esc cancels')
     expect(result.terminal.output).toContain('Steering')
     expect(result.terminal.output).toContain('user context')
+    expect(result.terminal.output).toContain('Context · goal') // goal-sourced injected context labels by kind
     expect(result.terminal.output).toContain('Prompt blocked')
     expect(result.terminal.output).toContain('Turn cancelled')
     expect(result.terminal.progress).toContain(true)
@@ -552,16 +1354,16 @@ describe('pi-tui chat lifecycle and transcript', () => {
     expect(result.terminal.output).not.toContain('queued')
 
     const queueSteering = (text: string): void => {
-      result.ctx.emit('agent/queued', result.agent, [{ type: 'text', text }], { source: { kind: 'user' }, contexts: [], steering: true })
+      result.ctx.emit('agent/inbox/enqueue', result.agent, { id: AgentMessageId('stub'), content: [{ type: 'text', text }], source: { kind: 'user' }, contexts: [], steering: true, wakeup: true })
     }
     const drainSteering = (text: string): void => {
       result.session.append('steering/message', { turn: 1, content: [{ type: 'text', text }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     }
 
     // A steering queue for a different agent never touches this status line.
-    const other = { ...result.agent, id: SessionId('other') } as Agent
+    const other = { ...result.agent, id: SessionId('other') } as unknown as Agent
     result.terminal.output = ''
-    result.ctx.emit('agent/queued', other, [{ type: 'text', text: 'elsewhere' }], { source: { kind: 'user' }, contexts: [], steering: true })
+    result.ctx.emit('agent/inbox/enqueue', other, { id: AgentMessageId('stub'), content: [{ type: 'text', text: 'elsewhere' }], source: { kind: 'user' }, contexts: [], steering: true, wakeup: true })
     await tick()
     expect(result.terminal.output).not.toContain('queued')
 
@@ -574,7 +1376,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
 
     // A non-steering queue (an idle-style send) leaves the badge untouched.
     result.terminal.output = ''
-    result.ctx.emit('agent/queued', result.agent, [{ type: 'text', text: 'sent' }], { source: { kind: 'user' }, contexts: [], steering: false })
+    result.ctx.emit('agent/inbox/enqueue', result.agent, { id: AgentMessageId('stub'), content: [{ type: 'text', text: 'sent' }], source: { kind: 'user' }, contexts: [], steering: false, wakeup: true })
     drainSteering('first')
     await tick()
     expect(result.terminal.output).toContain('1 queued')
@@ -594,8 +1396,9 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await tick()
     expect(result.terminal.output).toContain('1 queued')
 
-    // A loop-authored steering event (plugin source, no matching agent/queued)
-    // cannot consume a pending user slot, even when it drains first.
+    // A steering/message whose source matches no pending badge entry (here a
+    // plugin source with no tracked enqueue) pops nothing, so it cannot consume
+    // a pending user slot even when it drains first.
     result.terminal.output = ''
     result.session.append('steering/message', {
       turn: 1,
@@ -627,7 +1430,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     const idle = await setup()
     // A steering queue arriving while idle has no status line to badge, so the
     // refresh is a no-op beyond requesting a render.
-    idle.ctx.emit('agent/queued', idle.agent, [{ type: 'text', text: 'early' }], { source: { kind: 'user' }, contexts: [], steering: true })
+    idle.ctx.emit('agent/inbox/enqueue', idle.agent, { id: AgentMessageId('stub'), content: [{ type: 'text', text: 'early' }], source: { kind: 'user' }, contexts: [], steering: true, wakeup: true })
     idle.session.append('tool/call', { turn: 1, step: 0, callId: 'pre' as never, name: 'bash', arguments: '{}' })
     await tick()
     expect(idle.terminal.output).not.toContain('Executing tools')
@@ -794,31 +1597,43 @@ describe('pi-tui chat lifecycle and transcript', () => {
         appendAssistant(session, [{ type: 'text', text: 'home' }], { inputTokens: 25_000, outputTokens: 10_000 })
       },
     })
-    expect(homeResult.terminal.output).toContain('~  ↑25k ↓10k')
+    await vi.waitFor(() => {
+      expect(homeResult.terminal.output).toContain('~  ↑25k ↓10k')
+    })
     await dispose(homeResult)
 
     const childResult = await setup({ cwd: join(home, 'projects', 'dsh-tui') })
-    expect(childResult.terminal.output).toContain(join('~', 'projects', 'dsh-tui'))
+    await vi.waitFor(() => {
+      expect(childResult.terminal.output).toContain(join('~', 'projects', 'dsh-tui'))
+    })
     await dispose(childResult)
 
     const unsetResult = await setup({ cwd: null })
-    expect(unsetResult.terminal.output).toContain('cwd unset')
+    await vi.waitFor(() => {
+      expect(unsetResult.terminal.output).toContain('cwd unset')
+    })
     await dispose(unsetResult)
 
     const homeParent = resolve(home, '..')
     const parentResult = await setup({ cwd: homeParent })
-    expect(parentResult.terminal.output).toContain(homeParent)
+    await vi.waitFor(() => {
+      expect(parentResult.terminal.output).toContain(homeParent)
+    })
     await dispose(parentResult)
 
     const outsideResult = await setup({ cwd: '/opt' })
-    expect(outsideResult.terminal.output).toContain('/opt')
+    await vi.waitFor(() => {
+      expect(outsideResult.terminal.output).toContain('/opt')
+    })
     await dispose(outsideResult)
 
     const logicalResult = await setup({
       cwd: '/w',
       formatCwd: cwd => `logical:${cwd}\x1b`,
     })
-    expect(logicalResult.terminal.output).toContain('logical:/w\\x1b')
+    await vi.waitFor(() => {
+      expect(logicalResult.terminal.output).toContain('logical:/w\\x1b')
+    })
     await dispose(logicalResult)
   })
 
@@ -1012,7 +1827,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     const result = await setup({
       async configureContext(ctx) {
         ctx.provide('tools', { get: () => undefined } as never)
-        await ctx.plugin(SessionQueryService)
+        await ctx.plugin(TestSessionQueryService)
         await ctx.plugin(SessionReferenceService)
         const source = ctx.sessions.create(SessionId('source-session'), { meta: { cwd: process.cwd(), createdAt: 1 } })
         sourceId = source.id
@@ -1056,13 +1871,133 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await dispose(result)
   })
 
+  it('fuzzy-completes files and directories while sending only the selected path text', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'dsh-tui-file-completion-'))
+    await mkdir(join(cwd, 'src'), { recursive: true })
+    await mkdir(join(cwd, 'docs'), { recursive: true })
+    await writeFile(join(cwd, 'src', 'source-file.ts'), 'export const source = true\n')
+    await writeFile(join(cwd, 'docs', 'design notes.md'), '# Design\n')
+    await writeFile(join(cwd, 'unsafe\u007ffile.ts'), 'unsafe name\n')
+    const result = await setup({
+      cwd,
+      tools: {
+        read: {
+          name: 'read',
+          description: 'Read a file.',
+          parameters: {},
+          output: UNUSED_TOOL_OUTPUT,
+          execute: () => Promise.resolve([]),
+        },
+      },
+    })
+    try {
+      const assembly = await result.ctx.systemPrompt.assemble(assembleContextFor(result.agent))
+      expect(assembly.sections).toContainEqual({
+        name: 'ui:tui-file-reference',
+        text: FILE_REFERENCE_PROMPT,
+      })
+
+      result.terminal.send('@sfts')
+      await vi.waitFor(() => {
+        expect(result.terminal.output).toContain('File · source-file.ts')
+      })
+      expect(result.terminal.output).toContain('src/source-file.ts')
+      result.terminal.send('\t')
+      await tick()
+      result.terminal.send('\r')
+      await vi.waitFor(() => { expect(result.agent.sent).toHaveLength(1) })
+      expect(result.agent.sent[0]).toEqual([{ type: 'text', text: '@src/source-file.ts' }])
+      expect(result.agent.sentOptions[0]?.contexts).toEqual([])
+
+      result.terminal.send('@do')
+      await vi.waitFor(() => {
+        expect(result.terminal.output).toContain('Folder · docs/')
+      })
+      result.terminal.send('\t')
+      result.terminal.output = ''
+      result.terminal.send('\t')
+      await vi.waitFor(() => {
+        expect(result.terminal.output).toContain('@"docs/design notes.md"')
+      })
+      await tick()
+      result.terminal.send('\r')
+      await vi.waitFor(() => { expect(result.agent.sent).toHaveLength(2) })
+      expect(result.agent.sent[1]).toEqual([{ type: 'text', text: '@"docs/design notes.md"' }])
+      expect(result.agent.sentOptions[1]?.contexts).toEqual([])
+
+      result.terminal.send('@unsafe')
+      await tick()
+      expect(result.terminal.output).not.toContain('File · unsafe')
+      result.terminal.send('\x03')
+    } finally {
+      await result.controller.dispose()
+      const assembly = await result.ctx.systemPrompt.assemble(assembleContextFor(result.agent))
+      expect(assembly.sections).not.toContainEqual({
+        name: 'ui:tui-file-reference',
+        text: FILE_REFERENCE_PROMPT,
+      })
+      await result.ctx.fiber.dispose()
+      await rm(cwd, { recursive: true, force: true })
+    }
+  })
+
+  it('isolates failed file discovery from editor autocomplete', async () => {
+    const list = vi.spyOn(WorkspaceFileSearch.prototype, 'list').mockRejectedValue(new Error('search failed'))
+    const result = await setup()
+    try {
+      result.terminal.send('@failed')
+      await vi.waitFor(() => { expect(list).toHaveBeenCalled() })
+      await tick()
+      expect(result.agent.sent).toEqual([])
+    } finally {
+      list.mockRestore()
+      await dispose(result)
+    }
+  })
+
+  it('shows file-reference guidance only while read is visible to the agent', async () => {
+    const read: ToolDefinition = {
+      name: 'read',
+      description: 'Read a file.',
+      parameters: {},
+      output: UNUSED_TOOL_OUTPUT,
+      execute: () => Promise.resolve([]),
+    }
+    let visibility: 'none' | 'global' | 'agent' = 'none'
+    const result = await setup({
+      async configureContext(ctx) {
+        ctx.provide('tools', {
+          get(name: string, scope?: Agent) {
+            if (name !== 'read' || visibility === 'none') return undefined
+            return (scope === undefined) === (visibility === 'global') ? read : undefined
+          },
+        } as never)
+      },
+    })
+    const fileReferenceText = async (): Promise<string | undefined> => {
+      const assembly = await result.ctx.systemPrompt.assemble(assembleContextFor(result.agent))
+      return assembly.sections.find(section => section.name === 'ui:tui-file-reference')?.text
+    }
+    try {
+      expect(await fileReferenceText()).toBe('')
+      visibility = 'global'
+      expect(await fileReferenceText()).toBe('')
+      visibility = 'agent'
+      expect(await fileReferenceText()).toBe(FILE_REFERENCE_PROMPT)
+      visibility = 'none'
+      expect(await fileReferenceText()).toBe('')
+    } finally {
+      await dispose(result)
+    }
+  })
+
   it('escapes session autocomplete metadata while preserving the referenced session id', async () => {
     const unsafeId = SessionId('evil\x1b\x07\u009b\ns')
     const unsafeCwd = '/x/\x1b\x07\u009b\nf'
     const result = await setup({
       async configureContext(ctx) {
         ctx.provide('tools', { get: () => undefined } as never)
-        await ctx.plugin(SessionQueryService)
+        await ctx.plugin(TestSessionQueryService)
         await ctx.plugin(SessionReferenceService)
         const source = ctx.sessions.create(unsafeId, { meta: { cwd: unsafeCwd, createdAt: 1 } })
         appendUser(source, 'safe background')
@@ -1094,7 +2029,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     const result = await setup({
       async configureContext(ctx) {
         ctx.provide('tools', { get: () => undefined } as never)
-        await ctx.plugin(SessionQueryService)
+        await ctx.plugin(TestSessionQueryService)
         await ctx.plugin(SessionReferenceService)
       },
     })
@@ -1159,7 +2094,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     const result = await setup({
       async configureContext(ctx) {
         ctx.provide('tools', { get: () => undefined } as never)
-        await ctx.plugin(SessionQueryService)
+        await ctx.plugin(TestSessionQueryService)
         await ctx.plugin(SessionReferenceService)
       },
     })
@@ -1221,7 +2156,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     expect(result.terminal.output).toContain('Referenced sessions · Steering source (steering-source)')
     expect(result.terminal.output).not.toContain('hidden non-reference prefix')
 
-    result.session.append('context/message', {
+    result.session.append('user/message', {
       content: [{ type: 'text', text: 'secret full snapshot payload' }],
       source: { kind: 'plugin', plugin: 'session-reference' },
       meta: {
@@ -1240,13 +2175,13 @@ describe('pi-tui chat lifecycle and transcript', () => {
       [{ kind: 'session-reference', references: [{}] }, 'invalid-fields'],
     ]
     for (const [meta, text] of invalidCards) {
-      result.session.append('context/message', {
+      result.session.append('user/message', {
         content: [{ type: 'text', text }],
         source: { kind: 'plugin', plugin: 'session-reference' },
         meta,
       }, { surfaceOp: 'append' })
     }
-    result.session.append('context/message', {
+    result.session.append('user/message', {
       content: [{ type: 'text', text: 'same-label snapshot' }],
       source: { kind: 'plugin', plugin: 'session-reference' },
       meta: { kind: 'session-reference', references: [{ sessionId: 'same', label: 'same' }] },
@@ -1279,7 +2214,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     const result = await setup({
       async configureContext(ctx) {
         ctx.provide('tools', { get: () => undefined } as never)
-        await ctx.plugin(SessionQueryService)
+        await ctx.plugin(TestSessionQueryService)
         await ctx.plugin(SessionReferenceService)
         ctx.sessions.create(SessionId('source'))
       },
@@ -1329,7 +2264,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     const lateSuccess = await setup({
       async configureContext(ctx) {
         ctx.provide('tools', { get: () => undefined } as never)
-        await ctx.plugin(SessionQueryService)
+        await ctx.plugin(TestSessionQueryService)
         await ctx.plugin(SessionReferenceService)
         ctx.sessions.create(SessionId('source'))
       },
@@ -1379,13 +2314,27 @@ describe('pi-tui chat lifecycle and transcript', () => {
     expect(result.terminal.output).toContain('advertised by multiple providers')
     expect(result.terminal.output).toContain('already alpha/a1')
 
-    result.agent.status = 'running'
+    const firstSelectorOutput = result.terminal.output.length
     result.terminal.send('/model')
     result.terminal.send('\r')
+    result.terminal.send('/model')
+    result.terminal.send('\r')
+    await vi.waitFor(() => {
+      expect(result.terminal.output.slice(firstSelectorOutput)).toContain('Select model')
+    })
+    result.terminal.send('\x1b')
     await tick()
-    expect(result.terminal.output).toContain('Select model')
-    expect(result.terminal.output).toContain('alpha/a1')
-    expect(result.terminal.output).toContain('Alpha One — Fast — current')
+
+    result.agent.status = 'running'
+    const runningSelectorOutput = result.terminal.output.length
+    result.terminal.send('/model')
+    result.terminal.send('\r')
+    await vi.waitFor(() => {
+      const output = result.terminal.output.slice(runningSelectorOutput)
+      expect(output).toContain('Select model')
+      expect(output).toContain('alpha/a1')
+      expect(output).toContain('Alpha One — Fast — current')
+    })
     result.terminal.send('\x1b[B')
     result.terminal.send('\x1b[B')
     result.terminal.send('\r')
@@ -1397,9 +2346,12 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await tick()
     expect(result.terminal.output).not.toContain('50% context  tools:collapsed')
 
+    const cancelledSelectorOutput = result.terminal.output.length
     result.terminal.send('/model')
     result.terminal.send('\r')
-    await tick()
+    await vi.waitFor(() => {
+      expect(result.terminal.output.slice(cancelledSelectorOutput)).toContain('Select model')
+    })
     result.terminal.send('\x1b')
     await tick()
     expect(result.agent.cancelled).not.toContain('cancelled from terminal')
@@ -1559,6 +2511,11 @@ describe('pi-tui chat lifecycle and transcript', () => {
       handler: () => ({ kind: 'error' as const, text: 'plugin error result' }),
     })
 
+    result.terminal.send('/plugin-ch')
+    await tick()
+    expect(result.terminal.output).toContain('<value> — Run a plugin command')
+    result.terminal.send('\x03')
+
     result.terminal.send('/plugin-check  value  ')
     result.terminal.send('\r')
     await tick()
@@ -1658,7 +2615,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
 
     const events = await setup()
     const unrelatedSession = events.ctx.sessions.create(SessionId('unrelated-session'))
-    const unrelatedAgent = { ...events.agent, id: unrelatedSession.id, session: unrelatedSession }
+    const unrelatedAgent = { ...events.agent, id: unrelatedSession.id, session: unrelatedSession } as unknown as Agent
     unrelatedSession.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     unrelatedSession.append('todo/write', { todos: [{ content: 'hidden', status: 'pending' }] })
     agentEvents(events.ctx, unrelatedAgent).emit('agent/status', 'running')
@@ -1846,17 +2803,17 @@ describe('renderSkillInvocation', () => {
 describe('tool cards and surface replay', () => {
   const tools: Record<string, ToolDefinition> = {
     bash: {
-      name: 'bash', description: '', parameters: {}, execute: async () => [],
+      name: 'bash', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({ card: 'terminal', title: 'printf hello', description: 'Run command', cwd: '/tmp' }),
       presentResult: () => ({ card: 'terminal', output: 'hello\nworld\nthird', exitCode: 0 }),
     },
     signal: {
-      name: 'signal', description: '', parameters: {}, execute: async () => [],
+      name: 'signal', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({ card: 'terminal', title: 'sleep 10' }),
       presentResult: () => ({ card: 'terminal', signal: 'SIGTERM' }),
     },
     edit: {
-      name: 'edit', description: '', parameters: {}, execute: async () => [],
+      name: 'edit', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({
         card: 'diff',
         title: 'Edit files',
@@ -1868,35 +2825,35 @@ describe('tool cards and surface replay', () => {
       presentResult: () => ({ card: 'diff', diffs: [{ path: 'a.txt', oldText: null, newText: 'created' }] }),
     },
     generic: {
-      name: 'generic', description: '', parameters: {}, execute: async () => [],
+      name: 'generic', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({ card: 'generic', title: 'Inspect value', rawInput: { alpha: 1 } }),
       presentResult: () => ({ card: 'generic', title: 'Inspected', content: [{ type: 'text', text: 'result text' }] }),
     },
     throwing: {
-      name: 'throwing', description: '', parameters: {}, execute: async () => [],
+      name: 'throwing', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => { throw new Error('call presenter boom') },
       presentResult: () => { throw new Error('result presenter boom') },
     },
     rawTerminal: {
-      name: 'rawTerminal', description: '', parameters: {}, execute: async () => [],
+      name: 'rawTerminal', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({ card: 'terminal', title: 'raw command' }),
     },
     undefinedViews: {
-      name: 'undefinedViews', description: '', parameters: {}, execute: async () => [],
+      name: 'undefinedViews', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => undefined,
       presentResult: () => undefined,
     },
     empty: {
-      name: 'empty', description: '', parameters: {}, execute: async () => [],
+      name: 'empty', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({ card: 'generic', title: 'Empty card' }),
     },
     terminalResult: {
-      name: 'terminalResult', description: '', parameters: {}, execute: async () => [],
+      name: 'terminalResult', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({ card: 'generic', title: 'Becomes terminal' }),
       presentResult: () => ({ card: 'terminal', output: 'converted terminal' }),
     },
     symbolic: {
-      name: 'symbolic', description: '', parameters: {}, execute: async () => [],
+      name: 'symbolic', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({ card: 'generic', title: 'Symbol input', rawInput: Symbol('input') }),
     },
   }
@@ -2021,7 +2978,7 @@ describe('tool cards and surface replay', () => {
       turn: 1, step: 1, callId: 'old-call' as never, content: [{ type: 'text', text: 'old output' }], isError: false,
     }, { surfaceOp: 'append' })
     const start = result.session.surface.nodes[0] as number
-    result.session.append('context/message', {
+    result.session.append('user/message', {
       content: [{ type: 'text', text: 'summary replacement' }],
       source: { kind: 'plugin', plugin: 'compact' },
     }, {
@@ -2193,6 +3150,141 @@ describe('TUI user-interaction dialogs', () => {
       .rejects.toMatchObject({ code: 'NO_PROVIDER' })
     await result.ctx.fiber.dispose()
   })
+
+  it('rejects malformed questions when a dialog cannot be constructed', async () => {
+    const result = await setup()
+    const broken = {
+      id: 'broken',
+      question: 'Broken question',
+      get options(): never {
+        throw new Error('question setup failed')
+      },
+    }
+    const answer = result.ctx.userInteraction.ask({ questions: [broken] })
+    await expect(answer).rejects.toThrow('ask_user_question TUI failed: question setup failed')
+    await tick()
+    expect(result.terminal.output).toContain('TUI overlay failed: question setup failed')
+    await dispose(result)
+  })
+})
+
+describe('TUI extension service', () => {
+  it('renders effect-owned plugin overlays in the shared FIFO and restores editor input', async () => {
+    const result = await setup()
+    const sessions: TuiOverlaySession[] = []
+    const hosts: TuiOverlayHost[] = []
+    const plugin = result.ctx.inject(['tui'], (pluginCtx) => {
+      expect(pluginCtx.tui.agent).toBe(result.agent)
+      for (const label of ['first', 'second']) {
+        sessions.push(pluginCtx.tui.openOverlay({
+          create(host) {
+            hosts.push(host)
+            return {
+              focused: false,
+              render: width => [
+                host.theme.accent(`${label} plugin overlay`),
+                [
+                  host.theme.text('text'),
+                  host.theme.muted('muted'),
+                  host.theme.dim('dim'),
+                  host.theme.success('success'),
+                  host.theme.warning('warning'),
+                  host.theme.error('error'),
+                  host.theme.bold('bold'),
+                ].join(' '),
+                `${String(host.viewport.columns)}x${String(host.viewport.rows)} · ${String(width)}`,
+              ],
+              handleInput(data) {
+                host.invalidate()
+                if (data === label[0]) host.close()
+              },
+              invalidate() {},
+            }
+          },
+          options: { width: 50, maxHeight: 8, anchor: 'center', margin: 1 },
+        }))
+      }
+    })
+    await plugin
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('first plugin overlay')
+    })
+    expect(sessions.map(session => session.state)).toEqual(['active', 'queued'])
+    expect(hosts).toHaveLength(1)
+
+    const question = result.ctx.userInteraction.ask({
+      questions: [{ id: 'after-plugin', question: 'Question after plugins?', options: [{ label: 'Yes' }] }],
+    })
+    result.terminal.send('f')
+    await expect(sessions[0]!.closed).resolves.toEqual({ reason: 'closed' })
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('second plugin overlay')
+    })
+    expect(hosts).toHaveLength(2)
+    expect(sessions[1]?.state).toBe('active')
+
+    result.terminal.send('s')
+    await expect(sessions[1]!.closed).resolves.toEqual({ reason: 'closed' })
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('Question after plugins?')
+    })
+    result.terminal.send('\r')
+    await expect(question).resolves.toEqual({
+      answers: [{ id: 'after-plugin', selected: ['Yes'] }],
+    })
+
+    result.terminal.send('editor works again')
+    result.terminal.send('\r')
+    expect(result.agent.sent.at(-1)).toEqual([{ type: 'text', text: 'editor works again' }])
+    await plugin.dispose()
+    await dispose(result)
+  })
+
+  it('unloads and reloads dependent plugins with the mounted TUI', async () => {
+    const result = await setup()
+    const sessions: TuiOverlaySession[] = []
+    const signals: AbortSignal[] = []
+    let starts = 0
+    const plugin = result.ctx.inject(['tui'], (pluginCtx) => {
+      starts += 1
+      sessions.push(pluginCtx.tui.openOverlay({
+        create(host) {
+          signals.push(host.signal)
+          return {
+            render: () => [`plugin mount ${String(starts)}`],
+            invalidate() {},
+          }
+        },
+      }))
+    })
+    await plugin
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('plugin mount 1')
+    })
+
+    await result.controller.dispose()
+    await expect(sessions[0]!.closed).resolves.toEqual({ reason: 'owner-disposed' })
+    expect(signals[0]?.aborted).toBe(true)
+    expect(result.ctx.get('tui')).toBeUndefined()
+
+    const secondTerminal = new FakeTerminal()
+    const secondController = createTuiChat(result.ctx, {
+      sessionId: result.agent.id,
+      color: false,
+      welcome: 'Mounted again.',
+    }, {
+      terminal: secondTerminal,
+      exit: vi.fn(),
+    })
+    await vi.waitFor(() => {
+      expect(starts).toBe(2)
+      expect(secondTerminal.output).toContain('plugin mount 2')
+    })
+    await sessions[1]?.close()
+    await secondController.dispose()
+    await plugin.dispose()
+    await result.ctx.fiber.dispose()
+  })
 })
 
 describe('terminal mounting', () => {
@@ -2207,7 +3299,7 @@ describe('terminal mounting', () => {
     const session = ctx.sessions.create(SessionId('main'))
     ctx.agents.register({
       id: session.id, options: {}, session, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
     })
     const terminal = new FakeTerminal()
     mountTui(ctx, { color: false }, { terminal, exit: vi.fn() })
@@ -2231,7 +3323,7 @@ describe('terminal mounting', () => {
     const session = ctx.sessions.create(SessionId('main'))
     ctx.agents.register({
       id: session.id, options: {}, session, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
     })
     const terminal = new FakeTerminal()
     // Mirror dsh-tui's own inject (minus loader, the absence under test).
@@ -2265,14 +3357,14 @@ describe('terminal mounting', () => {
     const otherSession = ctx.sessions.create(SessionId('other-session'))
     ctx.agents.register({
       id: otherSession.id, options: {}, session: otherSession, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
     })
     expect(terminal.started).toBe(0)
 
     const session = ctx.sessions.create(SessionId('late-session'))
     const agent = {
       id: session.id, options: {}, session, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
     } as Agent
     ctx.agents.register(agent)
     await tick()
@@ -2302,7 +3394,7 @@ describe('terminal mounting', () => {
     const session = ctx.sessions.create(SessionId('main-session'))
     ctx.agents.register({
       id: session.id, options: {}, session, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
     })
     await tick()
     expect(terminal.started).toBe(0)
@@ -2344,7 +3436,7 @@ describe('terminal mounting', () => {
     session.append('step/start', { turn: 1, step: 1 })
     ctx.agents.register({
       id: session.id, options: {}, session, status: 'running', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
     })
     const terminal = new FakeTerminal()
     terminal.start = () => { throw new Error('terminal startup failed') }
@@ -2355,6 +3447,7 @@ describe('terminal mounting', () => {
     expect(ctx.commands.list(ctx.agents.get(SessionId('failed-start-session'))!)).toEqual([])
     expect(terminal.stopped).toBe(1)
     expect(terminal.progress).toEqual([false, true, false])
+    expect(ctx.get('tui')).toBeUndefined()
     await expect(ctx.userInteraction.ask({ questions: [{ id: 'late', question: 'Late?' }] }))
       .rejects.toMatchObject({ code: 'NO_PROVIDER' })
     session.append('assistant/chunk', {
diff --git a/packages/ui/tui/tsconfig.json b/packages/ui/tui/tsconfig.json
index cf0a2b544f..3560d6bc9d 100644
--- a/packages/ui/tui/tsconfig.json
+++ b/packages/ui/tui/tsconfig.json
@@ -20,6 +20,9 @@
     {
       "path": "../../core/agent-loop"
     },
+    {
+      "path": "../../goal/goal"
+    },
     {
       "path": "../../core/session"
     },
@@ -29,6 +32,9 @@
     {
       "path": "../../session-persistence/session-persistence"
     },
+    {
+      "path": "../../session-query/session-query"
+    },
     {
       "path": "../../session-title/session-title"
     },
diff --git a/packages/ui/user-interaction/README.md b/packages/ui/user-interaction/README.md
index 153e9a270d..f0e14b81bd 100644
--- a/packages/ui/user-interaction/README.md
+++ b/packages/ui/user-interaction/README.md
@@ -17,7 +17,7 @@ Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a mod
 - `UserInteractionProvider` — UI implementation with `ask(request)`.
 - `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`.
 
-When an answer includes `custom`, `selected` is empty; custom text is an override rather than a supplement to selected choices.
+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.
 
 ## Role
 
diff --git a/packages/ui/user-interaction/src/types.ts b/packages/ui/user-interaction/src/types.ts
index 861ab7c12a..ddf3e43489 100644
--- a/packages/ui/user-interaction/src/types.ts
+++ b/packages/ui/user-interaction/src/types.ts
@@ -33,7 +33,7 @@ export interface AskUserQuestionItem {
 export interface AskUserQuestionAnswerItem {
   /** The answered question id. */
   id: string
-  /** Selected option labels. Empty when the answer is purely custom text. */
+  /** Selected option labels. Empty for custom or unanswered choices. */
   selected: string[]
   /** Optional free-text "Other" answer. */
   custom?: string
diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md
index 8cdb9ea737..27147104e9 100644
--- a/packages/web/tool-web/README.md
+++ b/packages/web/tool-web/README.md
@@ -13,6 +13,8 @@ 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.
+
 ## Config
 
 | Key | Default | Meaning |
diff --git a/packages/web/tool-web/src/fetch.ts b/packages/web/tool-web/src/fetch.ts
index 83358251fb..cc2ae52970 100644
--- a/packages/web/tool-web/src/fetch.ts
+++ b/packages/web/tool-web/src/fetch.ts
@@ -8,7 +8,6 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { WebFetchBody, WebFetchResult } from '@deepseek-ai/dsh-web'
 import { assertNever } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -91,16 +90,54 @@ export function applyWebFetchTool(ctx: Context, timeoutMs: number): void {
     parameters: {
       url: { type: 'string', required: true, description: 'The HTTP(S) URL to fetch.' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          url: { type: 'string', required: true },
+          statusCode: { type: 'integer', required: true },
+          body: {
+            required: true,
+            oneOf: [
+              {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  kind: { type: 'string', required: true, const: 'html' },
+                  content: { type: 'string', required: true },
+                },
+              },
+              {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  kind: { type: 'string', required: true, const: 'text' },
+                  content: { type: 'string', required: true },
+                },
+              },
+            ],
+          },
+          truncated: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: formatFetchOutput(value) }],
+    },
     timeoutMs,
     // Provider reads do not mutate parent-agent state.
     isConcurrencySafe: () => true,
-    async execute(args, exec): Promise<ContentBlock[]> {
+    async execute(args, exec) {
       const input = parseFetchArgs(args)
       const result = await ctx.web.fetch(
         { url: input.url },
         exec.signal,
       )
-      return [{ type: 'text', text: formatFetchOutput(result) }]
+      return {
+        url: result.url,
+        statusCode: result.statusCode,
+        body: { kind: result.body.kind, content: result.body.content },
+        truncated: result.truncated,
+      }
     },
     presentCall: presentFetchCall,
   }))
diff --git a/packages/web/tool-web/src/search.ts b/packages/web/tool-web/src/search.ts
index af8753720d..816650e4b0 100644
--- a/packages/web/tool-web/src/search.ts
+++ b/packages/web/tool-web/src/search.ts
@@ -8,7 +8,6 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { WebSearchResult } from '@deepseek-ai/dsh-web'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 
@@ -108,16 +107,50 @@ export function applyWebSearchTool(ctx: Context, maxResults: number, timeoutMs:
     parameters: {
       query: { type: 'string', required: true, description: 'The search query.' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          content: { type: 'string' },
+          sources: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                url: { type: 'string', required: true },
+                title: { type: 'string' },
+                snippet: { type: 'string' },
+                publishedAt: { type: 'string' },
+              },
+            },
+          },
+          truncated: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: formatSearchOutput(value) }],
+    },
     timeoutMs,
     // Provider reads do not mutate parent-agent state.
     isConcurrencySafe: () => true,
-    async execute(args, exec): Promise<ContentBlock[]> {
+    async execute(args, exec) {
       const input = parseSearchArgs(args)
       const result = await ctx.web.search(
         { query: input.query, maxResults },
         exec.signal,
       )
-      return [{ type: 'text', text: formatSearchOutput(result) }]
+      return {
+        ...result.content !== undefined ? { content: result.content } : {},
+        sources: result.sources.map(source => ({
+          url: source.url,
+          ...source.title !== undefined ? { title: source.title } : {},
+          ...source.snippet !== undefined ? { snippet: source.snippet } : {},
+          ...source.publishedAt !== undefined ? { publishedAt: source.publishedAt } : {},
+        })),
+        truncated: result.truncated,
+      }
     },
     presentCall: presentSearchCall,
   }))
diff --git a/packages/web/tool-web/tests/integration.spec.ts b/packages/web/tool-web/tests/integration.spec.ts
index abc5256b9f..7650231a10 100644
--- a/packages/web/tool-web/tests/integration.spec.ts
+++ b/packages/web/tool-web/tests/integration.spec.ts
@@ -12,7 +12,7 @@ import { AddressInfo } from 'node:net'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { type ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import WebService from '@deepseek-ai/dsh-web'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
 import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
@@ -56,8 +56,7 @@ afterEach(async () => {
 })
 
 let counter = 0
-type ToolResult = { isError: boolean; content: { type: string; text?: string }[]; error?: { code: string } }
-function call(name: string, args: unknown): Promise<ToolResult> {
+function call(name: string, args: unknown): Promise<ToolExecutionResult> {
   return ctx.tools.execute({ signal: testToolSignal, callId: CallId(`call-${++counter}`), name, arguments: args })
 }
 
@@ -65,7 +64,7 @@ describe('web_fetch integration over the real backend', () => {
   it('fetches an html page and renders it to markdown', async () => {
     const out = await call('web_fetch', { url: base })
     expect(out.isError).toBe(false)
-    const text = out.content.map(b => b.text).join('')
+    const text = out.content.map(b => b.type === 'text' ? b.text : '').join('')
     expect(text).toContain(`Fetched ${base}`)
     expect(text).toContain('# Hello')
     expect(text).toContain('World')
@@ -75,20 +74,20 @@ describe('web_fetch integration over the real backend', () => {
     handler = (_req, res) => { res.writeHead(404, { 'content-type': 'text/plain' }); res.end('missing') }
     const out = await call('web_fetch', { url: base })
     expect(out.isError).toBe(false)
-    expect(out.content.map(b => b.text).join('')).toContain('HTTP 404')
+    expect(out.content.map(b => b.type === 'text' ? b.text : '').join('')).toContain('HTTP 404')
   })
 
   it('surfaces WEB_INVALID_URL as a structured tool error', async () => {
     const out = await call('web_fetch', { url: 'ftp://example.com' })
     expect(out.isError).toBe(true)
-    expect(out.error?.code).toBe('WEB_INVALID_URL')
+    expect(out.error?.info?.code).toBe('WEB_INVALID_URL')
   })
 
   it('surfaces a blocked cross-origin redirect as WEB_REDIRECT_BLOCKED', async () => {
     handler = (_req, res) => { res.writeHead(302, { location: 'https://example.com/' }); res.end() }
     const out = await call('web_fetch', { url: base })
     expect(out.isError).toBe(true)
-    expect(out.error?.code).toBe('WEB_REDIRECT_BLOCKED')
+    expect(out.error?.info?.code).toBe('WEB_REDIRECT_BLOCKED')
   })
 })
 
@@ -100,7 +99,7 @@ describe('web_search integration over the real Exa provider', () => {
     )))
     const out = await call('web_search', { query: 'deepseek' })
     expect(out.isError).toBe(false)
-    expect(out.content.map(b => b.text).join('')).toContain('[Result](https://result.test)')
+    expect(out.content.map(b => b.type === 'text' ? b.text : '').join('')).toContain('[Result](https://result.test)')
   })
 })
 
@@ -153,7 +152,7 @@ describe('tool-call timeout returns TOOL_TIMEOUT (deadline wins over a slow fetc
     expect(out.isError).toBe(true)
     // The outer tool-call deadline won: TOOL_TIMEOUT, owned by dsh-timeout-policy,
     // NOT the provider's own WEB_FETCH_TIMEOUT (its 30s backstop never fired).
-    expect(out.error?.code).toBe('TOOL_TIMEOUT')
+    expect(out.error?.info?.code).toBe('TOOL_TIMEOUT')
     const text = out.content.map(b => (b.type === 'text' ? b.text : '')).join('')
     expect(text).toContain('timed out after 50ms')
   })
diff --git a/packages/web/tool-web/tests/tool-web.spec.ts b/packages/web/tool-web/tests/tool-web.spec.ts
index c7d8dd572a..093184c4a7 100644
--- a/packages/web/tool-web/tests/tool-web.spec.ts
+++ b/packages/web/tool-web/tests/tool-web.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { type ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import WebService from '@deepseek-ai/dsh-web'
 import type { WebSearchProvider, WebSearchResult } from '@deepseek-ai/dsh-web'
 import * as ToolWeb from '@deepseek-ai/dsh-tool-web'
@@ -32,7 +32,7 @@ async function mountTools(opts: {
   webConfig?: ConstructorParameters<typeof WebService>[1]
   search?: WebSearchProvider
   fetchProvider?: import('@deepseek-ai/dsh-web').WebFetchProvider
-} = {}): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>>; call: (name: string, args: unknown) => Promise<{ isError: boolean; content: { type: string; text?: string }[]; error?: { code: string } }> }> {
+} = {}): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>>; call: (name: string, args: unknown) => Promise<ToolExecutionResult> }> {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
@@ -41,7 +41,7 @@ async function mountTools(opts: {
   if (opts.fetchProvider) ctx.web.registerFetchProvider(opts.fetchProvider)
   const fiber = await ctx.plugin(ToolWeb, opts.config ?? {})
   let counter = 0
-  const call = (name: string, args: unknown) => ctx.tools.execute({ signal: testToolSignal, callId: CallId(`call-${++counter}`), name, arguments: args }) as never
+  const call = (name: string, args: unknown) => ctx.tools.execute({ signal: testToolSignal, callId: CallId(`call-${++counter}`), name, arguments: args })
   return { ctx, fiber, call }
 }
 
@@ -198,7 +198,7 @@ describe('tool-web registration', () => {
     // No provider is registered: the schema stays visible and execution reports
     // the structured unavailability instead.
     const out = await call('web_search', { query: 'q' })
-    expect(out.error?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
+    expect(out.error?.info?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
     await fiber.dispose()
   })
 
@@ -216,12 +216,13 @@ describe('tool-web execution through the real registry', () => {
   it('executes web_search and formats the result', async () => {
     const result: WebSearchResult = {
       content: 'answer', truncated: false,
-      sources: [{ url: 'https://a.test', title: 'A', snippet: 'snip' }],
+      sources: [{ url: 'https://a.test', title: 'A', snippet: 'snip', publishedAt: '2026-07-20' }],
     }
     const { fiber, call } = await mountTools({ webConfig: { searchProvider: 'stub-search' }, search: searchProvider(result) })
     const out = await call('web_search', { query: 'q' })
     expect(out.isError).toBe(false)
-    expect(out.content.map(b => b.text).join('')).toContain('[A](https://a.test)')
+    expect(out.value).toEqual(result)
+    expect(out.content.map(b => b.type === 'text' ? b.text : '').join('')).toContain('[A](https://a.test)')
     await fiber.dispose()
   })
 
@@ -229,7 +230,7 @@ describe('tool-web execution through the real registry', () => {
     const { fiber, call } = await mountTools()
     const out = await call('web_search', { query: 'q' })
     expect(out.isError).toBe(true)
-    expect(out.error?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
+    expect(out.error?.info?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
     await fiber.dispose()
   })
 
@@ -238,7 +239,7 @@ describe('tool-web execution through the real registry', () => {
     ctx.web.registerSearchProvider({ id: 'other', available: () => available, search: () => Promise.resolve({ sources: [], truncated: false }) })
     const out = await call('web_search', { query: 'q' })
     expect(out.isError).toBe(true)
-    expect(out.error?.code).toBe('WEB_PROVIDER_AMBIGUOUS')
+    expect(out.error?.info?.code).toBe('WEB_PROVIDER_AMBIGUOUS')
     await fiber.dispose()
   })
 
@@ -246,7 +247,7 @@ describe('tool-web execution through the real registry', () => {
     const { fiber, call } = await mountTools({ webConfig: { searchProvider: 'stub-search' }, search: searchProvider({ sources: [], truncated: false }) })
     const out = await call('web_search', { query: 123 })
     expect(out.isError).toBe(true)
-    expect(out.error?.code).toBe('INVALID_ARGS')
+    expect(out.error?.info?.code).toBe('INVALID_ARGS')
     await fiber.dispose()
   })
 
@@ -269,6 +270,12 @@ describe('tool-web execution through the real registry', () => {
     const controller = new AbortController()
     const out = await ctx.tools.execute({ callId: CallId('fetch-1'), name: 'web_fetch', arguments: { url: 'https://a.test' }, signal: controller.signal })
     expect(out.isError).toBe(false)
+    expect(out.value).toEqual({
+      url: 'https://a.test',
+      statusCode: 200,
+      body: { kind: 'text', content: 'ok' },
+      truncated: false,
+    })
     // The model schema exposes no timeout: the tool forwards only the url; the
     // tool-call budget is owned by dsh-timeout-policy over exec.signal.
     expect(seen.request).toEqual({ url: 'https://a.test' })
@@ -290,6 +297,12 @@ describe('tool-web execution through the real registry', () => {
     const { ctx, fiber } = await mountTools({ webConfig: { fetchProvider: 'stub-fetch' }, fetchProvider })
     const out = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('fetch-2'), name: 'web_fetch', arguments: { url: 'https://a.test' } })
     expect(out.isError).toBe(false)
+    expect(out.value).toEqual({
+      url: 'https://a.test',
+      statusCode: 200,
+      body: { kind: 'text', content: 'ok' },
+      truncated: false,
+    })
     expect(seen.passedSignal).toBe(true)
     expect(seen.signal).toBe(testToolSignal)
     await fiber.dispose()
@@ -334,7 +347,7 @@ describe('searchMaxResults is plugin config', () => {
     const { fiber, call } = await mountTools({ config: { searchMaxResults: 2 }, webConfig: { searchProvider: 'stub-search' }, search: provider })
     const out = await call('web_search', { query: 'q' })
     expect(out.isError).toBe(false)
-    const body = out.content.map(b => b.text).join('')
+    const body = out.content.map(b => b.type === 'text' ? b.text : '').join('')
     expect(body).toContain('https://s1.test')
     expect(body).not.toContain('https://s2.test')
     expect(body).toContain('Showing the first 2 sources.')
diff --git a/packages/workflow/tool-ralph/README.md b/packages/workflow/tool-ralph/README.md
index 230e2db643..8f54c101f0 100644
--- a/packages/workflow/tool-ralph/README.md
+++ b/packages/workflow/tool-ralph/README.md
@@ -8,7 +8,7 @@ The model-facing `ralph` tool runs a fixed foreground workflow that gives one im
 
 Each child receives only the immutable objective, its current Ralph round and cap, a shared-workspace-as-authority instruction, and the previous structured handoff. The workspace is long-term memory; parent conversation and prior child sessions are not seeded. Reports have `status: continue | complete | blocked`, a non-empty summary, evidence, next steps, and blocker text. Status-specific semantics and the serialized `maxHandoffChars` ceiling are validated inside the fixed workflow and again at the consumer boundary. Invalid, missing, or oversized reports fail the workflow instead of being truncated or mistaken for cap exhaustion.
 
-The successful terminal tool result is `complete`, `blocked`, or `budget-limited`, with the last bounded report and number of rounds started. Completion and blocker labels explicitly say that a worker reported the outcome; they are not independent certification. `maxResultChars` bounds the complete successful text including its envelope and truncation marker, without altering the validated report used as a cross-round handoff.
+The successful terminal tool result is `complete`, `blocked`, or `budget-limited`, with the last bounded report and number of rounds started. The canonical envelope is `{ runId, agentsStarted, result }`; completion and blocker labels in its Native renderer explicitly say that a worker reported the outcome, not independent certification. `maxResultChars` bounds only that rendered text including its truncation marker, without altering the validated report in the canonical value or the cross-round handoff.
 
 An ordinary child failure produces an error naming the failed round and retaining the last successful handoff when one exists. Ralph does not retry that round. Fatal provider-start, transport, worker, or workflow failures remain workflow errors and may settle before the fixed script can return a handoff. Cancellation is also an error; partial output is never success.
 
diff --git a/packages/workflow/tool-ralph/src/index.ts b/packages/workflow/tool-ralph/src/index.ts
index 3bfd438cf7..199d198262 100644
--- a/packages/workflow/tool-ralph/src/index.ts
+++ b/packages/workflow/tool-ralph/src/index.ts
@@ -8,6 +8,7 @@
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 import type { SubagentProvider } from '@deepseek-ai/dsh-subagent'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools'
@@ -374,6 +375,13 @@ function renderResult(result: RalphRunResult, maxChars: number): string {
   return boundResult(text, maxChars)
 }
 
+/** Canonical Ralph result fields shared by schema inference and rendering. */
+const RALPH_OUTPUT_PROPERTIES = {
+  runId: { type: 'string', required: true },
+  agentsStarted: { type: 'integer', required: true },
+  result: { type: 'json', required: true },
+} as const
+
 /** Render an ordinary child failure with the most recent durable handoff. */
 function renderRoundFailure(result: RalphRoundFailure, maxChars: number): string {
   const header = `Ralph round ${result.roundsStarted} child failed before producing a structured report.`
@@ -415,7 +423,18 @@ export function apply(ctx: Context, config: Config): void {
         description: 'Optional positive safe-integer round cap, bounded by the deployment ceiling.',
       },
     },
-    async execute(args, exec): Promise<ContentBlock[]> {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: RALPH_OUTPUT_PROPERTIES,
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: renderResult(value.result as unknown as RalphRunResult, resolved.maxResultChars),
+      }],
+    },
+    async execute(args, exec) {
       const parent = exec.agent
       if (parent === undefined) {
         throw new Error('Ralph tool requires a calling agent (exec.agent was undefined)')
@@ -444,7 +463,11 @@ export function apply(ctx: Context, config: Config): void {
         if (error !== undefined) throw new Error(error)
         const value = readRunResult(settled.value, maxRounds, resolved.maxHandoffChars)
         if (value.status === 'round-failed') throw new Error(renderRoundFailure(value, resolved.maxResultChars))
-        return [{ type: 'text', text: renderResult(value, resolved.maxResultChars) }]
+        return {
+          runId: run.id,
+          agentsStarted: settled.agentsStarted,
+          result: value as unknown as JsonValue,
+        }
       } finally {
         exec.signal.removeEventListener('abort', onAbort)
         await run.dispose()
diff --git a/packages/workflow/tool-ralph/tests/integration.spec.ts b/packages/workflow/tool-ralph/tests/integration.spec.ts
index dcc3b947fb..c9492b9450 100644
--- a/packages/workflow/tool-ralph/tests/integration.spec.ts
+++ b/packages/workflow/tool-ralph/tests/integration.spec.ts
@@ -70,7 +70,7 @@ describe('dsh-tool-ralph over the real spawn and worker-thread stack', () => {
       agentOptions: { provider: 'mock', model: 'mock' },
     })
     const parent = parentHandle.agent
-    parent.send([{ type: 'text', text: 'PARENT_PROMPT_MARKER' }])
+    parent.followup([{ type: 'text', text: 'PARENT_PROMPT_MARKER' }])
     await parent.whenIdle()
 
     const children: Agent[] = []
diff --git a/packages/workflow/tool-ralph/tests/tool-ralph.spec.ts b/packages/workflow/tool-ralph/tests/tool-ralph.spec.ts
index 974c4aaf88..29ba7edd4e 100644
--- a/packages/workflow/tool-ralph/tests/tool-ralph.spec.ts
+++ b/packages/workflow/tool-ralph/tests/tool-ralph.spec.ts
@@ -160,6 +160,12 @@ describe('dsh-tool-ralph', () => {
       report: COMPLETE,
     })
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected Ralph success')
+    expect(result.value).toEqual({
+      runId: 'ralph-1',
+      agentsStarted: 1,
+      result: { status: 'complete', roundsStarted: 1, report: COMPLETE },
+    })
     expect((result.content[0] as { text: string }).text)
       .toContain('Ralph worker reported completion after 1 round.')
     expect((result.content[0] as { text: string }).text).toContain('All required gates pass.')
@@ -271,7 +277,7 @@ describe('dsh-tool-ralph', () => {
     const already = new AbortController()
     already.abort()
     const skipped = await execute(ctx, { objective: 'Work.' }, { agent: parent, signal: already.signal })
-    expect(skipped.error?.code).toBe(TOOL_ABORTED_BEFORE_DISPATCH)
+    expect(skipped.error?.info?.code).toBe(TOOL_ABORTED_BEFORE_DISPATCH)
     expect(engine.requests).toHaveLength(1)
     expect(engine.cancels).toEqual(['parent step aborted'])
     expect(engine.disposed).toBe(1)
@@ -298,7 +304,7 @@ describe('dsh-tool-ralph', () => {
       expect((await execute(ctx, { objective: 'Work.', maxRounds }, { agent: parent })).isError).toBe(true)
     }
     const missing = await execute(ctx, {}, { agent: parent })
-    expect(missing.error?.code).toBe('INVALID_ARGS')
+    expect(missing.error?.info?.code).toBe('INVALID_ARGS')
     expect(engine.requests).toHaveLength(0)
   })
 
diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md
index 016f885914..e7cfceea9a 100644
--- a/packages/workflow/tool-workflow/README.md
+++ b/packages/workflow/tool-workflow/README.md
@@ -8,7 +8,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. The completed result renders the meta name, the agent count, and the return value as JSON, truncated at `maxResultChars` with an explicit notice.
+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`.
 
 ## Render intent
 
@@ -74,5 +74,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **The parent turn blocks until the whole workflow settles** — there is no background start/poll surface, and cancellation discards partial output as an error.
-- **`args` must be an object and the result is bounded text** — callers wrap top-level arrays/scalars in a field, and JSON beyond `maxResultChars` is truncated rather than stored behind a retrieval handle.
+- **`args` must be an object and Native result text is bounded** — callers wrap top-level arrays/scalars in a field; the canonical workflow result remains complete, while JSON beyond `maxResultChars` is truncated in the model-facing projection rather than stored behind a retrieval handle.
 - **Workflow policy is fixed per tool registration** — provider selection, caps, and tool name are deployment config, not model-call arguments.
diff --git a/packages/workflow/tool-workflow/src/index.ts b/packages/workflow/tool-workflow/src/index.ts
index 6aa8ea1c96..2531a72241 100644
--- a/packages/workflow/tool-workflow/src/index.ts
+++ b/packages/workflow/tool-workflow/src/index.ts
@@ -15,6 +15,7 @@ import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 import type { WorkflowResult, WorkflowRun } from '@deepseek-ai/dsh-workflow'
 // Declaration merge only: makes ctx.systemPrompt visible for the section registration.
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -47,7 +48,7 @@ const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagent
 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 — no oneOf/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.
+- \`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.
@@ -100,13 +101,13 @@ function stopReasonError(result: WorkflowResult): string | undefined {
 }
 
 /** Render the run's outcome text: the meta name, agent count, and the JSON value (capped). */
-function renderResult(run: WorkflowRun, result: WorkflowResult, maxChars: number): string {
+function renderResult(name: string, agentsStarted: number, value: JsonValue, maxChars: number): string {
   // The engine returns JSON data (null for a valueless script), so stringify never yields undefined.
-  const rendered = JSON.stringify(result.value, null, 2)
+  const rendered = JSON.stringify(value, null, 2)
   const clipped = rendered.length > maxChars
     ? `${rendered.slice(0, maxChars)}\n… [truncated: ${rendered.length - maxChars} more characters]`
     : rendered
-  return `workflow "${run.meta.name}" completed (${result.agentsStarted} agent${result.agentsStarted === 1 ? '' : 's'}).\nReturn value:\n${clipped}`
+  return `workflow "${name}" completed (${agentsStarted} agent${agentsStarted === 1 ? '' : 's'}).\nReturn value:\n${clipped}`
 }
 
 export function apply(ctx: Context, config: Config): void {
@@ -131,6 +132,7 @@ export function apply(ctx: Context, config: Config): void {
       },
       meta: {
         type: 'object',
+        additionalProperties: true,
         required: true,
         description: 'The workflow identity block (plain JSON — never code).',
         properties: {
@@ -142,6 +144,7 @@ export function apply(ctx: Context, config: Config): void {
             description: 'Optional phase declarations matched by phase() calls.',
             items: {
               type: 'object',
+              additionalProperties: true,
               properties: {
                 title: { type: 'string', required: true, description: 'The phase title phase() calls match by exact string.' },
                 detail: { type: 'string', description: 'Optional one-line description of the phase.' },
@@ -154,10 +157,26 @@ export function apply(ctx: Context, config: Config): void {
       },
       args: {
         type: 'object',
+        additionalProperties: true,
         description: 'Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}).',
       },
     },
-    async execute(args, exec): Promise<ContentBlock[]> {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          runId: { type: 'string', required: true },
+          agentsStarted: { type: 'integer', required: true },
+          result: { type: 'json', required: true },
+        },
+      },
+      render: (args, value) => [{
+        type: 'text',
+        text: renderResult(args.meta.name, value.agentsStarted, value.result, maxResultChars),
+      }],
+    },
+    async execute(args, exec) {
       const parent = exec.agent
       if (!parent) {
         // The loop sets `exec.agent` for every model-driven call; its absence
@@ -191,7 +210,11 @@ export function apply(ctx: Context, config: Config): void {
           // throw into an isError). Report the reason, not partial output.
           throw new Error(error)
         }
-        return [{ type: 'text', text: renderResult(run, result, maxResultChars) }]
+        return {
+          runId: run.id,
+          agentsStarted: result.agentsStarted,
+          result: result.value as JsonValue,
+        }
       } finally {
         exec.signal.removeEventListener('abort', onAbort)
         // Always reach run quiescence — never leak a live script or children.
diff --git a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts
index 3295af07eb..a61862cffd 100644
--- a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts
+++ b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts
@@ -82,8 +82,10 @@ describe('dsh-tool-workflow', () => {
     engine.settle({ value: { findings: [1, 2] }, stopReason: 'completed', agentsStarted: 7 })
     const result = await pending
     expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected workflow success')
+    expect(result.value).toEqual({ runId: 'run-1', agentsStarted: 7, result: { findings: [1, 2] } })
     const rendered = (result.content[0] as { text: string }).text
-    expect(rendered).toContain('workflow "stub-flow" completed (7 agents)')
+    expect(rendered).toContain('workflow "audit" completed (7 agents)')
     expect(rendered).toContain('"findings"')
     expect(engine.disposed).toBe(1)
   })
@@ -154,7 +156,7 @@ describe('dsh-tool-workflow', () => {
     const { ctx, parent } = await setup()
     const result = await execute(ctx, {}, { agent: parent })
     expect(result.isError).toBe(true)
-    expect(result.error?.code).toBe('INVALID_ARGS')
+    expect(result.error?.info?.code).toBe('INVALID_ARGS')
   })
 
   it('skips workflow startup when exec.signal is already aborted', async () => {
@@ -163,7 +165,10 @@ describe('dsh-tool-workflow', () => {
     controller.abort()
     const result = await execute(ctx, { script: SCRIPT, meta: META }, { agent: parent, signal: controller.signal })
     expect(result.isError).toBe(true)
-    expect(result.error).toEqual({ name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH })
+    expect(result.error).toEqual({
+      message: 'tool call aborted before dispatch',
+      info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH },
+    })
     expect(engine.requests).toHaveLength(0)
     expect(engine.cancels).toHaveLength(0)
     expect(engine.disposed).toBe(0)
@@ -174,7 +179,10 @@ describe('dsh-tool-workflow', () => {
     const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent })
     await vi.waitFor(() => { expect(engine.requests.length).toBe(1) })
     engine.settle({ value: { blob: 'x'.repeat(500) }, stopReason: 'completed', agentsStarted: 1 })
-    const rendered = ((await pending).content[0] as { text: string }).text
+    const result = await pending
+    if (result.isError) throw new Error('expected workflow success')
+    expect(result.value).toEqual({ runId: 'run-1', agentsStarted: 1, result: { blob: 'x'.repeat(500) } })
+    const rendered = (result.content[0] as { text: string }).text
     expect(rendered).toContain('[truncated:')
     expect(rendered.length).toBeLessThan(400)
   })
diff --git a/packages/workflow/workflow-workerthread/src/runtime.ts b/packages/workflow/workflow-workerthread/src/runtime.ts
index 535917fc42..38194f4c03 100644
--- a/packages/workflow/workflow-workerthread/src/runtime.ts
+++ b/packages/workflow/workflow-workerthread/src/runtime.ts
@@ -15,8 +15,8 @@
 import * as vm from 'node:vm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import { assertSupportedOutputSchema, OutputSchemaError } from '@deepseek-ai/dsh-tools'
-import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools'
+import { assertObjectJsonSchema, JsonSchemaError } from '@deepseek-ai/dsh-tools'
+import type { ObjectJsonSchema } from '@deepseek-ai/dsh-tools'
 import { isFatalWorkflowError, WorkflowError } from '@deepseek-ai/dsh-workflow'
 import type {
   WorkflowAgentEndInfo,
@@ -350,7 +350,7 @@ export class WorkflowExecution {
     phase?: string
     provider?: string
     model?: string
-    schema?: StructuredOutputSchema
+    schema?: ObjectJsonSchema
   } {
     if (rawOpts === undefined) return {}
     let opts: unknown
@@ -377,14 +377,14 @@ export class WorkflowExecution {
         throw new WorkflowError(`agent() option "${key}" must be a string`, 'INVALID_ARGUMENT')
       }
     }
-    let schema: StructuredOutputSchema | undefined
+    let schema: ObjectJsonSchema | undefined
     if (record.schema !== undefined) {
       try {
-        assertSupportedOutputSchema(record.schema)
+        assertObjectJsonSchema(record.schema)
         schema = record.schema
       } catch (error: unknown) {
-        /* v8 ignore next -- defensive rethrow arm: assertSupportedOutputSchema only throws OutputSchemaError */
-        if (!(error instanceof OutputSchemaError)) throw error
+        /* v8 ignore next -- defensive rethrow arm: assertObjectJsonSchema only throws JsonSchemaError */
+        if (!(error instanceof JsonSchemaError)) throw error
         throw new WorkflowError(`agent() schema is outside the supported subset — ${error.message}`, 'UNSUPPORTED_SCHEMA', { cause: error })
       }
     }
diff --git a/packages/workflow/workflow-workerthread/src/types.ts b/packages/workflow/workflow-workerthread/src/types.ts
index 7e2bfff36c..9d7ddf6808 100644
--- a/packages/workflow/workflow-workerthread/src/types.ts
+++ b/packages/workflow/workflow-workerthread/src/types.ts
@@ -6,7 +6,7 @@
  */
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools'
+import type { ObjectJsonSchema } from '@deepseek-ai/dsh-tools'
 import type { WorkflowMeta } from '@deepseek-ai/dsh-workflow'
 
 /**
@@ -41,7 +41,7 @@ export interface ChildStartRequest {
   /** The child's prompt text. */
   prompt: string
   /** The structured-output schema, if the call passed one (already subset-checked). */
-  schema?: StructuredOutputSchema
+  schema?: ObjectJsonSchema
   /** The per-child provider override, if the call passed one. */
   provider?: string
   /** The per-child model override, if the call passed one. */
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e83b05f35c..15baee1425 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -77,9 +77,6 @@ importers:
       publint:
         specifier: ^0.3.21
         version: 0.3.21
-      saxes:
-        specifier: ^6.0.0
-        version: 6.0.0
       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)
@@ -104,6 +101,36 @@ importers:
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
         version: link:../../packages/ui/app-boot
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../../packages/client/connection
+      '@deepseek-ai/dsh-client-hmr':
+        specifier: workspace:^
+        version: link:../../packages/client/hmr
+      '@deepseek-ai/dsh-client-i18n':
+        specifier: workspace:^
+        version: link:../../packages/client/i18n
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../../packages/client/runtime
+      '@deepseek-ai/dsh-client-ui-conversation':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-conversation
+      '@deepseek-ai/dsh-client-ui-layout':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-layout
+      '@deepseek-ai/dsh-client-ui-question':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-question
+      '@deepseek-ai/dsh-client-ui-sidebar':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-sidebar
+      '@deepseek-ai/dsh-client-ui-theme':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-theme
+      '@deepseek-ai/dsh-client-ui-trajectory':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-trajectory
       '@deepseek-ai/dsh-frontend':
         specifier: workspace:^
         version: link:../web
@@ -122,9 +149,15 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../packages/core/session
+      '@deepseek-ai/dsh-tui':
+        specifier: workspace:^
+        version: link:../../packages/ui/tui
       commander:
         specifier: ^15.0.0
         version: 15.0.0
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
   apps/web:
     dependencies:
@@ -138,9 +171,9 @@ importers:
         specifier: ^18.2.0
         version: 18.3.1(react@18.3.1)
     devDependencies:
-      '@deepseek-ai/dsh-client-runtime':
+      '@deepseek-ai/dsh-client-modules':
         specifier: workspace:^
-        version: link:../../packages/client/runtime
+        version: link:../../packages/client/modules
       '@deepseek-ai/dsh-client-ui-primitives':
         specifier: workspace:^
         version: link:../../packages/client/ui-primitives
@@ -243,6 +276,9 @@ importers:
       '@deepseek-ai/dsh-llm-deepseek':
         specifier: workspace:*
         version: link:../packages/llm/llm-deepseek
+      '@deepseek-ai/dsh-llm-pi-ai':
+        specifier: workspace:*
+        version: link:../packages/llm/llm-pi-ai
       '@deepseek-ai/dsh-llm-replay':
         specifier: workspace:*
         version: link:../packages/support/llm-replay
@@ -279,6 +315,12 @@ importers:
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:*
         version: link:../packages/session-persistence/session-persistence-jsonl
+      '@deepseek-ai/dsh-session-query':
+        specifier: workspace:*
+        version: link:../packages/session-query/session-query
+      '@deepseek-ai/dsh-session-query-sqlite':
+        specifier: workspace:*
+        version: link:../packages/session-query/session-query-sqlite
       '@deepseek-ai/dsh-session-title-first-message-llm':
         specifier: workspace:*
         version: link:../packages/session-title/session-title-first-message-llm
@@ -509,6 +551,21 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/client/hmr:
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-client-modules':
+        specifier: workspace:^
+        version: link:../modules
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@vendor+loader)
+
   packages/client/i18n:
     dependencies:
       '@deepseek-ai/dsh-client-runtime':
@@ -522,6 +579,15 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/client/modules:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
   packages/client/runtime:
     dependencies:
       '@deepseek-ai/dsh-client-connection':
@@ -530,6 +596,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-host-apiproxy':
+        specifier: workspace:^
+        version: link:../../host/apiproxy
       '@deepseek-ai/dsh-llm':
         specifier: workspace:^
         version: link:../../llm/llm
@@ -558,9 +627,10 @@ importers:
 
   packages/client/ui-conversation:
     dependencies:
-      '@deepseek-ai/dsh-client-i18n':
-        specifier: workspace:^
-        version: link:../i18n
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+    devDependencies:
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime
@@ -573,13 +643,6 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
-      clsx:
-        specifier: ^2.0.0
-        version: 2.1.1
-      react:
-        specifier: ^18.2.0
-        version: 18.3.1
-    devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -589,19 +652,18 @@ importers:
       cordis:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
 
   packages/client/ui-layout:
-    dependencies:
+    devDependencies:
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
-      react:
-        specifier: ^18.2.0
-        version: 18.3.1
-    devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -611,6 +673,9 @@ importers:
       cordis:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
 
   packages/client/ui-primitives:
     dependencies:
@@ -620,6 +685,12 @@ importers:
       react:
         specifier: ^18.2.0
         version: 18.3.1
+      react-markdown:
+        specifier: ^10.1.0
+        version: 10.1.0(@types/react@18.3.31)(react@18.3.1)
+      remark-gfm:
+        specifier: ^4.0.1
+        version: 4.0.1
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
@@ -631,8 +702,61 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/client/ui-question:
+    dependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../connection
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../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-tool-ask-user':
+        specifier: workspace:^
+        version: link:../../ui/tool-ask-user
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@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:../../ui/user-interaction
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
   packages/client/ui-sidebar:
     dependencies:
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+    devDependencies:
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime
@@ -645,13 +769,6 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
-      clsx:
-        specifier: ^2.0.0
-        version: 2.1.1
-      react:
-        specifier: ^18.2.0
-        version: 18.3.1
-    devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -661,6 +778,9 @@ importers:
       cordis:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
 
   packages/client/ui-slots:
     devDependencies:
@@ -684,17 +804,16 @@ importers:
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
   packages/client/ui-trajectory:
-    dependencies:
-      '@deepseek-ai/dsh-client-ui-conversation':
-        specifier: workspace:^
-        version: link:../ui-conversation
-      react:
-        specifier: ^18.2.0
-        version: 18.3.1
     devDependencies:
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../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
@@ -704,15 +823,15 @@ importers:
       cordis:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
 
   packages/client/web:
     dependencies:
-      '@deepseek-ai/dsh-client-connection':
+      '@deepseek-ai/dsh-client-modules':
         specifier: workspace:^
-        version: link:../connection
-      '@deepseek-ai/dsh-client-runtime':
-        specifier: workspace:^
-        version: link:../runtime
+        version: link:../modules
       '@deepseek-ai/dsh-client-ui-primitives':
         specifier: workspace:^
         version: link:../ui-primitives
@@ -732,6 +851,12 @@ importers:
         specifier: ^18.2.0
         version: 18.3.1(react@18.3.1)
     devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../runtime
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -743,7 +868,7 @@ importers:
         version: 18.3.7(@types/react@18.3.31)
       cordis:
         specifier: ^4.0.0-rc.7
-        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@vendor+loader)
       typescript:
         specifier: ^6.0.3
         version: 6.0.3
@@ -791,6 +916,9 @@ importers:
       '@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: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
@@ -1223,6 +1351,9 @@ importers:
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../session-query/session-query
+      '@deepseek-ai/dsh-session-query-sqlite':
+        specifier: workspace:^
+        version: link:../../session-query/session-query-sqlite
       '@deepseek-ai/dsh-session-reference':
         specifier: workspace:^
         version: link:../../context/session-reference
@@ -1450,6 +1581,9 @@ importers:
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../session-query/session-query
+      '@deepseek-ai/dsh-session-query-sqlite':
+        specifier: workspace:^
+        version: link:../../session-query/session-query-sqlite
       '@deepseek-ai/dsh-session-reference':
         specifier: workspace:^
         version: link:../../context/session-reference
@@ -1966,30 +2100,6 @@ importers:
       '@deepseek-ai/dsh-bash-local':
         specifier: workspace:^
         version: link:../../bash/bash-local
-      '@deepseek-ai/dsh-client-connection':
-        specifier: workspace:^
-        version: link:../../client/connection
-      '@deepseek-ai/dsh-client-i18n':
-        specifier: workspace:^
-        version: link:../../client/i18n
-      '@deepseek-ai/dsh-client-runtime':
-        specifier: workspace:^
-        version: link:../../client/runtime
-      '@deepseek-ai/dsh-client-ui-conversation':
-        specifier: workspace:^
-        version: link:../../client/ui-conversation
-      '@deepseek-ai/dsh-client-ui-layout':
-        specifier: workspace:^
-        version: link:../../client/ui-layout
-      '@deepseek-ai/dsh-client-ui-sidebar':
-        specifier: workspace:^
-        version: link:../../client/ui-sidebar
-      '@deepseek-ai/dsh-client-ui-theme':
-        specifier: workspace:^
-        version: link:../../client/ui-theme
-      '@deepseek-ai/dsh-client-ui-trajectory':
-        specifier: workspace:^
-        version: link:../../client/ui-trajectory
       '@deepseek-ai/dsh-compact-basic':
         specifier: workspace:^
         version: link:../../compact/compact-basic
@@ -2017,6 +2127,12 @@ importers:
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
         version: link:../../session-persistence/session-persistence-jsonl
+      '@deepseek-ai/dsh-session-title':
+        specifier: workspace:^
+        version: link:../../session-title/session-title
+      '@deepseek-ai/dsh-session-title-first-message-llm':
+        specifier: workspace:^
+        version: link:../../session-title/session-title-first-message-llm
       '@deepseek-ai/dsh-skill':
         specifier: workspace:^
         version: link:../../skill/skill
@@ -2077,6 +2193,9 @@ importers:
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
+      '@deepseek-ai/dsh-user-interaction':
+        specifier: workspace:^
+        version: link:../../ui/user-interaction
       '@deepseek-ai/dsh-workflow-workerthread':
         specifier: workspace:^
         version: link:../../workflow/workflow-workerthread
@@ -2315,6 +2434,9 @@ importers:
       schemastery:
         specifier: ^3.18.0
         version: 3.18.0
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
@@ -2334,9 +2456,6 @@ importers:
       cordis:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
-      zod:
-        specifier: ^4.4.3
-        version: 4.4.3
 
   packages/plan/plan-mode:
     devDependencies:
@@ -2424,6 +2543,10 @@ importers:
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
   packages/pty/tool-pty:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
     devDependencies:
       '@cordisjs/plugin-include':
         specifier: workspace:^
@@ -2446,6 +2569,9 @@ importers:
       '@deepseek-ai/dsh-pty-local':
         specifier: workspace:^
         version: link:../pty-local
+      '@deepseek-ai/dsh-retention':
+        specifier: workspace:^
+        version: link:../../util/retention
       '@deepseek-ai/dsh-sandbox':
         specifier: workspace:^
         version: link:../../sandbox/sandbox
@@ -2677,6 +2803,9 @@ importers:
 
   packages/session-persistence/session-persistence:
     devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -2732,11 +2861,10 @@ importers:
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
   packages/session-query/session-query:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: 3.18.0
     devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -2756,6 +2884,34 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/session-query/session-query-sqlite:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+    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: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@vendor+loader)
+
   packages/session-title/session-title:
     dependencies:
       schemastery:
@@ -2989,6 +3145,9 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
+      '@deepseek-ai/dsh-code-runtime-worker':
+        specifier: workspace:^
+        version: link:../../code-runtime/code-runtime-worker
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3363,6 +3522,9 @@ importers:
       '@deepseek-ai/dsh-llm':
         specifier: workspace:^
         version: link:../../llm/llm
+      '@deepseek-ai/dsh-retention':
+        specifier: workspace:^
+        version: link:../../util/retention
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -3686,6 +3848,9 @@ importers:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
         version: link:../commands
+      '@deepseek-ai/dsh-goal':
+        specifier: workspace:^
+        version: link:../../goal/goal
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -4254,6 +4419,9 @@ importers:
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../packages/session-query/session-query
+      '@deepseek-ai/dsh-session-query-sqlite':
+        specifier: workspace:^
+        version: link:../../packages/session-query/session-query-sqlite
       '@deepseek-ai/dsh-session-reference':
         specifier: workspace:^
         version: link:../../packages/context/session-reference
@@ -6472,6 +6640,9 @@ packages:
   '@types/esrecurse@4.3.1':
     resolution: {integrity: sha512-xJBAbDifo5hpffDBuHl0Y8ywswbiAp/Wi7Y/GtAgSlZyIABppyurxVueOPE8LUQOxdlgi6Zqce7uoEpqNTeiUw==}
 
+  '@types/estree-jsx@1.0.5':
+    resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
+
   '@types/estree@1.0.9':
     resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
 
@@ -6537,6 +6708,9 @@ packages:
   '@types/trusted-types@2.0.7':
     resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
 
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
   '@types/unist@3.0.3':
     resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
 
@@ -6830,6 +7004,9 @@ packages:
   ast-v8-to-istanbul@1.0.4:
     resolution: {integrity: sha512-0bC0/4bTSrnwdhU3IsZDwEdojvuPrSg59OYZfKsLRtJZ0u8VBx9DebfqqG8bRdCC0I7vjgxmPi41P0lpkhJHtA==}
 
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
   balanced-match@1.0.2:
     resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
 
@@ -6918,6 +7095,9 @@ packages:
   character-entities@2.0.2:
     resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
 
+  character-reference-invalid@2.0.1:
+    resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+
   chokidar@4.0.3:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
@@ -7383,6 +7563,9 @@ packages:
     resolution: {integrity: sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==}
     engines: {node: '>=4.0'}
 
+  estree-util-is-identifier-name@3.0.0:
+    resolution: {integrity: sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==}
+
   estree-walker@2.0.2:
     resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
 
@@ -7611,6 +7794,9 @@ packages:
   hast-util-to-html@9.0.5:
     resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==}
 
+  hast-util-to-jsx-runtime@2.3.6:
+    resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+
   hast-util-whitespace@3.0.0:
     resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
 
@@ -7631,6 +7817,9 @@ packages:
   html-escaper@2.0.2:
     resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==}
 
+  html-url-attributes@3.0.1:
+    resolution: {integrity: sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==}
+
   html-void-elements@3.0.0:
     resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==}
 
@@ -7682,6 +7871,9 @@ packages:
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
+  inline-style-parser@0.2.7:
+    resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
+
   internmap@1.0.1:
     resolution: {integrity: sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==}
 
@@ -7697,6 +7889,15 @@ packages:
     resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
     engines: {node: '>= 0.10'}
 
+  is-alphabetical@2.0.1:
+    resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
+
+  is-alphanumerical@2.0.1:
+    resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
+
+  is-decimal@2.0.1:
+    resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
+
   is-extglob@2.1.1:
     resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
     engines: {node: '>=0.10.0'}
@@ -7709,6 +7910,13 @@ packages:
     resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
     engines: {node: '>=0.10.0'}
 
+  is-hexadecimal@2.0.1:
+    resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
+
+  is-plain-obj@4.1.0:
+    resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
+    engines: {node: '>=12'}
+
   is-potential-custom-element-name@1.0.1:
     resolution: {integrity: sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==}
 
@@ -8099,6 +8307,15 @@ packages:
   mdast-util-gfm@3.1.0:
     resolution: {integrity: sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==}
 
+  mdast-util-mdx-expression@2.0.1:
+    resolution: {integrity: sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==}
+
+  mdast-util-mdx-jsx@3.2.0:
+    resolution: {integrity: sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==}
+
+  mdast-util-mdxjs-esm@2.0.1:
+    resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==}
+
   mdast-util-phrasing@4.1.0:
     resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
 
@@ -8416,6 +8633,9 @@ packages:
   pako@1.0.11:
     resolution: {integrity: sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==}
 
+  parse-entities@4.0.2:
+    resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
+
   parse5@8.0.1:
     resolution: {integrity: sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==}
 
@@ -8550,6 +8770,12 @@ packages:
   react-is@17.0.2:
     resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==}
 
+  react-markdown@10.1.0:
+    resolution: {integrity: sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==}
+    peerDependencies:
+      '@types/react': '>=18'
+      react: '>=18'
+
   react-refresh@0.17.0:
     resolution: {integrity: sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==}
     engines: {node: '>=0.10.0'}
@@ -8582,6 +8808,18 @@ packages:
     resolution: {integrity: sha512-sZuz1dYW/ZsfG17WSAG7eS85r5a0dDsvg+7BiiYR5o6lKCAtUrEwdmRmaGF6rwVj3LcmAeYkOWKEPlbPzN3Y3A==}
     engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
 
+  remark-gfm@4.0.1:
+    resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-rehype@11.1.2:
+    resolution: {integrity: sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==}
+
+  remark-stringify@11.0.0:
+    resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+
   require-from-string@2.0.2:
     resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
     engines: {node: '>=0.10.0'}
@@ -8791,6 +9029,12 @@ packages:
   strnum@2.4.0:
     resolution: {integrity: sha512-sHrVyWWdq28RbhjuJdZsA1SnGRJV6NiXbk6AXBxDOsgAcA+lmpUZCYjOdLBxkXMwis6RRe7dlZt4VlIWFVzkmg==}
 
+  style-to-js@1.1.21:
+    resolution: {integrity: sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==}
+
+  style-to-object@1.0.14:
+    resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==}
+
   stylis@4.4.0:
     resolution: {integrity: sha512-5Z9ZpRzfuH6l/UAvCPAPUo3665Nk2wLaZU3x+TLHKVzIz33+sbJqbtrYoC3KD4/uVOr2Zp+L0LySezP9OHV9yA==}
 
@@ -8853,6 +9097,9 @@ packages:
   trim-lines@3.0.1:
     resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
 
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
   ts-algebra@2.0.0:
     resolution: {integrity: sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==}
 
@@ -8969,6 +9216,9 @@ packages:
     resolution: {integrity: sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==}
     engines: {node: '>=20.18.1'}
 
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
   unist-util-is@6.0.1:
     resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
 
@@ -11090,6 +11340,10 @@ snapshots:
 
   '@types/esrecurse@4.3.1': {}
 
+  '@types/estree-jsx@1.0.5':
+    dependencies:
+      '@types/estree': 1.0.9
+
   '@types/estree@1.0.9': {}
 
   '@types/geojson@7946.0.16': {}
@@ -11154,6 +11408,8 @@ snapshots:
   '@types/trusted-types@2.0.7':
     optional: true
 
+  '@types/unist@2.0.11': {}
+
   '@types/unist@3.0.3': {}
 
   '@types/web-bluetooth@0.0.21': {}
@@ -11529,6 +11785,8 @@ snapshots:
       estree-walker: 3.0.3
       js-tokens: 10.0.0
 
+  bail@2.0.2: {}
+
   balanced-match@1.0.2: {}
 
   balanced-match@4.0.4: {}
@@ -11609,6 +11867,8 @@ snapshots:
 
   character-entities@2.0.2: {}
 
+  character-reference-invalid@2.0.1: {}
+
   chokidar@4.0.3:
     dependencies:
       readdirp: 4.1.2
@@ -12159,6 +12419,8 @@ snapshots:
 
   estraverse@5.3.0: {}
 
+  estree-util-is-identifier-name@3.0.0: {}
+
   estree-walker@2.0.2: {}
 
   estree-walker@3.0.3:
@@ -12433,6 +12695,26 @@ snapshots:
       stringify-entities: 4.0.4
       zwitch: 2.0.4
 
+  hast-util-to-jsx-runtime@2.3.6:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/hast': 3.0.5
+      '@types/unist': 3.0.3
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
   hast-util-whitespace@3.0.0:
     dependencies:
       '@types/hast': 3.0.5
@@ -12451,6 +12733,8 @@ snapshots:
 
   html-escaper@2.0.2: {}
 
+  html-url-attributes@3.0.1: {}
+
   html-void-elements@3.0.0: {}
 
   http-errors@2.0.1:
@@ -12499,6 +12783,8 @@ snapshots:
 
   inherits@2.0.4: {}
 
+  inline-style-parser@0.2.7: {}
+
   internmap@1.0.1: {}
 
   internmap@2.0.3: {}
@@ -12507,6 +12793,15 @@ snapshots:
 
   ipaddr.js@1.9.1: {}
 
+  is-alphabetical@2.0.1: {}
+
+  is-alphanumerical@2.0.1:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-decimal: 2.0.1
+
+  is-decimal@2.0.1: {}
+
   is-extglob@2.1.1: {}
 
   is-fullwidth-code-point@3.0.0: {}
@@ -12515,6 +12810,10 @@ snapshots:
     dependencies:
       is-extglob: 2.1.1
 
+  is-hexadecimal@2.0.1: {}
+
+  is-plain-obj@4.1.0: {}
+
   is-potential-custom-element-name@1.0.1: {}
 
   is-promise@4.0.0: {}
@@ -12934,6 +13233,45 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  mdast-util-mdx-expression@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-jsx@3.2.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      parse-entities: 4.0.2
+      stringify-entities: 4.0.4
+      unist-util-stringify-position: 4.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdxjs-esm@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
   mdast-util-phrasing@4.1.0:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13401,6 +13739,16 @@ snapshots:
 
   pako@1.0.11: {}
 
+  parse-entities@4.0.2:
+    dependencies:
+      '@types/unist': 2.0.11
+      character-entities-legacy: 3.0.0
+      character-reference-invalid: 2.0.1
+      decode-named-character-reference: 1.3.0
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+      is-hexadecimal: 2.0.1
+
   parse5@8.0.1:
     dependencies:
       entities: 8.0.0
@@ -13523,6 +13871,24 @@ snapshots:
 
   react-is@17.0.2: {}
 
+  react-markdown@10.1.0(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      '@types/react': 18.3.31
+      devlop: 1.1.0
+      hast-util-to-jsx-runtime: 2.3.6
+      html-url-attributes: 3.0.1
+      mdast-util-to-hast: 13.2.1
+      react: 18.3.1
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      unified: 11.0.5
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
   react-refresh@0.17.0: {}
 
   react@18.3.1:
@@ -13560,6 +13926,40 @@ snapshots:
       '@eslint-community/regexpp': 4.12.2
       refa: 0.12.1
 
+  remark-gfm@4.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-gfm: 3.1.0
+      micromark-extension-gfm: 3.0.0
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-rehype@11.1.2:
+    dependencies:
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      mdast-util-to-hast: 13.2.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  remark-stringify@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-to-markdown: 2.1.2
+      unified: 11.0.5
+
   require-from-string@2.0.2: {}
 
   resolve-pkg-maps@1.0.0: {}
@@ -13844,6 +14244,14 @@ snapshots:
     dependencies:
       anynum: 1.0.0
 
+  style-to-js@1.1.21:
+    dependencies:
+      style-to-object: 1.0.14
+
+  style-to-object@1.0.14:
+    dependencies:
+      inline-style-parser: 0.2.7
+
   stylis@4.4.0: {}
 
   superjson@2.2.6:
@@ -13891,6 +14299,8 @@ snapshots:
 
   trim-lines@3.0.1: {}
 
+  trough@2.2.0: {}
+
   ts-algebra@2.0.0: {}
 
   ts-api-utils@2.5.0(typescript@6.0.3):
@@ -13984,6 +14394,16 @@ snapshots:
 
   undici@7.28.0: {}
 
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
   unist-util-is@6.0.1:
     dependencies:
       '@types/unist': 3.0.3
diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json
index dbafb21881..8a8d31c815 100644
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -53,6 +53,7 @@
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
     "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml
index 956d6f8ff8..ed74d60087 100644
--- a/python/sdk/README.i18n.yaml
+++ b/python/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
-README.md: 23d15d617b3d295a6cc2d8d20c6d03abc226834b
-README.zh.md: 4f6aef13833af937babc2e5a92bfd14c12170534
+README.md: bfa31a712acd6fccf1458a0a80fc2ff80dfe114e
+README.zh.md: 11ebcdd133b2fd839b73f50ef2be2e531e8bbc2a
diff --git a/python/sdk/README.md b/python/sdk/README.md
index 23d15d617b..bfa31a712a 100644
--- a/python/sdk/README.md
+++ b/python/sdk/README.md
@@ -34,9 +34,7 @@ with DeepSeekHarness(
 
 `provider` selects a provider route registered by the chosen Cordis composition; `model` is the model id resolved by that adapter. The bundled default composition registers `deepseek`. A custom composition can mount `llm-pi-ai`, configure provider-specific credentials/endpoints there, and select any provider/model present in pi-ai's installed catalog.
 
-`TurnResult.final_response` is the text content from the last
-`assistant/message` event in the turn. Use `TurnResult.events` for the complete
-event stream, including intermediate assistant messages and tool activity.
+`HarnessClient` retains discovered subagent ancestry for the lifetime of the runtime process. During each `Session.run()`, `TurnResult.notifications` and `on_notification` receive the root session and all known descendant notifications in wire order, including nested subagent lifecycle and session events. `TurnResult.events` remains the root session's complete event stream, and `TurnResult.final_response` is the text content from its last `assistant/message`; descendant messages therefore cannot replace the root response.
 
 The same behavior can be selected for the runtime subprocess with `DSH_CORDIS_CONFIG`. The injection lives in `HarnessClient.start()`, so the low-level client's default launch gets it too: when the launch resolves to the bundled runtime and neither `cordis` nor a non-empty `DSH_CORDIS_CONFIG` is set (the runtime treats an empty value as absent, and so does the injection check), the bundled default configuration is used; an explicit `runtime_bin`, `bridge_bin`, or `launch_args_override` disables the injection entirely. See the [sdk-runtime README](../sdk-runtime/README.md) for the runtime carriers (production exe vs dev-only node closure) and how to obtain them.
 
diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md
index 4f6aef1383..11ebcdd133 100644
--- a/python/sdk/README.zh.md
+++ b/python/sdk/README.zh.md
@@ -30,7 +30,7 @@ with DeepSeekHarness(
 
 `provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。内置默认组合注册 `deepseek`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。
 
-`TurnResult.final_response` 是本轮次最后一个 `assistant/message` 事件的文本内容。完整的事件流（包括中间的助手消息与工具活动）用 `TurnResult.events` 获取。
+`HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`TurnResult.notifications` 与 `on_notification` 会按线上的原始顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期与会话事件。`TurnResult.events` 仍只保存根会话的完整事件流，`TurnResult.final_response` 则取该会话最后一个 `assistant/message` 的文本内容，因此后代消息不会覆盖根会话回复。
 
 同样的行为也可以通过 `DSH_CORDIS_CONFIG` 为运行时子进程选定。注入逻辑位于 `HarnessClient.start()`，因此底层客户端的默认启动也具有此行为：当启动解析到内置运行时，且 `cordis` 与非空的 `DSH_CORDIS_CONFIG` 均未设置时（运行时把空值视为缺省，注入检查与之一致），使用内置的默认配置；显式给出 `runtime_bin`、`bridge_bin` 或 `launch_args_override` 则完全禁用注入。运行时载体（生产用 exe 与仅限开发的 `node` 闭包）及其获取方式见 [sdk-runtime README](../sdk-runtime/README.md)。
 
diff --git a/python/sdk/src/deepseek_harness/api.py b/python/sdk/src/deepseek_harness/api.py
index 2b44a50c64..d96e974bc3 100644
--- a/python/sdk/src/deepseek_harness/api.py
+++ b/python/sdk/src/deepseek_harness/api.py
@@ -143,7 +143,10 @@ class Session:
             notifications.append(notification)
             if on_notification is not None:
                 on_notification(notification)
-            if notification.method == "session.event":
+            if (
+                notification.method == "session.event"
+                and notification.payload.get("sessionId") == self.id
+            ):
                 event = notification.payload.get("event")
                 if isinstance(event, dict):
                     events.append(event)
diff --git a/python/sdk/src/deepseek_harness/client.py b/python/sdk/src/deepseek_harness/client.py
index e552c8b685..8d4ec7f848 100644
--- a/python/sdk/src/deepseek_harness/client.py
+++ b/python/sdk/src/deepseek_harness/client.py
@@ -47,6 +47,7 @@ class HarnessClient:
         self._notification_subscribers: dict[
             str, tuple[queue.Queue[Notification | BaseException], NotificationFilter | None]
         ] = {}
+        self._session_parents: dict[str, str] = {}
         self._requests: queue.Queue[IncomingRequest | BaseException] = queue.Queue()
         self._stderr_lines: deque[str] = deque(maxlen=400)
         self._reader_thread: threading.Thread | None = None
@@ -62,6 +63,8 @@ class HarnessClient:
     def start(self) -> None:
         if self._proc is not None:
             return
+        with self._lock:
+            self._session_parents.clear()
         args = list(self.config.launch_args_override or self._default_launch_args())
         env = os.environ.copy()
         if self.config.env:
@@ -143,7 +146,7 @@ class HarnessClient:
             payload,
             response_model=_SessionPromptResponse,
             on_notification=on_notification,
-            notification_filter=_notification_belongs_to_session(session_id),
+            notification_filter=self._notification_belongs_to_session_tree(session_id),
             notification_subscription=notification_subscription,
         )
 
@@ -193,7 +196,8 @@ class HarnessClient:
         return NotificationSubscription(self, subscription_id, notifications)
 
     def subscribe_session_notifications(self, session_id: str) -> "NotificationSubscription":
-        return self.subscribe_notifications(_notification_belongs_to_session(session_id))
+        """Subscribe to a session and descendants discovered from subagent lifecycle edges."""
+        return self.subscribe_notifications(self._notification_belongs_to_session_tree(session_id))
 
     def next_request(self) -> IncomingRequest:
         item = self._requests.get()
@@ -352,6 +356,7 @@ class HarnessClient:
             params = message.get("params")
             notification = Notification(method=method, payload=params if isinstance(params, dict) else {})
             with self._lock:
+                self._record_session_relationship_locked(notification)
                 subscribers = list(self._notification_subscribers.items())
             delivered = False
             for subscription_id, (subscriber, predicate) in subscribers:
@@ -439,6 +444,52 @@ class HarnessClient:
         with self._lock:
             self._notification_subscribers.pop(subscription_id, None)
 
+    def _record_session_relationship_locked(self, notification: Notification) -> None:
+        if notification.method != "subagent.started":
+            return
+        parent_id = notification.payload.get("parentSessionId")
+        child_id = notification.payload.get("childSessionId")
+        if (
+            isinstance(parent_id, str)
+            and parent_id
+            and isinstance(child_id, str)
+            and child_id
+            and parent_id != child_id
+        ):
+            self._session_parents[child_id] = parent_id
+
+    def _notification_belongs_to_session_tree(self, session_id: str) -> NotificationFilter:
+        def belongs(notification: Notification) -> bool:
+            payload = notification.payload
+            if notification.method in {"subagent.started", "subagent.finished"}:
+                parent_id = payload.get("parentSessionId")
+                if (
+                    isinstance(parent_id, str)
+                    and self._session_is_descendant_of(parent_id, session_id)
+                ):
+                    return True
+                return payload.get("childSessionId") == session_id
+            related_id = payload.get("sessionId")
+            return (
+                isinstance(related_id, str)
+                and self._session_is_descendant_of(related_id, session_id)
+            )
+
+        return belongs
+
+    def _session_is_descendant_of(self, session_id: str, root_session_id: str) -> bool:
+        current = session_id
+        visited: set[str] = set()
+        while current not in visited:
+            if current == root_session_id:
+                return True
+            visited.add(current)
+            parent = self._session_parents.get(current)
+            if parent is None:
+                return False
+            current = parent
+        return False
+
 
 class NotificationSubscription:
     def __init__(
@@ -491,15 +542,3 @@ class _ShutdownResponse(BaseModel):
 
 def _int_or_none(value: object) -> int | None:
     return value if isinstance(value, int) else None
-
-
-def _notification_belongs_to_session(session_id: str) -> NotificationFilter:
-    def belongs(notification: Notification) -> bool:
-        payload = notification.payload
-        return (
-            payload.get("sessionId") == session_id
-            or payload.get("parentSessionId") == session_id
-            or payload.get("childSessionId") == session_id
-        )
-
-    return belongs
diff --git a/python/sdk/tests/test_client.py b/python/sdk/tests/test_client.py
index f66abf4b36..d5460b8683 100644
--- a/python/sdk/tests/test_client.py
+++ b/python/sdk/tests/test_client.py
@@ -9,7 +9,7 @@ from pathlib import Path
 
 import pytest
 
-from deepseek_harness import DeepSeekHarness, HarnessClient, HarnessConfig
+from deepseek_harness import DeepSeekHarness, HarnessClient, HarnessConfig, Notification
 
 
 def test_high_level_sdk_runs_turn_and_collects_final_response(tmp_path: Path) -> None:
@@ -198,6 +198,65 @@ for line in sys.stdin:
     ]
 
 
+def test_session_run_collects_nested_subagent_tree_without_polluting_root_events(
+    tmp_path: Path,
+) -> None:
+    script = tmp_path / "fake_runtime.py"
+    script.write_text(
+        """
+import json
+import sys
+
+for line in sys.stdin:
+    msg = json.loads(line)
+    method = msg.get("method")
+    if method == "initialize":
+        print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"serverInfo": {"name": "fake-runtime"}}}), flush=True)
+    elif method == "session/prompt":
+        root = (msg.get("params") or {})["sessionId"]
+        print(json.dumps({"jsonrpc": "2.0", "method": "subagent.started", "params": {"parentSessionId": root, "childSessionId": "child"}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": "child", "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "child response"}]}}}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "subagent.started", "params": {"parentSessionId": "child", "childSessionId": "grandchild"}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": "grandchild", "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "grandchild response"}]}}}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "subagent.finished", "params": {"parentSessionId": "child", "childSessionId": "grandchild", "status": "ok"}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "subagent.finished", "params": {"parentSessionId": root, "childSessionId": "child", "status": "ok"}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": root, "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "root response"}]}}}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": root, "status": "ok"}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True)
+    elif method == "shutdown":
+        print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True)
+        break
+""".strip()
+    )
+
+    seen: list[str] = []
+    with DeepSeekHarness(
+        launch_args_override=(sys.executable, str(script)),
+        cwd=str(tmp_path),
+    ) as harness:
+        result = harness.run(
+            "delegate recursively",
+            session_id="main",
+            on_notification=lambda notification: seen.append(notification.method),
+        )
+        assert harness.client._notifications.qsize() == 0
+
+    assert result.status == "ok"
+    assert result.final_response == "root response"
+    assert [event["data"]["content"][0]["text"] for event in result.events] == ["root response"]
+    assert [notification.method for notification in result.notifications] == [
+        "subagent.started",
+        "session.event",
+        "subagent.started",
+        "session.event",
+        "subagent.finished",
+        "subagent.finished",
+        "session.event",
+        "session.finished",
+    ]
+    assert seen == [notification.method for notification in result.notifications]
+
+
 def test_session_run_ignores_notifications_for_other_sessions(tmp_path: Path) -> None:
     script = tmp_path / "fake_runtime.py"
     script.write_text(
@@ -356,6 +415,92 @@ def test_client_keeps_unmatched_notifications_available_globally_while_subscribe
         assert notification.payload["sessionId"] == "other"
 
 
+def test_session_subscription_keeps_descendant_relationships_across_subscriptions() -> None:
+    client = HarnessClient()
+    with client.subscribe_session_notifications("main") as first:
+        client._handle_message({
+            "jsonrpc": "2.0",
+            "method": "subagent.started",
+            "params": {"parentSessionId": "main", "childSessionId": "child"},
+        })
+        assert first.next().payload["childSessionId"] == "child"
+
+    with client.subscribe_session_notifications("main") as second:
+        client._handle_message({
+            "jsonrpc": "2.0",
+            "method": "subagent.started",
+            "params": {"parentSessionId": "child", "childSessionId": "grandchild"},
+        })
+        client._handle_message({
+            "jsonrpc": "2.0",
+            "method": "session.event",
+            "params": {"sessionId": "grandchild", "event": {"type": "assistant/message"}},
+        })
+        assert second.next().payload["childSessionId"] == "grandchild"
+        assert second.next().payload["sessionId"] == "grandchild"
+
+    assert client._notifications.qsize() == 0
+
+
+def test_session_subscription_preserves_reused_child_ancestry_after_late_finish() -> None:
+    client = HarnessClient()
+    old_seen: list[Notification] = []
+    new_seen: list[Notification] = []
+    with (
+        client.subscribe_session_notifications("old-parent") as old_subscription,
+        client.subscribe_session_notifications("new-parent") as new_subscription,
+    ):
+        client._handle_message({
+            "jsonrpc": "2.0",
+            "method": "subagent.started",
+            "params": {"parentSessionId": "old-parent", "childSessionId": "reused-child"},
+        })
+        old_subscription.drain(old_seen.append)
+        new_subscription.drain(new_seen.append)
+        assert [notification.method for notification in old_seen] == ["subagent.started"]
+        assert new_seen == []
+
+        client._handle_message({
+            "jsonrpc": "2.0",
+            "method": "subagent.started",
+            "params": {"parentSessionId": "new-parent", "childSessionId": "reused-child"},
+        })
+        old_subscription.drain(old_seen.append)
+        new_subscription.drain(new_seen.append)
+        assert [notification.method for notification in new_seen] == ["subagent.started"]
+
+        client._handle_message({
+            "jsonrpc": "2.0",
+            "method": "subagent.finished",
+            "params": {"parentSessionId": "old-parent", "childSessionId": "reused-child"},
+        })
+        old_subscription.drain(old_seen.append)
+        new_subscription.drain(new_seen.append)
+        assert [notification.method for notification in old_seen] == [
+            "subagent.started",
+            "subagent.finished",
+        ]
+        assert [notification.method for notification in new_seen] == ["subagent.started"]
+
+        client._handle_message({
+            "jsonrpc": "2.0",
+            "method": "session.event",
+            "params": {"sessionId": "reused-child", "event": {"type": "assistant/message"}},
+        })
+        old_subscription.drain(old_seen.append)
+        new_subscription.drain(new_seen.append)
+
+    assert [notification.method for notification in old_seen] == [
+        "subagent.started",
+        "subagent.finished",
+    ]
+    assert [notification.method for notification in new_seen] == [
+        "subagent.started",
+        "session.event",
+    ]
+    assert client._notifications.qsize() == 0
+
+
 def test_client_contains_notification_filter_failure_to_its_subscription(tmp_path: Path) -> None:
     script = tmp_path / "fake_bridge.py"
     script.write_text(
diff --git a/scripts/client-bundle-purity.spec.ts b/scripts/client-bundle-purity.spec.ts
index 8f04e2f044..379346134a 100644
--- a/scripts/client-bundle-purity.spec.ts
+++ b/scripts/client-bundle-purity.spec.ts
@@ -1,9 +1,10 @@
 /**
- * Pins the client-bundle purity gate (tsdown preset resolveId classifier):
- * a bare-name import of a module-table package must rewrite to its /client
- * external form (inlining it duplicates runtime identity — the P0
-/* leak that is not an
- * inline-safe wire layer must fail the build loudly.
+ * Pins the client-bundle purity gate (tsdown preset resolveId classifier),
+ * the build-time mirror of the module-edge rules: platform module-table
+ * entries stay external, inline-safe wire layers inline, and every other
+ * @deepseek-ai value import — including a bare plugin-package name and a
+ * cross-plugin /client subpath — must fail the build loudly (cross-plugin
+ * collaboration goes through cordis services, never module imports).
  */
 import { describe, expect, it } from 'vitest'
 import { CLIENT_EXTERNALS, clientBundle } from '../packages/client/tsdown.client.ts'
@@ -23,22 +24,16 @@ function purityResolveId(): ResolveId {
 describe('client bundle purity gate', () => {
   const resolveId = purityResolveId()
 
-  it('leaves table entries and non-scoped specifiers alone', () => {
+  it('leaves platform table entries and non-scoped specifiers alone', () => {
     expect(resolveId('@deepseek-ai/dsh-client-ui-slots')).toBeNull()
-    expect(resolveId('@deepseek-ai/dsh-client-runtime/client')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-client-web-react')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-client-ui-primitives')).toBeNull()
     expect(resolveId('react')).toBeNull()
     expect(resolveId('zod')).toBeNull()
   })
 
-  it('rewrites a bare table-package name to its external /client form (duplicate-instance prevention)', () => {
-    expect(resolveId('@deepseek-ai/dsh-client-connection')).toEqual({
-      id: '@deepseek-ai/dsh-client-connection/client',
-      external: true,
-    })
-    expect(resolveId('@deepseek-ai/dsh-client-ui-layout')).toEqual({
-      id: '@deepseek-ai/dsh-client-ui-layout/client',
-      external: true,
-    })
+  it('rejects retired table entries (web-react/store left the 8-entry seed)', () => {
+    expect(() => resolveId('@deepseek-ai/dsh-client-web-react/store')).toThrow(/purity/)
   })
 
   it('lets inline-safe wire layers inline', () => {
@@ -52,9 +47,16 @@ describe('client bundle purity gate', () => {
     expect(() => resolveId('@deepseek-ai/dsh-client-web')).toThrow(/purity/)
   })
 
-  it('every /client external has no bare-name twin in the table (the rewrite assumption)', () => {
-    for (const entry of CLIENT_EXTERNALS) {
-      if (entry.endsWith('/client')) expect(CLIENT_EXTERNALS).not.toContain(entry.slice(0, -'/client'.length))
-    }
+  it('throws on cross-plugin value imports — bare plugin names and /client subpaths alike (the rewrite arm is gone)', () => {
+    expect(() => resolveId('@deepseek-ai/dsh-client-connection')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-client-runtime')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-client-ui-layout/client')).toThrow(/purity/)
+  })
+
+  it('carries exactly one documented temporary exemption: runtime/client (store engine pending rehoming)', () => {
+    expect(resolveId('@deepseek-ai/dsh-client-runtime/client')).toBeNull()
+    const dshClientChannels = CLIENT_EXTERNALS.filter(
+      entry => entry.startsWith('@deepseek-ai/') && entry.endsWith('/client'))
+    expect(dshClientChannels).toEqual(['@deepseek-ai/dsh-client-runtime/client'])
   })
 })
diff --git a/scripts/cordis-config-files.spec.ts b/scripts/cordis-config-files.spec.ts
new file mode 100644
index 0000000000..ae5c4b1580
--- /dev/null
+++ b/scripts/cordis-config-files.spec.ts
@@ -0,0 +1,36 @@
+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 { cordisConfigFiles } from './cordis-config-files.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+describe('cordisConfigFiles', () => {
+  it('finds Loader YAML without treating translation records as configs', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-cordis-config-files-'))
+    roots.push(root)
+    for (const directory of ['.claude', 'docs', 'examples', 'node_modules/pkg', 'vendor/pkg']) {
+      mkdirSync(join(root, directory), { recursive: true })
+    }
+    for (const file of [
+      '.claude/hidden.cordis.yml',
+      'docs/cordis-primer.i18n.yaml',
+      'examples/agent.cordis.yaml',
+      'examples/headless.cordis.yml',
+      'node_modules/pkg/hidden.cordis.yml',
+      'vendor/pkg/hidden.cordis.yml',
+    ]) {
+      writeFileSync(join(root, file), '[]\n')
+    }
+
+    expect(cordisConfigFiles(root)).toEqual([
+      join('examples', 'agent.cordis.yaml'),
+      join('examples', 'headless.cordis.yml'),
+    ])
+  })
+})
diff --git a/scripts/cordis-config-files.ts b/scripts/cordis-config-files.ts
new file mode 100644
index 0000000000..9473779efe
--- /dev/null
+++ b/scripts/cordis-config-files.ts
@@ -0,0 +1,18 @@
+/** Cordis Loader configuration file discovery. */
+
+import { globSync } from 'node:fs'
+
+/**
+ * Return repository-relative Cordis Loader YAML paths under `root`.
+ *
+ * Translation consistency records are YAML sidecars, never Loader inputs.
+ *
+ * @param root Repository root to scan.
+ * @returns Sorted repository-relative Loader configuration paths.
+ */
+export function cordisConfigFiles(root: string): string[] {
+  return globSync(['**/*cordis*.yml', '**/*cordis*.yaml'], {
+    cwd: root,
+    exclude: ['.claude/**', 'node_modules/**', 'vendor/**', '**/*.i18n.yaml'],
+  }).sort()
+}
diff --git a/scripts/demo-code-mode.mjs b/scripts/demo-code-mode.mjs
index 273e6e1b38..c3e7849a6b 100644
--- a/scripts/demo-code-mode.mjs
+++ b/scripts/demo-code-mode.mjs
@@ -7,7 +7,7 @@ import { spawn } from 'node:child_process'
 
 // Each UI's node invocation matches its base demo script plus the overlay config.
 const UIS = new Map([
-  ['tui', ['--expose-internals', '--import', 'tsx', 'packages/examples/tui-demo/src/bin.ts', 'examples/tui-agent/code-mode.cordis.yml']],
+  ['tui', ['--import', 'tsx', 'packages/examples/tui-demo/src/bin.ts', 'examples/tui-agent/code-mode.cordis.yml']],
   ['acp', ['--import', 'tsx', 'packages/examples/acp-demo/src/bin.ts', '--config', 'examples/acp-agent/code-mode.cordis.yml']],
 ])
 
diff --git a/scripts/dev-web.ts b/scripts/dev-web.ts
new file mode 100644
index 0000000000..ac45f2d02e
--- /dev/null
+++ b/scripts/dev-web.ts
@@ -0,0 +1,85 @@
+/**
+ * Watch-build for client-plugin HMR: runs every dshClient plugin package
+ * through the tsdown JS API in watch mode. Reload signaling is not this
+ * script's business — the host webserver stat-polls the bundles it serves and
+ * broadcasts `rebuilt` frames itself (`dsh web --dev`), so any process that
+ * rewrites `lib/client.js` files triggers reloads; this script is merely the
+ * convenient way to keep them all rebuilt on source change.
+ *
+ * Usage: `pnpm exec tsx scripts/dev-web.ts [--poll[=ms]]`. Requires the
+ * packages' node halves built once (`tsc -b tsconfig.build.json`): the lib
+ * config's entries are tsc output. `--poll` switches the source-file watcher
+ * to polling (default 500ms): network mounts (weka) deliver no inotify
+ * events, so native watching sees the initial build only and never a source
+ * change.
+ *
+ * Each package keeps its own tsdown.config.ts untouched: this script layers
+ * `watch` through API-level inline config (tsdown workspace mode fills inline
+ * keys under each package's file config, and no package config defines it).
+ */
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'tsdown'
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url))
+
+/**
+ * Discover the watch workspace by declaration: every packages/<group>/<name>
+ * whose package.json carries `dshClient` with platform "web" is a client
+ * plugin bundle emitter. Scanned once at startup — a package added while
+ * watching means restarting this script.
+ * @returns workspace-relative plugin package directories.
+ */
+function discoverPluginDirs(): string[] {
+  const dirs: string[] = []
+  for (const group of readdirSync(join(repoRoot, 'packages'), { withFileTypes: true })) {
+    if (!group.isDirectory()) continue
+    for (const pkg of readdirSync(join(repoRoot, 'packages', group.name), { withFileTypes: true })) {
+      if (!pkg.isDirectory()) continue
+      let manifest: { dshClient?: { platform?: unknown } }
+      try {
+        manifest = JSON.parse(
+          readFileSync(join(repoRoot, 'packages', group.name, pkg.name, 'package.json'), 'utf8'),
+        ) as { dshClient?: { platform?: unknown } }
+      } catch {
+        continue // no package.json (support dirs, scratch): not a workspace package
+      }
+      if (manifest.dshClient?.platform === 'web') dirs.push(`packages/${group.name}/${pkg.name}`)
+    }
+  }
+  return dirs
+}
+
+const PLUGIN_DIRS = discoverPluginDirs()
+if (PLUGIN_DIRS.length === 0) {
+  console.error('dev-web: no dshClient (platform "web") packages found under packages/')
+  process.exit(1)
+}
+
+const args = process.argv.slice(2)
+const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll='))
+if (args.some(a => a !== pollArg)) {
+  console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]')
+  process.exit(1)
+}
+const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500')
+if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) {
+  console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`)
+  process.exit(1)
+}
+
+await build({
+  cwd: repoRoot,
+  workspace: PLUGIN_DIRS,
+  watch: true,
+  // Rolldown watch options ride through inputOptions (tsdown has no watcher
+  // tuning of its own); polling is opt-in for network mounts without inotify.
+  ...pollInterval !== undefined
+    ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } }
+    : {},
+})
+console.log(
+  `dev-web: watching ${String(PLUGIN_DIRS.length)} dshClient plugin packages`
+  + `${pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : ''}:\n  ${PLUGIN_DIRS.join('\n  ')}`,
+)
diff --git a/scripts/fixtures/translation-prompt/response.txt b/scripts/fixtures/translation-prompt/response.txt
new file mode 100644
index 0000000000..d31e8405e6
--- /dev/null
+++ b/scripts/fixtures/translation-prompt/response.txt
@@ -0,0 +1,23 @@
+<translation>
+---
+layout: doc
+---
+
+# 快照说明
+
+agent（智能体）执行一个步骤。
+</translation>
+
+<review>
+- 无修正
+</review>
+
+<final>
+---
+layout: doc
+---
+
+# 快照说明
+
+agent（智能体）执行一个步骤。
+</final>
diff --git a/scripts/fixtures/translation-prompt/snapshot-note.md b/scripts/fixtures/translation-prompt/snapshot-note.md
new file mode 100644
index 0000000000..2fa22215cb
--- /dev/null
+++ b/scripts/fixtures/translation-prompt/snapshot-note.md
@@ -0,0 +1,7 @@
+---
+layout: doc
+---
+
+# Snapshot note
+
+The agent performs one step.
diff --git a/scripts/gen-cordis-api.ts b/scripts/gen-cordis-api.ts
index 7c61b9395d..5f2080b149 100644
--- a/scripts/gen-cordis-api.ts
+++ b/scripts/gen-cordis-api.ts
@@ -30,8 +30,45 @@ function quote(value: string): string {
 }
 
 /**
- * Collect exported interface and type shapes; omit names declared in multiple
- * packages rather than risk serving the wrong package's shape.
+ * Reduce an exported class to its type shape: drop method/constructor bodies
+ * and property initializers so the catalog serves member signatures, not
+ * implementation.
+ */
+function classShape(node: ts.ClassDeclaration): ts.ClassDeclaration {
+  const isNonPublic = (member: ts.ClassElement): boolean =>
+    (ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined)?.some(m =>
+      m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false
+  const members = node.members.flatMap((member): ts.ClassElement[] => {
+    if (isNonPublic(member) || (ts.isPropertyDeclaration(member) && ts.isPrivateIdentifier(member.name))) return []
+    if (ts.isMethodDeclaration(member)) {
+      return [ts.factory.updateMethodDeclaration(
+        member, member.modifiers, member.asteriskToken, member.name, member.questionToken,
+        member.typeParameters, member.parameters, member.type, undefined)]
+    }
+    if (ts.isConstructorDeclaration(member)) {
+      return [ts.factory.updateConstructorDeclaration(member, member.modifiers, member.parameters, undefined)]
+    }
+    if (ts.isGetAccessorDeclaration(member)) {
+      return [ts.factory.updateGetAccessorDeclaration(
+        member, member.modifiers, member.name, member.parameters, member.type, undefined)]
+    }
+    if (ts.isSetAccessorDeclaration(member)) {
+      return [ts.factory.updateSetAccessorDeclaration(
+        member, member.modifiers, member.name, member.parameters, undefined)]
+    }
+    if (ts.isPropertyDeclaration(member)) {
+      return [ts.factory.updatePropertyDeclaration(
+        member, member.modifiers, member.name, member.questionToken ?? member.exclamationToken, member.type, undefined)]
+    }
+    return [member]
+  })
+  return ts.factory.updateClassDeclaration(
+    node, node.modifiers, node.name, node.typeParameters, node.heritageClauses, members)
+}
+
+/**
+ * Collect exported interface, type-alias, and body-stripped class shapes; omit
+ * names declared in multiple packages rather than serve the wrong shape.
  */
 function collectTypeDecls(scanRoot: string = root): Map<string, string> {
   const printer = ts.createPrinter({ removeComments: true })
@@ -41,14 +78,16 @@ function collectTypeDecls(scanRoot: string = root): Map<string, string> {
     const abs = resolve(scanRoot, rel)
     const sf = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true)
     for (const stmt of sf.statements) {
-      if (!ts.isInterfaceDeclaration(stmt) && !ts.isTypeAliasDeclaration(stmt)) continue
+      const named = ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isClassDeclaration(stmt)
+      if (!named || stmt.name === undefined) continue
       if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) continue
       const name = stmt.name.text
       if (decls.has(name)) {
         ambiguous.add(name)
         continue
       }
-      const printed = printer.printNode(ts.EmitHint.Unspecified, stmt, sf).replace(/\r/g, '')
+      const emit = ts.isClassDeclaration(stmt) ? classShape(stmt) : stmt
+      const printed = printer.printNode(ts.EmitHint.Unspecified, emit, sf).replace(/\r/g, '')
       decls.set(name, printed.length > MAX_DECL_CHARS
         ? `${printed.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */`
         : printed)
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 40f1a22377..a3274a83c3 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -35,6 +35,8 @@ export const LINK_MAP: Record<string, string> = {
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
+  AgentMessage: 'core.md',
+  AgentMessageId: 'core.md',
   HookContext: 'core.md',
   LlmCallConfig: 'core.md',
   LlmModelContext: 'core.md',
@@ -52,6 +54,7 @@ export const LINK_MAP: Record<string, string> = {
   SessionEvent: 'core.md',
   SessionId: 'core.md',
   SessionStartSource: 'core.md',
+  SessionLogSnapshot: 'session-query.md',
   SessionSurfaceSnapshot: 'session-query.md',
   ApprovalOutcome: 'approval.md',
   ApprovalPolicy: 'approval.md',
@@ -94,6 +97,7 @@ export const LINK_MAP: Record<string, string> = {
   CreateSessionOptions: 'persistence.md',
   SessionHeader: 'persistence.md',
   SessionLocation: 'persistence.md',
+  SessionPersistenceSnapshot: 'persistence.md',
   ConfinedArgv: 'sandbox.md',
   SandboxExecutionPolicy: 'sandbox.md',
   SandboxMode: 'sandbox.md',
@@ -120,11 +124,20 @@ export const LINK_MAP: Record<string, string> = {
   TurnTrigger: 'session.md',
   SessionEventReadRequest: 'session-query.md',
   SessionEventRecord: 'session-query.md',
+  SessionEventResultFilter: 'session-query.md',
+  SessionEventSearchDocument: 'session-query.md',
+  SessionEventSearchHit: 'session-query.md',
+  SessionEventSearchRequest: 'session-query.md',
   SessionEventTrace: 'session-query.md',
   SessionEventTraceRequest: 'session-query.md',
   SessionEventWindow: 'session-query.md',
   SessionLineageTrace: 'session-query.md',
   SessionRecord: 'session-query.md',
+  SessionResultFilter: 'session-query.md',
+  SessionSearchExecContext: 'session-query.md',
+  SessionSearchHit: 'session-query.md',
+  SessionSearchPage: 'session-query.md',
+  SessionSearchRequest: 'session-query.md',
   SessionTitleProvider: 'session-title.md',
   SessionTitleSnapshot: 'session-title.md',
   SkillDefinition: 'skills.md',
@@ -198,6 +211,8 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   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',
+  TuiOverlayRequest: 'service-local extension contract is owned by packages/ui/tui/README.md',
+  TuiOverlaySession: 'service-local extension contract is owned by packages/ui/tui/README.md',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/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',
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index c93f70cf81..1f54f7358f 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -112,7 +112,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session',
     title: 'In-memory session store',
     mode: 'core',
-    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'subagent-inprocess'],
+    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.',
   },
   {
@@ -129,16 +129,17 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Durable session persistence seam',
     mode: 'seam',
     implementations: ['session-persistence-jsonl', 'session-persistence-sqlite'],
-    consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'acp', 'session-query'],
+    consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'acp', 'session-query', 'session-query-sqlite'],
     note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
   },
   {
     key: 'sessionQuery',
     pkg: 'session-query',
-    title: 'Exact session-history reads and traces',
+    title: 'Session reads, traces, filters, and search',
     mode: 'seam',
+    implementations: ['session-query-sqlite'],
     consumers: ['session-reference'],
-    note: 'Resolves live and optional persisted logs into one logical corpus for exact reads and relationship traces.',
+    note: 'The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations on the same service.',
   },
   {
     key: 'sessionReferences',
@@ -197,6 +198,13 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['tui', 'acp'],
     note: 'Plugins register direct human commands; TUI and ACP consume the same effective per-agent catalog without sending invocations to the model.',
   },
+  {
+    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',
@@ -910,8 +918,8 @@ function renderLifecycle(): string {
     '  participant Session',
     '  participant Persistence',
     '  participant SDK as UI or SDK listener',
-    '  User->>Agent: send(content)',
-    `  Agent-->>SDK: ${mermaidCode('agent/queued')}`,
+    '  User->>Agent: followup(content)',
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/enqueue')}`,
     '  Agent->>Driver: queued work wakes driver',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
     `  Driver->>Session: ${mermaidCode('turn/start')}`,
@@ -971,7 +979,7 @@ function renderToolPipeline(): string {
   const maintenance = 'curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs'
   return [
     ...generatedHeader('Tool Execution Pipeline'),
-    'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering fit without changing the loop. The transformable extension points are the `tools/pre-execute`, `tools/execute`, and `tools/post-execute` waterfalls; monotonic guards and `tools/result` are the owner-enforced boundaries around them.',
+    'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering fit without changing the loop. The transformable extension points are the `tools/pre-execute`, `tools/execute`, and `tools/post-execute` waterfalls; monotonic guards, definition-owned `finalizeContent`, and `tools/result` are the owner-enforced boundaries around them.',
     '',
     '```mermaid',
     'flowchart TD',
@@ -987,8 +995,10 @@ function renderToolPipeline(): string {
     `  fsGate["${mermaidCode('fs/write-intent')} or ${mermaidCode('fs/edit-intent')}<br/>tool-fs mutations only"]`,
     `  owned["Tool-owned session events<br/>${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}, ${mermaidCode('tool/code-dispatch')}"]`,
     `  post["${mermaidCode('tools/post-execute')} 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["${mermaidCode('tools/result')} synchronous notification<br/>frozen authoritative outcome"]`,
-    '  context["Active-batch additionalContexts FIFO<br/>context/message after recorded tool results"]',
+    '  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]',
     `  toolResult["Session event: ${mermaidCode('tool/result')}<br/>single model-facing outcome"]`,
     '  allResults["Tool batch settled<br/>recorded tool/result events complete"]',
     '  presentResult["UI completed card<br/>presentResult(args, result)"]',
@@ -998,25 +1008,32 @@ function renderToolPipeline(): string {
     '  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',
-    '  post --> final',
+    '  around -.->|wrapper throws| normalized',
+    '  post -.->|throw| normalized',
+    '  post --> finalize',
+    '  normalized --> finalize',
+    '  finalize --> final',
     '  final --> toolResult',
     '  toolResult --> presentResult',
     '  toolResult --> allResults',
     '  allResults --> context',
     '```',
     '',
-    'Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`, while `tools/result` observes the immutable outcome after transforms, lossless-JSON validation, and outer error normalization. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.',
+    'Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition\'s snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.',
     '',
     ...maintenanceFooter(maintenance),
   ].join('\n')
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index cc85d48ba5..0ddfff5aa6 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -263,7 +263,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-goal',
     source: 'packages/goal/tool-goal/src/index.ts',
     requires: ['ctx.tools', 'ctx.agents', 'ctx.goals', 'ctx.systemPrompt', 'a calling Agent in an authorized open turn'],
-    writes: ['tool/call', 'context/message goal snapshot for mutations', 'tool/result'],
+    writes: ['tool/call', 'user/message goal snapshot for mutations', 'tool/result'],
     async mount(ctx) {
       await ctx.plugin(AgentRegistry)
       await ctx.plugin(GoalService)
@@ -336,7 +336,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-tasks',
     source: 'packages/tasks/tool-tasks/src/index.ts',
     requires: ['ctx.tools', 'ctx.tasks', 'ctx.systemPrompt'],
-    writes: ['tool/call', 'tool/result', 'context/message via agent.inject() for background completion notices'],
+    writes: ['tool/call', 'tool/result', 'user/message via agent.inject() for background completion notices'],
     async mount(ctx) {
       await ctx.plugin(TaskService)
       await ctx.plugin(ToolTasks)
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 7d1c3c1550..e6cc11ae6e 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -172,13 +172,13 @@ describe('rewriteMarkdown', () => {
 })
 
 describe('docsPages locale routes', () => {
-  it('publishes every route in both locales and selects paired user sources', () => {
+  it('publishes every route in both locales and selects paired sources', () => {
     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}`)
       expect(counterpart, page.route).toBeDefined()
       expect(counterpart?.locale).toBe('en')
-      if (page.source.startsWith('docs/user/')) {
+      if (page.contentLocale === 'zh-CN') {
         expect(page.source).toMatch(/\.zh\.md$/)
         expect(page.contentLocale).toBe('zh-CN')
         expect(counterpart?.source).toBe(page.source.replace(/\.zh\.md$/, '.md'))
@@ -190,6 +190,22 @@ 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/')
+    ))
+    const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
+    const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
+
+    expect(translated).toHaveLength(18)
+    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',
+    ])
+  })
+
   it('publishes the Cordis core API under matching locale structures', () => {
     const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md']
     for (const file of files) {
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 896ffacfd1..91e70f7b1b 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -317,14 +317,8 @@ function ciWindowsCompleteGates(): Gate[] {
 function ciWindowsObservationalGates(): Gate[] {
   return [
     ...ciStaticGates(),
-    lintGate(),
+    // Linux owns required lint, coverage, and snapshots; Windows omits those duplicates.
     pnpmScript('duplication', 'duplication'),
-    {
-      ...coverageGate(),
-      env: { DSH_EXAMPLE_MODE: 'lib' },
-      needs: ['build'],
-    },
-    snapshotGate(),
     pnpmScript('publint', 'publint', { needs: ['build'] }),
     pnpmScript('node-next-types', 'verify-node-next-types', {
       label: 'node-next types',
@@ -385,9 +379,9 @@ function coverageGate(): Gate {
   })
 }
 
-// The snapshot suite boots the example bins in `lib` mode (built artifact under plain Node,
-// plugins via real exports) — CI and check-all already build, so they exercise what ships rather
-// than the tsx/source path dev uses. It therefore waits on `build`.
+// Example and package snapshots boot their bins in `lib` mode (built artifacts under plain Node,
+// plugins via real exports); repository-script snapshots execute their real source entry path.
+// CI and check-all already build before either class runs, so the suite waits on `build`.
 function snapshotGate(): Gate {
   return pnpmScript('snapshot', 'test:snapshot', {
     env: { DSH_EXAMPLE_MODE: 'lib' },
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
new file mode 100644
index 0000000000..9aa08c3793
--- /dev/null
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -0,0 +1,60 @@
+{
+  "request": {
+    "targetFilename": "snapshot-note.zh.md",
+    "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 given source document from English to Chinese, producing natural, professional technical prose.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains exactly the same structure as the source: heading hierarchy, list shape, table columns, link targets, and code blocks.\n- Fenced code blocks must be byte-identical to the source, including ALL comments inside them. Do NOT translate comments inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans (commands, flags, paths, API names, version numbers) must be kept verbatim. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Link text is translated; link targets are not.\n- Language switcher line: when translating into Chinese, write `[English](source-filename.md) | 中文`. When translating into English, write `English | [中文](source-filename.zh.md)`. Do NOT copy the switcher line from the source file unchanged — you must flip the link direction.\n- After a closing bold marker `**`, insert a space before the next character when that character is a Latin letter, digit, or CJK ideograph. Never insert a space before any punctuation (full-width or half-width).\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native speaker. 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- Use polite imperative forms where the text instructs the reader to do something.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences with commas or semicolons. Avoid run-on sentences.\n- Prefer active voice. Convert passive constructions to active if it reads more naturally.\n- Translate meaning, not words. Restructure sentences where the target language grammar requires it.\n- Do not invent words or expressions that do not exist in natural technical writing of the target language.\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- 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 two different source-language terms that carry distinct meanings.\n- Avoid repeating the same verb in close proximity; vary word choice for readability.\n\n#### When translating into Chinese\n- When a number modifies a noun, always include a Chinese classifier or measure word (量词). For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\".\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in prose: `，。：；？！（）「」`.\n- Strongly prefer replacing all em-dashes (——) with colons, periods, commas, or parentheses. Keep an em-dash only if no other punctuation works at all.\n- Use enumeration commas (、) between parallel items, not regular commas.\n- List item endings: use semicolons or no punctuation. Do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words/numbers.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以) and keep the SOURCE emphasis marker: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n(To be added.)\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 first occurrence, write the \"首次出现\" value with its parenthetical gloss; on subsequent occurrences, write only the part before the parentheses.\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- For technical terms not in the table, follow the target language: for a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source, or keep the source term and flag it as pending when no such precedent exists; for an English target, use the established English technical term, or preserve an ambiguous source term with a short English gloss and flag it as pending. Do not invent a translation. 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 | Agent Note（agent 决策记录） | 智能体注记、智能体笔记 | 本仓库中由 agent 撰写的提案与决策记录 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| backlog | backlog | backlog（待翻清单） | | 仅在双语翻译语境里括注`待翻清单` |\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| 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| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| thinking | thinking | | | API 字段保留英文；描述模型模式时译为`思考` |\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| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\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| coverage | 覆盖率 | | | |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| enforcement frontier | 执行红线 | | 强制边界 | i18n 配对机制用语：manifest `required` 清单所划的门禁生效范围；与金标样例（style-samples ⑦）一致 |\n| ergonomics | 易用性 / 开发体验 | | 人体工学 | API 或面向模型的接口用「易用性」；工具链或开发者工作流用「开发体验」 |\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| 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| memory | 记忆 / 内存 | | | 与 `agent` 搭配时译为`记忆`（如 `agent memory` →`智能体记忆`）；指系统资源时译为`内存` |\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 | 包 | 包（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| 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| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | | |\n| spine | 主干 | | | |\n| staged | 暂存 | | | 沿用 git 官方中文翻译 |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| streaming | 流式输出 | | | |\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\nProduce your output in three XML sections:\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(Complete translation of the source document)\n</translation>\n\n<review>\n(Self-review notes, one correction per line with category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- 无修正\n</review>\n\n<final>\n(Final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, re-read it in the target language only, without looking at the source. Check by category:\n\n**Structure**\n- Is the heading hierarchy, list shape, and code block content identical to the source?\n- Are ALL comments inside code blocks left untranslated (byte-identical to source)?\n- Is the language switcher line correctly flipped (not copied from source)?\n- Are link targets preserved, and are spaces after bold markers present only before Latin letters, digits, or CJK ideographs?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native speaker?\n- Is there any colloquial, casual, or overly informal phrasing?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that should be converted to active voice?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Is the same target-language word used to translate two distinct source concepts?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied (not missing, not repeated)? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- For unlisted terms, does a Chinese target use established Chinese precedent or retain the source term as pending, and does an English target use established English terminology or preserve only an ambiguous source term with a short English gloss?\n\n**Punctuation** (when target is Chinese)\n- Are there em-dashes that should be replaced with colons, periods, or commas?\n- Are list items ending with commas instead of semicolons?\n- Do RFC 2119 keywords preserve the source emphasis exactly?\n\nRecord corrections in `<review>` with category tags. Then output the corrected version in `<final>`. If no corrections are needed, write \"无修正\" in `<review>` and copy the translation unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions.\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",
+        "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## Install\n\nInstall `dsh` with one command:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key.\n\nThe installer clones DeepSeek Harness to `~/.dsh/source`, links `dsh` into `~/.local/bin`, and launches it. Re-running the command updates the checkout. See [`scripts/install.sh`](scripts/install.sh) for alternate install locations and other options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, build the frontend after installation and after each update, then start the Web UI:\n\n```sh\npnpm --dir ~/.dsh/source run build && pnpm --dir ~/.dsh/source run build:web\ndsh web\n```\n\nThe Web UI is served at `http://127.0.0.1:3080` by default.\n\n### TUI\n\nStart the full-screen terminal interface:\n\n```sh\ndsh\n```\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh -p \"summarize this workspace\"\n```\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell execution; reusable skills; task tracking; subagents and workflows; persistent sessions; and context compaction. The TUI also 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- **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\n```sh\npnpm install\npnpm run test:coverage\n```\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 pre-release.\n\n## License\n\n[BSD 3-Clause](LICENSE)\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\n使用一条命令安装 `dsh`：\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥。\n\n安装器会将 DeepSeek Harness 克隆到 `~/.dsh/source`，把 `dsh` 链接到 `~/.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\npnpm --dir ~/.dsh/source run build && pnpm --dir ~/.dsh/source run build:web\ndsh web\n```\n\nWeb UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### TUI\n\n启动全屏终端界面：\n\n```sh\ndsh\n```\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh -p \"summarize this workspace\"\n```\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 执行、可复用 skill（技能）、任务跟踪、subagent 与工作流、持久化会话，以及上下文压缩（context compaction）。TUI 还包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\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```sh\npnpm install\npnpm run test:coverage\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"
+      },
+      {
+        "role": "user",
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThis onboarding guide helps project contributors get started with the local environment, daily workflow, and CI flow; see the Agent Notes for design rationale and technical trade-offs.\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.\n- Optional: a DeepSeek API key for the TUI/Headless/ACP agent 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 runs the root `postinstall` script, which installs lefthook from the repo dev dependency through `scripts/install-lefthook.mjs`; the wrapper script uses lefthook's reviewed `--force` mode so linked worktrees with an existing `core.hooksPath` do not fail normal `pnpm run …` commands.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\npnpm exec lefthook install --force\n```\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nThat first typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through the two no-emit aggregates described below.\n\n## TypeScript project layout\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` runs staged-file ESLint fixes, 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\nUse these from the repo root:\n\n```sh\npnpm run test           # unit tests\npnpm run test:coverage  # unit tests with per-file coverage gates\npnpm run test:e2e       # real-API tests; self-skips without DEEPSEEK_API_KEY\npnpm run check:all      # comprehensive opt-in gate set; not wired to Git hooks\npnpm run typecheck      # tsc -b over the root solution: emits package/vendor lib/types, checks both aggregates\npnpm run lint           # eslint .\npnpm run lint:fix       # eslint . --fix\npnpm run doc-typecheck  # compile checked TypeScript snippets in Markdown docs\npnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events.md + services.md from source\npnpm run verify-cordis-catalog  # fail if either cordis catalog is stale\npnpm run verify-export-jsdoc    # fail if a module-level package export lacks complete JSDoc\npnpm run gen-doc-graphs     # regenerate generated relationship docs from source and curated graph definitions\npnpm run verify-doc-graphs  # fail if generated relationship docs are stale\npnpm run verify-md-wrap  # fail on hard-wrapped prose paragraphs in docs/README markdown\npnpm run verify-mermaid  # fail if a ```mermaid diagram has invalid Mermaid syntax\npnpm run verify-type-equiv  # fail if a ```ts type-equiv doc block drifts from its source type\npnpm run verify-doc-budgets  # fail if a budgeted standing doc exceeds its word ceiling\npnpm run doc-sync       # all Markdown/doc gates, scheduled concurrently; the doc-sync leaf list in scripts/run-gates.ts is the full list\npnpm run gen-module-graph     # regenerate docs/module-graph.md from package peerDeps\npnpm run verify-module-graph  # fail if docs/module-graph.md is stale\npnpm run build          # emit lib/types intermediates, then bundle lib/index.* runtime files\npnpm run verify-node-next-types  # fail if built declarations are not NodeNext-consumable\npnpm run hygiene        # knip, publint, workspace constraints, and NodeNext declaration check\n```\n\nWhen changing package public behavior, update the relevant README or JSDoc in the same change. `pnpm run doc-sync` catches checked TypeScript snippets, generated doc freshness, markdown wrap/link drift, type equivalence, translation pairing, Mermaid syntax, and doc budgets, but broader prose/API sync still needs review.\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 full-screen interactive coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:tui\n```\n\nThe self-referential cordis-agent demo can inspect and modify its live plugin runtime and needs the same credentials:\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP server agent demo exposes the agent 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 also enforces a 1:1 correspondence by document, symbol, and projection, so a block can't go silently unchecked and a stale entry can't linger. `doc-typecheck` skips both fence kinds (they aren't standalone-compilable) and excludes them from its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a block, update the manifest in the same change.\n\n## Architecture context\n\nRead `docs/architecture.md` before changing anything under `packages/`. The codebase is built around Cordis plugins, event-sourced sessions, typed service seams, and explicit extension points.\n"
+      },
+      {
+        "role": "assistant",
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建、日常工作流与 CI 流程；设计动机与技术权衡请查阅相应 Agent Note。\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。\n- 可选：一个 DeepSeek API key，用于 TUI/Headless/ACP（Agent Client Protocol） agent（智能体）演示和真实 API 的 e2e 测试。\n\n## 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程同时会运行根目录的 `postinstall` 脚本，该脚本通过 `scripts/install-lefthook.mjs` 从仓库 dev 依赖安装 lefthook。包装脚本使用 lefthook 经过评审的 `--force` 模式，确保已存在 `core.hooksPath` 的关联 worktree 不会导致正常的 `pnpm run …` 命令失败。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\npnpm exec lefthook install --force\n```\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n首次类型检查会执行全仓 `tsc -b tsconfig.json` 图：发射每个 package/vendor 的 `lib/types`，并通过下述两个 no-emit 聚合检查示例、测试和脚本。\n\n## TypeScript 项目布局\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 修复，检查暂存 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在仓库根目录使用：\n\n```sh\npnpm run test           # unit tests\npnpm run test:coverage  # unit tests with per-file coverage gates\npnpm run test:e2e       # real-API tests; self-skips without DEEPSEEK_API_KEY\npnpm run check:all      # comprehensive opt-in gate set; not wired to Git hooks\npnpm run typecheck      # tsc -b over the root solution: emits package/vendor lib/types, checks both aggregates\npnpm run lint           # eslint .\npnpm run lint:fix       # eslint . --fix\npnpm run doc-typecheck  # compile checked TypeScript snippets in Markdown docs\npnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events.md + services.md from source\npnpm run verify-cordis-catalog  # fail if either cordis catalog is stale\npnpm run verify-export-jsdoc    # fail if a module-level package export lacks complete JSDoc\npnpm run gen-doc-graphs     # regenerate generated relationship docs from source and curated graph definitions\npnpm run verify-doc-graphs  # fail if generated relationship docs are stale\npnpm run verify-md-wrap  # fail on hard-wrapped prose paragraphs in docs/README markdown\npnpm run verify-mermaid  # fail if a ```mermaid diagram has invalid Mermaid syntax\npnpm run verify-type-equiv  # fail if a ```ts type-equiv doc block drifts from its source type\npnpm run verify-doc-budgets  # fail if a budgeted standing doc exceeds its word ceiling\npnpm run doc-sync       # all Markdown/doc gates, scheduled concurrently; the doc-sync leaf list in scripts/run-gates.ts is the full list\npnpm run gen-module-graph     # regenerate docs/module-graph.md from package peerDeps\npnpm run verify-module-graph  # fail if docs/module-graph.md is stale\npnpm run build          # emit lib/types intermediates, then bundle lib/index.* runtime files\npnpm run verify-node-next-types  # fail if built declarations are not NodeNext-consumable\npnpm run hygiene        # knip, publint, workspace constraints, and NodeNext declaration check\n```\n\n修改 package 的公开行为时，请在同一个变更中更新相关 README 或 JSDoc。`pnpm run doc-sync` 能检测到被检查的 TypeScript 片段、生成文档的新鲜度、Markdown 换行/链接漂移、type-equiv、翻译配对、Mermaid 语法和文档预算，但更广泛的行文/API 同步仍需评审把关。\n\n## 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n全屏交互式 coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:tui\n```\n\n自指的 cordis-agent 演示可以检查并修改其实时插件运行时，并需要相同的凭证：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 服务器 agent 演示通过 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（包括成员文档），让读者同时看到源码契约和确切形状。该门禁还按文档、符号和投影强制 1:1 对应，因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过两种围栏（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个块时，请在同一个变更里更新 manifest。\n\n## 架构上下文\n\n在修改 `packages/` 目录下的任何内容之前，请先阅读 `docs/architecture.md`。这套代码围绕 Cordis 插件、事件溯源的会话、类型化的服务 seam 与显式扩展点构建。\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 the README, Agent Notes, and docs tree are maintained in English and Simplified Chinese. This page defines the pairing contract, the enforcement gate, and the rollout policy; [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. The recorded hash also recovers the exact last-confirmed text of either side (`git cat-file -p <hash>`), so an out-of-sync pair is updated by diffing the edited side against its last-confirmed state and patching the counterpart minimally — never by re-translating whole files. After bringing the pair back in line, `pnpm run verify-translation-pairing --write` re-records both hashes; that yaml diff is the reviewable act of confirming consistency.\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 file listed as `required` in [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) has a complete pair.\n2. Every pair that exists at all — required or not — 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.\n4. Every date-named document (`yyyy-mm-dd-*.md`) dated on or after the manifest's `requiredSince` cutoff has a complete pair — new date-named Agent Notes merge bilingual from birth.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok — and is the work list for translation batches. It never fails; it reports.\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`), 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, exclusions, and rollout\n\n**Scope**: the root `README.md`, everything under `.agents/notes/**`, `docs/**`, and `python/**`. Package READMEs (`packages/**`) join the scope in a later batch.\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; their generators emit English only today, so a hand-written translation would go stale on every regeneration. The planned follow-up is to teach the generators to emit Chinese alongside English, at which point these leave the exclusion list.\n- `docs/AGENTS.md` and `.agents/notes/**/AGENTS.md` — 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\n**Rollout**: a date-named document (`yyyy-mm-dd-*.md`, i.e. an Agent Note) dated on or after the manifest's `requiredSince` cutoff must merge with its pair. Earlier dates are backlog, including files created on the cutoff's eve. An Agent Note filename records its first-proposed date, so backdating past the cutoff is a review-visible violation. The manifest's `required` list is the current enforcement frontier, not the goal of full coverage. Translation batches add paths to `required`, ratcheting the gate forward. Unlisted documents remain visible in `--list`, while every existing pair is governed by the full contract. Because later edits must update both sides, expand `required` only as fast as translation review can support.\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（智能体）阅读，因此 README、Agent Note（agent 决策记录）与 docs 目录树以英文和简体中文双语维护。本页定义配对契约、强制门禁与推进策略；[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`），一致性是纯内容比较。记录的 hash 还能还原任一侧上次确认时的确切文本（`git cat-file -p <hash>`），所以失去同步的配对是「把被改的一侧与其上次确认状态做 diff、再最小化地修补另一侧」，从不整篇重译。两侧对齐后，`pnpm run verify-translation-pairing --write` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审。\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. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个文件都有完整配对。\n2. 任何已存在的配对（无论是否 required）都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。\n4. 凡文件名符合 `yyyy-mm-dd-*.md` 且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，都必须有完整配对；新建的日期命名 Agent Note 从创建起便须配齐中英文。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok），是翻译批次的工作清单。它从不失败；它只报告。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围、排除与推进\n\n**范围**：根 `README.md`，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部内容。包（package）README（`packages/**`）在后续批次加入范围。\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`：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n\n**推进**：以日期命名的文档（`yyyy-mm-dd-*.md`，即 Agent Note），只要标注日期等于或晚于 manifest 的 `requiredSince` 分界日期，合并时就必须配齐双语文件。更早日期的文件属于 backlog（待翻清单），包括分界前夜创建的文件。Agent Note 文件名记录首次提出日期，因此倒填日期绕过分界属于评审可见的违规。manifest 中的 `required` 列表是当前执行红线，并非全量覆盖这一最终目标。翻译批次将路径加入 `required`，使门禁只向前收紧。未列入的文档仍可通过 `--list` 查看，而任何已存在的配对都受完整契约约束。后续修改必须同步更新两侧，因此 `required` 的扩展速度不能超过翻译评审的承载能力。\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",
+        "content": "# Translation rules\n\nEnglish | [中文](translation-rules.zh.md)\n\nHow to translate between the two sides of a documentation pair in this repo. Both languages carry equal authority ([README.md](README.md)): a change is authored in either language, and that side is the source for that update — these rules govern producing or updating the counterpart. They bind humans and agents equally; the committed agent workflow that applies them is [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md). Rule levels follow RFC 2119 usage: **MUST** / **MUST NOT** are gate- or review-blocking; **SHOULD** needs a stated reason to deviate; **MAY** is discretionary.\n\n## Faithfulness\n\n- The counterpart *MUST* say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.\n- The counterpart *SHOULD* read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.\n- Do not translate the untranslatable: if a sentence resists natural rendering because it leans on an idiom of the source language, translate the idea, not the idiom.\n\n## Voice\n\n- The register is calibrated by [style-samples.md](style-samples.md) — human-approved gold pairs, one per document genre. The counterpart MUST match the target-language side of the nearest sample; where its voice and a prose voice rule disagree, the sample wins. Chinese targets use institutional technical Chinese; English targets use concise professional developer prose.\n- Write as a native technical author restating the content, not as a translator transposing sentences. Then verify against the source clause by clause: nothing added, nothing dropped — fluency never justifies losing a clause.\n- Give sentences an explicit actor when the target language would otherwise obscure it; for Chinese, replace vague passives or abstract subjects with the actual actor (系统、门禁、评审人).\n- Prefer established target-language engineering idiom over calques (误报／漏检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack noun chains where the target language requires it.\n- Split long paragraphs by semantic unit — one idea per paragraph. Paragraph boundaries MAY differ from the source; the structural signature does not count paragraphs.\n- When translating into Chinese, category nouns use Chinese with a first-mention English annotation (实操手册（cookbook）); when translating into English, use the conventional English category name. Literal directory or file references stay code-formatted English.\n\n## Structure preservation\n\nThe pairing gate checks heading depths, fenced code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:\n\n- heading hierarchy (same levels, same order — heading TEXT is translated),\n- list shape and numbering,\n- tables (same columns, same row order; header cells translated per terminology),\n- fenced code blocks — **byte-identical, including comments**; the pairing signature compares their info strings and contents, and ` ```ts ` blocks compile under `doc-typecheck`,\n- inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,\n- links and anchors: every relative link MUST point at the same target in both files — by convention the `.md` path, not the `.zh.md` sibling — so links never dangle when one pair lands before its neighbors. The ONLY zh-specific link is the language switcher. Link TEXT is translated; the target is not.\n\nThe repo's Markdown conventions apply to `.zh.md` files unchanged: one physical line per paragraph (`verify-md-wrap`), resolving relative links (`verify-md-links`), exactly one trailing newline.\n\n## Terminology\n\n- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; every listed term MUST follow its row and its \"不要译作\" prohibitions. A Chinese target uses the \"中文\" column and its \"首次出现\" annotation; an English target uses the \"English\" column without adding a Chinese gloss.\n- For a Chinese target, an unlisted technical term MAY use an established rendering from a major Chinese-language OSS or vendor source (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs), cited in the PR. Without such precedent it MUST stay in English and be listed under 「待定术语」(pending terms) with a suggested rendering.\n- For an English target, use the established English technical term. If the source term has no unambiguous established equivalent, preserve it with a short explanatory gloss and list it under pending terms. Neither direction may invent a rendering inline; a decided term enters [terminology.md](terminology.md) in the same PR or a follow-up.\n\n## Typography\n\nThese rules govern the Chinese side; the English side follows the repo's normal Markdown conventions (root `AGENTS.md`). The mixed-script rules below follow the cross-project consensus of the [MDN Simplified Chinese translation guide](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md), the [Kubernetes zh-cn localization guide](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/), the [Vue.js Chinese translation conventions](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5), and [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines), which in turn ground in [W3C clreq](https://www.w3.org/TR/clreq/) and GB/T 15834—2011:\n\n- MUST put one half-width space between Chinese text and Latin words, and between Chinese text and numerals: `每个 plugin 注册 3 个 tool`。No space between a full-width punctuation mark and anything.\n- MUST use full-width (Chinese) punctuation in Chinese prose: `，。：；？！（）「」`. Half-width punctuation stays inside code spans, inside complete English sentences quoted as-is, and in numbers (`3.5`, `1,024`).\n- Chinese prose *SHOULD* prefer colons, periods, commas, or parentheses over em dashes. Keep an em dash only when no other punctuation preserves the sentence naturally.\n- Enumeration commas: a Chinese list of parallel items uses 顿号（、）, not commas.\n- MUST NOT use full-width digits or full-width Latin letters — `１２３` never, `123` always.\n- Proper nouns keep their canonical casing: GitHub, TypeScript, DeepSeek — never `github`/`Github` unless quoting code.\n- Second person is 你, not 您 (matches the Vue and Kubernetes Chinese conventions and this repo's direct voice).\n- Emphasis markers (`**bold**`, `*italic*`) stay on the same spans as the source; Chinese has no italics, so the rendered emphasis may look identical — do not substitute quotation marks or other decoration.\n\n## Quality bar\n\n- A pair is done when a bilingual engineer reading either file alone gets everything a reader of the other gets — same facts, same caveats, same tone — and nothing extra.\n- Before handing off, self-check the result against this file and re-read the counterpart ALONE, without the source side by side; awkward phrasing is easier to hear without the source anchoring you.\n- Run `pnpm run verify-translation-pairing` and the rest of `doc-sync` for records, switchers, heading depths, code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, links, and repository Markdown rules. Manually verify list and table order, noncanonical list numbering, inline code, emphasis, meaning, terminology, and tone.\n\n## References\n\nAuthorities cited by these rules, for humans and agents who want the underlying reasoning:\n\n- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines) — the de-facto community standard for mixed CJK/Latin spacing and punctuation.\n- [MDN zh-CN translation guide](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md) — an in-repo translation-rules file of the same shape as this one; spacing, punctuation, and glossary practice.\n- [Kubernetes zh-cn localization guide](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/) — terminology-first-occurrence and punctuation practice from the largest zh localization team.\n- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) — per-term translate/keep decisions and tone.\n- [zh-style-guide](https://zh-style-guide.readthedocs.io) — a community Chinese technical-writing style guide whose rule-level taxonomy (and RFC 2119 keyword levels) this file borrows; aggregates GB/T 15834/15835, clreq, and vendor guides.\n- [W3C clreq](https://www.w3.org/TR/clreq/) and the [Microsoft Simplified Chinese style guide](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides) — the formal typographic and vendor-localization baselines.\n- GB/T 19682-2005《翻译服务译文质量要求》 — the national standard whose three base requirements (忠实原文、术语统一、行文通顺) this file's Faithfulness and Terminology sections operationalize.\n"
+      },
+      {
+        "role": "assistant",
+        "content": "# 翻译规则\n\n[English](translation-rules.md) | 中文\n\n本文规定：如何在本仓库文档配对的中英文两种语言之间进行翻译。两种语言同权（见 [README.md](README.md)）：每次变更可以用任一语言撰写，被编辑的一侧即为本次更新的源；本文的规则约束如何产出或更新对侧文件。这些规则对人类和 agent（智能体）同等生效；应用这些规则的仓库内置 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）** ／ **禁止（MUST NOT）** 会卡门禁或评审；**应当（SHOULD）** 偏离时要说明理由；**可以（MAY）** 自行裁量。\n\n## 忠实性\n\n- 对侧文件*必须*传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。\n- 对侧文件读起来*应当*是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。\n- 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。\n\n## 行文\n\n- 语体以 [style-samples.md](style-samples.md) 为校准锚点。人工定稿的金标样例按文体各一组，译文必须参照文体最接近的样例，采用其中目标语言一侧的语体；如果样例与本文的行文规则冲突，以样例为准。译成中文时，采用规范的技术制度文；译成英文时，采用简洁、专业的开发者文档语体。\n- 以母语技术作者的身份重述内容，而不是逐句转写的译者。写完后逐句对照原文核验：不添加、不遗漏——流畅永远不是丢掉语义成分的理由。\n- 如果直译会让执行主体含糊，请明确写出实际执行者；译成中文时，应由「系统、门禁、评审人」等实际执行者作主语，避免含糊的被动句或抽象主语。\n- 优先采用目标语言中通行的工程表达，避免生硬直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻应自然改写，名词链则按目标语言的习惯拆开。\n- 长段按语义单元拆分，一段一件事。段落边界可以与原文不同；结构签名不比对段落数。\n- 翻译为中文时，类别名词使用中文并在首现括注英文（实操手册（cookbook））；翻译为英文时，使用通行的英文类别名。指目录或文件本身时保留代码体英文。\n\n## 结构保持\n\n配对门禁会检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起始编号、列表项数量与链接目标；门禁未覆盖的结构仍需人工核对。两个配对文件必须在以下方面一一对应：\n\n- 标题层级（相同级别、相同顺序；标题的**文字**要翻译）；\n- 列表形态与编号；\n- 表格（相同的列、相同的行序；表头单元格按术语表翻译）；\n- 围栏代码块：**逐字节一致，包括注释**。配对签名比对信息字符串与内容，` ```ts ` 块还要通过 `doc-typecheck` 编译；\n- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；\n- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 `.md` 路径而非 `.zh.md` 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。\n\n本仓库的 Markdown 约定对 `.zh.md` 文件原样生效：一个段落一个物理行（`verify-md-wrap`）、相对链接必须可解析（`verify-md-links`）、文件末尾恰好一个换行。\n\n## 术语\n\n- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。译成中文时，采用「中文」列，并按「首次出现」列括注；译成英文时，采用「English」列，不加中文括注。\n- 译成中文时，术语表未收录的技术术语只有在主流中文 OSS 文档或厂商资料中已有通行译法时才可以翻译（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档），并须在 PR 中注明出处；否则必须保留英文，并在 PR 描述的「待定术语」中给出建议译法。\n- 译成英文时，采用通行的英文技术术语。如果源术语没有明确的通行对应词，则保留原词、附上简短说明，并列入「待定术语」。两个方向都不得自行创造译法；确定后的术语须在同一个 PR 或后续 PR 中加入 [terminology.md](terminology.md)。\n\n## 排版\n\n本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 `AGENTS.md`）。以下中西文混排规则遵循 [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)、[Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)、[Vue.js 中文翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) 与[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)的跨项目共识，其根据是 [W3C clreq](https://www.w3.org/TR/clreq/) 与 GB/T 15834—2011：\n\n- 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。\n- 中文行文必须使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。\n- 中文行文*应当*优先使用冒号、句号、逗号或括号，尽量不用破折号；只有其他标点都无法自然表达时才保留破折号。\n- 顿号：中文的并列项之间使用顿号（、），而非逗号。\n- 禁止使用全角数字或全角拉丁字母：永远不写 `１２３`，永远写 `123`。\n- 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek。除非引用代码，否则绝不写 `github`／`Github`。\n- 第二人称用「你」，不用「您」（与 Vue、Kubernetes 中文约定及本仓库的直接语气一致）。\n- 强调标记（`**加粗**`、`*斜体*`）落在与对侧相同的文字段上。中文没有斜体，渲染效果可能看不出差别，不要用引号或其他装饰替代。\n\n## 质量标准\n\n- 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。\n- 交付前，请对照本文自查一遍，并**单独通读对侧文件**，不与源侧对照；不对照原文时，更容易察觉别扭的表达。\n- 请运行 `pnpm run verify-translation-pairing` 与 `doc-sync` 的其余门禁。这些门禁会检查一致性记录、切换行、标题深度、代码块、表格行列数、列表类型、有序列表起始编号、列表项数量、链接及仓库 Markdown 规则；列表与表格的顺序、非常规列表编号、行内代码、强调标记、语义、术语和语体仍需人工核对。\n\n## 参考资料\n\n本文各规则引用的权威出处，供想了解底层依据的人和 agent 查阅：\n\n- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)：中西文混排空格与标点的社区事实标准。\n- [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)：与本文同形态的仓库内置翻译规则文件；空格、标点与术语表实践。\n- [Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)：最大的中文本地化团队的术语首现与标点实践。\n- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)：逐术语的译／留决策与语气。\n- [zh-style-guide](https://zh-style-guide.readthedocs.io)：社区中文技术文档写作规范，本文借用了它的规则级别分类体系（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。\n- [W3C clreq](https://www.w3.org/TR/clreq/) 与[微软简体中文风格指南](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides)：排版学与厂商本地化的正式基线。\n- GB/T 19682-2005《翻译服务译文质量要求》：国家标准；本文「忠实性」与「术语」两节将其三项基本要求（忠实原文、术语统一、行文通顺）落实为可操作的规则。\n"
+      },
+      {
+        "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 README and docs tree are 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](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`) 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: required pairs exist, every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical), excluded (generated or bilingual-by-construction) files stay unpaired, and date-named documents on or after the manifest's `requiredSince` cutoff have complete pairs. The `required` list in [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) is a ratchet: each merged translation batch adds its files, so coverage only grows.\n- **The enforcement frontier advances in coherent review batches.** A related set enters `required` only when reviewers can evaluate it as a unit. The core frontier groups [architecture](../../../../docs/architecture.md), the [Cordis primer](../../../../docs/cordis-primer.md), [defensive patterns](../../../../docs/defensive-patterns.md), the [glossary](../../../../docs/glossary.md), and [testing](../../../../docs/testing.md) because their terminology, links, and contributor contracts inform one another; admitting only part would leave the enforced corpus internally inconsistent. 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- Rollout is incremental by design: documents outside `required` are visible backlog (`--list`), not red CI, so pairs land in reviewable batches without a big-bang PR. A date-named document dated on or after the manifest's `requiredSince` cutoff merges bilingual or not at all, so new date-named Agent Notes do not enlarge that backlog.\n- The recorded hashes double as the update tool (`git cat-file -p <hash>` recovers either side's last-confirmed text for a minimal diff-based update), 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本仓库的 README 与 docs 目录树会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](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`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）不得配对；凡文件名以日期开头且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，也必须有完整配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。\n- **执行红线按连贯的评审批次推进。** 一组相关文档只有在评审者能够将其作为整体评估时，才进入 `required`。核心红线将[架构](../../../../docs/architecture.md)、[Cordis 入门](../../../../docs/cordis-primer.md)、[防御性模式](../../../../docs/defensive-patterns.md)、[术语表](../../../../docs/glossary.md)和[测试](../../../../docs/testing.md)归为一组，因为它们的术语、链接和贡献者契约相互关联；只纳入其中一部分会使受门禁约束的文档集合内部不一致。发布到文档站的配对使用 `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- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（待翻清单，`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。凡文件名以日期开头且日期不早于 manifest 中 `requiredSince` 分界日期的文档，都必须配齐双语文件，因此新建的日期命名 Agent Note 不会增加这份 backlog。\n- 记录的 hash 兼作更新工具（`git cat-file -p <hash>` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），因此这套机制从不强迫整篇重译。\n"
+      },
+      {
+        "role": "user",
+        "content": "---\nlayout: doc\n---\n\n# Snapshot note\n\nThe agent performs one step.\n"
+      }
+    ]
+  },
+  "response": {
+    "translation": "---\nlayout: doc\n---\n\n# 快照说明\n\nagent（智能体）执行一个步骤。",
+    "review": "- 无修正",
+    "final": "---\nlayout: doc\n---\n\n# 快照说明\n\n[English](snapshot-note.md) | 中文\n\nagent（智能体）执行一个步骤。\n"
+  }
+}
diff --git a/scripts/translation-pairing.manifest.json b/scripts/translation-pairing.manifest.json
index b96b92c7a8..a6503ce282 100644
--- a/scripts/translation-pairing.manifest.json
+++ b/scripts/translation-pairing.manifest.json
@@ -1,23 +1,201 @@
 {
   "requiredSince": "2026-07-14",
   "required": [
+    ".agents/notes/README.md",
+    ".agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.md",
+    ".agents/notes/implemented/architecture/2026-06-11-custom-schema-dsl.md",
+    ".agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md",
+    ".agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md",
+    ".agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md",
+    ".agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md",
+    ".agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md",
+    ".agents/notes/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.md",
+    ".agents/notes/implemented/architecture/2026-06-13-capability-seams.md",
+    ".agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md",
+    ".agents/notes/implemented/architecture/2026-06-14-session-persistence.md",
+    ".agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md",
+    ".agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md",
+    ".agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md",
+    ".agents/notes/implemented/architecture/2026-06-18-session-surface.md",
+    ".agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md",
+    ".agents/notes/implemented/architecture/2026-06-20-branded-ids.md",
+    ".agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md",
+    ".agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md",
+    ".agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md",
+    ".agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md",
+    ".agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md",
+    ".agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md",
+    ".agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md",
+    ".agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md",
+    ".agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md",
+    ".agents/notes/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md",
+    ".agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md",
+    ".agents/notes/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md",
+    ".agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md",
+    ".agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md",
+    ".agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md",
+    ".agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md",
+    ".agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md",
+    ".agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md",
     ".agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md",
+    ".agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md",
     ".agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md",
     ".agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md",
     ".agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md",
     ".agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md",
+    ".agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md",
+    ".agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.md",
+    ".agents/notes/implemented/feature/2026-06-14-acp-multi-session.md",
+    ".agents/notes/implemented/feature/2026-06-15-code-mode.md",
+    ".agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md",
+    ".agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md",
+    ".agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md",
+    ".agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md",
+    ".agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md",
+    ".agents/notes/implemented/feature/2026-06-25-ask-user-question.md",
+    ".agents/notes/implemented/feature/2026-06-29-todo-write-tool.md",
+    ".agents/notes/implemented/feature/2026-06-30-hook-bridges.md",
+    ".agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md",
+    ".agents/notes/implemented/feature/2026-06-30-interception-seams.md",
+    ".agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md",
+    ".agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.md",
+    ".agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md",
+    ".agents/notes/implemented/feature/2026-07-05-skill-system.md",
+    ".agents/notes/implemented/feature/2026-07-06-approval-seam.md",
+    ".agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md",
+    ".agents/notes/implemented/feature/2026-07-06-sandbox.md",
+    ".agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.md",
+    ".agents/notes/implemented/feature/2026-07-07-session-prefix.md",
+    ".agents/notes/implemented/feature/2026-07-08-repeat-tool-guard.md",
+    ".agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md",
+    ".agents/notes/implemented/feature/2026-07-10-session-query-service.md",
+    ".agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md",
+    ".agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.md",
+    ".agents/notes/implemented/process/2026-06-11-quality-gates.md",
+    ".agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.md",
+    ".agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.md",
+    ".agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md",
+    ".agents/notes/implemented/process/2026-06-17-ts-build-config.md",
+    ".agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md",
+    ".agents/notes/implemented/process/2026-06-20-agent-note-classification.md",
+    ".agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md",
+    ".agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md",
     ".agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md",
+    ".agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md",
+    ".agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md",
+    ".agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md",
+    ".agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md",
+    ".agents/notes/implemented/process/2026-07-04-persistence-log-catalog.md",
+    ".agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md",
+    ".agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md",
+    ".agents/notes/implemented/process/2026-07-06-generated-config-catalog.md",
+    ".agents/notes/implemented/process/2026-07-06-node-engine-floor.md",
+    ".agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.md",
+    ".agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.md",
+    ".agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.md",
+    ".agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md",
     ".agents/notes/implemented/process/2026-07-19-web-styling-system.md",
+    ".agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md",
+    ".agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md",
+    ".agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md",
+    ".agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.md",
+    ".agents/notes/implemented/simplification/2026-06-20-prune-dead-seam-methods.md",
+    ".agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md",
+    ".agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md",
+    ".agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md",
+    ".agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md",
+    ".agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.md",
+    ".agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md",
+    ".agents/notes/implemented/simplification/2026-07-04-drop-inert-request-knobs.md",
+    ".agents/notes/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md",
+    ".agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md",
+    ".agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.md",
+    ".agents/notes/implemented/simplification/2026-07-04-prune-write-only-fs-surface.md",
+    ".agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.md",
+    ".agents/notes/implemented/simplification/2026-07-04-share-app-bin-boot-glue.md",
+    ".agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md",
+    ".agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md",
+    ".agents/notes/implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.md",
+    ".agents/notes/implemented/simplification/2026-07-12-prune-unused-web-seam-fields.md",
+    ".agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md",
+    ".agents/notes/implemented/testing/2026-06-11-property-based-testing.md",
+    ".agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md",
+    ".agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md",
+    ".agents/notes/implemented/testing/2026-06-20-remove-redundant-snapshot-log-expected-output.md",
+    ".agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md",
+    ".agents/notes/implemented/testing/2026-06-22-fork-snapshot-scenarios.md",
+    ".agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md",
+    ".agents/notes/implemented/testing/2026-07-04-hook-snapshot-matrix.md",
+    ".agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.md",
+    ".agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md",
+    ".agents/notes/implemented/testing/2026-07-08-shared-acp-snapshot-package.md",
+    ".agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md",
+    ".agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md",
+    ".agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md",
+    ".agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md",
+    ".agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md",
+    ".agents/notes/proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md",
+    ".agents/notes/proposed/process/2026-06-11-api-extractor-reports.md",
+    ".agents/notes/proposed/process/2026-06-11-architectural-conformance.md",
+    ".agents/notes/proposed/process/2026-06-11-supply-chain-and-vendor-drift.md",
+    ".agents/notes/proposed/process/2026-06-20-discover-package-inventory.md",
+    ".agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md",
+    ".agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md",
+    ".agents/notes/proposed/testing/2026-06-11-mutation-testing.md",
+    ".agents/notes/rejected/architecture/2026-06-11-immutable-public-surfaces.md",
+    ".agents/notes/rejected/architecture/2026-06-20-providerless-example-base.md",
+    ".agents/notes/rejected/process/2026-07-04-generate-agent-note-index-tables.md",
+    ".agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md",
+    ".agents/notes/rejected/simplification/2026-06-20-drop-acp-session-load.md",
+    ".agents/notes/rejected/simplification/2026-06-20-drop-acp-terminal-meta.md",
+    ".agents/notes/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md",
+    ".agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.md",
+    ".agents/notes/rejected/simplification/2026-06-20-drop-unused-session-lineage.md",
+    ".agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md",
+    ".agents/notes/rejected/simplification/2026-06-20-generic-tool-rendering.md",
+    ".agents/notes/rejected/simplification/2026-06-20-retire-mid-turn-steering.md",
+    ".agents/notes/rejected/simplification/2026-06-20-single-session-acp-bridge.md",
+    ".agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md",
+    ".agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md",
+    ".agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md",
+    ".agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md",
     "README.md",
+    "docs/architecture.md",
     "docs/cookbook/adding-a-package.md",
     "docs/cookbook/adding-a-tool.md",
     "docs/cookbook/adding-a-vendored-package.md",
     "docs/cookbook/adding-an-llm-adapter.md",
     "docs/cookbook/extension-cookbook.md",
     "docs/cookbook/responding-to-pr-review-on-a-stack.md",
+    "docs/cordis-primer.md",
+    "docs/core-data-structures/approval.md",
+    "docs/core-data-structures/bash.md",
+    "docs/core-data-structures/code-runtime.md",
+    "docs/core-data-structures/compaction.md",
+    "docs/core-data-structures/core.md",
+    "docs/core-data-structures/filesystem.md",
+    "docs/core-data-structures/llm-streaming.md",
+    "docs/core-data-structures/persistence.md",
+    "docs/core-data-structures/sandbox.md",
+    "docs/core-data-structures/scope.md",
+    "docs/core-data-structures/session-query.md",
+    "docs/core-data-structures/session.md",
+    "docs/core-data-structures/skills.md",
+    "docs/core-data-structures/subagent.md",
+    "docs/core-data-structures/system-prompt.md",
+    "docs/core-data-structures/tools.md",
+    "docs/core-data-structures/user-interaction.md",
+    "docs/core-data-structures/web.md",
+    "docs/core-data-structures/workflow.md",
+    "docs/defensive-patterns.md",
     "docs/development.md",
+    "docs/glossary.md",
     "docs/i18n/README.md",
     "docs/i18n/translation-rules.md",
+    "docs/postmortem/0001-acp-default-export-drops-inject.md",
+    "docs/postmortem/0002-js-expression-disabled-filesystem-tools.md",
+    "docs/postmortem/README.md",
+    "docs/testing.md",
     "docs/user/develop/basic/config.md",
     "docs/user/develop/basic/index.md",
     "docs/user/develop/basic/tool.md",
@@ -38,14 +216,19 @@
     ".agents/notes/AGENTS.md",
     ".agents/notes/implemented/AGENTS.md",
     "docs/AGENTS.md",
+    "docs/agent-lifecycle.md",
+    "docs/capability-seams.md",
     "docs/config-catalog.md",
     "docs/cordis-catalog/",
+    "docs/event-producer-consumer.md",
+    "docs/graph-atlas.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",
     "python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/"
   ]
 }
diff --git a/scripts/translation-prompt.snapshot.ts b/scripts/translation-prompt.snapshot.ts
new file mode 100644
index 0000000000..f99e5d5801
--- /dev/null
+++ b/scripts/translation-prompt.snapshot.ts
@@ -0,0 +1,32 @@
+/** Runnable keyless snapshot for the assembled translation request and consumed response. */
+
+import { execFile } from 'node:child_process'
+import { access, mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { promisify } from 'node:util'
+import { describe, expect, it } from 'vitest'
+
+const execFileAsync = promisify(execFile)
+const root = resolve(import.meta.dirname, '..')
+const expected = join(root, 'scripts/snapshots/translation-prompt-v4/request-response.expected.json')
+const refreshing = process.env.DSH_SNAPSHOT === 'record' || process.env.DSH_SNAPSHOT === 'refresh'
+
+describe('translation prompt runnable snapshot', () => {
+  it('assembles the reviewed examples and consumes a recorded new-pair response', async () => {
+    const { stdout, stderr } = await execFileAsync(process.execPath, [
+      join(root, 'scripts/verify-translation-prompt.ts'),
+      '--snapshot',
+    ], { cwd: root, maxBuffer: 4 * 1024 * 1024 })
+    expect(stderr).toBe('')
+    expect(() => {
+      JSON.parse(stdout)
+    }).not.toThrow()
+    if (refreshing) {
+      await mkdir(dirname(expected), { recursive: true })
+      await writeFile(expected, stdout)
+    } else {
+      await access(expected)
+    }
+    await expect(stdout).toMatchFileSnapshot(expected)
+  })
+})
diff --git a/scripts/translation-prompt.spec.ts b/scripts/translation-prompt.spec.ts
index 93754a79a1..949962b91c 100644
--- a/scripts/translation-prompt.spec.ts
+++ b/scripts/translation-prompt.spec.ts
@@ -1,76 +1,200 @@
-/** Regression tests for the executable translation prompt contract. */
+/** Unit tests for the prompt-v4 renderer and three-section response parser. */
 
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
+  consumeTranslationResponse,
   parseTranslationResponse,
   renderTranslationPrompt,
+  renderTranslationRequest,
   renderTranslationResponse,
 } from './translation-prompt.ts'
 
-const document = `# Wrapper
-
-## 模板正文
-
-\`\`\`\`text
-{{source_lang}} to {{target_lang}}
-{{translation_rules}}
-{{terminology}}
-[English]({{source_filename}}) | [中文]({{source_filename_zh}})
-\`\`\`\`
-`
+const root = resolve(import.meta.dirname, '..')
+const document = readFileSync(join(root, 'docs/i18n/translation-prompt.md'), 'utf8')
+const terminology = '| English | 中文 |\n|---|---|\n| agent | agent |'
 
 describe('translation prompt rendering', () => {
-  it('renders every supported placeholder without recursively rewriting injected rules', () => {
-    const rendered = renderTranslationPrompt(document, {
+  it('renders both directions with every placeholder resolved', () => {
+    const en = renderTranslationPrompt(document, { sourceLanguage: 'English', sourceFilename: 'guide.md', terminology })
+    expect(en).toContain('from English to Chinese')
+    expect(en).toContain(terminology)
+    expect(en).not.toContain('{{')
+    expect(en).toContain('plain source stays plain (必须)')
+    expect(en).toContain('When the target language is English, use the "English" column without a Chinese gloss')
+    expect(en).toContain('for a Chinese target, use an established Chinese rendering')
+    expect(en).toContain('for an English target, use the established English technical term')
+    expect(en).toContain('does an English target use established English terminology')
+    expect(en).toContain('The parser removes exactly one framing escape')
+    const zh = renderTranslationPrompt(document, { sourceLanguage: 'Chinese', sourceFilename: 'guide.zh.md', terminology })
+    expect(zh).toContain('from Chinese to English')
+  })
+
+  it('rejects a template with unknown or missing placeholders', () => {
+    const alien = document.replaceAll('{{terminology}}', '{{terms_prompt}}')
+    expect(() => renderTranslationPrompt(alien, { sourceLanguage: 'English', sourceFilename: 'guide.md', terminology })).toThrow(/unsupported placeholder/)
+    const missing = document.replaceAll('{{terminology}}', '')
+    expect(() => renderTranslationPrompt(missing, { sourceLanguage: 'English', sourceFilename: 'guide.md', terminology })).toThrow(/required placeholder/)
+  })
+
+  it('rejects unmatched placeholder delimiters', () => {
+    for (const delimiter of ['{{', '}}']) {
+      const malformed = document.replace('Your task is to translate', `Your task ${delimiter} is to translate`)
+      expect(() => renderTranslationPrompt(malformed, {
+        sourceLanguage: 'English',
+        sourceFilename: 'guide.md',
+        terminology,
+      })).toThrow(/malformed placeholder syntax/)
+    }
+  })
+
+  it('assembles bare few-shot turns before the real source document', () => {
+    const request = renderTranslationRequest(document, {
       sourceLanguage: 'English',
       sourceFilename: 'guide.md',
-      translationRules: 'A literal {{source_lang}} in injected rules.',
-      terminology: '| English | 中文 |',
+      sourceDocument: '# Guide\n\nNew source.',
+      terminology,
+      examples: [{ english: '# Example\n\nEnglish.', chinese: '# 示例\n\n中文。' }],
     })
-    expect(rendered).toContain('English to Chinese')
-    expect(rendered).toContain('A literal {{source_lang}} in injected rules.')
-    expect(rendered).toContain('[English](guide.md) | [中文](guide.zh.md)')
-  })
+    expect(request.targetFilename).toBe('guide.zh.md')
+    expect(request.messages.map(message => message.role)).toEqual(['system', 'user', 'assistant', 'user'])
+    expect(request.messages.slice(1).map(message => message.content)).toEqual([
+      '# Example\n\nEnglish.',
+      '# 示例\n\n中文。',
+      '# Guide\n\nNew source.',
+    ])
 
-  it('rejects a filename whose suffix contradicts the source language', () => {
-    expect(() => renderTranslationPrompt(document, {
+    const reverse = renderTranslationRequest(document, {
       sourceLanguage: 'Chinese',
-      sourceFilename: 'guide.md',
-      translationRules: 'rules',
-      terminology: 'terms',
-    })).toThrow('does not match source language Chinese')
-  })
-
-  it('rejects malformed template placeholders before injecting rule contents', () => {
-    expect(() => renderTranslationPrompt(document.replace('{{source_lang}}', '{{source-lang}}'), {
-      sourceLanguage: 'English',
-      sourceFilename: 'guide.md',
-      translationRules: 'A literal {{source_lang}} in injected rules.',
-      terminology: '| English | 中文 |',
-    })).toThrow('template contains malformed placeholder syntax')
+      sourceFilename: 'guide.zh.md',
+      sourceDocument: '# 指南\n\n新源文。',
+      terminology,
+      examples: [{ english: '# Example\n\nEnglish.', chinese: '# 示例\n\n中文。' }],
+    })
+    expect(reverse.targetFilename).toBe('guide.md')
+    expect(reverse.messages.slice(1).map(message => message.content)).toEqual([
+      '# 示例\n\n中文。',
+      '# Example\n\nEnglish.',
+      '# 指南\n\n新源文。',
+    ])
   })
 })
 
-describe('translation response XML', () => {
-  it('round-trips Markdown and the CDATA terminator', () => {
-    const response = {
-      translation: '# Draft\n\nA ]]> marker.',
-      review: '- [Tone] Fixed.',
-      final: '# Final\n\nA ]]> marker.',
-    }
+describe('translation response sections', () => {
+  it('round-trips Markdown bodies', () => {
+    const response = { translation: '# 标题\n\n正文 **加粗**。', review: '- [Tone] 修正一处。\n- 无修正', final: '# 标题\n\n定稿。' }
     expect(parseTranslationResponse(renderTranslationResponse(response))).toEqual(response)
   })
 
-  it('rejects missing, reordered, nested, attributed, or non-CDATA children', () => {
-    expect(() => parseTranslationResponse('<dsh-translation-response version="1"/>')).toThrow('translation, review, and final')
-    expect(() => parseTranslationResponse('<dsh-translation-response version="1"><review><![CDATA[x]]></review></dsh-translation-response>'))
-      .toThrow('expected translation, got review')
-    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' })
-      .replace('<translation><![CDATA[x]]></translation>', '<translation><b><![CDATA[x]]></b></translation>')))
-      .toThrow('nested element b is not allowed')
-    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' }).replace('<review>', '<review lang="en">')))
-      .toThrow('review must not have attributes')
-    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' }).replace('<![CDATA[x]]>', 'x')))
-      .toThrow('all response field content must be inside CDATA')
+  it('tolerates a fenced xml wrapper around the whole response', () => {
+    const fenced = '```xml\n<translation>\nA\n</translation>\n\n<review>\n- 无修正\n</review>\n\n<final>\nA\n</final>\n```'
+    expect(parseTranslationResponse(fenced).final).toBe('A')
+  })
+
+  it('keeps an inline close tag inside prose from terminating the section', () => {
+    const doc = { translation: 'the wire format uses </translation> as its close tag', review: '- 无修正', final: 'F' }
+    expect(parseTranslationResponse(renderTranslationResponse(doc))).toEqual(doc)
+  })
+
+  it('round-trips wrapper-tag lines inside Markdown bodies', () => {
+    const doc = {
+      translation: '```xml\n</translation>\n```',
+      review: '- [Structure] Preserved `<final>` on its own line.',
+      final: 'literal delimiters\n</final>\n\\</final>',
+    }
+    const rendered = renderTranslationResponse(doc)
+    expect(parseTranslationResponse(rendered)).toEqual(doc)
+    expect(() => parseTranslationResponse(rendered.replace('\\</translation>', '</translation>'))).toThrow(/duplicate <translation>/)
+  })
+
+  it('rejects a duplicate section appearing before final', () => {
+    const early = '<translation>\nA\n</translation>\n<translation>\nB\n</translation>\n<review>\nR\n</review>\n<final>\nF\n</final>'
+    expect(() => parseTranslationResponse(early)).toThrow(/duplicate <translation>/)
+  })
+
+  it('rejects missing, unterminated, or duplicated sections', () => {
+    expect(() => parseTranslationResponse('<translation>\nA\n</translation>')).toThrow(/missing or unterminated <review>/)
+    expect(() => parseTranslationResponse('<translation>\nA')).toThrow(/missing or unterminated <translation>/)
+    const dup = '<translation>\nA\n</translation>\n<review>\nR\n</review>\n<final>\nF\n</final>\n<final>\nG\n</final>'
+    expect(() => parseTranslationResponse(dup)).toThrow(/duplicate <final>/)
+    expect(() => parseTranslationResponse(`${renderTranslationResponse({ translation: 'A', review: 'R', final: 'F' })}\nstray`))
+      .toThrow(/content is not allowed outside/)
+  })
+
+  it('inserts or corrects the target switcher after parsing a new-pair response', () => {
+    const response = renderTranslationResponse({
+      translation: '# 指南\n\n初稿。',
+      review: '- 无修正',
+      final: '# 指南\n\nEnglish | [中文](guide.zh.md)\n\n定稿。',
+    })
+    expect(consumeTranslationResponse(response, { sourceLanguage: 'English', sourceFilename: 'guide.md' }).final).toBe([
+      '# 指南',
+      '',
+      '[English](guide.md) | 中文',
+      '',
+      '定稿。',
+      '',
+    ].join('\n'))
+  })
+
+  it('preserves YAML frontmatter before inserting the target switcher', () => {
+    const response = renderTranslationResponse({
+      translation: '# 指南\n\n初稿。',
+      review: '- 无修正',
+      final: [
+        '---',
+        'layout: home',
+        '---',
+        '',
+        '# 指南',
+        '',
+        '定稿。',
+      ].join('\n'),
+    })
+    expect(consumeTranslationResponse(response, { sourceLanguage: 'English', sourceFilename: 'guide.md' }).final).toBe([
+      '---',
+      'layout: home',
+      '---',
+      '',
+      '# 指南',
+      '',
+      '[English](guide.md) | 中文',
+      '',
+      '定稿。',
+      '',
+    ].join('\n'))
+  })
+
+  it('rejects unterminated YAML frontmatter before the target H1', () => {
+    const response = renderTranslationResponse({
+      translation: '# 指南\n\n初稿。',
+      review: '- 无修正',
+      final: '---\nlayout: home\n\n# 指南\n\n定稿。',
+    })
+    expect(() => consumeTranslationResponse(response, {
+      sourceLanguage: 'English',
+      sourceFilename: 'guide.md',
+    })).toThrow(/unterminated YAML frontmatter/)
+  })
+
+  it('rejects a source filename that contradicts the translation direction', () => {
+    expect(() => renderTranslationPrompt(document, {
+      sourceLanguage: 'Chinese',
+      sourceFilename: 'guide.md',
+      terminology,
+    })).toThrow(/does not match source language Chinese/)
+  })
+
+  it('inserts the English target switcher for a Chinese source', () => {
+    const response = renderTranslationResponse({
+      translation: '# Guide\n\nDraft.',
+      review: '- [None] No corrections.',
+      final: '# Guide\n\nFinal.',
+    })
+    expect(consumeTranslationResponse(response, {
+      sourceLanguage: 'Chinese',
+      sourceFilename: 'guide.zh.md',
+    }).final).toContain('\n\nEnglish | [中文](guide.zh.md)\n\n')
   })
 })
diff --git a/scripts/translation-prompt.ts b/scripts/translation-prompt.ts
index e30c962498..aaf114efe8 100644
--- a/scripts/translation-prompt.ts
+++ b/scripts/translation-prompt.ts
@@ -1,20 +1,18 @@
 /**
- * Executable renderer and strict response parser for the committed
- * documentation-translation prompt contract.
+ * Executable renderer and response parser for the committed
+ * documentation-translation prompt contract (prompt-v4).
+ *
+ * The v4 contract: three placeholders (`source_lang`, `target_lang`,
+ * `terminology`), whole-document translation, and a three-section response
+ * (`<translation>`, `<review>`, `<final>` in order, bare XML tags with raw
+ * Markdown bodies). The pipeline retains filename context outside the model
+ * request and corrects the final language switcher after parsing.
  */
 
 import { basename } from 'node:path'
-import { SaxesParser } from 'saxes'
 
 /** Placeholder names supported by the committed translation prompt. */
-export const TRANSLATION_PROMPT_PLACEHOLDERS = [
-  'source_lang',
-  'target_lang',
-  'translation_rules',
-  'terminology',
-  'source_filename',
-  'source_filename_zh',
-] as const
+export const TRANSLATION_PROMPT_PLACEHOLDERS = ['source_lang', 'target_lang', 'terminology'] as const
 
 type TranslationPromptPlaceholder = (typeof TRANSLATION_PROMPT_PLACEHOLDERS)[number]
 
@@ -26,13 +24,35 @@ export interface TranslationPromptInput {
   sourceLanguage: TranslationLanguage
   /** Source basename, including `.md` or `.zh.md`. */
   sourceFilename: string
-  /** Complete current `translation-rules.md` contents. */
-  translationRules: string
   /** Complete current `terminology.md` contents. */
   terminology: string
 }
 
-/** Parsed contents of the three-element XML response. */
+/** One reviewed whole-document example available in both directions. */
+export interface TranslationExample {
+  english: string
+  chinese: string
+}
+
+/** Inputs for one complete model request. */
+export interface TranslationRequestInput extends TranslationPromptInput {
+  sourceDocument: string
+  examples: TranslationExample[]
+}
+
+/** One model message in the provider-neutral translation request. */
+interface TranslationMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+/** Fully assembled request plus the filename that receives the final body. */
+export interface TranslationRequest {
+  targetFilename: string
+  messages: TranslationMessage[]
+}
+
+/** Parsed contents of the three-section response. */
 export interface TranslationResponse {
   translation: string
   review: string
@@ -42,7 +62,35 @@ export interface TranslationResponse {
 const PLACEHOLDER = /{{([a-z_]+)}}/g
 const TEMPLATE_OPEN = '## 模板正文\n\n````text\n'
 const TEMPLATE_CLOSE = '\n````'
-const RESPONSE_CHILDREN = ['translation', 'review', 'final'] as const
+const RESPONSE_SECTIONS = ['translation', 'review', 'final'] as const
+const RESPONSE_DELIMITERS = new Set(RESPONSE_SECTIONS.flatMap(section => [`<${section}>`, `</${section}>`]))
+const LANGUAGE_SWITCHER = /^(?:English \| \[中文\]\(.+\)|\[English\]\(.+\) \| 中文)$/
+
+interface TranslationFiles {
+  targetFilename: string
+  targetSwitcher: string
+}
+
+function translationFiles(input: Pick<TranslationPromptInput, 'sourceFilename' | 'sourceLanguage'>): TranslationFiles {
+  if (basename(input.sourceFilename) !== input.sourceFilename) {
+    throw new Error(`translation prompt: sourceFilename must be a basename; got ${JSON.stringify(input.sourceFilename)}`)
+  }
+  const sourceIsChinese = input.sourceFilename.endsWith('.zh.md')
+  const sourceIsEnglish = input.sourceFilename.endsWith('.md') && !sourceIsChinese
+  if (input.sourceLanguage === 'Chinese' ? !sourceIsChinese : !sourceIsEnglish) {
+    throw new Error(`translation prompt: ${input.sourceFilename} does not match source language ${input.sourceLanguage}`)
+  }
+  if (sourceIsChinese) {
+    return {
+      targetFilename: input.sourceFilename.replace(/\.zh\.md$/, '.md'),
+      targetSwitcher: `English | [中文](${input.sourceFilename})`,
+    }
+  }
+  return {
+    targetFilename: input.sourceFilename.replace(/\.md$/, '.zh.md'),
+    targetSwitcher: `[English](${input.sourceFilename}) | 中文`,
+  }
+}
 
 /** Extract the machine-consumed text fence from `translation-prompt.md`. */
 function extractTranslationPrompt(document: string): string {
@@ -61,25 +109,14 @@ export function documentedTranslationPromptPlaceholders(document: string): strin
   return [...document.slice(0, preambleEnd).matchAll(/^\| `{{([a-z_]+)}}` \|/gm)].map(match => match[1] ?? '')
 }
 
-/** Render one system prompt from the checked-in template and canonical rules. */
+/** Render one system prompt from the checked-in template. */
 export function renderTranslationPrompt(document: string, input: TranslationPromptInput): string {
-  if (basename(input.sourceFilename) !== input.sourceFilename) {
-    throw new Error(`translation prompt: sourceFilename must be a basename; got ${JSON.stringify(input.sourceFilename)}`)
-  }
-  const sourceIsChinese = input.sourceFilename.endsWith('.zh.md')
-  if (input.sourceLanguage === 'Chinese' ? !sourceIsChinese : sourceIsChinese || !input.sourceFilename.endsWith('.md')) {
-    throw new Error(`translation prompt: ${input.sourceFilename} does not match source language ${input.sourceLanguage}`)
-  }
-
+  translationFiles(input)
   const targetLanguage: TranslationLanguage = input.sourceLanguage === 'English' ? 'Chinese' : 'English'
-  const sourceFilenameZh = sourceIsChinese ? input.sourceFilename : input.sourceFilename.replace(/\.md$/, '.zh.md')
   const values: Record<TranslationPromptPlaceholder, string> = {
     source_lang: input.sourceLanguage,
     target_lang: targetLanguage,
-    translation_rules: input.translationRules,
     terminology: input.terminology,
-    source_filename: input.sourceFilename,
-    source_filename_zh: sourceFilenameZh,
   }
   const template = extractTranslationPrompt(document)
   const placeholderFreeTemplate = template.replace(PLACEHOLDER, '')
@@ -95,77 +132,128 @@ export function renderTranslationPrompt(document: string, input: TranslationProm
   return template.replace(PLACEHOLDER, (_token, name: string) => values[name as TranslationPromptPlaceholder])
 }
 
-/** Escape one value so it remains byte-identical inside an XML CDATA field. */
-function escapeTranslationCdata(value: string): string {
-  return value.replaceAll(']]>', ']]]]><![CDATA[>')
+/**
+ * Assemble the calibrated system prompt, reviewed bare-text examples, and source document.
+ *
+ * @param document - Checked-in translation prompt asset.
+ * @param input - Direction, filename, terminology, examples, and source document.
+ * @returns Provider-neutral messages and the target basename.
+ */
+export function renderTranslationRequest(document: string, input: TranslationRequestInput): TranslationRequest {
+  const files = translationFiles(input)
+  const sourceKey = input.sourceLanguage === 'English' ? 'english' : 'chinese'
+  const targetKey = input.sourceLanguage === 'English' ? 'chinese' : 'english'
+  const messages: TranslationMessage[] = [{ role: 'system', content: renderTranslationPrompt(document, input) }]
+  for (const example of input.examples) {
+    messages.push(
+      { role: 'user', content: example[sourceKey] },
+      { role: 'assistant', content: example[targetKey] },
+    )
+  }
+  messages.push({ role: 'user', content: input.sourceDocument })
+  return { targetFilename: files.targetFilename, messages }
 }
 
-/** Serialize a response using the exact XML wire contract in the prompt. */
+function escapeResponseBody(value: string): string {
+  return value.split('\n').map((line) => {
+    const delimiter = line.replace(/^\\+/, '')
+    return RESPONSE_DELIMITERS.has(delimiter) ? `\\${line}` : line
+  }).join('\n')
+}
+
+function unescapeResponseBody(value: string): string {
+  return value.split('\n').map((line) => {
+    if (!line.startsWith('\\')) return line
+    const candidate = line.slice(1)
+    return RESPONSE_DELIMITERS.has(candidate.replace(/^\\+/, '')) ? candidate : line
+  }).join('\n')
+}
+
+/** Serialize a response in the exact escaped three-section shape the prompt requests. */
 export function renderTranslationResponse(response: TranslationResponse): string {
-  return [
-    '<dsh-translation-response version="1">',
-    `<translation><![CDATA[${escapeTranslationCdata(response.translation)}]]></translation>`,
-    `<review><![CDATA[${escapeTranslationCdata(response.review)}]]></review>`,
-    `<final><![CDATA[${escapeTranslationCdata(response.final)}]]></final>`,
-    '</dsh-translation-response>',
-  ].join('\n')
+  return RESPONSE_SECTIONS.map(section => `<${section}>\n${escapeResponseBody(response[section])}\n</${section}>`).join('\n\n')
 }
 
-/** Parse and validate the exact XML response shape emitted by the model. */
-export function parseTranslationResponse(xml: string): TranslationResponse {
-  const values: TranslationResponse = { translation: '', review: '', final: '' }
-  const stack: string[] = []
-  const cdataFields = new Set<string>()
-  let rootSeen = false
-  let childIndex = 0
-  const fail = (message: string): never => {
-    throw new Error(`translation response: ${message}`)
-  }
-  const parser = new SaxesParser({ xmlns: false })
+/**
+ * Parse the three-section response. Sections must each appear exactly once
+ * and in order; escaped delimiter lines in Markdown bodies are restored.
+ * A fenced ```xml wrapper around the whole response is tolerated, matching
+ * the shape some models echo back from the prompt's own example.
+ */
+export function parseTranslationResponse(text: string): TranslationResponse {
+  let body = text.trim()
+  const fenced = /^```(?:xml)?\n([\s\S]*?)\n```$/.exec(body)
+  if (fenced?.[1] !== undefined) body = fenced[1].trim()
 
-  parser.on('opentag', (tag) => {
-    if (stack.length === 0) {
-      if (rootSeen) fail('contains more than one root element')
-      if (tag.name !== 'dsh-translation-response') fail(`expected dsh-translation-response root, got ${tag.name}`)
-      const attributes = Object.keys(tag.attributes)
-      if (attributes.length !== 1 || tag.attributes.version !== '1') fail('root must have only version="1"')
-      rootSeen = true
-    } else if (stack.length === 1) {
-      const expected = RESPONSE_CHILDREN[childIndex]
-      if (tag.name !== expected) fail(`expected ${expected ?? 'no more children'}, got ${tag.name}`)
-      if (Object.keys(tag.attributes).length !== 0) fail(`${tag.name} must not have attributes`)
-      childIndex++
-    } else {
-      fail(`nested element ${tag.name} is not allowed`)
+  const values: Partial<Record<(typeof RESPONSE_SECTIONS)[number], string>> = {}
+  const lines = body.split('\n')
+  let previousCloseEnd = 0
+  for (const [index, section] of RESPONSE_SECTIONS.entries()) {
+    const open = `<${section}>`
+    const close = `</${section}>`
+    const openCount = lines.filter(line => line === open).length
+    const closeCount = lines.filter(line => line === close).length
+    if (openCount === 0 || closeCount === 0) {
+      throw new Error(`translation response: missing or unterminated <${section}> section`)
     }
-    stack.push(tag.name)
-  })
-  parser.on('text', (value) => {
-    if (stack.length <= 1 && value.trim() === '') return
-    fail('all response field content must be inside CDATA')
-  })
-  parser.on('cdata', (value) => {
-    const field = stack.at(-1)
-    if (field === undefined || !RESPONSE_CHILDREN.includes(field as (typeof RESPONSE_CHILDREN)[number])) {
-      fail('CDATA is allowed only inside translation, review, or final')
-    }
-    const key = field as (typeof RESPONSE_CHILDREN)[number]
-    values[key] += value
-    cdataFields.add(key)
-  })
-  parser.on('closetag', (tag) => {
-    const expected = stack.pop()
-    if (expected !== tag.name) fail(`closing ${tag.name} does not match ${expected ?? 'nothing'}`)
-  })
-  parser.on('comment', () => fail('comments are not allowed'))
-  parser.on('doctype', () => fail('doctypes are not allowed'))
-  parser.on('processinginstruction', () => fail('processing instructions are not allowed'))
-  parser.on('error', error => fail(`invalid XML: ${error.message}`))
-  parser.write(xml).close()
+    if (openCount > 1 || closeCount > 1) throw new Error(`translation response: duplicate <${section}> section`)
 
-  if (childIndex !== RESPONSE_CHILDREN.length) fail('translation, review, and final must each appear exactly once and in order')
-  for (const field of RESPONSE_CHILDREN) {
-    if (!cdataFields.has(field)) fail(`${field} must contain a CDATA section`)
+    const openStart = body.search(new RegExp(`^<${section}>$`, 'm'))
+    const closeStart = body.search(new RegExp(`^</${section}>$`, 'm'))
+    const separator = body.slice(previousCloseEnd, openStart)
+    if (closeStart < openStart || (index === 0 ? separator !== '' : !/^\n+$/.test(separator))) {
+      throw new Error('translation response: sections must appear in translation, review, final order')
+    }
+
+    let contentStart = openStart + open.length
+    if (body[contentStart] === '\n') contentStart++
+    let contentEnd = closeStart
+    if (body[contentEnd - 1] === '\n') contentEnd--
+    values[section] = unescapeResponseBody(body.slice(contentStart, contentEnd))
+    previousCloseEnd = closeStart + close.length
   }
-  return values
+  if (previousCloseEnd !== body.length) throw new Error('translation response: content is not allowed outside response sections')
+  return values as TranslationResponse
+}
+
+function correctLanguageSwitcher(markdown: string, switcher: string): string {
+  const lines = markdown.replaceAll('\r\n', '\n').split('\n')
+  while (lines.at(-1) === '') lines.pop()
+
+  let headingIndex = 0
+  if (lines[0] === '---') {
+    const frontmatterEnd = lines.indexOf('---', 1)
+    if (frontmatterEnd === -1) throw new Error('translation response: final document has unterminated YAML frontmatter')
+    headingIndex = frontmatterEnd + 1
+    while (lines[headingIndex] === '') headingIndex++
+  }
+  if (!/^#\s+\S/.test(lines[headingIndex] ?? '')) {
+    throw new Error('translation response: final document must start with an H1 heading')
+  }
+
+  let contentStart = headingIndex + 1
+  while (lines[contentStart] === '') contentStart++
+  if (LANGUAGE_SWITCHER.test(lines[contentStart] ?? '')) contentStart++
+  while (lines[contentStart] === '') contentStart++
+
+  const output = [...lines.slice(0, headingIndex), lines[headingIndex] as string, '', switcher]
+  const content = lines.slice(contentStart)
+  if (content.length > 0) output.push('', ...content)
+  return `${output.join('\n')}\n`
+}
+
+/**
+ * Parse a model response and make its consumed final document target-path correct.
+ *
+ * @param text - Raw three-section model response.
+ * @param input - Source direction and basename retained by the pipeline.
+ * @returns Parsed response whose `final` body has the canonical target switcher.
+ */
+export function consumeTranslationResponse(
+  text: string,
+  input: Pick<TranslationPromptInput, 'sourceFilename' | 'sourceLanguage'>,
+): TranslationResponse {
+  const parsed = parseTranslationResponse(text)
+  const files = translationFiles(input)
+  return { ...parsed, final: correctLanguageSwitcher(parsed.final, files.targetSwitcher) }
 }
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index f95f47e580..3c199d4d04 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -73,12 +73,32 @@
     },
     {
       "doc": "docs/core-data-structures/core.md",
-      "symbol": "AgentCancelCause",
+      "symbol": "InjectOptions",
       "source": "packages/core/agent/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/core.md",
-      "symbol": "InjectOptions",
+      "symbol": "ResolvedAgentInput",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "AgentMessageId",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "AgentMessage",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "CancelOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "AgentCancelCause",
       "source": "packages/core/agent/src/types.ts"
     },
     {
@@ -136,7 +156,11 @@
       "symbol": "Scope",
       "source": "packages/core/scope/src/index.ts"
     },
-    { "doc": "docs/core-data-structures/scope.md", "symbol": "ScopeLayer", "source": "packages/core/scope/src/store.ts" },
+    {
+      "doc": "docs/core-data-structures/scope.md",
+      "symbol": "ScopeLayer",
+      "source": "packages/core/scope/src/store.ts"
+    },
     {
       "doc": "docs/core-data-structures/goal.md",
       "symbol": "GoalRef",
@@ -294,7 +318,11 @@
       "symbol": "SessionEventMap",
       "source": "packages/core/session/src/types.ts"
     },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "OutOfBandSessionEventMap", "source": "packages/core/session/src/types.ts" },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "OutOfBandSessionEventMap",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "EpochHeader",
@@ -381,6 +409,11 @@
       "symbol": "SessionRecord",
       "source": "packages/session-query/session-query/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionLogSnapshot",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session-query.md",
       "symbol": "SessionSurfaceSnapshot",
@@ -426,7 +459,61 @@
       "symbol": "SessionEventTrace",
       "source": "packages/session-query/session-query/src/types.ts"
     },
-
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleProviderId",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleModelProvenance",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleSource",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleEventData",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleSnapshot",
+      "source": "packages/session-title/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"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleUserMessage",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleAutomaticMode",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleProviderRequest",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleProviderResult",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-title.md",
+      "symbol": "SessionTitleProvider",
+      "source": "packages/session-title/session-title/src/index.ts"
+    },
     {
       "doc": "docs/core-data-structures/session-reference.md",
       "symbol": "SessionReferenceInput",
@@ -447,18 +534,11 @@
       "symbol": "SessionReferenceErrorCode",
       "source": "packages/context/session-reference/src/config.ts"
     },
-
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleProviderId", "source": "packages/session-title/session-title/src/index.ts" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleModelProvenance", "source": "packages/session-title/session-title/src/index.ts" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleSource", "source": "packages/session-title/session-title/src/index.ts" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleEventData", "source": "packages/session-title/session-title/src/index.ts" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleSnapshot", "source": "packages/session-title/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" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleUserMessage", "source": "packages/session-title/session-title/src/index.ts" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleAutomaticMode", "source": "packages/session-title/session-title/src/index.ts" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleProviderRequest", "source": "packages/session-title/session-title/src/index.ts" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleProviderResult", "source": "packages/session-title/session-title/src/index.ts" },
-    { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleProvider", "source": "packages/session-title/session-title/src/index.ts" },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolOutputDefinition",
+      "source": "packages/core/tools/src/index.ts"
+    },
     {
       "doc": "docs/core-data-structures/tools.md",
       "symbol": "ToolDefinition",
@@ -466,12 +546,22 @@
     },
     {
       "doc": "docs/core-data-structures/tools.md",
-      "symbol": "SchemaProp",
+      "symbol": "ValueSchemaSpec",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
       "doc": "docs/core-data-structures/tools.md",
-      "symbol": "SchemaSpec",
+      "symbol": "ParameterPropertySpec",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ParameterSchemaSpec",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "InferValue",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
@@ -519,6 +609,21 @@
       "symbol": "ToolRestriction",
       "source": "packages/core/tools/src/index.ts"
     },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolFailure",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolExecutionSuccess",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolExecutionFailure",
+      "source": "packages/core/tools/src/index.ts"
+    },
     {
       "doc": "docs/core-data-structures/tools.md",
       "symbol": "ToolExecutionResult",
@@ -536,22 +641,22 @@
     },
     {
       "doc": "docs/core-data-structures/tools.md",
-      "symbol": "StructuredScalar",
+      "symbol": "JsonSchemaScalar",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
       "doc": "docs/core-data-structures/tools.md",
-      "symbol": "StructuredSchemaType",
+      "symbol": "JsonSchemaType",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
       "doc": "docs/core-data-structures/tools.md",
-      "symbol": "StructuredSchemaNode",
+      "symbol": "JsonSchemaNode",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
       "doc": "docs/core-data-structures/tools.md",
-      "symbol": "StructuredOutputSchema",
+      "symbol": "ObjectJsonSchema",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
@@ -749,6 +854,11 @@
       "symbol": "ConfinedArgv",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
+    {
+      "doc": "docs/core-data-structures/code-runtime.md",
+      "symbol": "CodeJsonValue",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/code-runtime.md",
       "symbol": "CodeRunRequest",
@@ -764,6 +874,11 @@
       "symbol": "CodeBindingNamespace",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/code-runtime.md",
+      "symbol": "CodeBindingErrorClass",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/code-runtime.md",
       "symbol": "CodeBindingFunction",
@@ -1058,6 +1173,984 @@
       "doc": "docs/core-data-structures/lsp.md",
       "symbol": "LspService",
       "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.md",
+      "symbol": "SessionPersistenceRevision",
+      "source": "packages/session-persistence/session-persistence/src/revision.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.md",
+      "symbol": "SessionPersistenceSnapshot",
+      "source": "packages/session-persistence/session-persistence/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionResultFilter",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventResultFilter",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventSearchDocument",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionSearchCursor",
+      "source": "packages/session-query/session-query/src/cursor.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionSearchRequest",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventSearchRequest",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionSearchPage",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventSearchHit",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionSearchHit",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "Branded",
+      "source": "packages/util/brand/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "ContentBlockMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AssistantProvenance",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "Message",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "MessageSourceMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "FinishReasonMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "LlmProviderInfo",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "LlmModelInfo",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "LlmModelContext",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "GenerateOptions",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "ToolSchema",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "LlmCallConfig",
+      "source": "packages/llm/llm/src/call-config.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "SessionEvent",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "SendOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AgentCancelCause",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "InjectOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "ResolvedAgentInput",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AgentMessageId",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AgentMessage",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "CancelOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "Agent",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "HookContext",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "PromptDecision",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "ContinuationDecision",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "RequestError",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "RequestErrorDecision",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "ContinuationStop",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "SessionStartSource",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/scope.zh.md",
+      "symbol": "ScopeKey",
+      "source": "packages/core/scope/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/scope.zh.md",
+      "symbol": "Scoped",
+      "source": "packages/core/scope/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/scope.zh.md",
+      "symbol": "Scope",
+      "source": "packages/core/scope/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/scope.zh.md",
+      "symbol": "ScopeLayer",
+      "source": "packages/core/scope/src/store.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/system-prompt.zh.md",
+      "symbol": "AssembleContext",
+      "source": "packages/core/system-prompt/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/system-prompt.zh.md",
+      "symbol": "PromptSection",
+      "source": "packages/core/system-prompt/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/system-prompt.zh.md",
+      "symbol": "ToolProviderResult",
+      "source": "packages/core/system-prompt/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.zh.md",
+      "symbol": "StreamChunk",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.zh.md",
+      "symbol": "LlmFailure",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.zh.md",
+      "symbol": "TokenUsage",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.zh.md",
+      "symbol": "ContentBlockMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.zh.md",
+      "symbol": "AppIdentity",
+      "source": "packages/llm/llm/src/attribution.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.zh.md",
+      "symbol": "BlockAssembler",
+      "source": "packages/llm/llm/src/assembler.ts",
+      "projection": "public-api"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.zh.md",
+      "symbol": "LlmAdapter",
+      "source": "packages/llm/llm/src/index.ts",
+      "projection": "public-api"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "PromptMessageData",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SessionEventMap",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "OutOfBandSessionEventMap",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "EpochHeader",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "TodoItem",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SessionEvent",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "TurnTriggerMap",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "TurnEndReasonMap",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceEventType",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceOp",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceIntent",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SessionSurface",
+      "source": "packages/core/session/src/surface.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceFoldReplacement",
+      "source": "packages/core/session/src/surface.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceFoldResult",
+      "source": "packages/core/session/src/surface.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "Session",
+      "source": "packages/core/session/src/index.ts",
+      "projection": "public-api"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.zh.md",
+      "symbol": "SessionHeader",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.zh.md",
+      "symbol": "CreateSessionOptions",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.zh.md",
+      "symbol": "SessionLocation",
+      "source": "packages/session-persistence/session-persistence/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.zh.md",
+      "symbol": "SessionPersistenceRevision",
+      "source": "packages/session-persistence/session-persistence/src/revision.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.zh.md",
+      "symbol": "SessionPersistenceSnapshot",
+      "source": "packages/session-persistence/session-persistence/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventSurface",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionRecord",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionLogSnapshot",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionSurfaceSnapshot",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventRecord",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionResultFilter",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventResultFilter",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventSearchDocument",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionSearchCursor",
+      "source": "packages/session-query/session-query/src/cursor.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionSearchRequest",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventSearchRequest",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionSearchPage",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventSearchHit",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionSearchHit",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionLineageNode",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionLineageTrace",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionQueryErrorCode",
+      "source": "packages/session-query/session-query/src/config.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventReadRequest",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventWindow",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventTraceRequest",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.zh.md",
+      "symbol": "SessionEventTrace",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolOutputDefinition",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolDefinition",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ValueSchemaSpec",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ParameterPropertySpec",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ParameterSchemaSpec",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "InferValue",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "InferArgs",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolExecutionToken",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolExecutionInput",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolExecution",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolDispatchExecution",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolExecutionMode",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolRunContext",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolGuard",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolRestriction",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolFailure",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolExecutionSuccess",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolExecutionFailure",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ToolExecutionResult",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "PreToolDecision",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "PostToolDecision",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "JsonSchemaScalar",
+      "source": "packages/core/tools/src/json-schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "JsonSchemaType",
+      "source": "packages/core/tools/src/json-schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "JsonSchemaNode",
+      "source": "packages/core/tools/src/json-schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.zh.md",
+      "symbol": "ObjectJsonSchema",
+      "source": "packages/core/tools/src/json-schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.zh.md",
+      "symbol": "AskUserQuestionOption",
+      "source": "packages/ui/user-interaction/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.zh.md",
+      "symbol": "AskUserQuestionItem",
+      "source": "packages/ui/user-interaction/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.zh.md",
+      "symbol": "AskUserQuestionRequest",
+      "source": "packages/ui/user-interaction/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.zh.md",
+      "symbol": "AskUserQuestionAnswerItem",
+      "source": "packages/ui/user-interaction/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.zh.md",
+      "symbol": "AskUserQuestionAnswer",
+      "source": "packages/ui/user-interaction/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.zh.md",
+      "symbol": "UserInteractionProvider",
+      "source": "packages/ui/user-interaction/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.zh.md",
+      "symbol": "UserInteractionError",
+      "source": "packages/ui/user-interaction/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/approval.zh.md",
+      "symbol": "ApprovalRequestId",
+      "source": "packages/ui/user-approval/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/approval.zh.md",
+      "symbol": "ApprovalOutcome",
+      "source": "packages/ui/user-approval/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/approval.zh.md",
+      "symbol": "ApprovalPolicy",
+      "source": "packages/ui/user-approval/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/approval.zh.md",
+      "symbol": "ApprovalRequest",
+      "source": "packages/ui/user-approval/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "DshEnvironmentKey",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "DshEnvironment",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "BashExecRequest",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "BashExecSpec",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "BashRunResult",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "BashSandboxInfo",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "CollectedOutput",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "BashProcess",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.zh.md",
+      "symbol": "BashProcessRead",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.zh.md",
+      "symbol": "SandboxMode",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.zh.md",
+      "symbol": "ConfinedSandboxMode",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.zh.md",
+      "symbol": "SandboxExecutionPolicy",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.zh.md",
+      "symbol": "SandboxEnforcement",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.zh.md",
+      "symbol": "SandboxPolicy",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.zh.md",
+      "symbol": "SandboxPolicyRequest",
+      "source": "packages/sandbox/sandbox-policy/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.zh.md",
+      "symbol": "ConfinedArgv",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.zh.md",
+      "symbol": "CodeJsonValue",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.zh.md",
+      "symbol": "CodeRunRequest",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.zh.md",
+      "symbol": "CodeRunResult",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.zh.md",
+      "symbol": "CodeBindingNamespace",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.zh.md",
+      "symbol": "CodeBindingErrorClass",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.zh.md",
+      "symbol": "CodeBindingFunction",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.zh.md",
+      "symbol": "CodeRunFailure",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsTarget",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsTargetKey",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsVersion",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsInfo",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsPathInfo",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsDirEntry",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsWriteIntent",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsWriteOutcome",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsEditRequest",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsEditOutcome",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsErrorCode",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FsPolicyExec",
+      "source": "packages/fs/fs-policy/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.zh.md",
+      "symbol": "FileReadOutcome",
+      "source": "packages/fs/tool-fs/src/read-render.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "SkillSource",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "SkillResourceBase",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "SkillSummary",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "SkillCandidate",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "SkillDefinition",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "SkillRegistration",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "SkillLookupOptions",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "SkillProvider",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.zh.md",
+      "symbol": "Config",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/compaction.zh.md",
+      "symbol": "CompactionResult",
+      "source": "packages/compact/compact/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/compaction.zh.md",
+      "symbol": "CompactionTrigger",
+      "source": "packages/compact/compact/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/compaction.zh.md",
+      "symbol": "PrunedEntry",
+      "source": "packages/compact/compact-tool-result-prune/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/compaction.zh.md",
+      "symbol": "PruneResult",
+      "source": "packages/compact/compact-tool-result-prune/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.zh.md",
+      "symbol": "SubagentCapabilities",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.zh.md",
+      "symbol": "SubagentStartRequest",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.zh.md",
+      "symbol": "SubagentResult",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.zh.md",
+      "symbol": "SubagentStopReasonMap",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.zh.md",
+      "symbol": "SubagentRun",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.zh.md",
+      "symbol": "SubagentProvider",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.zh.md",
+      "symbol": "WebSearchRequest",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.zh.md",
+      "symbol": "WebSearchResult",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.zh.md",
+      "symbol": "WebSearchSource",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.zh.md",
+      "symbol": "WebFetchRequest",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.zh.md",
+      "symbol": "WebFetchResult",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.zh.md",
+      "symbol": "WebFetchBody",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/workflow.zh.md",
+      "symbol": "WorkflowStartRequest",
+      "source": "packages/workflow/workflow/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/workflow.zh.md",
+      "symbol": "WorkflowMeta",
+      "source": "packages/workflow/workflow/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/workflow.zh.md",
+      "symbol": "WorkflowResult",
+      "source": "packages/workflow/workflow/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/workflow.zh.md",
+      "symbol": "WorkflowRun",
+      "source": "packages/workflow/workflow/src/types.ts"
     }
   ]
 }
diff --git a/scripts/verify-cordis-config.ts b/scripts/verify-cordis-config.ts
index 916db4a168..6041be78ed 100644
--- a/scripts/verify-cordis-config.ts
+++ b/scripts/verify-cordis-config.ts
@@ -12,6 +12,7 @@ import { globSync, readFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import ts from 'typescript'
+import { cordisConfigFiles } from './cordis-config-files.ts'
 
 interface JsExpr {
   __jsExpr: string
@@ -39,10 +40,7 @@ const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
 })
 const schema = yaml.JSON_SCHEMA.extend(jsExprType)
 
-const files = globSync(['**/*cordis*.yml', '**/*cordis*.yaml'], {
-  cwd: root,
-  exclude: ['.claude/**', 'node_modules/**', 'vendor/**'],
-}).sort()
+const files = cordisConfigFiles(root)
 const errors: string[] = []
 const examplePluginReferences: PluginReference[] = []
 
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 6fc46dbdb8..d5fa282a24 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -45,6 +45,8 @@ 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/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/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/ui-slots': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-primitives': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/web-react': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
@@ -53,6 +55,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-question': { kind: 'indirect', reason: 'The package mounts dsh-tool-ask-user; that tool owns the model-visible schema and answer rendering.' },
   'packages/client/ui-trajectory': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-theme': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/i18n': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
@@ -76,6 +79,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/sdk/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
   'packages/sdk/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or 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/skill/skill': { kind: 'indirect', reason: 'The provider registry 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.' },
diff --git a/scripts/verify-translation-prompt.ts b/scripts/verify-translation-prompt.ts
index 66d83e47ad..6ad1787a9d 100644
--- a/scripts/verify-translation-prompt.ts
+++ b/scripts/verify-translation-prompt.ts
@@ -3,11 +3,14 @@
 import { readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import {
+  consumeTranslationResponse,
   documentedTranslationPromptPlaceholders,
   parseTranslationResponse,
   renderTranslationPrompt,
+  renderTranslationRequest,
   renderTranslationResponse,
   TRANSLATION_PROMPT_PLACEHOLDERS,
+  type TranslationExample,
 } from './translation-prompt.ts'
 
 const root = resolve(import.meta.dirname, '..')
@@ -17,38 +20,76 @@ function read(path: string): string {
 }
 
 try {
+  const mode = process.argv[2]
+  if (mode !== undefined && mode !== '--snapshot') throw new Error(`unsupported argument ${JSON.stringify(mode)}`)
   const document = read('docs/i18n/translation-prompt.md')
-  const translationRules = read('docs/i18n/translation-rules.md')
   const terminology = read('docs/i18n/terminology.md')
+  const examplePaths = [
+    ['README.md', 'README.zh.md'],
+    ['docs/development.md', 'docs/development.zh.md'],
+    ['docs/i18n/README.md', 'docs/i18n/README.zh.md'],
+    ['docs/i18n/translation-rules.md', 'docs/i18n/translation-rules.zh.md'],
+    [
+      '.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md',
+      '.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md',
+    ],
+  ] as const
+  const examples: TranslationExample[] = examplePaths.map(([english, chinese]) => ({
+    english: read(english),
+    chinese: read(chinese),
+  }))
+  const sourceDocument = read('scripts/fixtures/translation-prompt/snapshot-note.md')
+  const recordedResponse = read('scripts/fixtures/translation-prompt/response.txt')
   const documented = documentedTranslationPromptPlaceholders(document)
   if (documented.join('\n') !== TRANSLATION_PROMPT_PLACEHOLDERS.join('\n')) {
     throw new Error(`placeholder table must list exactly: ${TRANSLATION_PROMPT_PLACEHOLDERS.join(', ')}`)
   }
 
-  const englishSource = renderTranslationPrompt(document, {
-    sourceLanguage: 'English',
-    sourceFilename: 'example.md',
-    translationRules,
-    terminology,
-  })
+  const englishInput = { sourceLanguage: 'English' as const, sourceFilename: 'snapshot-note.md', terminology }
+  const englishSource = renderTranslationPrompt(document, englishInput)
   const chineseSource = renderTranslationPrompt(document, {
     sourceLanguage: 'Chinese',
-    sourceFilename: 'example.zh.md',
-    translationRules,
+    sourceFilename: 'snapshot-note.zh.md',
     terminology,
   })
-  if (!englishSource.includes('[English](example.md) | 中文')) throw new Error('English-source render does not carry the Chinese switcher instruction')
-  if (!chineseSource.includes('English | [中文](example.zh.md)')) throw new Error('Chinese-source render does not carry the English switcher instruction')
+  if (englishSource.includes('{{') || chineseSource.includes('{{')) throw new Error('rendered prompt contains an unresolved placeholder')
+  if (!englishSource.includes('from English to Chinese')) throw new Error('English-source render does not translate into Chinese')
+  if (!chineseSource.includes('from Chinese to English')) throw new Error('Chinese-source render does not translate into English')
 
   const example = /```xml\n([\s\S]*?)\n```/.exec(englishSource)?.[1]
-  if (example === undefined) throw new Error('rendered prompt has no XML response example')
+  if (example === undefined) throw new Error('rendered prompt has no three-section response example')
   parseTranslationResponse(example)
 
-  const roundTrip = { translation: 'first ]]> pass', review: '- [None] No corrections.', final: 'final ]]> text' }
+  const roundTrip = { translation: 'first pass\n\nwith **markdown**', review: '- 无修正', final: 'final text' }
   const parsed = parseTranslationResponse(renderTranslationResponse(roundTrip))
-  if (JSON.stringify(parsed) !== JSON.stringify(roundTrip)) throw new Error('CDATA split rule does not round-trip response content')
+  if (JSON.stringify(parsed) !== JSON.stringify(roundTrip)) throw new Error('three-section response does not round-trip')
 
-  console.log('verify-translation-prompt: both directions render and the XML response contract parses.')
+  const request = renderTranslationRequest(document, { ...englishInput, sourceDocument, examples })
+  if (request.targetFilename !== 'snapshot-note.zh.md') throw new Error('English request resolves the wrong target filename')
+  const expectedRoles = ['system', ...examples.flatMap(() => ['user', 'assistant']), 'user']
+  if (request.messages.map(message => message.role).join('\n') !== expectedRoles.join('\n')) {
+    throw new Error('reviewed examples are not assembled as system, example pairs, then source')
+  }
+  const consumed = consumeTranslationResponse(recordedResponse, englishInput)
+  const expectedFinalPrefix = [
+    '---',
+    'layout: doc',
+    '---',
+    '',
+    '# 快照说明',
+    '',
+    '[English](snapshot-note.md) | 中文',
+    '',
+  ].join('\n')
+  if (!consumed.final.startsWith(expectedFinalPrefix)) {
+    throw new Error('recorded frontmatter response does not preserve metadata and receive the canonical target switcher')
+  }
+
+  if (mode === '--snapshot') {
+    process.stdout.write(`${JSON.stringify({ request, response: consumed }, null, 2)}\n`)
+  } else {
+    console.log('verify-translation-prompt: both directions render, reviewed examples assemble, and the consumed response is target-path correct.')
+  }
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error)
   console.error(`verify-translation-prompt: ${message}`)
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 2018a1c747..56ab3ffef3 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -102,12 +102,14 @@
       "@deepseek-ai/dsh-client-ui-primitives": ["./packages/client/ui-primitives/src"],
       "@deepseek-ai/dsh-client-web-react": ["./packages/client/web-react/src"],
       "@deepseek-ai/dsh-client-connection": ["./packages/client/connection/src"],
+      "@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"],
       "@deepseek-ai/dsh-client-runtime/client": ["./packages/client/runtime/src/client"],
-      "@deepseek-ai/dsh-client-runtime/loader": ["./packages/client/runtime/src/client/loader"],
       "@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-question": ["./packages/client/ui-question/src"],
       "@deepseek-ai/dsh-client-ui-trajectory": ["./packages/client/ui-trajectory/src"],
       "@deepseek-ai/dsh-client-ui-theme": ["./packages/client/ui-theme/src"],
       "@deepseek-ai/dsh-client-i18n": ["./packages/client/i18n/src"],
diff --git a/tsconfig.client.json b/tsconfig.client.json
index d7ee9090e7..7915df50ff 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -27,11 +27,14 @@
     { "path": "./packages/client/ui-slots" },
     { "path": "./packages/client/ui-primitives" },
     { "path": "./packages/client/web-react" },
+    { "path": "./packages/client/modules" },
+    { "path": "./packages/client/hmr" },
     { "path": "./packages/client/connection" },
     { "path": "./packages/client/runtime" },
     { "path": "./packages/client/ui-layout" },
     { "path": "./packages/client/ui-sidebar" },
     { "path": "./packages/client/ui-conversation" },
+    { "path": "./packages/client/ui-question" },
     { "path": "./packages/client/ui-trajectory" },
     { "path": "./packages/client/ui-theme" },
     { "path": "./packages/client/i18n" },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 5419347734..b3ae9b21da 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -44,6 +44,7 @@
     { "path": "./packages/session-persistence/session-persistence-jsonl" },
     { "path": "./packages/session-persistence/session-persistence-sqlite" },
     { "path": "./packages/session-query/session-query" },
+    { "path": "./packages/session-query/session-query-sqlite" },
     { "path": "./packages/session-title/session-title" },
     { "path": "./packages/session-title/session-title-llm" },
     { "path": "./packages/session-title/session-title-first-message-llm" },
diff --git a/vendor/README.md b/vendor/README.md
index ae43760ceb..1f4d61e6b1 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -37,6 +37,7 @@ 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.
 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. **`include/src/index.ts` hot-reload hardening**: `refresh()` awaits the full read-and-update and catches failures (logging a warning and keeping the last good entry tree) instead of rethrowing — upstream's throw escaped `@cordisjs/plugin-hmr`'s async watcher callback as an unhandled rejection, so one bad `cordis.yml` edit killed a live app. `read()` rejects a non-array parse result (an empty or mid-write truncated file parses to `undefined`, which upstream later crashed on) and commits `content`/`data` only on success, so reverting an edit to the exact last good content reads as "unchanged". `refresh()` and the `internal/update` listener re-apply `config.patches` before `root.update()`, matching initial load; upstream applied patches only in `[Service.init]`, so any config hot-reload silently reverted overlay-patched entries and removed inserted ones. `applyPatches` deep-copies via `structuredClone` instead of mutating the cached parse (repeated application converges; removing a patch reverts), and the veto-style `internal/update` listener persists the incoming config itself (`Fiber.update` only assigns behind `next()`), so later re-reads use the new patches. `[Service.init]` falls back to `initial` only on `ENOENT`; an existing-but-invalid file fails loud with its real parse error instead of "config file not found" (or a silent overwrite). Covered by `packages/ui/app-boot/tests/config-reload.spec.ts`.
 
 ## Sync procedure
 
diff --git a/vendor/include/src/index.ts b/vendor/include/src/index.ts
index 2258d3af06..b1517d5458 100644
--- a/vendor/include/src/index.ts
+++ b/vendor/include/src/index.ts
@@ -77,7 +77,15 @@ export class Include extends EntryTree {
 
     ctx.on('internal/update', (config, _, next) => {
       if (config.path !== this.config.path) return next()
-      this.root.update(this.data!)
+      // Veto the fiber restart (children update in place), but persist the new
+      // config ourselves — `Fiber.update` only assigns `this.config` behind
+      // `next()`, and a stale `this.config.patches` would make the next
+      // `refresh()` re-apply the old overlay.
+      this.config = config
+      this.root.update(this.applyPatches(this.data!, config.patches)).catch((error) => {
+        this.ctx.logger.warn('config update at %C failed', this.filename)
+        this.ctx.logger.warn(error)
+      })
     })
   }
 
@@ -93,22 +101,37 @@ export class Include extends EntryTree {
   private async read(forced = false) {
     const content = await readFile(this.filename, 'utf8')
     if (!forced && this.content === content) return false
-    this.content = content
+    let data: any
     if (this.type === 'application/yaml') {
-      this.data = yaml.load(this.content, { schema }) as any
+      data = yaml.load(content, { schema })
     } else if (this.type === 'application/json') {
-      this.data = JSON.parse(this.content) as any
+      data = JSON.parse(content)
     } else {
       const module = await import(/* @vite-ignore */ this.filename)
-      this.data = module.default || module
+      data = module.default || module
     }
+    // An empty or truncated file (common mid-edit: editors and `sed -i` write
+    // through temp states) parses to `undefined`, not an error; reject every
+    // non-array shape here so callers see one "invalid file" signal. Content
+    // and data commit only on success, so an edit that is later reverted to
+    // the exact last good content correctly reads as "unchanged".
+    if (!Array.isArray(data)) {
+      throw new TypeError(`config file must be a top-level array of entries: ${this.filename}`)
+    }
+    this.content = content
+    this.data = data
     await this.checkAccess()
     return true
   }
 
-  private applyPatches(data: EntryOptions[]): EntryOptions[] {
-    const { patches } = this.config
-    if (!patches?.length) return data
+  private applyPatches(data: EntryOptions[], patches = this.config.patches): EntryOptions[] {
+    // Always detach from the cached parse: patching shared entry objects would
+    // bake earlier patch values into `this.data`, so repeated application
+    // (config hot-reloads) could never revert a removed or changed patch. The
+    // supported extensions guarantee JSON-safe plain data, so `structuredClone`
+    // cannot throw here.
+    if (!patches?.length) return [...data]
+    data = structuredClone(data)
 
     const entryMap = new Map<string, EntryOptions>()
     const buildMap = (entries: EntryOptions[]) => {
@@ -174,7 +197,11 @@ export class Include extends EntryTree {
   async* [Service.init]() {
     try {
       await this.read()
-    } catch {
+    } catch (error) {
+      // Only a missing file falls back to `initial` (or the not-found error):
+      // an existing-but-invalid file must fail loud with its real parse error,
+      // never be mislabelled as absent or silently overwritten.
+      if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') throw error
       if (this.config.initial) {
         this.writeFile(this.config.initial as any)
         await this.read()
@@ -184,18 +211,26 @@ export class Include extends EntryTree {
     }
 
     yield () => this.stop()
-    const data = this.applyPatches([...this.data!])
-    await this.root.update(data)
+    await this.root.update(this.applyPatches(this.data!))
   }
 
   stop() {
     this.root.stop()
   }
 
-  /** Re-read the file and refresh child entries when content changed. */
+  /**
+   * Re-read the file and refresh child entries when content changed. An
+   * unreadable or unparsable file logs a warning and keeps the last good
+   * tree: a hot-reload of a live app must never take the process down.
+   */
   async refresh() {
-    if (!await this.read()) return
-    this.root.update(this.data!)
+    try {
+      if (!await this.read()) return
+      await this.root.update(this.applyPatches(this.data!))
+    } catch (error) {
+      this.ctx.logger.warn('config reload at %C failed; keeping the running tree', this.filename)
+      this.ctx.logger.warn(error)
+    }
   }
 
   private async _writeFile(config: EntryOptions[]) {
diff --git a/vitest.config.ts b/vitest.config.ts
index fe704797f5..6bbe339960 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -11,6 +11,7 @@ const windowsUnsupportedPackages = process.platform === 'win32'
   ? [
       'packages/bash/*',
       'packages/hooks/*',
+      'packages/pty/pty-local',
       'packages/sandbox/sandbox-local',
       'packages/sdk/create-sdk',
       'packages/sdk/helper',
@@ -60,7 +61,10 @@ export default defineConfig({
         plugins: [pathsPlugin()],
         test: {
           name: 'thread-safe',
-          pool: 'threads',
+          // 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: [
@@ -97,6 +101,7 @@ export default defineConfig({
         // 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/*',
+        'packages/client/ui-question/src/client/QuestionComposer.tsx',
         'packages/client/web-react/src/*',
         'packages/client/runtime/src/*',
         'packages/client/ui-conversation/src/*',
@@ -104,6 +109,8 @@ export default defineConfig({
         'packages/client/ui-layout/src/*',
         'packages/client/web/src/*',
         'packages/host/webserver/src/*',
+        'packages/client/modules/src/loader.ts',
+        'packages/client/hmr/src/client/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
       ],
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 24764cf6c7..2ccec62702 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -20,10 +20,11 @@ const snapshotMaxConcurrency = positiveIntFromEnv(
   Math.min(DEFAULT_SNAPSHOT_MAX_CONCURRENCY, availableParallelism()),
 )
 
-// Replay is the keyless default: boot real example subprocesses from recorded model scripts and diff
-// normalized protocol or transcript output plus persisted-log expected outputs. `record` calls the real API
-// and updates fixtures and expected outputs; `refresh` replays committed scripts and updates current expected outputs.
-// Replay/refresh never load `.env`; only record reads a key from the environment or root `.env`.
+// Replay is the keyless default: boot real subprocess paths from recorded model responses and diff
+// assembled requests, normalized protocol or transcript output, and persisted-log expected outputs.
+// `record` calls the real API and updates fixtures and expected outputs; `refresh` replays committed scripts
+// and updates current expected outputs. Replay/refresh never load `.env`; only record reads a key from the
+// environment or root `.env`.
 if (process.env.DSH_SNAPSHOT === 'record') {
   try {
     process.loadEnvFile(new URL('.env', import.meta.url).pathname)
@@ -42,6 +43,10 @@ export default defineConfig({
   test: {
     setupFiles: ['./scripts/test-invariants.ts'],
     include: [
+      'scripts/**/*.snapshot.ts',
+      // 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'] : []),
       'examples/*/tests/**/*.snapshot.ts',
       'packages/sdk/*/tests/**/*.snapshot.ts',
       'packages/ui/tui/tests/**/*.snapshot.ts',
diff --git a/website/docs.ts b/website/docs.ts
index ee7ad64061..1888cd908c 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -226,14 +226,53 @@ const cordisTutorial = mirroredPages(([
   ...(file === 'index.md' ? { sourceAliases: ['docs/cordis-tutorial'] } : {}),
 })))
 
+const cordisPrimerReference = pairedPages([
+  {
+    source: 'docs/cordis-primer.md',
+    route: 'reference/cordis-primer.md',
+    label: { root: 'Cordis 入门', en: 'Cordis primer' },
+    sidebar: { root: 'zh-reference', en: 'en-reference' },
+    section: { root: '概念', en: 'Concepts' },
+    order: 1,
+  },
+])
+
+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],
+] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
+  source: `docs/core-data-structures/${file}`,
+  route: `reference/core-data-structures/${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'] } : {}),
+})))
+
 const reference = mirroredPages([
   ...([
-    ['docs/architecture.md', 'reference/index.md', '架构', 'Architecture'],
-    ['docs/cordis-primer.md', 'reference/cordis-primer.md', 'Cordis 入门', 'Cordis primer'],
-    ['docs/capability-seams.md', 'reference/capability-seams.md', '能力服务', 'Capability services'],
-    ['docs/agent-lifecycle.md', 'reference/agent-lifecycle.md', 'Agent 生命周期', 'Agent lifecycle'],
-    ['docs/tool-execution-pipeline.md', 'reference/tool-execution-pipeline.md', 'Tool 执行', 'Tool execution'],
-  ] as const).map(([source, route, rootLabel, enLabel], order): MirroredPage => ({
+    ['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,
     contentLocale: 'en-US',
@@ -273,28 +312,10 @@ const reference = mirroredPages([
     order,
   })),
   ...([
-    ['core.md', '核心数据结构', 'Core data structures'],
-    ['scope.md', '作用域', 'Scopes'],
-    ['session.md', '会话', 'Sessions'],
-    ['goal.md', '目标', 'Goals'],
-    ['system-prompt.md', '系统提示词', 'System prompts'],
-    ['tools.md', '工具', 'Tools'],
-    ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming'],
-    ['bash.md', 'Bash 执行', 'Bash execution'],
-    ['pty.md', 'PTY 会话', 'PTY sessions'],
-    ['filesystem.md', '文件系统', 'Filesystem'],
-    ['code-runtime.md', '代码运行时', 'Code runtime'],
-    ['compaction.md', '上下文压缩', 'Compaction'],
-    ['subagent.md', '子代理', 'Subagents'],
-    ['workflow.md', '工作流', 'Workflows'],
-    ['skills.md', '技能', 'Skills'],
-    ['approval.md', '审批', 'Approvals'],
-    ['user-interaction.md', '用户交互', 'User interaction'],
-    ['commands.md', '命令', 'Human commands'],
-    ['sandbox.md', '沙箱', 'Sandboxing'],
-    ['web.md', 'Web 访问', 'Web access'],
-    ['persistence.md', '会话持久化', 'Session persistence'],
-  ] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
+    ['goal.md', '目标', 'Goals', 3],
+    ['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}`,
     contentLocale: 'en-US',
@@ -302,7 +323,6 @@ const reference = mirroredPages([
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '数据结构', en: 'Data structures' },
     order,
-    ...(file === 'core.md' ? { sourceAliases: ['docs/core-data-structures'] } : {}),
   })),
   ...([
     ['adding-a-package.md', '新增 Package', 'Adding a package'],
@@ -325,5 +345,7 @@ export const docsPages: DocsPage[] = [
   ...homeAndGuide,
   ...develop,
   ...cordisTutorial,
+  ...cordisPrimerReference,
+  ...coreDataReference,
   ...reference,
 ]